# Coordinator Database
> Super simple SQL database built for a trillion values. Plain SQL from the first row to the last — embedded in your app or on a server.
---
Source: https://coordinatordb.com/docs
Language: en
# CoordinatorDB documentation
CoordinatorDB provides relational SQL, transactions and checked native value types through embedded, native TCP and HTTP interfaces.
## Start using CoordinatorDB
[Get started](https://coordinatordb.com/docs/get-started) explains how to install CoordinatorDB, start a server and connect. The quickstarts create a table, load rows and run queries with complete examples.
## Learn the concepts
[Concepts](https://coordinatordb.com/docs/concepts) describes connection state, namespaces, data operations, configuration and authentication. Use it to understand which settings persist and which choices apply to one request.
## Complete a task
[Guides](https://coordinatordb.com/docs/guides/clickhouse) covers formats, modelling, arrays, joins and query observation with worked SQL.
## Look up a contract
The [reference](https://coordinatordb.com/docs/reference/home) lists supported statements, types, functions, formats, settings, system relations and error identifiers. Its syntax and examples describe CoordinatorDB's implemented public behavior.
---
Source: https://coordinatordb.com/docs/concepts
Language: en
# Concepts
Concepts explain the scopes and behavior behind public SQL operations: how connections retain state, where settings apply, how data is changed and how clients authenticate.
Start with the core terms, then choose an interface or operation. Practical-choice guides connect those contracts to schema and input decisions.
::: cards
* [Practical choices](https://coordinatordb.com/docs/concepts/best-practices)
* [Core concepts](https://coordinatordb.com/docs/concepts/core-concepts)
* [Features](https://coordinatordb.com/docs/concepts/features)
:::
---
Source: https://coordinatordb.com/docs/concepts/best-practices
Language: en
# Practical choices
These guides help choose value contracts and input paths for an application. Start with the data the application must accept, then verify the exact SQL behavior in the reference.
## Guides
* [Choose a primary key](https://coordinatordb.com/docs/concepts/best-practices/choosing-a-primary-key)
* [Choose JSON declarations](https://coordinatordb.com/docs/concepts/best-practices/json-type)
* [Choose a data type](https://coordinatordb.com/docs/concepts/best-practices/select-data-type)
* [Choose an insert method](https://coordinatordb.com/docs/concepts/best-practices/selecting-an-insert-strategy)
* [Check joins](https://coordinatordb.com/docs/concepts/best-practices/minimize-optimize-joins)
---
Source: https://coordinatordb.com/docs/concepts/best-practices/choosing-a-primary-key
Language: en
# Choose a primary key
A primary key identifies a row. Choose values that remain stable when other row fields change, and make additional business identifiers UNIQUE when they also need duplicate protection.
## Ordinary integer identity
In an ordinary rowid table, a column declared exactly `INTEGER PRIMARY KEY` aliases the row identifier. Other native integer declarations, such as `UInt64 PRIMARY KEY`, do not have that alias contract.
Use UNIQUE constraints or unique indexes for additional keys. These constraints enforce uniqueness; a ClickHouse sorting-key or sparse-index contract does not apply.
## Compound identity
A table-level PRIMARY KEY can contain several columns. A WITHOUT ROWID table uses that declared key as its row identity:
```sql
CREATE TABLE readings
(
sensor UInt32,
day Date32,
value Float64,
PRIMARY KEY(sensor, day)
) WITHOUT ROWID;
INSERT INTO readings VALUES (7, '2025-03-05', 12.5);
```
```sql
SELECT sensor, day, value
FROM readings
FORMAT csv;
```
```text
7,"2025-03-05",12.5
```
This key allows one reading per sensor and day. Declare explicit NOT NULL constraints where the row's identity must never be missing under ordinary table nullability rules.
See [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) and [`CREATE INDEX`](https://coordinatordb.com/docs/reference/statements/create/create-index).
---
Source: https://coordinatordb.com/docs/concepts/best-practices/json-type
Language: en
# Choose JSON declarations
Use plain JSON when any validated JSON document is acceptable. It can hold an object, array or scalar.
Use `JSON(path Type, ...)` when selected fields need declared types and dotted projection. This form requires an object and retains members that were not declared as typed paths.
## Defaults and missing paths
A missing or explicit-null typed path receives the type's default. For a number this is usually zero; Nullable paths remain NULL. Choose Nullable when the distinction between missing and zero matters.
Paths are case-sensitive and cannot duplicate or overlap a declared parent. A scalar parent where an object is required is rejected.
## Example
```sql
CREATE TABLE documents(doc JSON(id UInt64, comment Nullable(String)));
INSERT INTO documents VALUES ('{"id":7}');
```
```sql
SELECT doc.id, doc.comment
FROM documents
FORMAT csv;
```
```text
7,\N
```
The id has a native integer contract, while an absent comment remains missing. See [JSON](https://coordinatordb.com/docs/reference/data-types/json) for nested typed paths and [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) for document operations.
---
Source: https://coordinatordb.com/docs/concepts/best-practices/minimize-optimize-joins
Language: en
# Check joins
A join can return more rows than either input because every matching pair contributes. Check that this is the relationship the query intends before comparing its performance.
## State the relationship
Use ON or USING to name the matching keys. Qualify ambiguous columns and select the fields the result actually needs. A NATURAL join depends on every shared name, so a schema change can change its condition.
When one row is expected per key, enforce or verify uniqueness on that side. LEFT, RIGHT and FULL joins retain unmatched rows with NULL fields.
## Example
Two matches on the right produce two joined rows for id 1:
```sql
CREATE TABLE accounts (id INTEGER);
INSERT INTO accounts VALUES (1), (2);
CREATE TABLE visits (id INTEGER);
INSERT INTO visits VALUES (1), (1);
```
```sql
SELECT accounts.id, count(visits.id) AS matching_visits
FROM accounts
LEFT JOIN visits USING (id)
GROUP BY accounts.id
ORDER BY accounts.id
FORMAT csv;
```
```text
1,2
2,0
```
## Compare a change
Verify the selected rows and counts before comparing EXPLAIN QUERY PLAN and timings after a rewrite or index change. Use the same data and query parameters. No specific join algorithm or speedup is guaranteed by the SQL spelling.
See the [join guide](https://coordinatordb.com/docs/guides/clickhouse/working-with-joins) and [`JOIN` reference](https://coordinatordb.com/docs/reference/statements/select/join).
---
Source: https://coordinatordb.com/docs/concepts/best-practices/select-data-type
Language: en
# Choose a data type
Choose a type by its value contract: which values must fit, whether decimal digits must remain exact, and which operations the application will perform.
## Numbers
Choose an integer width that covers the full required range, including future values. Unsigned declarations reject negatives. Use Decimal for exact fixed-point amounts and Float32/Float64 for approximate measurements.
`NUMERIC` is Decimal, defaulting to `Decimal(10, 0)`. Use `LEGACY_NUMERIC` when SQLite numeric affinity is intended.
## Dates and text
Date and Date32 represent calendar days. DateTime and DateTime64 represent instants with a timezone and chosen precision. Time and Time64 represent signed seconds without a calendar date.
String stores UTF-8 text. VARCHAR(n) limits Unicode characters, while FixedString(n) requires a byte width and pads short input with zeros.
## Structured values
Use Array for an ordered list, a named Tuple for a fixed record, and Map for ordered key/value pairs. Use JSON when the document itself is the value; add typed JSON paths for fields that need a native contract.
Top-level SQL columns allow NULL unless NOT NULL is declared. Inside a typed collection, use Nullable(T) for a missing member.
## Example
```sql
CREATE TABLE products
(
id UInt32 PRIMARY KEY,
name VARCHAR(80) NOT NULL,
price Decimal(18, 2),
tags Array(String)
);
```
The declarations express different rules: identity range, text length, exact price scale and typed list members. See the [data type reference](https://coordinatordb.com/docs/reference/data-types) for limits, conversions and errors.
---
Source: https://coordinatordb.com/docs/concepts/best-practices/selecting-an-insert-strategy
Language: en
# Choose an insert method
Choose the input path according to where the rows already exist and which representation preserves their types and missing values.
## Input paths
| Source | Method |
| ------------------------------ | --------------------------------------------------------------------------- |
| Explicit values in SQL | `INSERT ... VALUES`. |
| A query of existing data | `INSERT ... SELECT`. |
| A native client's input stream | Attached `INSERT ... FORMAT` data on stdin. |
| Files on the client machine | Native client `FROM INFILE`, including supported compressed file patterns. |
| An HTTP upload | INSERT SQL in the `query` URL parameter, input bytes in the body. |
| Files available to the server | `file()` under `user_files_path`, with an explicit schema for most formats. |
## Format choice
Choose a format that supports input and can preserve the value types you need. Plain CSV uses field order; names-header variants can name fields. JSON row objects use `json_each_row` in CoordinatorDB.
All paths validate destination declarations and constraints. No asynchronous INSERT queue is provided: success follows statement completion. Use a transaction to group several related statements.
See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into), [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and the [format guide](https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro).
---
Source: https://coordinatordb.com/docs/concepts/core-concepts
Language: en
# Core concepts
CoordinatorDB distinguishes a database, a connection, a namespace and a request. These scopes determine which state is shared and how names are resolved.
A managed database can serve several clients. A native connection retains its selected database and transaction; an HTTP request creates an independent session. Within either session, `main` and `temp` are namespaces rather than managed database names.
Read the [glossary](https://coordinatordb.com/docs/concepts/core-concepts/glossary) for the public terms, [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) for connection lifetime and file sharing, and [settings](https://coordinatordb.com/docs/concepts/features/configuration/settings/overview) for server, database and statement scope.
---
Source: https://coordinatordb.com/docs/concepts/core-concepts/glossary
Language: en
# Glossary
## Database
A named server database, or a file-backed or in-memory database opened by an embedded application. A native session selects a managed database with USE.
## Connection and session
A connection owns SQL and transaction state. A native session lasts for the connection; an HTTP session lasts for one request. Temporary objects and uncommitted changes belong to that scope.
## Namespace
A connection's `main`, `temp` or attached database name. A namespace qualifies a table within a connection. It is distinct from managed server database selection.
## Statement and request
A statement is one parsed SQL operation. A request can contain several statements and has one query ID. Request limits can span all of those statements.
## Format
A named encoding that writes result rows, reads INSERT rows, or both. CoordinatorDB format names use snake_case. Each format documents its supported directions and options.
## Database setting and format setting
A database setting is stored with the database and managed by SET or its documented alternative. A format setting applies to one statement through SETTINGS and is not persisted.
## System catalog
The server's `system` relations expose database metadata, settings, functions, formats, active requests and history. Qualify them with `system.`.
## Query log and diagnostic log
The query log is structured request history available as `system.query_log`. The diagnostic log contains service messages and errors. These are separate interfaces with different fields and uses.
---
Source: https://coordinatordb.com/docs/concepts/core-concepts/query-parallelism
Language: en
# Query Parallelism
CoordinatorDB can use several threads for eligible large scan aggregates.
`max_threads` sets a ceiling on the total number of threads used by one query.
It does not guarantee that a query uses the entire allowance.
## Controlling query parallelism
Choose the limit for the workload:
* `1` requests serial execution.
* `0`, the default, selects the available hardware count capped at eight total
query threads.
* An explicit value from `2` through `64` allows that many total query threads,
subject to available hardware and the configured server ceiling.
The count includes the query's main thread. Some query shapes remain serial,
and a small input may not benefit from additional threads. Compare results on
the actual workload before choosing a larger value.
On the server, select a database and change its persisted default with `SET`:
```sql
SET max_threads = 1;
```
```sql
SELECT name, value FROM system.settings WHERE name = 'max_threads' FORMAT csv;
```
```text
"max_threads","1"
```
The change requires autocommit and no active transactions in that database.
Other clients observe the committed setting before later requests. Resource
limits are sampled once per request, so changing the value inside a batch affects
later requests.
An embedded connection uses `PRAGMA max_threads = value`. See the
[`max_threads` reference](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads).
## Monitoring query parallelism
Read [`system.processes`](https://coordinatordb.com/docs/reference/system-tables/processes) while another
connection runs the workload:
```sql
SELECT query_id, query, peak_threads_usage, memory_usage
FROM system.processes
ORDER BY query_id
FORMAT csv;
```
`peak_threads_usage` reports the largest total thread count observed for an
active request. Serial execution reports one. The rows depend on the requests
currently running; the observing query can appear in its own result.
Use [`system.query_log`](https://coordinatordb.com/docs/reference/system-tables/query-log) to compare completed
requests and their duration, row counts, and memory use. That table does not
contain `peak_threads_usage`.
---
Source: https://coordinatordb.com/docs/concepts/features
Language: en
# Features
These guides describe the supported interfaces and operational behavior of CoordinatorDB. They cover configuration, request limits, data changes, transaction scope and query observation.
For exact SQL grammar, format layouts and setting defaults, follow the linked reference pages.
## Feature guides
* [Database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview)
* [Configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files)
* [Server ceilings](https://coordinatordb.com/docs/concepts/features/configuration/settings/constraints-on-settings)
* [Settings](https://coordinatordb.com/docs/concepts/features/configuration/settings/overview)
* [Request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity)
* [Admission limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/server-overload)
* [Statement settings](https://coordinatordb.com/docs/concepts/features/configuration/settings/settings-query-level)
* [Connection limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/tcp-connection-limits)
* [Interfaces](https://coordinatordb.com/docs/concepts/features/interfaces/overview)
* [Deleting rows](https://coordinatordb.com/docs/concepts/features/operations/delete)
* [Delete data](https://coordinatordb.com/docs/concepts/features/operations/delete/overview)
* [Batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts)
* [Insert data](https://coordinatordb.com/docs/concepts/features/operations/insert/inserting-data)
* [Transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions)
* [Joining tables](https://coordinatordb.com/docs/concepts/features/operations/select/joining-tables)
* [Updating rows](https://coordinatordb.com/docs/concepts/features/operations/update)
* [Update data](https://coordinatordb.com/docs/concepts/features/operations/update/overview)
* [Query observation](https://coordinatordb.com/docs/concepts/features/performance)
* [Authentication and network access](https://coordinatordb.com/docs/concepts/features/security)
---
Source: https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk
Language: en
# Local database copy
This procedure creates an independent local copy with VACUUM INTO. The source must use UTF-8 and contain no WITHOUT ROWID user tables.
## Create the copy
1. Finish the current connection's open transaction.
2. Choose an absent or empty destination path.
3. Run VACUUM INTO from the source connection.
```text
VACUUM INTO '/tmp/coordinator-copy.db';
```
The command copies `main`. Native CoordinatorDB values remain native in the result.
## Open the copy
Stop any process using the destination before reopening it. Start a separate CoordinatorDB instance with `--db` pointing to the copy and its own native and HTTP listener addresses.
Use independent database files for separate processes. Simultaneous access to one file from different processes is unsupported.
See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview) for command restrictions and [server configuration](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for address and path overrides.
---
Source: https://coordinatordb.com/docs/concepts/features/backup-restore/overview
Language: en
# Database copies
VACUUM INTO writes a database copy to another path. Use it instead of copying only a database file that is actively in use.
## Syntax
```text
VACUUM INTO '/path/to/copy.db';
```
The destination must be absent or empty. Run the command outside an open transaction. The copy reads `main`, even when a schema qualifier is present.
## Current limits
The source must use UTF-8 storage and must not contain WITHOUT ROWID user tables. Native values require CoordinatorDB when the copy is opened. Plain VACUUM performs no work.
Separate processes can use independent copies. They must not open the same database file simultaneously.
## Procedure
See [Local database copy](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk) for the steps to reopen a copy with separate listeners. BACKUP/RESTORE commands, scheduled backups and object-storage backup targets are not supported.
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files
Language: en
# Configuration files
The server reads an existing XML configuration with one `coordinator` root and a required logger section. It applies the file at startup; edits require a restart.
## Configuration path
Without `--config-file`, the server finds `config.xml` beside the executable. A relative explicit path starts at the working directory. `--db` selects a database file independently and does not change where configuration is found.
The server does not generate or rewrite these files.
## Server example
```xml
127.0.0.1
7400
7401
users.xml
information
server.log
server.err.log
10M
3
```
## Users example
Create `users.xml` in the configuration directory:
```xml
```
## Start the server
```sh
./coordinator serve --config-file config.xml --db data.db
```
## Paths and validation
Relative users and log paths start at the configuration directory, independently of `--db`. Unknown or duplicate elements, attributes, namespaces, invalid numbers and missing required sections are configuration errors.
Comments, CDATA and standard XML entities are accepted. DTD declarations are rejected.
## Credentials
A user has exactly one `password` or `password_sha256_hex` field. The latter contains a 64-character SHA-256 digest. An optional `api_key_sha256_hex` associates an HTTP Bearer key with the same user.
Usernames are case-sensitive identifiers. Duplicate users and shared API-key digests are rejected. Password and API-key changes require a restart.
[Server settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings)
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/constraints-on-settings
Language: en
# Server ceilings
Server resource settings constrain saved database resource settings. For time, memory, result rows and response bytes, a request uses the stricter nonzero limit.
Zero means no added ceiling at that scope; it does not disable a nonzero ceiling from the other scope.
## Example
With XML `max_result_rows` set to 1000:
| Saved database value | Effective maximum |
| -------------------- | ----------------- |
| `0` | 1000 rows. |
| `5000` | 1000 rows. |
| `100` | 100 rows. |
`system.settings` and SHOW SETTINGS expose the effective value. The saved value remains available in `main.settings`.
## Changing a ceiling
XML changes require a restart and do not rewrite stored database values. Lowering the server ceiling can therefore change the effective setting while leaving its saved value unchanged.
This mechanism is distinct from per-user profiles or permissions, which are not implemented. See [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) and the [settings reference](https://coordinatordb.com/docs/reference/settings/session-settings).
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/overview
Language: en
# Settings
Settings apply at three scopes. Choose the scope according to whether a value should configure the service, persist with a database or affect one format operation.
## Scopes
| Scope | Interface | Lifetime |
| ---------------- | ---------------------------------------- | ----------------------------------------------------------------------- |
| Server | XML configuration | Applied at startup; changes require restart. |
| Database | SET or a documented PRAGMA/catalog write | Persisted with the selected database and applied before later requests. |
| Format statement | SETTINGS clause | Applies only to that statement. |
`foreign_keys`, `recursive_triggers`, `user_version` and `application_id` use PRAGMA or validated `system.settings` writes rather than SET.
Database management changes require autocommit and no active transactions in the selected database. Resource limits are sampled once per request, so a SET within a batch changes defaults for later requests.
## Inspecting values
SHOW SETTINGS and `system.settings` report effective database values and read-only format defaults. Server-only XML options are not listed there. Read `main.settings` when the stored database value is required instead of its effective value.
## Ceilings
A nonzero server resource limit is a ceiling. A larger saved database value, or a saved zero meaning no database limit, cannot bypass it. A smaller nonzero database value tightens the ceiling.
See [database settings](https://coordinatordb.com/docs/reference/settings/session-settings), [format settings](https://coordinatordb.com/docs/reference/settings/formats) and [server ceilings](https://coordinatordb.com/docs/concepts/features/configuration/settings/constraints-on-settings).
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity
Language: en
# Request limits
Request limits bound one SQL request, including its statements. Configure a server ceiling in XML or save a tighter value for the selected database with SET.
## Limits
| Setting | Unit |
| -------------------- | --------------------------------------------------------------------- |
| `max_execution_time` | Seconds. |
| `max_memory_usage` | Bytes of accounted query memory. |
| `max_result_rows` | Returned rows accumulated across the request. |
| `max_response_bytes` | Encoded successful response bytes, including logical protocol fields. |
All default to zero, meaning no added ceiling at that level. The stricter nonzero server and database values apply.
## Results and errors
Returned rows include the result-bearing statements covered by the request contract. Response-byte limits count encoded output and protocol fields, rather than only cell values. The protocol independently caps a response at 16 MiB.
Exceeding a limit returns a database error. Transaction recovery commands remain available so the client can finish or roll back its transaction.
Use [`system.settings`](https://coordinatordb.com/docs/reference/system-tables/settings) to inspect effective values and [`system.query_log`](https://coordinatordb.com/docs/reference/system-tables/query-log) for completed request metrics. See the [database settings reference](https://coordinatordb.com/docs/reference/settings/session-settings) for each setting's exact accounting scope.
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/server-overload
Language: en
# Admission limits
Admission limits bound how many connections and how much incoming request data the service accepts. Native TCP and HTTP share `max_connections` and `max_inflight_request_bytes`.
A request that exceeds admission is refused before its SQL executes. HTTP reports admission failures with status 503. These failures are separate from time, memory or result limits encountered while executing SQL.
## Uploads
A supported attached input upload has no total input-size ceiling. Its retained receive buffers still count toward admission, and receive timeouts still apply. A large upload does not bypass the service's connection or buffer limits.
## Diagnosis
Use the response error, request identifier and diagnostic log to distinguish admission failures from SQL execution errors. Inspect the configured connection and incoming-byte limits before changing them.
See [connection limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/tcp-connection-limits), [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) and the [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/settings-query-level
Language: en
# Statement settings
A SETTINGS clause changes data-format behavior for one statement. It can choose a CSV delimiter, a JSON output policy or another option supported by the selected format.
These options are not persisted. Use SET for supported database settings such as request resource limits; those names do not belong in a format SETTINGS clause.
## Output example
```sql
SELECT 7 AS id, 'Ada' AS name
SETTINGS csv_separator = ';'
FORMAT csv;
```
```text
7;"Ada"
```
Output statements also accept format settings after the FORMAT name. Each format page lists the options relevant to its codec.
## Input placement
On INSERT, SETTINGS must precede FORMAT. The request bytes after the format name are input data, so a later settings clause would be interpreted as data rather than SQL.
```text
INSERT INTO people
SETTINGS csv_separator = ';'
FORMAT csv
7;Ada
```
See [format settings](https://coordinatordb.com/docs/reference/settings/formats) and [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into).
---
Source: https://coordinatordb.com/docs/concepts/features/configuration/settings/tcp-connection-limits
Language: en
# Connection limits
Connection limits are server-only XML options shared by native TCP and HTTP. Database SET and SHOW SETTINGS do not manage or list them.
## Defaults
| Setting | Default | Contract |
| ---------------------------- | ---------- | --------------------------------------------------------- |
| `max_connections` | 128 | Positive concurrent connection limit. |
| `max_inflight_request_bytes` | 67,108,864 | Positive limit on admitted incoming request bytes. |
| `request_read_timeout` | 5 seconds | Positive socket timeout; fractional seconds are accepted. |
## Native request timing
A native login must complete within the receive timeout. After authentication, an idle session can wait between requests: the next ordinary request deadline starts when its first byte arrives.
Occasional additional bytes do not restart that ordinary request deadline. Socket writes also use the configured timeout.
## HTTP and uploads
HTTP bounds complete headers and ordinary bodies, and each upload body frame. Upload support does not remove header or timeout limits.
See [admission limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/server-overload), [native TCP](https://coordinatordb.com/docs/concepts/features/interfaces/tcp) and [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) for the resulting client behavior.
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/cli
Language: en
# Command-line interface
The `coordinator` executable contains the server and its native client. Use a subcommand to choose the mode.
## Syntax
```text
coordinator serve [--addr HOST:PORT] [--http-addr HOST:PORT]
[--db PATH] [--config-file PATH]
coordinator --config-file=PATH [--addr HOST:PORT]
[--http-addr HOST:PORT] [--db PATH]
coordinator client [--addr HOST:PORT] [--user NAME]
[--password VALUE] [--database NAME] [--query SQL]
```
`--help` displays the available options. Configuration and credentials files must already exist before server startup.
## Server paths and addresses
`--addr` overrides the native listener host and port together. `--http-addr` controls HTTP independently. `--db` selects a database file and does not change where the default configuration is found.
Without an explicit configuration path, the server looks beside the executable. A relative `--config-file` argument starts at the current working directory.
## Client use
Omit `--query` for an interactive session. Supply it for one request that writes exact result bytes to stdout. The client connects to CoordinatorDB's native protocol rather than a ClickHouse or PostgreSQL protocol.
See [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [installation](https://coordinatordb.com/docs/get-started/setup/install) and [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files).
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/client
Language: en
# Native client
The supplied native client opens an authenticated, stateful CoordinatorDB connection. Start the server, then run `./coordinator client --database data` for an interactive session.
## Connection options
`--addr HOST:PORT` overrides the default `127.0.0.1:7400`. `--user` defaults to `default`. The password comes from `--password` when supplied, otherwise `COORDINATOR_PASSWORD`, otherwise an empty string.
## Interactive SQL
Enter complete SQL and press Enter. A final semicolon is optional. Incomplete quotes and trigger bodies continue on another line; a trailing backslash also continues an otherwise complete line.
Separate statements with semicolons. Type `help` for commands and `.quit` to leave. Up/Down recalls history, and Tab completes keywords, databases, tables and columns. Piped SQL does not read or write interactive history.
## Scripted requests
```sh
./coordinator client --database data --query "SELECT 1 AS value FORMAT csv"
```
```text
1
```
`--query` runs one request and writes only result bytes to stdout, including binary output. Redirected stdin can supply attached `INSERT ... FORMAT` input. FROM INFILE reads files on the client machine.
## Session state
The connection retains database selection, temporary tables and open transactions. Closing it rolls back uncommitted changes.
See [native TCP](https://coordinatordb.com/docs/concepts/features/interfaces/tcp), [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/http
Language: en
# HTTP interface
The HTTP interface accepts authenticated SQL at `POST /` and returns a registered output format. Enable `http_port` in config.xml or pass `serve --http-addr HOST:PORT`.
## First request
`GET /ping` is an unauthenticated health check. The following commands check readiness and run SQL against the selected database:
```sh
curl --silent http://127.0.0.1:7401/ping
curl --silent --user default: --data-binary 'SELECT 1 FORMAT csv' \
'http://127.0.0.1:7401/?database=data'
```
```text
Ok.
1
```
## Authentication
Basic authentication uses the configured username and password. Bearer authentication uses a configured API key. Without Authorization, the server attempts the explicitly configured default user with an empty password. Invalid explicit credentials never fall back to that user. There is no TLS; use a trusted connection or external TLS termination.
## URL parameters
Only these parameters are accepted; duplicate parameters are errors:
| Parameter | Meaning |
| ---------------- | -------------------------------------------------------------- |
| `query` | SQL text; when present, the body supplies INSERT FORMAT input. |
| `database` | Managed database selected for this request. |
| `default_format` | Output format for statements without an explicit FORMAT. |
| `result_limit` | Result-row cap per statement, from 1 through 50,000,000. |
Without `query`, the body is SQL. A result limit caps returned rows rather than a mutation's writes. Truncation is reported with `X-Coordinator-Result-Truncated: 1`.
## Request state
Each HTTP request has its own session. To use a transaction or temporary table, send every related statement in the same request. An open transaction rolls back before the response is delivered. Bound parameters, persistent HTTP sessions, streaming responses and server-side cancellation are unsupported.
## Body and response limits
SQL bodies require Content-Length and ordinary requests are limited to 16 MiB. An attached INSERT upload with SQL in query can use Content-Length or chunked transfer without a total upload-size ceiling. Header limits and receive timeouts still apply. Responses are buffered and retain the response-byte limit.
## Status codes
Successful requests return 200. SQL errors usually return 400; authentication uses 401, origin rejection 403, receive timeout 408, missing Content-Length 411, oversize ordinary requests 413, server I/O/internal errors 500, and admission/locking failures 503. Unknown paths use 404; unsupported methods use 405.
## Response metadata
Response headers include X-Coordinator-Query-Id, X-Coordinator-Database and X-Coordinator-Summary. Errors also have X-Coordinator-Exception-Code. The summary contains result_rows, elapsed_ms, read_rows, read_bytes, written_rows, written_bytes, memory_usage and peak_memory_usage. Content-Type follows the selected format; mixed results use text/plain.
## Browser access
Browser requests must have matching Origin and Host. Empty-password users are restricted to IP hosts or localhost. CORS headers are not emitted. Passwords and keys are not accepted in URL parameters.
[Formats](https://coordinatordb.com/docs/reference/formats) · [Query log](https://coordinatordb.com/docs/reference/system-tables/query-log)
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/native-clients-interfaces-index
Language: en
# Client interfaces
Use the supplied CoordinatorDB client for native access, or send SQL to the HTTP interface and select a registered result format. Third-party ClickHouse and PostgreSQL wire clients are not supported.
## Choose an interface
* [Command-line interface](https://coordinatordb.com/docs/concepts/features/interfaces/cli) describes server and client arguments.
* [Native client](https://coordinatordb.com/docs/concepts/features/interfaces/client) provides interactive state and scripted input/output.
* [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) accepts independent authenticated requests.
* [SQL console](https://coordinatordb.com/docs/concepts/features/interfaces/sql-console) runs queries in the browser.
* [Native TCP](https://coordinatordb.com/docs/concepts/features/interfaces/tcp) defines connection state and transport limits.
* [Browser workspace](https://coordinatordb.com/docs/concepts/features/interfaces/web-sql) organizes connections, tabs and table pages.
* [Notebooks](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-notebook) combine SQL cells and Markdown.
See [interface overview](https://coordinatordb.com/docs/concepts/features/interfaces/overview) for state scope and related format/schema guides.
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/overview
Language: en
# Interfaces
CoordinatorDB exposes native TCP and optional HTTP. The Playground is a browser client of that HTTP interface.
## State scope
A native connection retains its database selection, transaction and temporary tables. Each HTTP request creates a separate logical session. Browser tabs and notebook cells therefore do not share an open transaction merely because they use the same connection profile.
An embedded application opens the Connection API directly; it receives typed values and does not use the server's output formats or management commands.
## Interface guides
* [Command-line interface](https://coordinatordb.com/docs/concepts/features/interfaces/cli)
* [Native client](https://coordinatordb.com/docs/concepts/features/interfaces/client)
* [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http)
* [Native TCP](https://coordinatordb.com/docs/concepts/features/interfaces/tcp)
* [Client interfaces](https://coordinatordb.com/docs/concepts/features/interfaces/native-clients-interfaces-index)
* [SQL console](https://coordinatordb.com/docs/concepts/features/interfaces/sql-console)
* [Browser workspace](https://coordinatordb.com/docs/concepts/features/interfaces/web-sql)
* [Notebooks](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-notebook)
* [Result views](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-result-shaping)
* [File schemas](https://coordinatordb.com/docs/concepts/features/interfaces/schema-inference)
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) for embedded access and the supported file-sharing scope.
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/schema-inference
Language: en
# File schemas
An input format describes bytes; the target schema determines how those bytes become typed SQL values. Create an explicit destination table for INSERT FORMAT.
Most server `file()` sources also require a third argument containing a column/type list, including CSV, JSON, Arrow, Parquet and Avro. A container's stored schema does not replace this requirement in CoordinatorDB.
## Sources with column metadata
Two formats can provide file-source columns without the schema argument:
* `form` infers String columns from its field names. Empty input needs an explicit schema.
* `parquet_metadata` exposes a fixed schema describing the file footer.
Form keys are literal field names; its values are URL-decoded. An explicit supplied schema follows ordinary conversions and cannot contain column constraints or DEFAULT expressions.
## Examples
```text
SELECT * FROM file('people.csv', csv, 'id UInt64, name String');
SELECT * FROM file('fields.form', form);
SELECT num_rows FROM file('sample.parquet', parquet_metadata);
```
The files must exist under the configured server file root. See [`file`](https://coordinatordb.com/docs/reference/functions/table-functions/file), [form](https://coordinatordb.com/docs/reference/formats/form) and [Parquet metadata](https://coordinatordb.com/docs/reference/formats/parquet/parquet-metadata).
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/sql-console
Language: en
# SQL console
The Query Console is the Playground's SQL editor. Enable HTTP and open `http://127.0.0.1:7401/playground`, then choose Query Console from the home page.
## Run a query
1. Choose a connection profile.
2. Select a database in the explorer.
3. Enter SQL and choose Run.
4. Inspect the result table or output view.
For a first request, use:
```sql
SELECT 1 AS connected, upper('hello') AS message
FORMAT csv;
```
```text
1,"HELLO"
```
## Inspect and export
Format adjusts the SQL text. Explain displays the server's query plan. Result controls can copy or export loaded rows and display a chart; search and filters change the loaded view rather than rerun SQL.
Aborting browser waiting does not cancel a running server query. Each run uses a separate HTTP session, so put related transaction statements in one request.
## Workspace state
Tabs, profiles and history persist in this browser. A fresh workspace tries the configured default user with an empty password; use Connections for Basic or Bearer credentials.
See [browser workspace](https://coordinatordb.com/docs/concepts/features/interfaces/web-sql), [result views](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-result-shaping) and [HTTP behavior](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/tcp
Language: en
# Native TCP interface
The native interface provides a stateful CoordinatorDB connection. Its default listener is `127.0.0.1:7400`.
Use the supplied client. ClickHouse, PostgreSQL and SQLite wire clients are not compatible with the native protocol.
## Authentication and state
Every connection authenticates a configured username and password before SQL is accepted. It retains the selected database, transaction state and temporary objects until disconnection.
The native API can also carry positional values beside the SQL text. Those values are excluded from the logged SQL text.
## Transport and limits
Native transport has no TLS. Use trusted connectivity or an external secure tunnel for credentials in transit.
Ordinary SQL/control requests and responses are limited to 16 MiB. Client stdin and INFILE uploads have no total input-size ceiling; admission, response and request-processing limits still apply.
## Client
Use [the native client](https://coordinatordb.com/docs/concepts/features/interfaces/client) for interactive SQL, exact-byte output and file input. See [network settings](https://coordinatordb.com/docs/concepts/features/security/network-ports) for listener overrides and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) for connection lifetime.
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/web-sql
Language: en
# Browser SQL workspace
The Playground is available at `/playground` on an enabled HTTP listener. Its home page links to the Query Console, notebooks and dashboards.
## Connections
A fresh workspace tries the explicitly configured default user with an empty password. Add a Basic or Bearer profile through Connections when other credentials are required.
Connection profiles, including credentials, persist in this browser's localStorage. Open another server's own Playground to connect there; remote cross-origin connections are unsupported.
## Query and table pages
The explorer lists databases, tables and columns. Double-click a table to open its page. Table actions include querying and deletion; deletion asks for the qualified table name.
SQL tabs provide Run, Format and Explain. Results can be viewed, copied, exported or charted. Browser-side filtering operates on loaded rows and does not change the SQL request.
## Notebooks and saved state
Notebooks combine SQL and Markdown cells. Dashboards present queries and charts. Profiles, tabs, history, notebooks and dashboards persist locally in this browser.
Saved-query navigation and saving are temporarily disabled. Stopping browser waiting does not cancel execution on the server.
See [SQL console](https://coordinatordb.com/docs/concepts/features/interfaces/sql-console), [notebooks](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-notebook), [result views](https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-result-shaping) and [HTTP request behavior](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-notebook
Language: en
# SQL and Markdown notebooks
A Playground notebook combines executable SQL cells with Markdown notes. Each SQL cell is an independent HTTP request using the selected connection.
## Create and run cells
1. Open Playground and choose New notebook.
2. Add SQL or Markdown cells and choose a connection.
3. Run a SQL cell with Shift+Enter or use Run All.
4. Reorder, duplicate or remove cells with their controls.
Run All executes nonempty SQL cells in order. It skips Markdown and blank SQL cells and continues after errors. Cells do not share a transaction or temporary table; put related statements together in one SQL cell.
## Parameters
Use `$name` or `${name}` in SQL and define Number or Text fields. Substitution ignores quoted SQL, comments and inline format data. An unset value or invalid numeric input blocks execution.
Notebook text and parameter values persist in the browser along with workspace state.
## Stop waiting
Stop waiting ends browser waiting and discards the remaining queued cells. It does not cancel the current query on the server.
See [browser workspace](https://coordinatordb.com/docs/concepts/features/interfaces/web-sql) and [HTTP sessions](https://coordinatordb.com/docs/concepts/features/interfaces/http#request-state) for state lifetime.
---
Source: https://coordinatordb.com/docs/concepts/features/interfaces/web-ui-result-shaping
Language: en
# Shape result views
Playground result controls change how loaded rows are viewed. They do not rewrite the SQL or send another request. Use WHERE, ORDER BY or LIMIT in SQL when the server should perform those operations.
## Inspect rows
1. Open a column's filter icon and choose an operator and value.
2. Use a column menu for ascending or descending sorting.
3. Select cells to copy, or use Copy all rows with no selection.
4. Export the current filtered and sorted result.
Filters on different columns combine with AND. Search also applies to the loaded rows. Reset filters & sorting clears search as well.
## Pages and exports
Console and table Data views show 100-row pages when more than 100 rows match. Sorting, selection and export cover all loaded matching rows, including rows on other pages.
Export supports CSV, JSON, Excel and Parquet. Excel writes wide numbers and composite values as text to preserve their digits. Parquet uses text when a numeric encoding would lose precision.
Column statistics and Columns display result statistics and types. Maximum rows per result in Settings applies to later requests; it is separate from filtering rows already loaded.
See [SQL console](https://coordinatordb.com/docs/concepts/features/interfaces/sql-console) and [HTTP result limits](https://coordinatordb.com/docs/concepts/features/interfaces/http#url-parameters).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/delete
Language: en
# Deleting rows
Choose DELETE to remove rows while retaining a table, and DROP TABLE to remove its definition as well. The scope of the WHERE condition determines which rows a DELETE removes.
Read [Delete data](https://coordinatordb.com/docs/concepts/features/operations/delete/overview) for RETURNING and transaction behavior.
---
Source: https://coordinatordb.com/docs/concepts/features/operations/delete/overview
Language: en
# Delete data
DELETE removes rows satisfying its WHERE condition. Without WHERE, it removes every row but keeps the table definition. DROP TABLE removes the table itself.
Changes complete synchronously and use ordinary transaction rules. Foreign-key actions apply when enabled. TTL, partition drops and background deletion queues are not provided.
## Example
```sql
CREATE TABLE tasks(id INTEGER PRIMARY KEY, completed Bool);
INSERT INTO tasks VALUES (1, true), (2, false);
```
```sql
DELETE FROM tasks
WHERE completed
RETURNING id
FORMAT csv;
```
```text
1
```
```sql
SELECT id
FROM tasks
FORMAT csv;
```
```text
2
```
RETURNING reads deleted values. Use a transaction when the deletion must commit or roll back together with other changes.
See the [`DELETE` reference](https://coordinatordb.com/docs/reference/statements/delete), [`DROP`](https://coordinatordb.com/docs/reference/statements/drop) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts
Language: en
# Batch inserts
A batch inserts several rows together. Use one multi-row VALUES statement or one formatted input statement when the rows belong to one operation.
## Multi-row values
```sql
CREATE TABLE measurements(id UInt32, value Float64);
INSERT INTO measurements VALUES (1, 12.5), (2, 13.0), (3, 11.5);
```
```sql
SELECT count(*) AS measurements, avg(value) AS average_value
FROM measurements
FORMAT csv;
```
```text
3,12.333333333333334
```
## Files and streams
For data already encoded as CSV, JSON or a binary container, supply it with INSERT FORMAT, native stdin, FROM INFILE or an HTTP attached upload. Choose a format that supports input and preserves the intended types.
Client uploads can exceed 16 MiB in total. Ordinary SQL/control requests and responses retain their protocol limits; request-processing and admission limits still apply to uploads.
## Completion and transactions
There is no asynchronous INSERT queue. A successful response follows completion of the statement. Use one explicit transaction for several related statements that must commit together.
See [client file input](https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/insert/inserting-data
Language: en
# Insert data
INSERT adds rows through a common set of destination type and constraint checks. Choose the input path according to where the data already lives.
## Literal and query input
Use VALUES for explicit rows and INSERT SELECT to copy or transform rows produced by a query. A column list can leave other columns to their SQL defaults.
```sql
CREATE TABLE items(id INTEGER PRIMARY KEY, name String DEFAULT 'unknown');
INSERT INTO items(id) VALUES (1), (2);
```
```sql
SELECT id, name
FROM items
ORDER BY id
FORMAT csv;
```
```text
1,"unknown"
2,"unknown"
```
## Formats and files
INSERT FORMAT decodes a registered input format. The native client can send stdin or read local files with FROM INFILE, including supported compression. Every row from one file-input INSERT belongs to one statement.
For inline data, place SETTINGS before FORMAT and send later SQL in another request. HTTP can supply INSERT SQL in the query parameter and format bytes in the body.
All input paths validate target declarations and constraints. See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into), [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and the [format guide](https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/insert/transactions
Language: en
# Transactions
A transaction groups changes into one unit of commit or rollback. Statements outside an explicit transaction autocommit.
## Controls
| Statement | Effect |
| ------------------ | --------------------------------------------- |
| `BEGIN` | Start a transaction. |
| `COMMIT` | Keep its changes. |
| `ROLLBACK` | Undo its changes. |
| `SAVEPOINT name` | Create an inner undo point. |
| `ROLLBACK TO name` | Undo later changes and retain that savepoint. |
| `RELEASE name` | Remove the savepoint. |
## Example
### Undoing one adjustment
```sql
CREATE TABLE balances(id INTEGER PRIMARY KEY, amount INTEGER);
BEGIN;
INSERT INTO balances VALUES (1, 10);
SAVEPOINT adjustment;
UPDATE balances SET amount = 20;
ROLLBACK TO adjustment;
RELEASE adjustment;
COMMIT;
```
```sql
SELECT id, amount
FROM balances
FORMAT csv;
```
```text
1,10
```
The insert remains, while the adjustment after the savepoint is undone.
## Connection scope
A native connection retains its open transaction. Closing it rolls back uncommitted changes.
Every HTTP request has a separate session. Put BEGIN, the related statements and COMMIT in one request; an unclosed transaction is rolled back before the response is sent.
Several connections in one process can share a file. Simultaneous access from separate processes is outside the supported concurrency model. See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/select/joining-tables
Language: en
# Joining tables
A join relates rows from two sources. Use an explicit ON condition or a USING list to show the intended keys.
INNER JOIN returns matching pairs. LEFT, RIGHT and FULL joins also retain unmatched rows from the indicated sides and fill missing fields with NULL. CROSS JOIN creates every combination.
## Example
### Customers with optional orders
```sql
CREATE TABLE users (id INTEGER, name TEXT);
INSERT INTO users VALUES (1, 'Ada'), (2, 'Grace');
CREATE TABLE orders (user_id INTEGER, quantity INTEGER);
INSERT INTO orders VALUES (1, 2);
```
```sql
SELECT users.name, orders.quantity
FROM users
LEFT JOIN orders ON orders.user_id = users.id
ORDER BY users.id
FORMAT csv;
```
```text
"Ada",2
"Grace",\N
```
Grace is retained even without an order. A condition on the nullable order fields in WHERE can remove that unmatched row; put conditions defining eligible matches in ON when it should remain.
## Duplicate matches
A join returns every matching pair. If a key appears twice on the right, one matching left row produces two result rows. Verify counts when the keys are not unique.
See the [join guide](https://coordinatordb.com/docs/guides/clickhouse/working-with-joins) and [`JOIN` reference](https://coordinatordb.com/docs/reference/statements/select/join).
---
Source: https://coordinatordb.com/docs/concepts/features/operations/update
Language: en
# Updating rows
UPDATE changes matching rows immediately; an upsert combines insertion with a conflict-driven update. Both validate target types and constraints and follow transaction rules.
Read [Update data](https://coordinatordb.com/docs/concepts/features/operations/update/overview) for a worked example and the links to the exact statement syntax.
---
Source: https://coordinatordb.com/docs/concepts/features/operations/update/overview
Language: en
# Update data
UPDATE changes existing rows selected by WHERE. Expressions can read the old row values, so an assignment can increment or decrement a stored amount.
The resulting values are checked against declared types and constraints. Changes complete synchronously and can be grouped in a transaction.
## Example
```sql
CREATE TABLE stock(id INTEGER PRIMARY KEY, quantity INTEGER);
INSERT INTO stock VALUES (1, 5);
```
```sql
UPDATE stock
SET quantity = quantity - 1
WHERE id = 1
RETURNING id, quantity
FORMAT csv;
```
```text
1,4
```
Without WHERE, an update changes every row. RETURNING exposes the updated values.
## Upsert
Use `INSERT ... ON CONFLICT ... DO UPDATE` when the operation should insert a new row or update an existing conflicting row. This is separate from an ordinary UPDATE, which never inserts a missing row.
See [`UPDATE`](https://coordinatordb.com/docs/reference/statements/update), [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/concepts/features/performance
Language: en
# Query observation
Observe a concrete query through its plan and request metadata. Start by recording the SQL, parameters, data size and expected rows so that a later comparison describes the same task.
## Plans and execution
EXPLAIN QUERY PLAN shows the selected access path without executing the query. EXPLAIN ANALYZE executes the statement and reports measurements. An analyzed write changes data once, so use transaction controls when it should be rolled back.
## Active and finished requests
`system.processes` exposes active requests. `system.query_log` stores configured structured history. A query ID connects request information with the response and diagnostic messages.
Time, memory, result-row and response-byte settings can bound one request. Inspect effective settings when a saved value differs from a server ceiling.
See [query optimization](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization), [query history](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/diagnose-slow-queries) and [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain).
---
Source: https://coordinatordb.com/docs/concepts/features/security
Language: en
# Authentication and network access
Every native connection authenticates a configured username and password before SQL is accepted. HTTP supports Basic authentication, Bearer API keys, or the explicitly configured default user with an empty password when no Authorization header is present.
## Credentials
`users.xml` declares users and their credentials. A user has one password form and can also have one API-key digest for HTTP. Usernames are case-sensitive. Changes require a server restart.
Invalid explicit HTTP credentials do not fall back to the default user. Permissions, roles and settings profiles are not implemented.
## Transport and listeners
CoordinatorDB has no built-in TLS listener. Credentials travel without TLS, so choose trusted connectivity or an external secure transport for the intended deployment.
The listeners bind the configured host and ports. The sample uses loopback for local access. See [network ports](https://coordinatordb.com/docs/concepts/features/security/network-ports) for overrides and [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for credential examples.
---
Source: https://coordinatordb.com/docs/concepts/features/security/network-ports
Language: en
# Network ports
CoordinatorDB provides a native TCP listener and an optional HTTP listener. Both authenticate SQL access against the configured users file.
## Configuration
| Setting | Meaning |
| ------------- | ----------------------------------------------------- |
| `listen_host` | Listener host, default `127.0.0.1`. |
| `tcp_port` | Native TCP port, default `7400`. |
| `http_port` | Enables HTTP when configured; the sample uses `7401`. |
Port 0 asks the operating system to choose an available port. Startup output reports the resulting address.
`--addr HOST:PORT` overrides the native host and port together. `--http-addr HOST:PORT` independently overrides HTTP. Both listeners bind before the server announces that it is ready.
## Protocols
Use the supplied CoordinatorDB client for native TCP. No PostgreSQL, MySQL, interserver or metrics listener is provided. The HTTP listener serves SQL and the browser Playground.
There is no built-in TLS listener. See [authentication](https://coordinatordb.com/docs/concepts/features/security), [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for their public access rules.
---
Source: https://coordinatordb.com/docs/get-started
Language: en
# Get started with CoordinatorDB
This section takes you from installation to a running CoordinatorDB server and a table you can query.
## Start here
::: cards
1. [Install CoordinatorDB](https://coordinatordb.com/docs/get-started/setup/install)
2. [Create a table](https://coordinatordb.com/docs/get-started/quickstarts/creating-tables)
3. [Write queries](https://coordinatordb.com/docs/get-started/quickstarts/writing-queries)
4. [Change rows](https://coordinatordb.com/docs/get-started/quickstarts/mutations)
:::
Use the supplied native client or the browser Playground. Applications can also use HTTP or embed the `Connection` API.
## Choose an interface
Read [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) to compare server and embedded use. The [introduction](https://coordinatordb.com/docs/get-started/about/intro) describes the public SQL capabilities; the [quickstarts](https://coordinatordb.com/docs/get-started/quickstarts/home) provide independent worked examples.
---
Source: https://coordinatordb.com/docs/get-started/about/deployment-modes
Language: en
# Deployment modes
CoordinatorDB can run as a server or be opened directly by an application. Choose according to where connection state and access to the database should live.
## Server
The server manages named persistent databases and authenticates clients. It exposes native TCP and, when enabled, HTTP. Both interfaces use the same database inventory, request limits and users.
The supplied native client supports an interactive session, piped SQL, local input files and `--query` for exact result bytes. Its connection retains the selected database, transaction and temporary tables.
An HTTP SQL request owns a separate logical session. Select its database with the URL parameter or with `USE` inside the same request. The HTTP listener also provides the browser Playground.
## Embedded connection
An application opens `coordinator::Connection` with a file path or `open_in_memory()`. It executes SQL and receives typed result values directly.
The embedded API does not expose server commands such as `USE`, `SHOW` and `SET`, or server format encoders. It supports prepared statements and connection namespaces through `ATTACH` and `DETACH`.
## Sharing a file
Multiple connections in one process can share a database file. Simultaneous access to the same file from separate processes is outside the supported concurrency model. For clients in several applications, connect them to one server process.
## Related guides
* [Install and run](https://coordinatordb.com/docs/get-started/setup/install)
* [Native client](https://coordinatordb.com/docs/concepts/features/interfaces/client)
* [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http)
* [Embedded prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements)
---
Source: https://coordinatordb.com/docs/get-started/about/distinctive-features
Language: en
# Features
CoordinatorDB provides relational SQL with immediate row changes, transaction controls and checked native value types.
## SQL and constraints
Queries support joins, subqueries, recursive common table expressions, set operations, aggregates with FILTER and DISTINCT, and window frames. Tables support primary and unique keys, CHECK and NOT NULL constraints, generated columns, expression and partial indexes, and triggers.
Use [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain) to inspect a selected query plan or collect measurements from an execution.
## Typed values
Native types cover integers through 256 bits, decimals through 76 digits, dates, fractional timestamps, enums, UUIDs and network addresses. Arrays, named tuples, maps and JSON retain structured values. Aggregate states can be stored and combined explicitly.
The [type reference](https://coordinatordb.com/docs/reference/data-types) documents validation, conversions and examples.
## Data exchange
Registered formats encode query results and decode INSERT input. Native clients can supply local files or stdin; HTTP can attach input bytes; server `file()` reads confined server-side files.
Format names use snake_case. Consult the [format reference](https://coordinatordb.com/docs/reference/formats) for directions, settings and type mappings.
## Server and browser interfaces
The server provides authenticated native TCP and optional HTTP, managed database selection, persistent database settings, system relations and request history. The HTTP Playground provides SQL tabs, table pages, notebooks, dashboards and charts.
The reference describes implemented behavior. Similar names do not imply full compatibility with another database's SQL dialect, native protocol or binary state formats.
---
Source: https://coordinatordb.com/docs/get-started/about/intro
Language: en
# What is CoordinatorDB?
CoordinatorDB is a relational SQL database for storing, querying and changing structured data. Tables can enforce primary keys, uniqueness, required values and other constraints. Transactions let an application commit or roll back related changes together.
## Querying data
Use SQL to filter rows, join tables, calculate grouped totals and rank observations with window functions. Common table expressions and subqueries let a query be written in several named stages.
Native declarations include checked signed and unsigned integers, exact decimals, dates and timestamps, JSON, arrays, tuples and maps. The type reference describes the values and conversions accepted by each declaration.
## Connecting
* Run the server and connect with the supplied native client for interactive or scripted SQL.
* Enable HTTP to send authenticated queries and use the browser Playground for SQL tabs, table pages and notebooks.
* Embed the `Connection` API when the application should open a database directly.
Native connections and HTTP share the server's managed databases. The embedded API opens file-backed or in-memory databases without a server.
## First steps
[Install CoordinatorDB](https://coordinatordb.com/docs/get-started/setup/install), then [create a table](https://coordinatordb.com/docs/get-started/quickstarts/creating-tables) and [write a query](https://coordinatordb.com/docs/get-started/quickstarts/writing-queries). See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) for connection lifetime and file-sharing rules, and [features](https://coordinatordb.com/docs/get-started/about/distinctive-features) for the supported public surface.
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/creating-tables
Language: en
# Create a table
This quickstart creates a table of events with a primary key, a required text field and an exact decimal amount.
Start the server, then connect with `./coordinator client --database data`. Use a database where the sample table name is available.
## Create the table
```sql
CREATE TABLE events
(
id INTEGER PRIMARY KEY,
kind String NOT NULL,
amount Decimal(18, 2)
);
```
`INTEGER PRIMARY KEY` gives each row an integer identifier. `NOT NULL` requires a kind. `Decimal(18, 2)` retains two exact fractional digits.
## Insert rows
```sql
INSERT INTO events VALUES
(1, 'view', '1.20'),
(2, 'click', '2.40');
```
The amount strings are converted to the declared Decimal type and checked before storage.
## Read the result
```sql
SELECT id, kind, amount
FROM events
ORDER BY id
FORMAT csv;
```
```text
1,"view",1.20
2,"click",2.40
```
`ORDER BY` defines the row order. `FORMAT csv` selects a server output format; omitting it uses the default table display.
Continue with [writing queries](https://coordinatordb.com/docs/get-started/quickstarts/writing-queries), or consult [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) for constraints, defaults and generated columns.
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/home
Language: en
# Quickstarts
Each quickstart walks through one task with a small set of sample data. Start a server using the [installation guide](https://coordinatordb.com/docs/get-started/setup/install), then connect to a selected database.
Use a fresh set of table names for each guide. Execute setup statements first, followed by the query whose output is shown. Statements that create or change objects can print acknowledgements in the native client.
## Guides
* [Create a table](https://coordinatordb.com/docs/get-started/quickstarts/creating-tables): declare types, insert rows and inspect a result.
* [Insert with the native client](https://coordinatordb.com/docs/get-started/quickstarts/insert-data-using-clickhouse-client): use literal values or load a local CSV file.
* [Write queries](https://coordinatordb.com/docs/get-started/quickstarts/writing-queries): filter inputs, group rows and calculate totals.
* [Update and delete rows](https://coordinatordb.com/docs/get-started/quickstarts/mutations): change data within an explicit transaction.
* [Work with Map values](https://coordinatordb.com/docs/get-started/quickstarts/working-with-the-map-type): read, test and replace typed key/value pairs.
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/insert-data-using-clickhouse-client
Language: en
# Insert with the native client
Use the supplied `coordinator client` to insert literal rows or send rows from a local file. Its native protocol is CoordinatorDB-specific; a ClickHouse client cannot connect to it.
Start a server and open `./coordinator client --database data` before running the SQL below.
## Create a destination table
```sql
CREATE TABLE people(id UInt64, name String);
```
## Insert literal values
```sql
INSERT INTO people VALUES (1, 'Ada'), (2, 'Grace');
```
```sql
SELECT id, name
FROM people
ORDER BY id
FORMAT csv;
```
```text
1,"Ada"
2,"Grace"
```
## Load a client-side file
From a terminal in the directory containing the executable, create a CSV file and load it:
```sh
printf '3,Linus\n' > people.csv
./coordinator client --database data --query "INSERT INTO people FROM INFILE 'people.csv' FORMAT csv" > /dev/null
```
The file is read on the client machine. Relative paths use the client's working directory. Every matched file retains its own headers or container boundary during decoding.
A subsequent query of `people` includes `(3, 'Linus')`. The `UInt64` and String declarations validate file values just as they validate SQL values.
See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into) and [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) for stdin, compressed files and larger inputs.
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/mutations
Language: en
# Update and delete rows
UPDATE and DELETE change rows immediately. Use a transaction when several changes should succeed or roll back together.
This example reduces the stock of one item and removes an item that has no stock.
## Prepare sample data
```sql
CREATE TABLE stock(id INTEGER PRIMARY KEY, quantity INTEGER);
INSERT INTO stock VALUES (1, 5), (2, 0);
```
## Change matching rows
```sql
BEGIN;
UPDATE stock SET quantity = quantity - 1 WHERE id = 1;
DELETE FROM stock WHERE quantity = 0;
COMMIT;
```
`WHERE` determines which rows change. Omitting it would update or delete every row. `COMMIT` keeps the transaction's changes; use `ROLLBACK` instead to discard them.
## Verify the result
```sql
SELECT id, quantity
FROM stock
ORDER BY id
FORMAT csv;
```
```text
1,4
```
To read changed rows directly from a write, use its `RETURNING` clause. See [`UPDATE`](https://coordinatordb.com/docs/reference/statements/update), [`DELETE`](https://coordinatordb.com/docs/reference/statements/delete) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/working-with-the-map-type
Language: en
# Work with Map values
A Map stores ordered key/value pairs with declared key and value types. This quickstart stores text labels for one account.
## Create and insert a map
```sql
CREATE TABLE labels(id INTEGER PRIMARY KEY, tags Map(String, String));
INSERT INTO labels VALUES (1, map('team', 'sales', 'region', 'east'));
```
`map` takes alternating keys and values. A typed Map validates every pair. Keys cannot be NULL; duplicate keys are retained.
## Read values and test presence
```sql
SELECT map_element(tags, 'team') AS team,
map_contains(tags, 'missing') AS has_missing,
map_element(tags, 'missing') AS missing_value
FROM labels
FORMAT csv;
```
```text
"sales",false,""
```
A missing key returns the value type's default, an empty string here. `map_contains` distinguishes a missing key from a stored empty value. If a key is repeated, `map_element` returns its first matching value.
## Replace a map
```sql
UPDATE labels
SET tags = map('team', 'support', 'region', 'west')
WHERE id = 1;
```
```sql
SELECT map_element(tags, 'team'), map_keys(tags)
FROM labels
FORMAT csv;
```
```text
"support","[""team"",""region""]"
```
See the [Map reference](https://coordinatordb.com/docs/reference/data-types/map) and [map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions) for additional operations.
---
Source: https://coordinatordb.com/docs/get-started/quickstarts/writing-queries
Language: en
# Write queries
This self-contained example uses a common table expression to provide a small order dataset. It does not require a persistent sample table.
## Filter rows
`WHERE` keeps only input rows satisfying the condition:
```sql
CREATE TABLE sales (region TEXT, amount INTEGER);
INSERT INTO sales VALUES ('East', 10), ('East', 20), ('West', 5);
```
```sql
SELECT region, amount
FROM sales
WHERE amount >= 10
ORDER BY amount
FORMAT csv;
```
```text
"East",10
"East",20
```
## Group and aggregate
`GROUP BY` forms one group per region. `count` counts its rows and `sum` calculates its amount:
```sql
SELECT region, count(*) AS orders, sum(amount) AS total
FROM sales
GROUP BY region
ORDER BY total DESC, region
FORMAT csv;
```
```text
"East",2,30
"West",1,5
```
## Filter grouped results
`HAVING` filters an aggregate result after grouping:
```sql
SELECT region, sum(amount) AS total
FROM sales
GROUP BY region
HAVING sum(amount) >= 10
ORDER BY region
FORMAT csv;
```
```text
"East",30
```
Use `ORDER BY` whenever row order matters. See the [`SELECT` reference](https://coordinatordb.com/docs/reference/statements/select) for joins, windows, set operations and limits.
---
Source: https://coordinatordb.com/docs/get-started/setup/install
Language: en
# Install CoordinatorDB
Install CoordinatorDB from the latest GitHub release using a terminal with `curl` and `sh`.
## Install
Run the installer:
```sh
curl -fsSL https://github.com/coordinator-db/coordinator-db/releases/latest/download/install.sh | sh
```
## Start the server
From the directory containing the `coordinator` executable and the supplied `config.xml` and `users.xml` files, start the server:
```sh
./coordinator serve
```
The supplied users.xml explicitly configures user default with an empty password. The default native address is 127.0.0.1:7400. The supplied config.xml also enables HTTP on port 7401. The default database is data.db beside the executable.
## Verify the connection
Open another terminal in the same directory and run:
```sh
./coordinator client --database data --query "SELECT 1 AS connected FORMAT csv"
```
```text
1
```
## Configuration paths
The server requires existing `config.xml` and `users.xml` files; it does not generate them. `--config-file PATH` selects another configuration, and `--db PATH` selects another database file independently of the configuration directory.
The supplied credentials are suitable for this local example. Edit the configured users for the access you intend to provide; credentials changes require a server restart.
Continue with [creating a table](https://coordinatordb.com/docs/get-started/quickstarts/creating-tables). See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for listener, credential and path options.
---
Source: https://coordinatordb.com/docs/get-started/setup/self-managed/overview
Language: en
# Self-managed CoordinatorDB
A self-managed CoordinatorDB server runs as a local executable. It opens a persistent database and exposes authenticated native TCP and, optionally, HTTP.
## Before starting
Install the executable and prepare the supplied XML files using the [installation guide](https://coordinatordb.com/docs/get-started/setup/install). The server requires an existing configuration and credentials file.
Decide which host and ports the listeners should use, which users can connect, and where the database file should live. The sample configuration binds native TCP on `127.0.0.1:7400` and HTTP on port `7401`.
## Files and paths
`config.xml` configures the service and references its users file. `users.xml` declares explicit usernames, passwords and optional HTTP API keys. The sample `default` user has an empty password.
`--config-file PATH` selects the configuration. `--db PATH` selects the database independently of that configuration's directory. Without a database override, the default is `data.db` beside the executable.
## Clients and state
Use the supplied native client for sessions that retain transactions, temporary tables and database selection. Use HTTP for independent authenticated requests and the browser Playground.
Several applications should connect to the same server process. Do not open one database file simultaneously from separate processes.
## Configuration reference
Read [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for concrete XML examples, [network ports](https://coordinatordb.com/docs/concepts/features/security/network-ports) for address overrides, and [settings](https://coordinatordb.com/docs/reference/settings) for database settings and server ceilings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse
Language: en
# Guides
These guides complete concrete tasks with CoordinatorDB syntax and examples. They cover data exchange, schema choices, arrays and joins, partial aggregation and query observation.
Use the [reference](https://coordinatordb.com/docs/reference/home) for exact grammar, value ranges, format settings and error contracts. Each guide states the source files, tables or interface it needs.
## Guides
::: cards
* [Data formats](https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro)
* [Data modelling](https://coordinatordb.com/docs/guides/clickhouse/data-modelling)
* [Performance & monitoring](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization)
* [Aggregate combinator examples](https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-if)
:::
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/arrow-avro-orc
Language: en
# Arrow and Avro
Arrow IPC and Avro are schema-bearing interchange formats. Create explicit destination columns before importing them, then verify that their source types map to the intended CoordinatorDB declarations.
## Choose the container
* `arrow` uses an Arrow IPC file.
* `arrow_stream` uses an Arrow IPC stream.
* `avro` uses an Avro object container.
* `avro_confluent` uses schema identifiers resolved through a configured registry.
ORC is not supported.
## Import workflow
Use native FROM INFILE or attached INSERT FORMAT input. The destination declarations validate decoded values, including numeric ranges, collection members and NULL rules.
For a server file() relation, provide the explicit column/type list even when the container carries a schema. A schema registry is additionally required for the Confluent variant; an ordinary Avro container embeds its record schema.
## Type mappings and options
See [Arrow](https://coordinatordb.com/docs/reference/formats/arrow/arrow), [ArrowStream](https://coordinatordb.com/docs/reference/formats/arrow/arrow-stream), [Avro](https://coordinatordb.com/docs/reference/formats/avro/avro) and [AvroConfluent](https://coordinatordb.com/docs/reference/formats/avro/avro-confluent) for executable examples, supported types and statement settings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/binary
Language: en
# Binary file exchange
Binary formats can preserve typed values and container metadata without rendering every value as display text. Use the native client's `--query` and stdout redirection for exports, then supply the resulting bytes as input.
## Choose a representation
| Format family | Layout |
| --------------------------------- | ---------------------------------------------------- |
| `row_binary` | Positional fields using declared types. |
| `row_binary_with_names_and_types` | Field bytes plus column names and type declarations. |
| Arrow IPC | A file or stream with a schema and record batches. |
| Parquet | A columnar file with row groups and metadata. |
| Avro | An object container with a record schema. |
| `msg_pack` | Consecutive positional fields. |
A stored schema does not remove CoordinatorDB's requirement for an explicit destination table or the ordinary file() schema argument.
## Export and import
1. Query the required columns in a defined order.
2. Select an output-capable binary format and redirect exact bytes to a file.
3. Create the destination with compatible declarations.
4. Load the file through FROM INFILE or attached INSERT FORMAT input.
5. Query the destination to verify values and row counts.
Use the executable examples on the individual [format pages](https://coordinatordb.com/docs/reference/formats). CoordinatorDB aggregate-state bytes are not a portable ClickHouse format; finalize them when an interchange representation is required.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv
Language: en
# CSV and TSV
This example loads a client-side CSV file with named columns, then exports the rows as escaped tab-separated text. Start the server and run the commands where `./coordinator` is available.
## Create, import and inspect
Use a fresh destination table for this example:
```sh
printf 'id,name\n1,Ada\n2,Grace\n' > people.csv
./coordinator client --database data --query "CREATE TABLE people(id UInt64,name String)" > /dev/null
./coordinator client --database data --query "INSERT INTO people FROM INFILE 'people.csv' FORMAT csv_with_names" > /dev/null
./coordinator client --database data --query "SELECT * FROM people ORDER BY id FORMAT tab_separated"
```
```text
1 Ada
2 Grace
```
## Headers and separators
CSV names headers match target columns by default. `csv_with_names_and_types` adds a type header. Plain csv is positional, so its field order must match the selected destination columns.
Use `SETTINGS csv_separator=';'` for a different delimiter, before the INSERT FORMAT clause. Quoted CSV fields can contain delimiters and newlines; tab_separated instead uses escapes for control characters.
## Several files and compression
INFILE infers decompression from recognized suffixes such as `.gz` and `.zst`. Each matched file is decoded separately, preserving its own header. A malformed file cancels the whole INSERT.
See [CSV](https://coordinatordb.com/docs/reference/formats/csv/csv) and [TabSeparated](https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated) for NULL markers, quoting, escapes and settings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro
Language: en
# Load and export data
Data exchange has two parts: a format describes the bytes, and a table schema describes their SQL values. Create explicit target columns before importing rows.
## Choose a direction
Formats can support input, output or both. Inspect their registered directions before choosing one:
```sql
SELECT name, is_input, is_output
FROM system.formats
WHERE name IN ('csv', 'json_each_row', 'parquet', 'yaml')
ORDER BY name
FORMAT csv;
```
```text
"csv",1,1
"json_each_row",1,1
"parquet",1,1
"yaml",1,1
```
Names use snake_case and ignore ASCII case. CamelCase names are not aliases.
## Load rows
Native stdin, native FROM INFILE and HTTP attached input send data to INSERT FORMAT. FROM INFILE reads the client's files. `file()` instead reads confined regular files under the server's `user_files_path` and can be used in SELECT or INSERT SELECT.
Most file sources require an explicit column/type list. Only `form` and `parquet_metadata` can supply their own column metadata.
## Export rows
Use SELECT FORMAT to choose a result encoding. Native `--query` writes exact bytes to stdout, including binary containers. Redirect binary output to a file rather than treating it as a terminal table.
## Guides
* [CSV and TSV](https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv)
* [JSON](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/intro)
* [Binary files](https://coordinatordb.com/docs/guides/clickhouse/data-formats/binary)
* [Arrow and Avro](https://coordinatordb.com/docs/guides/clickhouse/data-formats/arrow-avro-orc)
* [Parquet](https://coordinatordb.com/docs/guides/clickhouse/data-formats/parquet)
* [SQL row exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/sql)
* [Templates and regular expressions](https://coordinatordb.com/docs/guides/clickhouse/data-formats/templates-regex)
The [format reference](https://coordinatordb.com/docs/reference/formats) defines layouts, settings and type mappings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/exporting
Language: en
# Export JSON
Choose named objects when consumers identify fields by key and positional arrays when they already know the column order. Give expressions stable aliases before writing named rows.
## Named objects
```sql
SELECT CAST('18446744073709551615' AS UInt64) AS id,
CAST('12.50' AS Decimal(18, 2)) AS amount
FORMAT json_each_row;
```
```text
{"id":18446744073709551615,"amount":12.50}
```
The digits are exact in the output. A consumer that parses every JSON number as binary floating point can still lose them; choose json_compact_each_row or json_object_each_row with the supported json_quote options when numeric strings are required. json_each_row does not apply those quoting options.
## Quoted numeric output
```sql
SELECT CAST('18446744073709551615' AS UInt64) AS id
SETTINGS json_quote_large_integers = 1
FORMAT json_compact_each_row;
```
```text
["18446744073709551615"]
```
## Positional rows
```sql
SELECT 7 AS id, 'Ada' AS name
FORMAT json_compact_each_row;
```
```text
[7, "Ada"]
```
The consumer must know that the first position is id and the second is name. Use a names-and-types variant when that metadata belongs in the stream.
## Options
JSON quoting and rendering settings belong to the statement SETTINGS clause. See [JSON settings](https://coordinatordb.com/docs/reference/formats/json/json-format-settings), [format choices](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/formats) and [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/formats
Language: en
# JSON format choices
Choose a JSON format by its outer structure and whether values retain their JSON types or become strings.
## Layouts
| Format | Shape |
| -------------------------------------------- | ----------------------------------------------------------- |
| `json_each_row` | One named object per row. |
| `json_compact_each_row` | One positional array per row. |
| `json_columns` | One object containing named column arrays. |
| `json_compact_columns` | Positional column arrays. |
| `json_strings_each_row` | Objects whose values are all JSON strings. |
| `json_compact_strings_each_row` | Positional arrays whose values are all JSON strings. |
| `json_compact_each_row_with_names_and_types` | Names and types header arrays followed by row arrays. |
| `json_compact` | One output-only document with metadata and positional data. |
The string-only variants also encode SQL NULL as the quoted marker `"ᴺᵁᴸᴸ"`, rather than JSON null. Their input values must be JSON strings for known fields.
## Column-oriented example
```sql
SELECT 7 AS id, 'Ada' AS name
FORMAT json_columns;
```
```text
{
"id": [7],
"name": ["Ada"]
}
```
Choose [json_each_row](https://coordinatordb.com/docs/reference/formats/json/json-each-row) for a simple row stream, or browse the [format reference](https://coordinatordb.com/docs/reference/formats) for every supported layout and its settings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/intro
Language: en
# JSON data
JSON formats expose several layouts. Choose according to the consumer's expected shape, rather than treating every JSON representation as interchangeable.
## Rows and columns
`json_each_row` writes one named object per row. `json_compact_each_row` writes positional arrays. `json_columns` and `json_compact_columns` transpose rows into arrays for each column.
`json` writes one document containing runtime metadata and row objects. The whole-document input formats `json_as_object` and `json_as_string` load a document into one destination column.
## Example
```sql
SELECT 7 AS id, 'Ada' AS name
FORMAT json_each_row;
```
```text
{"id":7,"name":"Ada"}
```
## Schema
Create explicit target declarations before loading; general schema inference is not supported. A JSON typed column can additionally validate selected paths within a document.
Read [Load JSON](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading), [Export JSON](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/exporting), [Format choices](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/formats), [Expand JSON into rows](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/other) and [Validate JSON fields](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/schema).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading
Language: en
# Load JSON rows
Use json_each_row to load one object per row into explicit destination columns. Input keys name the columns; the target declarations validate each value.
## Create the destination
```sql
CREATE TABLE json_rows(id UInt64,name String);
```
```text
OK
```
## Send the rows
```sql
INSERT INTO json_rows FORMAT json_each_row
{"id":1,"name":"Ada"}
{"id":2,"name":"Grace"}
```
```text
OK
```
## Verify in another request
```sql
SELECT * FROM json_rows ORDER BY id FORMAT csv;
```
```text
1,"Ada"
2,"Grace"
```
## Request and field rules
Inline input consumes the remaining request as data. Do not append SELECT after the JSON; send it as another request. Missing fields follow the format's default rules. Unknown fields are errors unless ignore_unknown_fields is enabled.
See [json_each_row](https://coordinatordb.com/docs/reference/formats/json/json-each-row) for field conversion and settings. Whole-document formats serve a different purpose from row objects.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/other
Language: en
# Expand JSON into rows
Use a table function to query a JSON document as rows. The resulting relation can be filtered, joined or aggregated with ordinary SQL.
## Immediate and recursive members
`json_each` expands immediate children. `json_tree` traverses recursively. JSON array keys are zero-based, unlike native Array element positions.
```sql
SELECT key, value
FROM json_each('[10,20]')
ORDER BY key
FORMAT csv;
```
```text
0,10
1,20
```
## Typed records
`json_to_record` projects an object into an explicit typed schema:
```sql
SELECT *
FROM json_to_record('{"id":7,"name":"Ada"}')
AS record(id UInt64, name String)
FORMAT csv;
```
```text
7,"Ada"
```
The alias schema defines the columns and conversions. This does not infer a persistent table definition. Use the appropriate recordset function for a sequence of records.
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) for schemas, missing fields, JSONPath and other expansion functions.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/schema
Language: en
# Validate JSON fields
JSON imports can validate a row schema and, separately, typed paths inside a JSON document. Choose the contract that matches the stored value.
## Row columns
Before INSERT FORMAT, create destination columns for the row fields. A JSON object field assigned to UInt64, for example, must convert to that declared integer range.
## Typed document paths
Use `JSON(path Type, ...)` when one column stores an object with selected typed paths:
```sql
CREATE TABLE typed_json
(
doc JSON(user_id UInt64, details.price Decimal(18, 2))
);
INSERT INTO typed_json VALUES
('{"user_id":7,"details":{"price":"12.50"}}');
```
```sql
SELECT doc.user_id, doc.details.price
FROM typed_json
FORMAT csv;
```
```text
7,12.50
```
## Missing and conflicting fields
A missing or explicit-null declared path uses its type default. Nullable paths remain NULL. An object path whose parent is a conflicting scalar is rejected; undeclared members remain in the document.
See [JSON](https://coordinatordb.com/docs/reference/data-types/json) for type-hint declarations and [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) for extraction and transformations.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/parquet
Language: en
# Parquet exchange
Parquet is a columnar interchange file. Use it when the consumer accepts its schema and value mappings, and inspect the format's conversion rules before exporting native values.
## Export and import
1. Run SELECT FORMAT parquet through native `--query` and redirect stdout to a file.
2. Create an explicit destination table with the intended types.
3. Load the file with native FROM INFILE or stdin and FORMAT parquet.
4. Query the destination to verify rows and values.
A server file() relation also needs a column/type schema for ordinary Parquet input. Compression, page, row-group and conversion options are statement SETTINGS rather than persisted SET values.
## Inspect metadata
To read the footer rather than data rows, use the input-only `parquet_metadata` format:
```text
SELECT num_rows
FROM file('sample.parquet', parquet_metadata);
```
The file must exist under `user_files_path`. This metadata source supplies its fixed schema without a third argument, including file, row-group and column-chunk fields.
See [Parquet](https://coordinatordb.com/docs/reference/formats/parquet/parquet) for complete round-trip commands and [Parquet metadata](https://coordinatordb.com/docs/reference/formats/parquet/parquet-metadata) for the footer schema.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/sql
Language: en
# SQL row exchange
SQL expressions, sql_values data and sql_insert output serve different purposes. Choose according to whether the source should be executed as SQL or decoded as row literals.
## Literal input
Use INSERT VALUES for ordinary SQL expressions and literals. Use INSERT FORMAT sql_values when the source contains comma-separated literal rows.
The sql_values codec does not evaluate arbitrary expressions. It decodes the supported literal representations and validates them against the destination schema.
## Executable output
`sql_insert` writes INSERT statements for a chosen table and is output-only. Run the resulting text as SQL when importing it; it is not an input codec.
```sql
SELECT 1 AS id, 'Ada' AS name
SETTINGS sql_insert_table = 'people'
FORMAT sql_insert;
```
```text
INSERT INTO people (`id`, `name`) VALUES (1, 'Ada');
```
The setting applies to this statement only. The target table must exist with a compatible schema when the generated SQL is later executed.
See [sql_values](https://coordinatordb.com/docs/reference/formats/sql-values), [sql_insert](https://coordinatordb.com/docs/reference/formats/sql-insert) and [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-formats/templates-regex
Language: en
# Templates and regular expressions
Use regexp when an input line can be described by capture groups. Use template when the input or output follows explicit literal separators and field escaping rules.
## Read with a regular expression
Declare destination columns in capture order and set regexp_pattern on the INSERT. `regexp_skip_unmatched` controls whether a nonmatching line can be skipped.
The regexp input format is line-based. Pattern matching and field conversion are separate: a captured string must still satisfy its target column type.
## Write a template
`template_row` describes field positions and escaping. This example writes two raw fields separated by a vertical bar:
```sql
SELECT 7 AS id, 'Ada' AS name
SETTINGS template_row = '${0:Raw}|${1:Raw}'
FORMAT template;
```
```text
7|Ada
```
There is no trailing newline. `template_row_separator` separates rows only; the template's literal bytes determine the rest of the output.
## Input matching
Template input must match its literal separators. Choose escaping rules that distinguish field content from those separators. All options are statement-scoped.
See [regexp](https://coordinatordb.com/docs/reference/formats/regexp) and [template](https://coordinatordb.com/docs/reference/formats/template/template) for complete input syntax and settings.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling
Language: en
# Data modelling
Data modelling connects table value contracts with the way an application reads and changes rows. These guides use explicit CoordinatorDB schemas and queries, including the limits of snapshot tables and prepared-statement interfaces.
## Guides
* [Backfill a table](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/backfilling)
* [Combine related data](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/denormalization)
* [Generate test data](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/generating-test-data)
* [Design a schema](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/schema-design)
* [Prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements)
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling/backfilling
Language: en
# Backfill a table
Backfilling populates a destination from rows that already exist. Define the target schema first so the copy validates the types and constraints the application will use.
## Prepare source and destination
```sql
CREATE TABLE source(id INTEGER PRIMARY KEY, amount TEXT);
INSERT INTO source VALUES (1, '1.20'), (2, '2.40');
CREATE TABLE destination(id INTEGER PRIMARY KEY, amount Decimal(18, 2));
```
The source contains text; the destination requires an exact two-place decimal.
## Convert during the copy
```sql
INSERT INTO destination
SELECT id, CAST(amount AS Decimal(18, 2))
FROM source;
```
## Verify values
```sql
SELECT id, amount
FROM destination
ORDER BY id
FORMAT csv;
```
```text
1,1.20
2,2.40
```
Check row counts and key values before using the destination. If the copy and related operations must share one transaction, wrap those statements explicitly. Constraint failures follow the failing INSERT's conflict policy; do not assume every policy rolls back the entire transaction.
See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into), [type conversion](https://coordinatordb.com/docs/reference/functions/regular-functions/type-conversion-functions) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling/denormalization
Language: en
# Combine related data
A query-derived table stores a snapshot of related data. It can make an application's read shape explicit, but later changes to the source tables do not propagate automatically.
## Prepare related records
```sql
CREATE TABLE users(id INTEGER PRIMARY KEY, name String);
CREATE TABLE actions(user_id INTEGER, kind String);
INSERT INTO users VALUES (1, 'Ada');
INSERT INTO actions VALUES (1, 'view');
```
## Store the selected fields
```sql
CREATE TABLE action_details AS
SELECT users.name, actions.kind
FROM actions
JOIN users ON users.id = actions.user_id;
```
```sql
SELECT name, kind
FROM action_details
FORMAT csv;
```
```text
"Ada","view"
```
## Constraints and refresh
CREATE TABLE AS SELECT retains projected values and native declarations but does not copy source constraints. Create an explicit destination schema first when its constraints are part of the contract, then use INSERT SELECT. Add indexes for the stored table's own queries.
Materialized views are not supported. Refreshing or extending this snapshot requires another explicit data operation.
See [backfilling](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/backfilling) and [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling/generating-test-data
Language: en
# Generate test data
Use generate_series as a row source for a repeatable test table. Its bounds are inclusive, and expressions can derive other columns from the generated value.
## Create a fixture
```sql
CREATE TABLE samples(id INTEGER PRIMARY KEY, value INTEGER);
INSERT INTO samples
SELECT generate_series, generate_series * 10
FROM generate_series(1, 100);
```
## Verify the shape
```sql
SELECT count(*) AS rows, min(value), max(value), sum(value)
FROM samples
FORMAT csv;
```
```text
100,10,1000,50500
```
The fixture has stable values and no dependence on random state. A descending series needs a negative step; zero is an error. NULL bounds or an unreachable direction produce no rows.
Use a data distribution representative of the query being tested when comparing plans or timings. A small sequential fixture verifies behavior but does not establish performance on a different workload.
See [`generate_series`](https://coordinatordb.com/docs/reference/functions/table-functions/generate-series) for numeric and calendar inputs.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling/schema-design
Language: en
# Design a schema
A schema states the values and relationships the application accepts. Begin with stable identifiers, required fields and the numeric or structured contracts those fields need.
## Define related tables
Enable foreign-key enforcement when the application relies on references:
```sql
PRAGMA foreign_keys = ON;
CREATE TABLE customers(id INTEGER PRIMARY KEY, name String NOT NULL);
CREATE TABLE orders
(
id INTEGER PRIMARY KEY,
customer_id INTEGER NOT NULL REFERENCES customers(id),
amount Decimal(18, 2) CHECK (amount >= 0)
);
INSERT INTO customers VALUES (1, 'Ada');
INSERT INTO orders VALUES (10, 1, '12.50');
```
The name and customer reference are required. The amount is an exact decimal and, when present, must be nonnegative. Add NOT NULL to amount too if missing amounts are invalid for the application.
## Read related values
```sql
SELECT orders.id, customers.name, orders.amount
FROM orders
JOIN customers ON customers.id = orders.customer_id
FORMAT csv;
```
```text
10,"Ada",12.50
```
## Index for actual queries
Use primary and unique keys to enforce identity, and other indexes for concrete filter and ordering patterns. Verify the plan with EXPLAIN QUERY PLAN rather than assuming an index is selected.
See [data types](https://coordinatordb.com/docs/reference/data-types), [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) and [`CREATE INDEX`](https://coordinatordb.com/docs/reference/statements/create/create-index).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements
Language: en
# Prepared statements
A prepared statement separates SQL structure from positional parameter values. Prepare one statement, then supply a new Value slice each time it is executed.
Missing bindings are errors. The API prepares a statement for the application; it does not define a stored procedure. SQL CREATE PROCEDURE and SQL PREPARE/EXECUTE are not supported.
## Prepare and bind
An application using the coordinator crate can open a connection and bind values:
```rust
use coordinator::{Connection, Value};
fn main() -> coordinator::Result<()> {
let mut db = Connection::open_in_memory()?;
db.execute("CREATE TABLE people(id INTEGER PRIMARY KEY,name TEXT)")?;
let insert = db.prepare("INSERT INTO people VALUES (?1,?2)")?;
db.execute_prepared(&insert, &[Value::Integer(1), Value::Text("Ada".into())])?;
let find = db.prepare("SELECT name FROM people WHERE id=?1")?;
let result = db.query_prepared(&find, &[Value::Integer(1)])?;
assert_eq!(result.rows[0][0].scalar_text(), "Ada");
Ok(())
}
```
## Connection and interfaces
Use `Connection::open(path)` for a file-backed database. The example uses an in-memory database so the parameter and result behavior can be tried independently.
A native parameter request can carry values beside SQL. The ordinary CLI and HTTP request options do not provide a parameter-binding interface; an application should use a supported binding API rather than inserting data values into SQL text.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) for embedded connection scope.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/array-agg-distinct
Language: en
# Distinct array aggregation
Use `array_agg(DISTINCT ...)` to collect unique admitted values into an array. An aggregate ORDER BY defines the resulting element order.
The CoordinatorDB function is array_agg; `groupArrayDistinct` is not a callable alias.
## Collect distinct values
```sql
CREATE TABLE labels (value INTEGER);
INSERT INTO labels VALUES (2), (1), (2), (NULL);
```
```sql
SELECT array_agg(DISTINCT value ORDER BY value NULLS LAST)
FROM labels
FORMAT csv;
```
```text
"[1,2,null]"
```
Array aggregation retains NULL as an element. DISTINCT keeps one copy of it.
## Exclude missing elements
Use FILTER when the result should contain only present values:
```sql
SELECT array_agg(DISTINCT value ORDER BY value)
FILTER (WHERE value IS NOT NULL)
FROM labels
FORMAT csv;
```
```text
"[1,2]"
```
See [`array_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg) for empty input and element types, and [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions) for operations on the result.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-if
Language: en
# avg_if
Calculate the average amount of paid orders. A conditional aggregate admits rows whose condition is SQL true, so one query can calculate a segment without filtering every other aggregate to that same segment.
## Prepare the input
The sample includes two paid orders and one pending order:
```sql
CREATE TABLE orders(id UInt32, status String, amount Int64);
INSERT INTO orders VALUES (1, 'paid', 100), (2, 'paid', 60), (3, 'pending', 40);
```
## Calculate the segment
```sql
SELECT avg_if(amount, status = 'paid') AS paid_result
FROM orders
FORMAT csv;
```
```text
80.0
```
Selected NULL amounts are skipped. False and NULL conditions do not contribute.
## Empty segments
avg_if returns NULL when no qualifying non-NULL value contributes. Arguments are evaluated before the condition is tested; an excluded row does not protect an argument expression from an evaluation error.
See [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) for the supported conditional functions and SQL FILTER alternatives.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-merge
Language: en
# avg_merge
`avg_merge` combines average states and returns the final mean. Each state's contribution is weighted by its admitted row count.
Averaging the batch means themselves would give the wrong result when batch sizes differ.
## Prepare unequal batches
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, state AggregateFunction(avg, Int64));
INSERT INTO partials
SELECT batch, avg_state(value)
FROM readings
GROUP BY batch;
```
The batch means are 15 and 90, with two and one observations respectively.
## Merge the states
```sql
SELECT avg_merge(state) AS overall_average
FROM partials
FORMAT csv;
```
```text
40.0
```
The result is `(10 + 20 + 90) / 3`, rather than `(15 + 90) / 2`.
Use [`avg_merge_state`](https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-merge-state) when another aggregation stage needs the combined state instead of its final value. See [AggregateFunction](https://coordinatordb.com/docs/reference/data-types/aggregatefunction) for signatures and empty-state behavior.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-merge-state
Language: en
# avg_merge_state
`avg_merge_state` merges average states and returns another state. Use it when a calculation has several stages, such as combining per-batch states before combining them across a larger period.
## Create batch states
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, state AggregateFunction(avg, Int64));
INSERT INTO partials
SELECT batch, avg_state(value)
FROM readings
GROUP BY batch;
```
## Retain the combined state
```sql
CREATE TABLE combined(state AggregateFunction(avg, Int64));
INSERT INTO combined SELECT avg_merge_state(state) FROM partials;
```
## Finalize at the boundary
```sql
SELECT finalize_aggregation(state)
FROM combined
FORMAT csv;
```
```text
40.0
```
The merged state still retains the contribution count needed by another `avg_merge` or `avg_merge_state`. Finalizing a state reads it without combining other rows.
See [`avg_state`](https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-state), [`avg_merge`](https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-merge) and [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-state
Language: en
# avg_state
`avg_state` returns an intermediate average state. It retains a total and count rather than only the average, so a later merge can combine batches with the correct weights.
## Create typed state storage
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, state AggregateFunction(avg, Int64));
```
## Store one state per batch
```sql
INSERT INTO partials
SELECT batch, avg_state(value)
FROM readings
GROUP BY batch;
```
## Read a state's value
`finalize_aggregation` reads a single state's result:
```sql
SELECT batch, finalize_aggregation(state) AS average_value
FROM partials
ORDER BY batch
FORMAT csv;
```
```text
1,15.0
2,90.0
```
Use [`avg_merge`](https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/avg-merge) to combine several states. State function names and argument types must match the storage declaration exactly; CoordinatorDB states are not compatible with ClickHouse state bytes.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/count-if
Language: en
# count_if
Count orders whose status is paid. A conditional aggregate admits rows whose condition is SQL true, so one query can calculate a segment without filtering every other aggregate to that same segment.
## Prepare the input
The sample includes two paid orders and one pending order:
```sql
CREATE TABLE orders(id UInt32, status String, amount Int64);
INSERT INTO orders VALUES (1, 'paid', 100), (2, 'paid', 60), (3, 'pending', 40);
```
## Calculate the segment
```sql
SELECT count_if(status = 'paid') AS paid_result
FROM orders
FORMAT csv;
```
```text
2
```
The function counts matching rows even when another field is NULL.
## Empty segments
count_if and sum_if return zero when no qualifying row contributes. Arguments are evaluated before the condition is tested; an excluded row does not protect an argument expression from an evaluation error.
See [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) for the supported conditional functions and SQL FILTER alternatives.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/max-simple-state
Language: en
# max_simple_state
`max_simple_state` calculates a partial max and returns a directly readable scalar wrapped as SimpleAggregateFunction. Ordinary `max` can combine those partial values again.
Unlike a full AggregateFunction state, the scalar does not need `_merge` or `finalize_aggregation` before it can be read.
## Prepare two batches
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, result SimpleAggregateFunction(max, Int64));
INSERT INTO partials
SELECT batch, max_simple_state(value)
FROM readings
GROUP BY batch;
```
## Read partial results
```sql
SELECT batch, result
FROM partials
ORDER BY batch
FORMAT csv;
```
```text
1,20
2,90
```
## Combine the scalars
```sql
SELECT max(result)
FROM partials
FORMAT csv;
```
```text
90
```
The table does not combine rows automatically when values are inserted. Use an explicit aggregate query. See [SimpleAggregateFunction](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction) for the supported inner types and functions.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/min-simple-state
Language: en
# min_simple_state
`min_simple_state` calculates a partial min and returns a directly readable scalar wrapped as SimpleAggregateFunction. Ordinary `min` can combine those partial values again.
Unlike a full AggregateFunction state, the scalar does not need `_merge` or `finalize_aggregation` before it can be read.
## Prepare two batches
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, result SimpleAggregateFunction(min, Int64));
INSERT INTO partials
SELECT batch, min_simple_state(value)
FROM readings
GROUP BY batch;
```
## Read partial results
```sql
SELECT batch, result
FROM partials
ORDER BY batch
FORMAT csv;
```
```text
1,10
2,90
```
## Combine the scalars
```sql
SELECT min(result)
FROM partials
FORMAT csv;
```
```text
10
```
The table does not combine rows automatically when values are inserted. Use an explicit aggregate query. See [SimpleAggregateFunction](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction) for the supported inner types and functions.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/sum-if
Language: en
# sum_if
Calculate revenue only from paid orders. A conditional aggregate admits rows whose condition is SQL true, so one query can calculate a segment without filtering every other aggregate to that same segment.
## Prepare the input
The sample includes two paid orders and one pending order:
```sql
CREATE TABLE orders(id UInt32, status String, amount Int64);
INSERT INTO orders VALUES (1, 'paid', 100), (2, 'paid', 60), (3, 'pending', 40);
```
## Calculate the segment
```sql
SELECT sum_if(amount, status = 'paid') AS paid_result
FROM orders
FORMAT csv;
```
```text
160
```
Selected NULL amounts are skipped. False and NULL conditions do not contribute.
## Empty segments
count_if and sum_if return zero when no qualifying non-NULL value contributes. Arguments are evaluated before the condition is tested; an excluded row does not protect an argument expression from an evaluation error.
See [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) for the supported conditional functions and SQL FILTER alternatives.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/examples/aggregate-function-combinators/sum-simple-state
Language: en
# sum_simple_state
`sum_simple_state` calculates a partial sum and returns a directly readable scalar wrapped as SimpleAggregateFunction. Ordinary `sum` can combine those partial values again.
Unlike a full AggregateFunction state, the scalar does not need `_merge` or `finalize_aggregation` before it can be read.
## Prepare two batches
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, result SimpleAggregateFunction(sum, Int64));
INSERT INTO partials
SELECT batch, sum_simple_state(value)
FROM readings
GROUP BY batch;
```
## Read partial results
```sql
SELECT batch, result
FROM partials
ORDER BY batch
FORMAT csv;
```
```text
1,30
2,90
```
## Combine the scalars
```sql
SELECT sum(result)
FROM partials
FORMAT csv;
```
```text
120
```
The table does not combine rows automatically when values are inserted. Use an explicit aggregate query. See [SimpleAggregateFunction](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction) for the supported inner types and functions.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/diagnose-slow-queries
Language: en
# Inspect query history
Use system.query_log to inspect finished work and system.processes to inspect requests that are still running. A query ID connects the request with response metadata and diagnostics.
## Enable history
```sql
SET log_queries = 1;
```
The setting persists for the selected database. log_queries_min_query_duration_ms can restrict history to requests meeting a duration threshold.
## Read terminal events
```sql
SELECT type, exception_code
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 1
FORMAT csv;
```
```text
"QueryFinish",0
```
A direct single-table SELECT from system.query_log waits for earlier queued events before reading. The current request's own terminal event appears only after it finishes. A duration threshold can omit short requests and their start events.
## Follow a request
Use its query_id to select duration, row/byte counters and exception details. Inspect system.processes for an active request rather than expecting its terminal history record before completion.
See [query_log](https://coordinatordb.com/docs/reference/system-tables/query-log), [processes](https://coordinatordb.com/docs/reference/system-tables/processes) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks
Language: en
# Inspect query measurements
Measurements describe a concrete execution, not an abstract SQL spelling. Keep its SQL, parameters, data and query ID together when investigating a request.
## Find the execution
Read the query ID from an HTTP response header or query history. Use system.query_log for finished requests and system.processes for active requests.
Compare elapsed time with read_rows, read_bytes, written_rows and written_bytes. Terminal memory_usage and peak_memory_usage both report the query's peak accounted memory, rather than a post-completion live allocation.
## Inspect the plan
EXPLAIN QUERY PLAN shows access choices without executing the statement. EXPLAIN ANALYZE executes once and includes runtime measurements:
```text
EXPLAIN ANALYZE
SELECT generate_series
FROM generate_series(1, 3);
```
Analyzed output replaces the underlying result rows. EXPLAIN ANALYZE also applies DML changes once; use a transaction and rollback when those changes should not remain.
## Compare runs
Durations vary between executions. Keep result limits and data fixed, verify that both queries perform the intended work, and inspect the plan alongside timings.
See [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain) and [query history](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/diagnose-slow-queries).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/optimization-approaches
Language: en
# Check a query change
A query change should preserve the intended result before its performance is compared. Different rows, duplicate counts or NULL handling can make a faster query an incorrect replacement.
## Establish a comparison
1. Keep a fixed dataset and parameters.
2. Write explicit output ordering where row order matters.
3. Record the result and EXPLAIN QUERY PLAN.
4. Change the intended predicate, projection or index.
5. Verify the same result before comparing measurements.
For joins, check duplicate-key multiplicity and unmatched rows. For aggregates, check missing values and empty groups.
## Measure the same task
Use system.query_log for request duration and resource counters. EXPLAIN ANALYZE executes a statement once; use it only when that execution is intended, including its DML writes.
ANALYZE supplies statistics for planning. An index can benefit one access pattern while adding write and storage costs. Inspect the concrete plan rather than assuming its presence guarantees a speedup.
See the [worked index example](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization-example), [plan guide](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization) and [measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization
Language: en
# Inspect and index a query
Start with a query's intended filters and ordering. EXPLAIN QUERY PLAN describes the selected access path without running the query.
An index should match an actual column or expression used by that query. ANALYZE collects statistics for planning; after creating an index, inspect the plan and verify the selected rows again.
## Prepare a filtered table
```sql
CREATE TABLE events(id INTEGER PRIMARY KEY,kind String);
INSERT INTO events VALUES(1,'view'),(2,'click');
CREATE INDEX events_kind ON events(kind);
ANALYZE;
```
## Inspect the selected access path
```sql
EXPLAIN QUERY PLAN SELECT id FROM events WHERE kind='click';
```
```text
┌─id─┬─parent─┬─notused─┬─detail───────────────────────────────────────────────────────┐
│ 1 │ 0 │ 0 │ PROJECTION id │
│ 2 │ 1 │ 0 │ INDEX_SCAN Table: events; Index: events_kind; Covering: true │
└────┴────────┴─────────┴──────────────────────────────────────────────────────────────┘
(2 rows)
```
The plan below the projection identifies the selected table access and whether an index covers the required values. Plan text can change between versions; use it to understand this execution choice rather than treating it as a permanent output schema.
Indexes also add write and storage work. Use [the comparison workflow](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/optimization-approaches) and [runtime measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks) for a representative dataset.
---
Source: https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/query-optimization-example
Language: en
# Index a filtered query
This example adds an index for a category predicate and checks that the selected rows remain the same. The small dataset illustrates the workflow; its timing is not a performance claim.
## Prepare and query the data
```sql
CREATE TABLE logs(id INTEGER PRIMARY KEY, category String);
INSERT INTO logs VALUES (1, 'read'), (2, 'write'), (3, 'read');
```
```sql
SELECT id
FROM logs
WHERE category = 'read'
ORDER BY id
FORMAT csv;
```
```text
1
3
```
## Add an index
```sql
CREATE INDEX logs_category ON logs(category);
ANALYZE;
```
Inspect EXPLAIN QUERY PLAN for the predicate. The selected plan depends on the data and implementation version; an index is not a universal speedup.
## Verify the result again
```sql
SELECT id
FROM logs
WHERE category = 'read'
ORDER BY id
FORMAT csv;
```
```text
1
3
```
Compare measurements only after confirming the result. See [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks) and [`CREATE INDEX`](https://coordinatordb.com/docs/reference/statements/create/create-index).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/working-with-arrays
Language: en
# Work with arrays
Arrays retain an ordered collection with one member type. Use explicit declarations when the element range or nullability must be enforced.
## Create and read an array
```sql
SELECT array_element(array(10, 20, 30), -1),
array_length(array(10, 20, 30))
FORMAT csv;
```
```text
30,3
```
Element positions are one-based; negative positions count from the end. Zero is invalid. A missing position returns the declared member type's default. This differs from array_position, which returns NULL when a value is not found.
## Expand into rows
Use unnest in FROM to expand the scalar leaves:
```sql
SELECT unnest AS value
FROM unnest(array(10, 20, 30))
ORDER BY unnest
FORMAT csv;
```
```text
10
20
30
```
## Collect rows
Array aggregation can restore an ordered collection and retain missing elements:
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (20), (10), (NULL);
```
```sql
SELECT array_agg(value ORDER BY value NULLS LAST)
FROM readings
FORMAT csv;
```
```text
"[10,20,null]"
```
Use Array(Nullable(T)) when typed input must admit NULL members. Bracket access and lambda expressions are not supported; use the documented functions.
See [Array](https://coordinatordb.com/docs/reference/data-types/array), [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions) and [`array_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg).
---
Source: https://coordinatordb.com/docs/guides/clickhouse/working-with-joins
Language: en
# Work with joins
This guide joins customers with orders and calculates one summary row per customer. A LEFT JOIN retains a customer even when there are no matching orders.
## Prepare the tables
```sql
CREATE TABLE customers(id INTEGER PRIMARY KEY, name String);
CREATE TABLE orders(id INTEGER PRIMARY KEY, customer_id INTEGER, amount INTEGER);
INSERT INTO customers VALUES (1, 'Ada'), (2, 'Grace');
INSERT INTO orders VALUES (10, 1, 5), (11, 1, 7);
```
## Join and aggregate
```sql
SELECT customer.id, customer.name,
count(orders.id) AS orders,
coalesce(sum(orders.amount), 0) AS total
FROM customers AS customer
LEFT JOIN orders ON orders.customer_id = customer.id
GROUP BY customer.id, customer.name
ORDER BY customer.id
FORMAT csv;
```
```text
1,"Ada",2,12
2,"Grace",0,0
```
## Understand unmatched rows
Grace's unmatched order fields are NULL. Counting orders.id skips that missing value, whereas count(\*) would count the retained joined row. sum returns NULL without a contributing amount, so coalesce supplies zero.
Several matches produce several joined rows. Include the intended key predicates and qualify shared column names. Use INNER JOIN when customers without orders should be excluded.
See [`JOIN`](https://coordinatordb.com/docs/reference/statements/select/join) and [join checks](https://coordinatordb.com/docs/concepts/best-practices/minimize-optimize-joins).
---
Source: https://coordinatordb.com/docs/reference/data-types
Language: en
# Data types
A column's data type defines which values it accepts and how they are converted, compared and returned. CoordinatorDB provides checked native numeric, temporal, collection and domain types alongside legacy SQL affinity declarations.
Type names ignore case: `UInt8` and `uint8` mean the same eight-bit unsigned type. Parameter values, field names, JSON paths and Enum labels follow their individual contracts.
## Choosing a type
| Data | Types |
| ------------------------------------- | --------------------------------------------------- |
| Whole numbers and counters | `Int8` through `Int256`; `UInt8` through `UInt256`. |
| Exact decimal amounts | `Decimal(P, S)`, including `NUMERIC(P, S)`. |
| Approximate measurements | `Float32`, `Float64`, `BFloat16`. |
| Text and fixed-width bytes | `String`, `VARCHAR(n)`, `FixedString(n)`. |
| Flags and fixed vocabularies | `Bool`, `Enum8`, `Enum16`. |
| Calendar dates and timestamps | `Date`, `Date32`, `DateTime`, `DateTime64`. |
| Date-independent clocks and durations | `Time`, `Time64`, `Interval`. |
| Repeated or structured values | `Array`, `Tuple`, `Map`, `Nested`, `JSON`. |
| Alternative or varying value types | `Variant`, `Dynamic`. |
| Identifiers and addresses | `UUID`, `IPv4`, `IPv6`, `inet`, `cidr`. |
| Spatial values and numeric vectors | Geometry aliases and `QBit`. |
| Partial aggregate results | `AggregateFunction`, `SimpleAggregateFunction`. |
| Full-text search values | `tsvector`, `tsquery`. |
Use the [IP address functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions) for `inet`/`cidr`, and [search functions](https://coordinatordb.com/docs/reference/functions/regular-functions/string-search-functions) for `tsvector`/`tsquery`.
## Declaring and converting values
Native declarations validate inserts, updates, defaults, generated values and explicit casts. The same range and shape rules apply wherever a value enters the declared type.
```sql
CREATE TABLE products
(
id UInt32 PRIMARY KEY,
name String NOT NULL,
price Decimal(18, 2),
tags Array(String)
);
INSERT INTO products VALUES (1, 'Notebook', '12.50', '["paper","office"]');
```
```sql
SELECT id, name, price, array_length(tags) AS tag_count
FROM products
FORMAT csv;
```
```text
1,"Notebook",12.50,2
```
Use `CAST(expression AS Type)` to convert explicitly, and `to_type_name` to inspect a native value's type. Individual type pages describe accepted inputs and conversion errors.
## NULL values
Top-level columns permit SQL `NULL` unless declared `NOT NULL`. Inside typed collections, use `Nullable(T)` for members that can be missing. A top-level `Array(UInt8)` column can therefore be `NULL`, but its non-`NULL` arrays cannot contain `NULL` elements.
## Legacy declarations
`INTEGER`, `REAL`, `TEXT` and `BLOB` follow SQLite-style affinity. `NUMERIC` is an exact Decimal declaration, defaulting to `Decimal(10, 0)`; use `LEGACY_NUMERIC` for SQLite numeric affinity.
`STRICT` tables enforce their allowed value classes; `ANY` preserves a supplied value's class. A ClickHouse table `ENGINE` clause is not required or supported.
## Type reference
* [AggregateFunction](https://coordinatordb.com/docs/reference/data-types/aggregatefunction)
* [Array](https://coordinatordb.com/docs/reference/data-types/array)
* [Bool](https://coordinatordb.com/docs/reference/data-types/bool)
* [Date](https://coordinatordb.com/docs/reference/data-types/date)
* [Date32](https://coordinatordb.com/docs/reference/data-types/date32)
* [DateTime](https://coordinatordb.com/docs/reference/data-types/datetime)
* [DateTime64](https://coordinatordb.com/docs/reference/data-types/datetime64)
* [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal)
* [Dynamic](https://coordinatordb.com/docs/reference/data-types/dynamic)
* [Enum](https://coordinatordb.com/docs/reference/data-types/enum)
* [FixedString](https://coordinatordb.com/docs/reference/data-types/fixedstring)
* [Floating-point numbers](https://coordinatordb.com/docs/reference/data-types/float)
* [Geometry types](https://coordinatordb.com/docs/reference/data-types/geometry-types)
* [Integers](https://coordinatordb.com/docs/reference/data-types/int-uint)
* [IPv4](https://coordinatordb.com/docs/reference/data-types/ipv4)
* [IPv6](https://coordinatordb.com/docs/reference/data-types/ipv6)
* [LowCardinality](https://coordinatordb.com/docs/reference/data-types/lowcardinality)
* [Map](https://coordinatordb.com/docs/reference/data-types/map)
* [Nested](https://coordinatordb.com/docs/reference/data-types/nested-data-structures)
* [JSON](https://coordinatordb.com/docs/reference/data-types/json)
* [Nullable](https://coordinatordb.com/docs/reference/data-types/nullable)
* [QBit](https://coordinatordb.com/docs/reference/data-types/qbit)
* [SimpleAggregateFunction](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction)
* [Interval](https://coordinatordb.com/docs/reference/data-types/special-data-types/interval)
* [String](https://coordinatordb.com/docs/reference/data-types/string)
* [Time](https://coordinatordb.com/docs/reference/data-types/time)
* [Time64](https://coordinatordb.com/docs/reference/data-types/time64)
* [Tuple](https://coordinatordb.com/docs/reference/data-types/tuple)
* [UUID](https://coordinatordb.com/docs/reference/data-types/uuid)
* [Variant](https://coordinatordb.com/docs/reference/data-types/variant)
* [Domain types](https://coordinatordb.com/docs/reference/data-types/domains)
* [Special data types](https://coordinatordb.com/docs/reference/data-types/special-data-types)
---
Source: https://coordinatordb.com/docs/reference/data-types/aggregatefunction
Language: en
# AggregateFunction
`AggregateFunction` stores an intermediate aggregate state. It retains enough information to combine several batches and calculate a final result later.
For example, an average state includes both a total and a count. Merging the states gives the average over all contributing rows, even when batches have different sizes.
## Syntax
```text
AggregateFunction(function, argument_type, ...)
```
* `function` — One of `sum`, `count`, `avg`, `min` or `max`.
* `argument_type` — The aggregate's declared input type. Count accepts zero or one argument type; the other functions require one.
## Usage
Use the function's `_state` variant to create a state. Use `_merge` to combine state rows and return a final value, or `_merge_state` to return another state. `finalize_aggregation` reads the result of a single state.
States must have exactly matching function names and argument types. Their native representation is specific to CoordinatorDB and is not compatible with ClickHouse aggregate-state bytes. Finalize a state before using its value in ordinary arithmetic or numeric aggregates.
## Usage Example
### Storing partial averages
```sql
CREATE TABLE measurements(batch UInt8, value Int64);
INSERT INTO measurements VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE partials(batch UInt8, result AggregateFunction(avg, Int64));
INSERT INTO partials
SELECT batch, avg_state(value)
FROM measurements
GROUP BY batch;
```
Read individual state results:
```sql
SELECT batch, finalize_aggregation(result) AS average_value
FROM partials
ORDER BY batch
FORMAT csv;
```
```text
1,15.0
2,90.0
```
Merge them to obtain the average of all observations:
```sql
SELECT avg_merge(result)
FROM partials
FORMAT csv;
```
```text
40.0
```
## Empty states
A count or sum state finalizes to zero when no values contribute. Minimum and maximum states finalize to the argument type's default; an average state finalizes to `NULL`.
These rules differ from ordinary `sum`, `min` and `max` on empty input. See [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) for the complete variant list and [SimpleAggregateFunction](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction) for directly readable scalar partial results.
---
Source: https://coordinatordb.com/docs/reference/data-types/array
Language: en
# Array
`Array(T)` stores an ordered collection of values of type `T`. Arrays can be empty and can contain other arrays or typed collections.
## Creating an Array
Construct an array with `array(...)`, or pass standard JSON array text to a typed column or cast. An explicit type is useful for empty arrays and when the element range must be checked.
```sql
SELECT array(1, 2, 3), CAST('[]' AS Array(UInt8))
FORMAT csv;
```
```text
"[1,2,3]","[]"
```
Nested declarations preserve their element contracts even when the arrays are empty:
```sql
SELECT CAST('[[1,2],[]]' AS Array(Array(UInt8)))
FORMAT csv;
```
```text
"[[1,2],[]]"
```
## Working with Data Types
```text
Array(T)
```
* `T` — The element type. Every element is converted and validated against this type.
Use `Array(Nullable(T))` to allow missing elements. A top-level array column can itself be `NULL` unless declared `NOT NULL`.
## Array Size
Use `array_length` to count array elements. An empty array has length zero;
`NULL` members still count as elements.
```sql
SELECT array_length(array(1, 2, 3)),
array_length(CAST('[]' AS Array(Int32)))
FORMAT csv;
```
```text
3,0
```
## Accessing elements
`array_element(array, index)` uses positions starting at 1. Negative positions count from the end. Position 0 raises `INVALID_ARGUMENT`. A position outside the array returns the declared element type's default, such as zero or an empty string; nullable elements default to `NULL`.
```sql
SELECT array_element(array(10, 20), 1),
array_element(array(10, 20), -1),
array_element(CAST('[10,20]' AS Array(UInt8)), 3)
FORMAT csv;
```
```text
10,20,0
```
Use the function syntax; bracket access such as `tags[1]` and lambda expressions are not implemented.
## Example
### Storing nullable measurements
```sql
CREATE TABLE samples(id UInt32, readings Array(Nullable(UInt8)));
INSERT INTO samples VALUES (1, '[10,null,20]');
```
```sql
SELECT id, readings, array_length(readings) AS positions
FROM samples
FORMAT csv;
```
```text
1,"[10,null,20]",3
```
See [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions) for membership, slicing and other operations, and [`array_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg) for collecting rows into an array.
---
Source: https://coordinatordb.com/docs/reference/data-types/bool
Language: en
# Bool
`Bool` represents the two logical values `true` and `false`. `BOOLEAN` is an alias.
## Syntax
```text
Bool
BOOLEAN
```
## Accepted values
A Boolean conversion accepts `true`, `false`, numeric `0` and `1`, and their equivalent flag text. Other numeric values are rejected rather than treated as true.
Boolean columns can be used directly in `WHERE`, `CASE` and conditional aggregate expressions. SQL `NULL` remains a missing value; declare `NOT NULL` when a column must always have a flag.
## Examples
### Converting flags
```sql
SELECT CAST('true' AS Bool), CAST(0 AS Bool), CAST(1 AS BOOLEAN)
FORMAT csv;
```
```text
true,false,true
```
### Filtering by a Boolean column
```sql
CREATE TABLE tasks(id UInt32, completed Bool NOT NULL);
INSERT INTO tasks VALUES (1, true), (2, false), (3, true);
```
```sql
SELECT id
FROM tasks
WHERE completed
ORDER BY id
FORMAT csv;
```
```text
1
3
```
See [logical functions](https://coordinatordb.com/docs/reference/functions/regular-functions/logical-functions) and [NULL functions](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls) for Boolean expressions with missing values.
---
Source: https://coordinatordb.com/docs/reference/data-types/date
Language: en
# Date
`Date` represents a Gregorian calendar date without a time of day or timezone. Its supported range is `1970-01-01` through `2149-06-06`, inclusive.
## Syntax
```text
Date
```
## Input and conversion
Text input uses `YYYY-MM-DD` and must be a valid date within the supported range. Integer input is the number of days since `1970-01-01`.
Casting a date to `INTEGER` returns its epoch-day count. Adding or subtracting an integer moves the date by that many days. Use an [`Interval`](https://coordinatordb.com/docs/reference/data-types/special-data-types/interval) for calendar-month or year arithmetic.
A Date compared with a timestamp represents midnight in the timestamp's timezone. Native date values cannot be summed directly; convert them explicitly when a numeric calculation is intended.
## Examples
### Creating a date column
```sql
CREATE TABLE events(id UInt32, day Date);
INSERT INTO events VALUES (1, '2025-03-05');
```
```sql
SELECT id, day, day + 1 AS next_day
FROM events
FORMAT csv;
```
```text
1,"2025-03-05","2025-03-06"
```
### Converting epoch days
```sql
SELECT CAST(1 AS Date),
CAST(CAST('1970-01-02' AS Date) AS INTEGER)
FORMAT csv;
```
```text
"1970-01-02",1
```
See [Date32](https://coordinatordb.com/docs/reference/data-types/date32) for the alternative date range, and [DateTime](https://coordinatordb.com/docs/reference/data-types/datetime) for whole-second timestamps.
---
Source: https://coordinatordb.com/docs/reference/data-types/date32
Language: en
# Date32
`Date32` represents a Gregorian calendar date without a time of day or timezone. Its supported range is `1900-01-01` through `2299-12-31`, inclusive.
## Syntax
```text
Date32
```
## Input and conversion
Text input uses `YYYY-MM-DD` and must be a valid date within the supported range. Integer input is the number of days since `1970-01-01` and can be negative for earlier dates.
Casting a date to `INTEGER` returns its epoch-day count. Adding or subtracting an integer moves the date by that many days. Use an [`Interval`](https://coordinatordb.com/docs/reference/data-types/special-data-types/interval) for calendar-month or year arithmetic.
A Date compared with a timestamp represents midnight in the timestamp's timezone. Native date values cannot be summed directly; convert them explicitly when a numeric calculation is intended.
## Examples
### Creating a date column
```sql
CREATE TABLE events(id UInt32, day Date32);
INSERT INTO events VALUES (1, '2100-01-01');
```
```sql
SELECT id, day, day + 1 AS next_day
FROM events
FORMAT csv;
```
```text
1,"2100-01-01","2100-01-02"
```
### Converting epoch days
```sql
SELECT CAST(1 AS Date32),
CAST(CAST('1970-01-02' AS Date32) AS INTEGER)
FORMAT csv;
```
```text
"1970-01-02",1
```
See [Date](https://coordinatordb.com/docs/reference/data-types/date) for the alternative date range, and [DateTime](https://coordinatordb.com/docs/reference/data-types/datetime) for whole-second timestamps.
---
Source: https://coordinatordb.com/docs/reference/data-types/datetime
Language: en
# DateTime
`DateTime` represents an instant with whole-second precision. The value is interpreted as a Unix-second count; its range is `1970-01-01 00:00:00` through `2106-02-07 06:28:15` in UTC.
## Syntax
```text
DateTime
DateTime('timezone')
```
* `timezone` — An IANA timezone name, such as `'UTC'` or `'Europe/Berlin'`. The default is `'UTC'`.
Use [DateTime64](https://coordinatordb.com/docs/reference/data-types/datetime64) for fractional seconds or a wider calendar range.
## Usage Remarks
Integer input is Unix seconds. Zone-free text is interpreted in the declared timezone. Text containing only a date represents midnight in that zone. Display uses the declared timezone.
Ambiguous local times during a backward clock change and nonexistent local times during a forward change are rejected. The type declaration establishes a timezone for the value; it does not accept an independently chosen zone per row.
Casting to `INTEGER` returns epoch seconds. Adding or subtracting an integer moves the timestamp by that many elapsed seconds. Calendar intervals preserve local calendar rules and can fail when the resulting local time is ambiguous or nonexistent.
## Examples
### Inserting and selecting timestamps
```sql
CREATE TABLE events(id UInt32, occurred_at DateTime('UTC'));
INSERT INTO events VALUES (1, '2025-03-05 12:30:00');
```
```sql
SELECT id, occurred_at, occurred_at + 60 AS one_minute_later
FROM events
FORMAT csv;
```
```text
1,"2025-03-05 12:30:00","2025-03-05 12:31:00"
```
### Converting Unix seconds
```sql
SELECT CAST(1 AS DateTime('UTC')),
CAST(CAST('1970-01-01 00:00:01' AS DateTime) AS INTEGER)
FORMAT csv;
```
```text
"1970-01-01 00:00:01",1
```
### Interpreting local text
The same instant has different local representations:
```sql
SELECT CAST('2025-01-15 12:00:00' AS DateTime('UTC'))
= CAST('2025-01-15 13:00:00' AS DateTime('Europe/Berlin'))
FORMAT csv;
```
```text
1
```
---
Source: https://coordinatordb.com/docs/reference/data-types/datetime64
Language: en
# DateTime64
`DateTime64` represents an instant with configurable fractional-second precision and a declared timezone. Use it for event times that require milliseconds, microseconds or nanoseconds.
## Syntax
```text
DateTime64
DateTime64(P)
DateTime64(P, 'timezone')
TIMESTAMP
TIMESTAMP(P)
TIMESTAMP(P, 'timezone')
```
## Parameters and range
* `P` — The number of fractional-second digits, from 0 through 9. `DateTime64` defaults to 3; the `TIMESTAMP` alias defaults to 6.
* `timezone` — An IANA timezone name. The default is `'UTC'`.
The calendar range is 1900 through 2299, further limited by signed 64-bit tick capacity. Precision 9 reaches its upper tick limit in 2262.
## Input units
Integer input is a count of ticks at the declared precision. At precision 3, `1234` means `1.234` seconds after the Unix epoch. Decimal input instead expresses epoch seconds. Text is interpreted as local date and time in the declared timezone.
Casting to a numeric type returns epoch seconds; a `REAL` or Decimal target can retain fractions. Lowering precision discards fractional digits while remaining in the containing tick, including for times before 1970.
As with [DateTime](https://coordinatordb.com/docs/reference/data-types/datetime), ambiguous or nonexistent local times are rejected. Text with no clock time denotes local midnight.
## Examples
### Preserving microseconds
```sql
SELECT CAST('2025-03-05 12:30:00.123456' AS DateTime64(6, 'UTC'))
FORMAT csv;
```
```text
"2025-03-05 12:30:00.123456"
```
### Integer ticks and decimal seconds
Both values below represent the same instant:
```sql
SELECT CAST(1234 AS DateTime64(3, 'UTC')),
CAST(CAST('1.234' AS Decimal(18, 3)) AS DateTime64(3, 'UTC'))
FORMAT csv;
```
```text
"1970-01-01 00:00:01.234","1970-01-01 00:00:01.234"
```
### Reducing precision
```sql
SELECT CAST(
CAST('2025-03-05 12:30:00.123456' AS DateTime64(6))
AS DateTime64(3)
)
FORMAT csv;
```
```text
"2025-03-05 12:30:00.123"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/decimal
Language: en
# Decimal
Decimal values represent exact fixed-point numbers. They preserve decimal digits during addition, subtraction and multiplication. Division discards excess fractional digits instead of rounding them.
Use Decimal for amounts, prices and other values that require an exact decimal scale.
## Syntax
```text
Decimal(P, S)
Decimal(P)
Decimal
Decimal32(S)
Decimal64(S)
Decimal128(S)
Decimal256(S)
NUMERIC(P, S)
```
## Parameters
* `P` — Precision: the total number of decimal digits, from 1 through 76.
* `S` — Scale: the number of fractional digits, from 0 through `P`.
`Decimal(P)` means `Decimal(P, 0)`. Bare `Decimal` and bare `NUMERIC` mean `Decimal(10, 0)`. Use `LEGACY_NUMERIC` for SQLite numeric affinity.
| Declaration | Precision |
| --------------- | --------- |
| `Decimal32(S)` | 9 |
| `Decimal64(S)` | 18 |
| `Decimal128(S)` | 38 |
| `Decimal256(S)` | 76 |
## Decimal Value Ranges
The coefficient must contain at most `P` digits. Values lie strictly between `-10^(P-S)` and `10^(P-S)`, in steps of `10^-S`. For example, `Decimal(5, 2)` accepts values from `-999.99` through `999.99`.
The range is checked during casts, table writes and arithmetic. Overflow raises `NUMERIC_OVERFLOW` for every supported precision.
## Operations and Result Type
| Operation | Result scale |
| ------------------------ | ------------------------------ |
| Addition and subtraction | The larger operand scale. |
| Multiplication | The sum of the operand scales. |
| Division | The left operand scale. |
Division truncates excess fractional digits toward zero. Decimal division and remainder by zero raise `INVALID_ARGUMENT`.
Cast approximate floating-point values explicitly before combining them with Decimal. A decimal literal supplied as text avoids an initial binary floating-point approximation. Statistical functions may return an approximate result even when their input is Decimal; consult the function reference.
## Examples
### Exact addition
```sql
SELECT CAST('1.20' AS Decimal(18, 2))
+ CAST('2.40' AS Decimal(18, 2)) AS amount
FORMAT csv;
```
```text
3.60
```
### Division without rounding
```sql
SELECT CAST('2.0000' AS Decimal(18, 4)) / 3,
CAST('-2.0000' AS Decimal(18, 4)) / 3
FORMAT csv;
```
```text
0.6666,-0.6666
```
### Storing prices
```sql
CREATE TABLE products(id UInt32, price Decimal(18, 2));
INSERT INTO products VALUES (1, '19.95'), (2, '5.05');
```
```sql
SELECT sum(price) AS total_price
FROM products
FORMAT csv;
```
```text
25.00
```
---
Source: https://coordinatordb.com/docs/reference/data-types/domains
Language: en
# Domain types
Domain types attach validation and useful comparison rules to a particular kind of value. UUID validates identifiers, IPv4 and IPv6 compare addresses numerically, and geometry aliases retain typed coordinate collections.
These are built-in types. CoordinatorDB does not provide a `CREATE DOMAIN` statement for defining additional SQL domains.
## Choosing a domain type
* [UUID](https://coordinatordb.com/docs/reference/data-types/uuid) stores a canonical identifier and supports generated version 4 and version 7 values.
* [IPv4](https://coordinatordb.com/docs/reference/data-types/ipv4) stores a four-byte address with numeric address ordering.
* [IPv6](https://coordinatordb.com/docs/reference/data-types/ipv6) stores an IPv6 address and normalizes its text representation.
* [Geometry types](https://coordinatordb.com/docs/reference/data-types/geometry-types) describe points, paths, rings and polygons using typed tuples and arrays.
For an address with a network prefix, use the `inet` or `cidr` types described with the [IP address functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions).
## Example
### Validated identifiers and addresses
```sql
CREATE TABLE devices(id UUID PRIMARY KEY, address IPv4);
INSERT INTO devices VALUES
('550e8400-e29b-41d4-a716-446655440000', '10.0.0.2');
```
```sql
SELECT id, address
FROM devices
FORMAT csv;
```
```text
"550e8400-e29b-41d4-a716-446655440000","10.0.0.2"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/dynamic
Language: en
# Dynamic
`Dynamic` stores values of different concrete types in the same declared column. Each value retains its active type, which can be inspected or extracted by a function.
Use Dynamic when the types are not known in advance. Use [Variant](https://coordinatordb.com/docs/reference/data-types/variant) to restrict values to a declared alternative list.
## Creating Dynamic
```text
Dynamic
Dynamic(max_types=N)
```
* `N` — A value from 0 through 254, defaulting to 32. This parameter is retained as type metadata; it does not limit the types admitted by CoordinatorDB.
SQL `NULL` is accepted without a Nullable wrapper.
## Using Dynamic type in functions
`dynamic_type(value)` returns the active type name, or `'None'` for `NULL`. `dynamic_element(value, 'Type')` extracts the payload when the active type matches and returns `NULL` otherwise.
Arithmetic uses the actual payload and retains a Dynamic result. Numeric aggregates require extraction or an explicit numeric cast. Ordering uses the active type's canonical name and then its value; distinct active numeric types are not collapsed merely because their numeric values are equal.
## Examples
### Different types in one column
```sql
CREATE TABLE observations(id UInt32, value Dynamic);
INSERT INTO observations VALUES
(1, CAST(7 AS UInt64)),
(2, 'hello'),
(3, NULL);
```
```sql
SELECT id, dynamic_type(value)
FROM observations
ORDER BY id
FORMAT csv;
```
```text
1,"UInt64"
2,"String"
3,"None"
```
### Extracting a matching type
```sql
SELECT dynamic_element(CAST('hello' AS Dynamic), 'String'),
dynamic_element(CAST('hello' AS Dynamic), 'UInt64')
FORMAT csv;
```
```text
"hello",\N
```
---
Source: https://coordinatordb.com/docs/reference/data-types/enum
Language: en
# Enum8 and Enum16
An Enum defines a fixed mapping between text labels and signed integer codes. Queries display the labels; comparison, grouping and sorting use the declared codes.
Use an Enum when the admitted labels form a known vocabulary, such as a job status. Use [String](https://coordinatordb.com/docs/reference/data-types/string) when new labels should be accepted without a schema declaration.
## Syntax
```text
Enum8('label' = code, ...)
Enum16('label' = code, ...)
Enum('label', ...)
```
Labels are case-sensitive and must be unique. Codes must also be unique. `Enum8` accepts codes from -128 through 127; `Enum16` accepts -32768 through 32767. `Enum` selects the smallest supported width containing all codes.
Omitted codes are assigned in declaration order, beginning at 1; a code after an explicit code continues from that value.
## General Rules and Usage
Writes accept declared labels or declared numeric codes. An unknown label or undeclared code is rejected. A numeric cast exposes the code; ordinary query output shows its label.
Two values from different Enum definitions compare equal only when both code and label agree. The type's implicit default is its lowest declared code. A column can still contain SQL `NULL` unless it declares `NOT NULL`.
## Usage Examples
### Job statuses
```sql
CREATE TABLE jobs
(
id UInt32,
status Enum8('pending' = 1, 'running' = 2, 'done' = 3) DEFAULT 'pending'
);
INSERT INTO jobs(id) VALUES (1);
INSERT INTO jobs VALUES (2, 'done');
```
```sql
SELECT id, status, CAST(status AS Int8) AS code
FROM jobs
ORDER BY status
FORMAT csv;
```
```text
1,"pending",1
2,"done",3
```
### Automatic numbering
```sql
SELECT CAST(CAST('medium' AS Enum('low', 'medium', 'high')) AS Int8)
FORMAT csv;
```
```text
2
```
---
Source: https://coordinatordb.com/docs/reference/data-types/fixedstring
Language: en
# FixedString
`FixedString(n)` stores exactly `n` bytes. Short input is padded with zero bytes; input longer than `n` bytes raises `STRING_TOO_LONG`.
Use this type when an external value has a fixed byte width. Use [String](https://coordinatordb.com/docs/reference/data-types/string) or `VARCHAR(n)` when the requirement is about text characters.
## Syntax
```text
FixedString(n)
```
* `n` — A positive byte length.
The size counts bytes, so a multibyte UTF-8 character can consume several positions. Padding is part of the value. Use `hex` to inspect it without embedding zero bytes in terminal output.
The length contract applies to casts, writes, defaults and generated values. A top-level column can contain SQL `NULL` unless declared `NOT NULL`.
## Examples
### Inspecting padding
```sql
SELECT hex(CAST('a' AS FixedString(3))) AS bytes,
length(CAST('a' AS FixedString(3))) AS byte_count
FORMAT csv;
```
```text
"610000",3
```
### An input at the exact byte length
```sql
SELECT hex(CAST('abc' AS FixedString(3)))
FORMAT csv;
```
```text
"616263"
```
Casting `'abcd'` to `FixedString(3)` raises `STRING_TOO_LONG`.
---
Source: https://coordinatordb.com/docs/reference/data-types/float
Language: en
# Float32, Float64 and BFloat16
Floating-point types represent approximate numeric values. They can cover a wide range, but most decimal fractions cannot be represented exactly. Use [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal) when decimal rounding differences are unacceptable.
## Syntax
```text
Float32
Float64
BFloat16
```
## Using floating-point numbers
| Type | Precision contract |
| ---------- | ------------------------------------------------------------------- |
| `Float32` | IEEE single precision, with about 7 significant decimal digits. |
| `Float64` | IEEE double precision, with about 15–16 significant decimal digits. |
| `BFloat16` | A truncated Float32 value retaining 7 fraction bits. |
Converting to a narrower type can change the value. `BFloat16` truncates the low Float32 bits; it does not round to the nearest representable value.
## NaN and Inf
Explicit positive and negative infinity are accepted. NaN is normalized to SQL `NULL`. A finite input that overflows its declared floating-point type raises `NUMERIC_OVERFLOW`.
Top-level columns accept `NULL` unless declared `NOT NULL`. Ordinary numeric comparisons, arithmetic and aggregates can consume these types; each function documents how it handles nonfinite results.
## BFloat16
`BFloat16` represents approximate numbers with seven fraction bits.
Conversion truncates the low Float32 bits. Use it when reduced precision is
acceptable.
```sql
SELECT to_type_name(CAST(1.5 AS BFloat16)), CAST(1.5 AS BFloat16)
FORMAT csv;
```
```text
"BFloat16",1.5
```
## Examples
### Precision loss in Float32
The integer `16777217` is exactly representable in Float64 but lies between two Float32 values:
```sql
SELECT CAST(16777217 AS Float32),
CAST(16777217 AS Float64)
FORMAT csv;
```
```text
16777216,16777217.0
```
### NaN becomes NULL
```sql
SELECT CAST('nan' AS Float32) IS NULL,
CAST('nan' AS Float64) IS NULL
FORMAT csv;
```
```text
1,1
```
### Explicit numeric conversion
```sql
SELECT to_float64(42), to_type_name(to_float32(42))
FORMAT csv;
```
```text
42.0,"Float32"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/geometry-types
Language: en
# Geometry types
Geometry types are named aliases over typed tuples and arrays. They preserve the shape and numeric types of coordinate collections.
## Supported types
| Type | Structure |
| ----------------- | ---------------------------------------------------- |
| `Point` | `Tuple(Float64, Float64)` — two coordinates. |
| `MultiPoint` | `Array(Point)` — independent points. |
| `Ring` | `Array(Point)` — a polygon boundary. |
| `LineString` | `Array(Point)` — an ordered path. |
| `MultiLineString` | `Array(LineString)` — a collection of paths. |
| `Polygon` | `Array(Ring)` — an outer boundary followed by holes. |
| `MultiPolygon` | `Array(Polygon)` — a collection of polygons. |
The types validate the collection shape and coordinate conversions. They do not validate topology, such as self-intersections or whether holes lie inside an outer ring.
Use consistent coordinate units for a calculation. The aliases do not assign a coordinate reference system or convert between geographic and projected coordinates.
## Examples
### A point
```sql
SELECT CAST('[1,2]' AS Point)
FORMAT csv;
```
```text
"[1,2]"
```
### Testing polygon membership
`point_in_polygon` includes the outer boundary and excludes hole boundaries:
```sql
SELECT point_in_polygon(
tuple(1, 1),
CAST('[[0,0],[2,0],[2,2],[0,2]]' AS Ring)
)
FORMAT csv;
```
```text
true
```
### Storing a polygon
```sql
CREATE TABLE regions(name String, boundary Polygon);
INSERT INTO regions VALUES
('square', '[[[0,0],[2,0],[2,2],[0,2]]]');
```
```sql
SELECT name, point_in_polygon(tuple(1, 1), boundary)
FROM regions
FORMAT csv;
```
```text
"square",true
```
See [geometry functions](https://coordinatordb.com/docs/reference/functions/regular-functions/geo) and [GeoJSON](https://coordinatordb.com/docs/reference/formats/geo-json) for geometry operations and interchange.
---
Source: https://coordinatordb.com/docs/reference/data-types/int-uint
Language: en
# Int and UInt
CoordinatorDB provides signed (`Int`) and unsigned (`UInt`) integers from 8 through 256 bits. Use a width that contains the values your column must accept. Unsigned types reject negative values.
## Syntax
```text
Int8 | Int16 | Int32 | Int64 | Int128 | Int256
UInt8 | UInt16 | UInt32 | UInt64 | UInt128 | UInt256
```
## Integer Ranges
A signed N-bit integer ranges from `-2^(N-1)` through `2^(N-1)-1`. An unsigned N-bit integer ranges from `0` through `2^N-1`.
| Type | Minimum | Maximum |
| --------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `Int8` | `-128` | `127` |
| `Int16` | `-32768` | `32767` |
| `Int32` | `-2147483648` | `2147483647` |
| `Int64` | `-9223372036854775808` | `9223372036854775807` |
| `Int128` | `-170141183460469231731687303715884105728` | `170141183460469231731687303715884105727` |
| `Int256` | `-57896044618658097711785492504343953926634992332820282019728792003956564819968` | `57896044618658097711785492504343953926634992332820282019728792003956564819967` |
| `UInt8` | `0` | `255` |
| `UInt16` | `0` | `65535` |
| `UInt32` | `0` | `4294967295` |
| `UInt64` | `0` | `18446744073709551615` |
| `UInt128` | `0` | `340282366920938463463374607431768211455` |
| `UInt256` | `0` | `115792089237316195423570985008687907853269984665640564039457584007913129639935` |
## Conversion and overflow
Inserts, updates, casts, defaults and generated expressions must fit the declared range. Out-of-range conversion raises `NUMERIC_OVERFLOW`; values do not wrap around. Fractional numeric input truncates toward zero before range checking.
Use quoted decimal text for wide values when the calling language or a JSON client cannot preserve a large integer exactly. Native wide integers support exact numeric operations; the legacy `INTEGER` declaration instead follows SQLite-style affinity.
A top-level column accepts SQL `NULL` unless it declares `NOT NULL`.
## Examples
### Creating a typed counter
```sql
CREATE TABLE counters(id UInt32 PRIMARY KEY, attempts UInt8 NOT NULL);
INSERT INTO counters VALUES (1, 255);
```
```sql
SELECT id, attempts
FROM counters
FORMAT csv;
```
```text
1,255
```
An attempt to store `256` in `attempts` raises `NUMERIC_OVERFLOW`.
### Converting a wide unsigned value
```sql
SELECT CAST('18446744073709551615' AS UInt64),
CAST('340282366920938463463374607431768211455' AS UInt128)
FORMAT csv;
```
```text
18446744073709551615,340282366920938463463374607431768211455
```
### Truncating fractional input
```sql
SELECT CAST(12.9 AS Int8), CAST(-12.9 AS Int8)
FORMAT csv;
```
```text
12,-12
```
See [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal) for exact fractional values and [floating-point types](https://coordinatordb.com/docs/reference/data-types/float) for approximate values.
---
Source: https://coordinatordb.com/docs/reference/data-types/ipv4
Language: en
# IPv4
`IPv4` stores a validated IPv4 address. Address ordering compares numeric address values rather than their text spellings, so `10.0.0.2` sorts before `10.0.0.10`.
## Syntax
```text
IPv4
```
Invalid addresses raise `TYPE_MISMATCH`. Cast an IPv4 value to UInt32 to obtain its numeric address, or to BLOB to obtain its four network-order bytes. Direct arithmetic and numeric aggregation require an explicit conversion.
An IPv4 address compares equal to its IPv4-mapped IPv6 equivalent. Use [inet and cidr functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions) for addresses with subnet prefixes.
## Examples
### Inspecting an address
```sql
SELECT CAST('10.0.0.2' AS IPv4),
CAST(CAST('10.0.0.2' AS IPv4) AS UInt32),
hex(CAST('10.0.0.2' AS IPv4))
FORMAT csv;
```
```text
"10.0.0.2",167772162,"0A000002"
```
### Sorting addresses
```sql
CREATE TABLE clients(ip IPv4);
INSERT INTO clients VALUES ('10.0.0.10'), ('10.0.0.2');
```
```sql
SELECT ip
FROM clients
ORDER BY ip
FORMAT csv;
```
```text
"10.0.0.2"
"10.0.0.10"
```
See [IPv6](https://coordinatordb.com/docs/reference/data-types/ipv6) and [IP address functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions).
---
Source: https://coordinatordb.com/docs/reference/data-types/ipv6
Language: en
# IPv6
`IPv6` stores a validated IPv6 address. Display uses lowercase hexadecimal and compressed groups of zeros. Ordering compares address values rather than their text spellings.
## Syntax
```text
IPv6
```
Invalid addresses raise `TYPE_MISMATCH`. Casting to BLOB exposes the 16 network-order bytes. An IPv4-mapped IPv6 address compares equal to its [IPv4](https://coordinatordb.com/docs/reference/data-types/ipv4) counterpart.
A top-level column permits SQL `NULL` unless it declares `NOT NULL`. Use the `inet` and `cidr` types when the value must also retain a subnet prefix.
## Examples
### Normalizing an address
```sql
SELECT CAST('2001:DB8:0:0:0:0:0:1' AS IPv6)
FORMAT csv;
```
```text
"2001:db8::1"
```
### Comparing IPv4-mapped addresses
```sql
SELECT CAST('127.0.0.1' AS IPv4)
= CAST('::ffff:127.0.0.1' AS IPv6)
FORMAT csv;
```
```text
1
```
### Storing client addresses
```sql
CREATE TABLE clients(id UInt32, ip IPv6);
INSERT INTO clients VALUES (1, '2001:db8::1'), (2, '2001:db8::2');
```
```sql
SELECT id, ip
FROM clients
ORDER BY ip
FORMAT csv;
```
```text
1,"2001:db8::1"
2,"2001:db8::2"
```
See [IP address functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions) for address and subnet operations.
---
Source: https://coordinatordb.com/docs/reference/data-types/json
Language: en
# JSON
`JSON` stores a validated JSON document. Plain JSON accepts objects, arrays and scalar documents. A JSON type with declared paths requires an object and validates those paths against their declared native types.
Use typed paths for fields with a known contract while retaining the other fields of the document.
## Creating JSON
```text
JSON
JSON(path1 T1, path2 T2, ...)
```
## Type inference for paths
Path names are case-sensitive. Dots describe nested object paths, such as `details.price`. Paths cannot be repeated or overlap a declared parent path.
Missing paths and explicit JSON nulls receive the declared type's default. A `Nullable` path retains `NULL`. A scalar value where a parent object is required is rejected. Undeclared members remain in the document.
Typed values are checked on inserts, updates, casts, defaults and generated values. JSON storage options such as `SKIP` and dynamic-subcolumn limits are not supported.
## Reading JSON paths as sub-columns
Use dotted column access, such as `doc.user_id` or `doc.details.price`, or `get_subcolumn(doc, 'details.price')`.
Declared paths return their declared native types. Undeclared paths return Dynamic values, and missing undeclared paths return `NULL`.
## Examples
### Creating a JSON column with typed paths
```sql
CREATE TABLE events
(
id UInt32,
doc JSON(user_id UInt64, details.price Decimal(18, 2))
);
INSERT INTO events VALUES
(1, '{"user_id":42,"details":{"price":"12.50"},"action":"purchase"}');
```
```sql
SELECT doc.user_id, doc.details.price,
get_subcolumn(doc, 'details.price') AS price
FROM events
FORMAT csv;
```
```text
42,12.50,12.50
```
### Defaults for missing paths
```sql
CREATE TABLE profiles(doc JSON(id UInt32, nickname Nullable(String)));
INSERT INTO profiles VALUES ('{}');
```
```sql
SELECT doc.id, doc.nickname
FROM profiles
FORMAT csv;
```
```text
0,\N
```
### Plain JSON arrays and scalars
```sql
SELECT CAST('[1,true,null]' AS JSON), CAST('42' AS JSON)
FORMAT csv;
```
```text
"[1,true,null]","42"
```
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) for extraction and transformation, and [JSON data formats](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/formats) for importing and exporting documents.
---
Source: https://coordinatordb.com/docs/reference/data-types/lowcardinality
Language: en
# LowCardinality
`LowCardinality(T)` wraps a scalar type while preserving its comparison and function behavior. It can be useful for columns whose values come from a small repeated vocabulary, such as a status or category.
## Syntax
```text
LowCardinality(T)
```
## Supported inner types
The inner type can be String, FixedString, an integer or floating-point number, a date, timestamp, clock, network address, UUID, Bool or Enum. These scalar domains may be nullable. Decimal and composite types are not accepted as the inner type.
The wrapper preserves the inner value's conversions, range checks and ordering. It is not a promise of column-wide on-disk compression or a guaranteed query speedup.
## Examples
### A status column
```sql
CREATE TABLE orders(id UInt32, status LowCardinality(String));
INSERT INTO orders VALUES (1, 'new'), (2, 'new'), (3, 'paid');
```
```sql
SELECT status, count(*) AS orders
FROM orders
GROUP BY status
ORDER BY status
FORMAT csv;
```
```text
"new",2
"paid",1
```
### Explicit conversion
`to_low_cardinality` constructs a wrapped scalar:
```sql
SELECT to_type_name(to_low_cardinality('open')),
lower(to_low_cardinality('OPEN'))
FORMAT csv;
```
```text
"LowCardinality(String)","open"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/map
Language: en
# Map
`Map(K, V)` stores an ordered collection of key/value pairs. Every key has type `K` and every value has type `V`.
Keys are not required to be unique. Duplicate keys and insertion order are retained. Keys cannot be `NULL` or have a nullable type.
## Syntax
```text
Map(K, V)
```
## Creating maps
Use `map(key, value, ...)`, a JSON object, or a JSON array of `[key, value]` pairs. Pair arrays preserve duplicate keys and allow non-string key types. Results render as pair arrays.
Every key and value is checked against its declared type. Use `Nullable(V)` when map values may be missing.
## Looking up keys
`map_element(map, key)` returns the value at the first matching key. A missing key returns the value type's default, such as zero, an empty string or `NULL` for a nullable value.
Use `map_contains` when you must distinguish a missing key from a stored default. `map_keys` and `map_values` return arrays that retain pair order and duplicates.
## Examples
### Storing counters
```sql
CREATE TABLE pages(id UInt32, counters Map(String, UInt64));
INSERT INTO pages VALUES (1, '{"views":10,"likes":2}');
```
```sql
SELECT map_element(counters, 'views'),
map_element(counters, 'shares'),
map_contains(counters, 'shares')
FROM pages
FORMAT csv;
```
```text
10,0,false
```
### Retaining duplicate keys
```sql
SELECT map_keys(map('a', 1, 'a', 2)),
map_values(map('a', 1, 'a', 2)),
map_element(map('a', 1, 'a', 2), 'a')
FORMAT csv;
```
```text
"[""a"",""a""]","[1,2]",1
```
### Non-string keys
```sql
SELECT CAST('[[1,"one"],[2,"two"]]' AS Map(UInt8, String))
FORMAT csv;
```
```text
"[[1,""one""],[2,""two""]]"
```
See [map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions) and the [Map quickstart](https://coordinatordb.com/docs/get-started/quickstarts/working-with-the-map-type).
---
Source: https://coordinatordb.com/docs/reference/data-types/nested-data-structures
Language: en
# Nested
`Nested` stores a collection of named records. Each record has the same fields and declared field types. Dotted field access returns an array of that field's values across the records.
In CoordinatorDB, a Nested value occupies one table column and behaves as an array of named tuples.
## Syntax
```text
Nested(name1 T1, name2 T2, ...)
```
Every field must have a unique name. Use `Nullable(T)` for a field that can contain missing values.
## Input values
A Nested column accepts either JSON rows or a JSON object of parallel arrays. The parallel arrays must all have the same length. Missing, duplicate or unknown fields, and unequal array lengths, are rejected.
To change records, assign a new typed value to the entire Nested column. Individual nested fields are not separate table columns.
## Examples
### Creating order items
```sql
CREATE TABLE orders(id UInt32, items Nested(sku String, quantity UInt16));
INSERT INTO orders VALUES
(1, '{"sku":["book","pen"],"quantity":[1,2]}');
```
```sql
SELECT id, items.sku, items.quantity
FROM orders
FORMAT csv;
```
```text
1,"[""book"",""pen""]","[1,2]"
```
### Replacing the item collection
The row-oriented form supplies one array per named record:
```sql
UPDATE orders
SET items = '[["book",3],["pencil",4]]'
WHERE id = 1;
```
```sql
SELECT items.sku, items.quantity
FROM orders
FORMAT csv;
```
```text
"[""book"",""pencil""]","[3,4]"
```
### Filtering on a projected field
```sql
SELECT id
FROM orders
WHERE has(items.sku, 'book')
FORMAT csv;
```
```text
1
```
See [Array](https://coordinatordb.com/docs/reference/data-types/array) and [Tuple](https://coordinatordb.com/docs/reference/data-types/tuple) for the underlying value contracts.
---
Source: https://coordinatordb.com/docs/reference/data-types/nullable
Language: en
# Nullable
`Nullable(T)` allows a missing value where a typed member would otherwise require a value of type `T`. It is particularly useful for elements of arrays, tuple fields and map values.
## Syntax
```text
Nullable(T)
```
## Column and member nullability
Top-level SQL columns permit `NULL` unless they declare `NOT NULL`, including columns whose type is written without `Nullable`. The wrapper is needed to admit `NULL` inside a native composite value.
For example, `Array(UInt8)` requires a non-`NULL` integer at every position, while `Array(Nullable(UInt8))` can contain missing elements. Map keys cannot be nullable.
`Nullable` can wrap supported collections as well as scalar types. Use a column `NOT NULL` constraint to forbid a missing value at the top level.
## Finding NULL
Most comparisons with `NULL` return `NULL`, rather than true or false. Use `IS NULL` or `IS NOT NULL` to test for a missing value. Use `coalesce` to supply a fallback. Aggregate functions document whether they skip or retain `NULL` values.
## Usage Example
### A nullable array element
```sql
SELECT CAST('[1,null,3]' AS Array(Nullable(UInt8)))
FORMAT csv;
```
```text
"[1,null,3]"
```
### Testing and replacing NULL
```sql
SELECT NULL = NULL,
NULL IS NULL,
coalesce(NULL, 7)
FORMAT csv;
```
```text
\N,1,7
```
See [NULL functions](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls) for additional operations.
---
Source: https://coordinatordb.com/docs/reference/data-types/qbit
Language: en
# QBit
`QBit` stores a numeric vector with a fixed element type and dimension. Its distance functions let a query choose how much precision to use when comparing the vector with a reference array.
## Creating QBit
```text
QBit(T, N)
QBit(T, N, stride)
```
## Parameters
* `T` — `Int8`, `BFloat16`, `Float32` or `Float64`.
* `N` — A positive number of coordinates. Every input must contain exactly `N` non-`NULL` coordinates.
* `stride` — A positive group size dividing `N`. The default is `N`. A smaller stride must be a multiple of eight.
Coordinates are converted to `T`. Use JSON array text or an array value as input.
## Vector search functions
`l2_distance_transposed`, `cosine_distance_transposed` and `dot_product_transposed` accept a QBit vector, an Array reference and a precision from 1 through the element bit width.
A full-precision probe recovers the stored coordinate values. A lower precision can change the result. The optional `used_dims` argument must be a positive multiple of stride and cannot exceed `N`; omitting it requires a reference for the full dimension.
Results are Float64. SQL `NULL` propagates, nonfinite coordinates raise an error, and cosine distance with a zero-norm vector returns `NULL`.
## Examples
### Euclidean distance
The vectors differ by one unit in their final coordinate:
```sql
SELECT l2_distance_transposed(
CAST('[1,2,3]' AS QBit(Float32, 3)),
array(1, 2, 4),
32
)
FORMAT csv;
```
```text
1.0
```
### An identical reference
```sql
SELECT l2_distance_transposed(
CAST('[1,2,3]' AS QBit(Float32, 3)),
array(1, 2, 3),
32
)
FORMAT csv;
```
```text
0.0
```
See [vector distance functions](https://coordinatordb.com/docs/reference/functions/regular-functions/distance-functions) for the complete function signatures and aliases.
---
Source: https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction
Language: en
# SimpleAggregateFunction
`SimpleAggregateFunction` stores an aggregate's scalar partial result. The value can be read directly and combined with the ordinary aggregate again, without an intermediate-state merge or finalization call.
This works for sum, minimum and maximum: summing partial sums, for example, gives the sum of all original rows. An average needs both a total and a count, so use [AggregateFunction](https://coordinatordb.com/docs/reference/data-types/aggregatefunction) for it.
## Syntax
```text
SimpleAggregateFunction(function, T)
```
* `function` — `sum`, `min` or `max`.
* `T` — The scalar value type. Assigned values must satisfy this inner type's constraints.
Construct values with `sum_simple_state`, `min_simple_state` or `max_simple_state`, or write plain scalar values to the declared column.
## Example
### Reading and combining partial totals
```sql
CREATE TABLE partial_totals
(
batch UInt8,
total SimpleAggregateFunction(sum, UInt64)
);
INSERT INTO partial_totals VALUES (1, 30), (2, 90);
```
The values can be selected directly:
```sql
SELECT batch, total
FROM partial_totals
ORDER BY batch
FORMAT csv;
```
```text
1,30
2,90
```
Combine them with ordinary `sum`:
```sql
SELECT sum(total)
FROM partial_totals
FORMAT csv;
```
```text
120
```
Inserting rows does not automatically merge rows that have the same batch. Use an explicit aggregate query when you need a combined result.
See [aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_simple_state) for the `_simple_state` constructors.
---
Source: https://coordinatordb.com/docs/reference/data-types/special-data-types
Language: en
# Special data types
[`Interval`](https://coordinatordb.com/docs/reference/data-types/special-data-types/interval) represents a signed quantity with one calendar or elapsed-time unit. Use it for date arithmetic rather than storing a duration as an unlabelled integer.
```sql
SELECT CAST('2024-01-31' AS Date) + INTERVAL 1 MONTH
FORMAT csv;
```
```text
"2024-02-29"
```
## Other special names
`Expression`, `Set` and `Nothing` have no dedicated native declarations in CoordinatorDB. Unrecognized type names follow legacy SQL affinity; declaring a column as `Nothing` does not restrict it to `NULL`.
Use [`Nullable`](https://coordinatordb.com/docs/reference/data-types/nullable) and SQL constraints for nullability, and the [supported type reference](https://coordinatordb.com/docs/reference/data-types) to choose a validated native declaration.
---
Source: https://coordinatordb.com/docs/reference/data-types/special-data-types/interval
Language: en
# Interval
An Interval is a signed quantity associated with one unit. It represents a duration or calendar offset, rather than a timestamp.
Calendar months, quarters and years preserve their calendar meaning; they are not approximated as a fixed number of seconds.
## Syntax
```text
Interval
IntervalNanosecond | IntervalMicrosecond | IntervalMillisecond
IntervalSecond | IntervalMinute | IntervalHour | IntervalDay
IntervalWeek | IntervalMonth | IntervalQuarter | IntervalYear
```
The quantity must be an integer in the signed 64-bit range. A unit-specific declaration supplies the unit for numeric input. Bare `Interval` accepts a typed interval or complete quantity-and-unit text, such as `'3 hours'`.
## Constructing intervals
SQL interval literals and the one-argument constructors create typed values:
```text
INTERVAL quantity unit
to_interval_nanosecond(quantity)
to_interval_microsecond(quantity)
to_interval_millisecond(quantity)
to_interval_second(quantity)
to_interval_minute(quantity)
to_interval_hour(quantity)
to_interval_day(quantity)
to_interval_week(quantity)
to_interval_month(quantity)
to_interval_quarter(quantity)
to_interval_year(quantity)
```
## Arithmetic
Adding or subtracting intervals combines elapsed units exactly, or calendar units in months. Mixing the two categories is rejected. One Interval value cannot retain an arbitrary combination of symbolic calendar and elapsed fields.
Adding a calendar interval to a date clamps to a valid day at the end of the target month. Adding a subday interval to a Date produces a DateTime64. Timestamp calendar arithmetic preserves local time and rejects ambiguous or nonexistent local results.
## Examples
### Constructing values
```sql
SELECT to_interval_day(2), CAST('3 hours' AS Interval)
FORMAT csv;
```
```text
"2 day","3 hour"
```
### Adding a calendar month
The target February does not have a 31st day:
```sql
SELECT CAST('2024-01-31' AS Date) + INTERVAL 1 MONTH
FORMAT csv;
```
```text
"2024-02-29"
```
### Converting calendar units
```sql
SELECT CAST(to_interval_quarter(2) AS IntervalMonth)
FORMAT csv;
```
```text
"6 month"
```
See [date and time functions](https://coordinatordb.com/docs/reference/functions/regular-functions/date-time-functions) for additional calendar operations.
---
Source: https://coordinatordb.com/docs/reference/data-types/string
Language: en
# String and VARCHAR
`String` stores variable-length UTF-8 text. Use it for names, labels, messages and other character data. Use `BLOB` for arbitrary bytes and [FixedString](https://coordinatordb.com/docs/reference/data-types/fixedstring) for a fixed byte length.
## Syntax
```text
String
VARCHAR
VARCHAR(n)
NVARCHAR
NVARCHAR(n)
CHARACTER VARYING
CHARACTER VARYING(n)
```
## Length limits
`String` and the declarations without a length have no declared character limit. `VARCHAR(n)` and its length-qualified aliases accept at most `n` Unicode characters, including embedded NUL characters.
The limit counts characters, not UTF-8 bytes. Overlong input raises `STRING_TOO_LONG`; it is not silently truncated. Invalid UTF-8 binary input raises a conversion error.
These rules apply to casts, inserts, updates, defaults and generated values. A top-level column accepts `NULL` unless declared `NOT NULL`.
## Examples
### Storing Unicode text
```sql
CREATE TABLE labels(id UInt32, name VARCHAR(5));
INSERT INTO labels VALUES (1, 'hello'), (2, 'café');
```
```sql
SELECT id, name, length(name) AS characters
FROM labels
ORDER BY id
FORMAT csv;
```
```text
1,"hello",5
2,"café",4
```
A six-character value cannot be stored in this `name` column.
### Casting to a limited string
```sql
SELECT CAST('abc' AS VARCHAR(3)), CAST(42 AS String)
FORMAT csv;
```
```text
"abc","42"
```
See [string functions](https://coordinatordb.com/docs/reference/functions/regular-functions/string-functions) for length, case conversion, slicing and concatenation.
---
Source: https://coordinatordb.com/docs/reference/data-types/time
Language: en
# Time
`Time` represents signed whole seconds without a calendar date or timezone. It can describe a clock value or an elapsed duration, including negative values and durations longer than one day.
## Syntax
```text
Time
```
## Input and range
Numeric input is a number of seconds. Text input uses a clock representation such as `'12:30:00'` or `'-01:02:03'`. Hours may exceed 23. Minute and second components are normalized, so `'25:70:70'` becomes `'26:11:10'`.
The numeric value must fit signed 32-bit seconds. Text display saturates at `999:59:59` in either direction; numeric casts and comparisons preserve the actual stored seconds. Timezone parameters are not accepted.
Adding a Time to a Date produces a UTC timestamp. Subtracting clocks produces an exact Decimal number of seconds. Use [Time64](https://coordinatordb.com/docs/reference/data-types/time64) for fractional seconds.
## Examples
### Reading durations
```sql
SELECT CAST('25:70:70' AS Time), CAST('-01:02:03' AS Time)
FORMAT csv;
```
```text
"26:11:10","-01:02:03"
```
### Converting seconds
```sql
SELECT CAST(3723 AS Time), CAST(CAST('01:02:03' AS Time) AS INTEGER)
FORMAT csv;
```
```text
"01:02:03",3723
```
### Combining a date and a clock
```sql
SELECT CAST('2025-03-05' AS Date) + CAST('12:30:00' AS Time)
FORMAT csv;
```
```text
"2025-03-05 12:30:00"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/time64
Language: en
# Time64
`Time64(P)` represents signed seconds with `P` fractional digits, without a calendar date or timezone. Values can be negative and can exceed 24 hours.
## Syntax
```text
Time64
Time64(P)
```
* `P` — Fractional-second precision from 0 through 9. The default is 3.
## Input and conversion
Numeric input is always seconds, including integer input. This differs from [DateTime64](https://coordinatordb.com/docs/reference/data-types/datetime64), whose integer input is ticks. Clock text can include a sign and a fractional part; excess fraction digits are truncated to the declared precision.
The value must fit signed 64-bit ticks. Displayed clock components saturate at `999:59:59` plus the declared fraction, while arithmetic and numeric casts retain the underlying value. Timezone arguments are not accepted.
Adding a Time64 to a Date produces a UTC timestamp. Numeric operations consume seconds, including the fraction. Cast to Decimal when an aggregate must preserve an exact fixed-scale total.
## Examples
### Seconds and fractional text
```sql
SELECT CAST(3723 AS Time64(3)),
CAST('-01:02:03.123' AS Time64(3))
FORMAT csv;
```
```text
"01:02:03.000","-01:02:03.123"
```
### Reading an exact numeric duration
```sql
SELECT CAST(CAST('01:02:03.125' AS Time64(3)) AS Decimal(18, 3))
FORMAT csv;
```
```text
3723.125
```
### Truncating fractional digits
```sql
SELECT CAST('00:00:01.123456' AS Time64(3))
FORMAT csv;
```
```text
"00:00:01.123"
```
---
Source: https://coordinatordb.com/docs/reference/data-types/tuple
Language: en
# Tuple
A Tuple groups a fixed number of values into one value. Each field has its own declared type. Fields can be addressed by position, and named fields can also be addressed by name.
## Syntax
```text
Tuple(T1, T2, ...)
Tuple(name1 T1, name2 T2, ...)
```
A tuple must contain at least one field. Either every field is named or every field is positional. Names must be nonempty, unique and case-sensitive.
## Creating Tuples
Construct a tuple with `tuple(...)` or provide JSON array text with exactly the declared number of fields. A named tuple also accepts a JSON object with exactly its declared field names.
Every field is converted to its declared type. Use `Nullable(T)` for a field that can contain SQL `NULL`.
## Referring to Tuple Elements
`tuple_element(value, position)` uses a positive one-based position within the declared field count. For named tuples, `tuple_element(value, 'name')` and dotted column access select the named field.
## Examples
### A positional tuple
```sql
SELECT tuple_element(CAST('[7,"Ada"]' AS Tuple(UInt32, String)), 2)
FORMAT csv;
```
```text
"Ada"
```
### Named records in a table
```sql
CREATE TABLE users(profile Tuple(id UInt64, name String));
INSERT INTO users VALUES ('{"id":7,"name":"Ada"}');
```
```sql
SELECT profile.id, profile.name,
tuple_element(profile, 'name') AS selected_name
FROM users
FORMAT csv;
```
```text
7,"Ada","Ada"
```
### A nullable field
```sql
SELECT CAST('[7,null]' AS Tuple(UInt32, Nullable(String)))
FORMAT csv;
```
```text
"[7,null]"
```
See [Nested](https://coordinatordb.com/docs/reference/data-types/nested-data-structures) for arrays of named records and [tuple functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-functions) for operations on tuple values.
---
Source: https://coordinatordb.com/docs/reference/data-types/uuid
Language: en
# UUID
`UUID` stores a universally unique identifier. Text input is parsed as a UUID and displayed using its canonical lowercase, hyphenated spelling.
## Syntax
```text
UUID
```
Invalid UUID text raises `TYPE_MISMATCH`. UUID values support equality, ordering, grouping and indexes. They are identifiers rather than numeric operands; direct numeric arithmetic and numeric aggregates reject them.
Use `gen_random_uuid()` for a random version 4 UUID or `uuidv7()` for a time-ordered version 7 UUID. These functions produce native UUID values.
## Usage Example
### Normalizing UUID text
```sql
SELECT CAST('550E8400-E29B-41D4-A716-446655440000' AS UUID)
FORMAT csv;
```
```text
"550e8400-e29b-41d4-a716-446655440000"
```
### Using a UUID key
```sql
CREATE TABLE documents(id UUID PRIMARY KEY, title String);
INSERT INTO documents VALUES
('550e8400-e29b-41d4-a716-446655440000', 'Project notes');
```
```sql
SELECT title
FROM documents
WHERE id = '550e8400-e29b-41d4-a716-446655440000'
FORMAT csv;
```
```text
"Project notes"
```
### Checking a generated UUID version
```sql
SELECT uuid_extract_version(gen_random_uuid()),
uuid_extract_version(uuidv7())
FORMAT csv;
```
```text
4,7
```
See [UUID functions](https://coordinatordb.com/docs/reference/functions/regular-functions/uuid-functions) for generation, version extraction and timestamp extraction.
---
Source: https://coordinatordb.com/docs/reference/data-types/variant
Language: en
# Variant
`Variant` stores one active value from a declared set of types. Each value retains its selected type, so text and numeric alternatives remain distinguishable.
## Creating Variant
```text
Variant(T1, T2, ...)
```
A Variant supports up to 254 distinct, nonnullable alternatives. Canonical type-name order determines their declaration order. Directly nested unions, nullable alternatives and similar numeric or calendar alternatives are rejected.
SQL `NULL` is accepted without a Nullable wrapper.
## Conversion between Variant and other columns
A value whose concrete type is an admitted alternative keeps it. Otherwise numeric values try a numeric alternative first. Text is tried against non-string alternatives before falling back to String.
A text value that would lose a fraction when converted to an integer remains String when that alternative is available. For example, `'123'` can select UInt64, while `'1.5'` remains String.
## Functions with Variant arguments
`variant_type(value)` returns the active type name, or `'None'` for `NULL`. `variant_element(value, 'Type')` extracts that alternative. An admitted but inactive alternative returns `NULL`; requesting an undeclared alternative raises an error.
Extract a numeric alternative before arithmetic. Ordering compares the active type's canonical name and then the contained value; equal numbers in different active types remain distinct.
## Examples
### Inspecting the active type
```sql
SELECT variant_type(CAST('123' AS Variant(UInt64, String))),
variant_type(CAST('hello' AS Variant(UInt64, String))),
variant_type(CAST('1.5' AS Variant(UInt64, String)))
FORMAT csv;
```
```text
"UInt64","String","String"
```
### Extracting an admitted alternative
```sql
SELECT variant_element(CAST('123' AS Variant(UInt64, String)), 'UInt64') + 1,
variant_element(CAST('hello' AS Variant(UInt64, String)), 'UInt64')
FORMAT csv;
```
```text
124,\N
```
See [Dynamic](https://coordinatordb.com/docs/reference/data-types/dynamic) when the alternative types are not known in advance.
---
Source: https://coordinatordb.com/docs/reference/errors
Language: en
# Error codes
## Error response
Failures include a CoordinatorDB number, symbolic name and operation-specific
message. The same identifier appears in the native response, CLI diagnostic and
query log. Successful query-log events use zero and an empty exception.
```text
Code: 1002. CoordinatorDB::Exception: no such table: users (UNKNOWN_TABLE)
```
## Identifying a failure
These numbers are independent of SQLite result codes and ClickHouse error codes.
Messages can include object names and other details; use the number or symbolic
name to identify the failure. The embedded API exposes code(), name(),
error_code() and message(); primary_code() exposes the separate SQLite-compatible
result code.
HTTP errors include X-Coordinator-Exception-Code. An HTTP status groups transport
and SQL failures and does not replace the database error identifier. See the
[HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) for status mapping.
## Registry
| Code | Name |
| ---- | ----------------------------------- |
| 1000 | `SQL_ERROR` |
| 1001 | `SYNTAX_ERROR` |
| 1002 | `UNKNOWN_TABLE` |
| 1003 | `UNKNOWN_COLUMN` |
| 1004 | `UNKNOWN_DATABASE` |
| 1005 | `UNKNOWN_INDEX` |
| 1006 | `UNKNOWN_VIEW` |
| 1007 | `UNKNOWN_TRIGGER` |
| 1008 | `UNKNOWN_FUNCTION` |
| 1009 | `UNKNOWN_COLLATION` |
| 1010 | `OBJECT_ALREADY_EXISTS` |
| 1011 | `AMBIGUOUS_COLUMN` |
| 1012 | `INVALID_ARGUMENT` |
| 1013 | `UNSUPPORTED_FEATURE` |
| 1014 | `INVALID_TRANSACTION_STATE` |
| 1015 | `UNKNOWN_SAVEPOINT` |
| 1016 | `NO_DATABASE_SELECTED` |
| 1017 | `READ_ONLY` |
| 1018 | `TYPE_MISMATCH` |
| 1019 | `NUMERIC_OVERFLOW` |
| 1020 | `SCHEMA_CHANGED` |
| 1021 | `STRING_TOO_LONG` |
| 1022 | `UNKNOWN_FORMAT` |
| 1023 | `FORMAT_IS_NOT_SUITABLE_FOR_INPUT` |
| 1024 | `FORMAT_IS_NOT_SUITABLE_FOR_OUTPUT` |
| 1025 | `INCORRECT_DATA` |
| 1026 | `DUPLICATE_JSON_KEY` |
| 2000 | `FORMAT_ERROR` |
| 3000 | `IO_ERROR` |
| 3001 | `DATABASE_LOCKED` |
| 4000 | `CONSTRAINT_VIOLATION` |
| 4001 | `PRIMARY_KEY_VIOLATION` |
| 4002 | `UNIQUE_VIOLATION` |
| 4003 | `NOT_NULL_VIOLATION` |
| 4004 | `CHECK_VIOLATION` |
| 4005 | `FOREIGN_KEY_VIOLATION` |
| 4006 | `ROWID_VIOLATION` |
| 4007 | `TRIGGER_VIOLATION` |
| 5000 | `UNKNOWN_ERROR` |
| 5001 | `PROTOCOL_ERROR` |
| 5002 | `CONFIGURATION_ERROR` |
| 5003 | `RESPONSE_TOO_LARGE` |
| 5004 | `INTERNAL_ERROR` |
| 5005 | `AUTHENTICATION_FAILED` |
| 6000 | `QUERY_TIME_LIMIT_EXCEEDED` |
| 6001 | `QUERY_MEMORY_LIMIT_EXCEEDED` |
| 6002 | `RESULT_ROWS_LIMIT_EXCEEDED` |
| 6003 | `RESULT_BYTES_LIMIT_EXCEEDED` |
| 6004 | `CONNECTION_LIMIT_EXCEEDED` |
| 6005 | `REQUEST_MEMORY_LIMIT_EXCEEDED` |
| 6006 | `REQUEST_READ_TIMEOUT` |
## Related contracts
Resource errors distinguish query time, accounted query memory, returned rows, encoded bytes, connection admission and incoming request memory. Use the permanent identifier to select the relevant limit; the message supplies details for the failing operation.
See [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity), [HTTP responses](https://coordinatordb.com/docs/concepts/features/interfaces/http#status-codes) and [query_log](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/reference/formats
Language: en
# Formats
CoordinatorDB reads rows with `INSERT ... FORMAT` and writes query results with
`SELECT ... FORMAT`. A format can support input, output, or both. The default
output format is `pretty_compact`.
Format names are case-insensitive. Use the snake_case names listed below;
ClickHouse CamelCase names are not aliases.
## Formats overview
| Format | Input | Output |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ |
| [arrow](https://coordinatordb.com/docs/reference/formats/arrow/arrow) | Yes | Yes |
| [arrow_stream](https://coordinatordb.com/docs/reference/formats/arrow/arrow-stream) | Yes | Yes |
| [avro](https://coordinatordb.com/docs/reference/formats/avro/avro) | Yes | Yes |
| [avro_confluent](https://coordinatordb.com/docs/reference/formats/avro/avro-confluent) | Yes | Yes |
| [bson_each_row](https://coordinatordb.com/docs/reference/formats/bson-each-row) | Yes | Yes |
| [csv](https://coordinatordb.com/docs/reference/formats/csv/csv) | Yes | Yes |
| [csv_with_names](https://coordinatordb.com/docs/reference/formats/csv/csv-with-names) | Yes | Yes |
| [csv_with_names_and_types](https://coordinatordb.com/docs/reference/formats/csv/csv-with-names-and-types) | Yes | Yes |
| [custom_separated](https://coordinatordb.com/docs/reference/formats/custom-separated/custom-separated) | Yes | Yes |
| [custom_separated_with_names](https://coordinatordb.com/docs/reference/formats/custom-separated/custom-separated-with-names) | Yes | Yes |
| [form](https://coordinatordb.com/docs/reference/formats/form) | Yes | No |
| [geo_json](https://coordinatordb.com/docs/reference/formats/geo-json) | Yes | Yes |
| [hash](https://coordinatordb.com/docs/reference/formats/hash) | No | Yes |
| [hive_text](https://coordinatordb.com/docs/reference/formats/hive-text) | Yes | Yes |
| [json](https://coordinatordb.com/docs/reference/formats/json/json) | Yes | Yes |
| [json_as_object](https://coordinatordb.com/docs/reference/formats/json/json-as-object) | Yes | No |
| [json_as_string](https://coordinatordb.com/docs/reference/formats/json/json-as-string) | Yes | No |
| [json_columns](https://coordinatordb.com/docs/reference/formats/json/json-columns) | Yes | Yes |
| [json_compact](https://coordinatordb.com/docs/reference/formats/json/json-compact) | No | Yes |
| [json_compact_columns](https://coordinatordb.com/docs/reference/formats/json/json-compact-columns) | Yes | Yes |
| [json_compact_each_row](https://coordinatordb.com/docs/reference/formats/json/json-compact-each-row) | Yes | Yes |
| [json_compact_each_row_with_names_and_types](https://coordinatordb.com/docs/reference/formats/json/json-compact-each-row-with-names-and-types) | Yes | Yes |
| [json_compact_strings_each_row](https://coordinatordb.com/docs/reference/formats/json/json-compact-strings-each-row) | Yes | Yes |
| [json_each_row](https://coordinatordb.com/docs/reference/formats/json/json-each-row) | Yes | Yes |
| [json_object_each_row](https://coordinatordb.com/docs/reference/formats/json/json-object-each-row) | Yes | Yes |
| [json_strings_each_row](https://coordinatordb.com/docs/reference/formats/json/json-strings-each-row) | Yes | Yes |
| [line_as_string](https://coordinatordb.com/docs/reference/formats/line-as-string/line-as-string) | Yes | Yes |
| [markdown](https://coordinatordb.com/docs/reference/formats/markdown) | No | Yes |
| [msg_pack](https://coordinatordb.com/docs/reference/formats/msg-pack) | Yes | Yes |
| [npy](https://coordinatordb.com/docs/reference/formats/npy) | Yes | Yes |
| [null_output](https://coordinatordb.com/docs/reference/formats/null-output) | No | Yes |
| [parquet](https://coordinatordb.com/docs/reference/formats/parquet/parquet) | Yes | Yes |
| [parquet_metadata](https://coordinatordb.com/docs/reference/formats/parquet/parquet-metadata) | Yes | No |
| [png](https://coordinatordb.com/docs/reference/formats/png) | No | Yes |
| [pretty_compact](https://coordinatordb.com/docs/reference/formats/pretty/pretty-compact) | No | Yes |
| [protobuf](https://coordinatordb.com/docs/reference/formats/protobuf/protobuf) | Yes | Yes |
| [regexp](https://coordinatordb.com/docs/reference/formats/regexp) | Yes | No |
| [row_binary](https://coordinatordb.com/docs/reference/formats/row-binary/row-binary) | Yes | Yes |
| [row_binary_with_names](https://coordinatordb.com/docs/reference/formats/row-binary/row-binary-with-names) | Yes | Yes |
| [row_binary_with_names_and_types](https://coordinatordb.com/docs/reference/formats/row-binary/row-binary-with-names-and-types) | Yes | Yes |
| [sql_insert](https://coordinatordb.com/docs/reference/formats/sql-insert) | No | Yes |
| [sql_values](https://coordinatordb.com/docs/reference/formats/sql-values) | Yes | Yes |
| [sqlite](https://coordinatordb.com/docs/reference/formats/sqlite) | Yes | Yes |
| [tab_separated](https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated) | Yes | Yes |
| [tab_separated_raw](https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-raw) | Yes | Yes |
| [tab_separated_with_names](https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-with-names) | Yes | Yes |
| [tab_separated_with_names_and_types](https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-with-names-and-types) | Yes | Yes |
| [template](https://coordinatordb.com/docs/reference/formats/template/template) | Yes | Yes |
| [tskv](https://coordinatordb.com/docs/reference/formats/tab-separated/tskv) | Yes | Yes |
| [vertical](https://coordinatordb.com/docs/reference/formats/vertical) | No | Yes |
| [xml](https://coordinatordb.com/docs/reference/formats/xml) | No | Yes |
| [yaml](https://coordinatordb.com/docs/reference/formats/yaml) | Yes | Yes |
Use [format settings](https://coordinatordb.com/docs/reference/settings/formats) in a statement's `SETTINGS` clause.
These settings apply to one statement and are not persisted by `SET`. On an
`INSERT`, put `SETTINGS` before `FORMAT`: the bytes after the format name are
input data.
## Reading and writing data
Create a destination table:
```sql
CREATE TABLE people (id UInt32, name String);
```
Read two CSV rows in a separate request:
```sql
INSERT INTO people FORMAT csv
1,Ada
2,Grace
```
Write the same rows as one JSON object per line:
```sql
SELECT id, name FROM people ORDER BY id FORMAT json_each_row;
```
```text
{"id":1,"name":"Ada"}
{"id":2,"name":"Grace"}
```
Inline input occupies the rest of its request. Send later SQL in another request.
For client files, see the [loading guide](https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro).
## Format schema
Schema-bearing containers include Arrow, Parquet, Avro, NumPy, and SQLite.
Input values must still satisfy the destination column declarations.
The `protobuf` format uses the statement settings `protobuf_schema` and
`protobuf_message` for its inline schema and message name. The
`avro_confluent` format resolves schema identifiers through its configured
schema registry. See their format pages for complete examples.
A container schema does not replace an explicit server `file()` schema except
for the input formats that support inference or supply fixed metadata columns.
See [file schemas](https://coordinatordb.com/docs/concepts/features/interfaces/schema-inference).
---
Source: https://coordinatordb.com/docs/reference/formats/arrow/arrow
Language: en
# arrow
## Description
Arrow IPC file with a schema, record batches and footer. Use arrow_stream for an IPC stream.
Input and output. Select it with `FORMAT arrow`. Names ignore ASCII case; use the snake_case name shown here.
Use this file layout when the consumer expects an Arrow IPC file with a footer. The stream variant has a different envelope and must be selected explicitly.
Input matches named fields to the target schema; arrow_ignore_case can relax ASCII case matching. Missing and unknown fields follow the listed settings. Nested arrays, tuples and maps use recursive Arrow types. A native file() source still requires an explicit schema.
```text
SELECT expressions FORMAT arrow;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT arrow
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT arrow" > sample.arrow
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT arrow" < sample.arrow > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| --------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `arrow_compression` | `String` | `lz4_frame` | Compress record batch buffers with lz4_frame or zstd; none writes uncompressed buffers. |
| `arrow_date_as_number` | `Bool` | `0` | Write Date as UInt16 days since the epoch instead of Date32; Date32 always remains Date32. |
| `arrow_dictionary` | `Bool` | `0` | Write LowCardinality as dictionary indices and values instead of expanding its scalars. |
| `arrow_dictionary_64bit_indices` | `Bool` | `0` | Use 64-bit dictionary indices instead of the smallest width that fits the dictionary. |
| `arrow_dictionary_signed_indices` | `Bool` | `1` | Use signed dictionary indices; when off, use unsigned indices. |
| `arrow_fixed_strings` | `Bool` | `1` | Write FixedString with a fixed byte width instead of variable-length Binary. |
| `arrow_ignore_case` | `Bool` | `0` | Ignore ASCII case when matching input field names to target columns. |
| `arrow_missing_as_default` | `Bool` | `1` | Give target columns absent from the input schema their DEFAULT; when off, reject missing columns. |
| `arrow_strings_as_text` | `Bool` | `1` | Write text strings as Utf8 instead of Binary; byte strings keep their exact bytes. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Native value | Arrow representation |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INTEGER, UInt64, Bool, Float32/64 | Int64, UInt64, Boolean, Float32/64. Top-level narrow integers retain only their runtime 64-bit class; typed collection members retain their declared width. |
| String/TEXT, BLOB, FixedString | Utf8, Binary, FixedSizeBinary. Settings can write text as Binary and FixedString as variable-width Binary. Bytes and padding remain exact. |
| Enum8/16, IPv4, IPv6, UUID | Int8/16 codes, UInt32, FixedSizeBinary(16), FixedSizeBinary(16). |
| Date/Date32, DateTime, DateTime64 | Date32 epoch days, UInt32 epoch seconds, Timestamp with timezone. Date can instead use UInt16 days. Fractional ticks use the next exact Arrow unit: milliseconds, microseconds, or nanoseconds; overflow is an error. |
| Time/Time64 | Time32 seconds/milliseconds or Time64 microseconds/nanoseconds. Output accepts clocks from 00:00 inclusive to 24:00 exclusive; native negative or longer elapsed times return NUMERIC_OVERFLOW. |
| Decimal/Decimal256 | Decimal128/Decimal256 with precision and scale. |
| Int128/UInt128/Int256/UInt256 | FixedSizeBinary(16/32), little-endian with two's complement for signed integers. |
| Interval | Duration for seconds and smaller units; Int64 quantities for larger units. |
| Array, Tuple, Map | List, Struct, Map, with recursive member types and NULLs. Named Tuple fields retain their names. |
| Nullable, LowCardinality, SimpleAggregateFunction | Inner representation; LowCardinality can instead use Dictionary. |
---
Source: https://coordinatordb.com/docs/reference/formats/arrow/arrow-stream
Language: en
# arrow_stream
## Description
Arrow IPC stream with a schema, record batches and an end marker.
Input and output. Select it with `FORMAT arrow_stream`. Names ignore ASCII case; use the snake_case name shown here.
Use this layout with consumers expecting sequential Arrow IPC messages rather than a seekable IPC file. A stream begins with its schema, can contain several record batches and must end cleanly; trailing bytes after its end marker are rejected.
The value mappings are the same as arrow. Use explicit target declarations when importing and the native client exact-byte mode when exporting.
```text
SELECT expressions FORMAT arrow_stream;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT arrow_stream
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT arrow_stream" > sample.arrow_stream
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT arrow_stream" < sample.arrow_stream > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| --------------------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------- |
| `arrow_compression` | `String` | `lz4_frame` | Compress record batch buffers with lz4_frame or zstd; none writes uncompressed buffers. |
| `arrow_date_as_number` | `Bool` | `0` | Write Date as UInt16 days since the epoch instead of Date32; Date32 always remains Date32. |
| `arrow_dictionary` | `Bool` | `0` | Write LowCardinality as dictionary indices and values instead of expanding its scalars. |
| `arrow_dictionary_64bit_indices` | `Bool` | `0` | Use 64-bit dictionary indices instead of the smallest width that fits the dictionary. |
| `arrow_dictionary_signed_indices` | `Bool` | `1` | Use signed dictionary indices; when off, use unsigned indices. |
| `arrow_fixed_strings` | `Bool` | `1` | Write FixedString with a fixed byte width instead of variable-length Binary. |
| `arrow_ignore_case` | `Bool` | `0` | Ignore ASCII case when matching input field names to target columns. |
| `arrow_missing_as_default` | `Bool` | `1` | Give target columns absent from the input schema their DEFAULT; when off, reject missing columns. |
| `arrow_strings_as_text` | `Bool` | `1` | Write text strings as Utf8 instead of Binary; byte strings keep their exact bytes. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/avro/avro
Language: en
# avro
## Description
Avro object container with an embedded record schema and independently compressed blocks.
Input and output. Select it with `FORMAT avro`. Names ignore ASCII case; use the snake_case name shown here.
The root schema must be a record. Field names match exactly, including case, and their source order can differ from destination column order. Missing target fields and NULL values in non-nullable native targets follow the corresponding Avro settings.
The schema is embedded in the container, so a registry is unnecessary for this variant. Recursive schemas and nesting beyond 64 levels are unsupported. Output types are inferred from runtime values; incompatible values in one column raise an error.
```text
SELECT expressions FORMAT avro;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT avro
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT avro" > sample.avro
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT avro" < sample.avro > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `avro_block_bytes` | `UInt64` | `16384` | Target uncompressed bytes per output block, from 32 through 1073741824; a complete row may exceed the target. |
| `avro_compression` | `String` | `''` | Output block compression: null, deflate, snappy, or zstd; empty selects snappy. |
| `avro_missing_as_default` | `Bool` | `0` | Give target fields absent from the input schema their SQL DEFAULT or native type default; otherwise reject them. |
| `avro_null_as_default` | `Bool` | `0` | Replace input NULL in a non-nullable native target with its SQL DEFAULT or native type default; legacy SQL columns retain NULL. |
| `avro_string_columns` | `String` | `''` | Regular expression matching output String column paths to encode as UTF-8 string instead of bytes; empty matches none. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Native value | Avro representation |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| INTEGER, UInt64; typed integers through 32 bits | `long`; retained narrow collection members use `int`. Unsigned UInt32/UInt64 preserve their bits in signed Avro int/long values; a matching unsigned target recovers them. |
| Bool, Float32/64, BFloat16 | `boolean`, `float`, `double`, or `float` for BFloat16. |
| String/TEXT, BLOB, FixedString | `bytes`, `bytes`, `fixed(N)`. `avro_string_columns` can select String paths for UTF-8 `string`. |
| Enum8/16 | Named `enum` with its labels; labels must be valid Avro symbols. |
| Date/Date32 | `int` with logical type `date`. |
| DateTime, DateTime64 | Epoch-second `long` for DateTime; `timestamp-millis` or `timestamp-micros` for precision 3 or 6. Other DateTime64 precisions use a decimal coefficient with the original scale. The target declaration supplies the timezone. |
| Decimal32/64/128/256 | `bytes` with logical type `decimal`, retaining precision and scale; coefficients use big-endian two's complement. |
| UUID, IPv4, IPv6 | UUID `string`, signed `int` containing IPv4 bits, or `fixed(16)` address bytes. |
| Int128/UInt128, Int256/UInt256 | `fixed(16/32)` little-endian coefficients, with two's complement for signed integers. |
| Array, Tuple, Map | Recursive `array`, named `record`, or `map` with string keys. Ordered Map entries keep their order; composite keys, binary keys that are not UTF-8, or keys that become duplicate strings are rejected. |
| Nullable, Variant | A union containing `null`; each wire branch must identify one native alternative. Ambiguous equal-width fixed types or multiple record/enum alternatives are rejected before output. |
| LowCardinality, SimpleAggregateFunction | Their contained scalar or collection representation. |
---
Source: https://coordinatordb.com/docs/reference/formats/avro/avro-confluent
Language: en
# avro_confluent
## Description
Consecutive Avro records prefixed with a zero byte and a big-endian registry schema ID. Configure avro_confluent_registry_url; output also needs avro_confluent_subject. This is a schema-registry format, rather than an Avro object container.
Input and output. Select it with `FORMAT avro_confluent`. Names ignore ASCII case; use the snake_case name shown here.
Every record carries a schema identifier rather than an embedded object-container schema. Input resolves that identifier through the configured registry. Output registers or obtains a schema under the configured subject.
Supply a reachable registry URL on the statement. Output also needs a writable subject. These are external-service requirements; ordinary avro files use a different envelope.
```text
SELECT expressions FORMAT avro_confluent;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT avro_confluent
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
Set `avro_confluent_registry_url` to your running schema registry and `avro_confluent_subject` to a writable subject before export. A registry-dependent command requires that external service.
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='avro_confluent' FORMAT csv;
```
```text
"avro_confluent",1,1
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `avro_confluent_connect_timeout` | `UInt64` | `1` | Connection and TLS handshake timeout in seconds; positive values are capped at 599. |
| `avro_confluent_receive_timeout` | `UInt64` | `1` | Registry response receive timeout in seconds; positive values are capped at 599. |
| `avro_confluent_registry_url` | `String` | `''` | HTTP or HTTPS schema registry base URL; URL-encoded credentials select Basic authentication. |
| `avro_confluent_retries` | `UInt64` | `5` | Retry transient registry failures this many times; zero disables retries and values above 20 are capped at 20. |
| `avro_confluent_retry_delay_ms` | `UInt64` | `100` | Initial retry delay in milliseconds, capped at 60000; subsequent delays double up to 10000 milliseconds. |
| `avro_confluent_send_timeout` | `UInt64` | `1` | Registry request send timeout in seconds; positive values are capped at 599. |
| `avro_confluent_subject` | `String` | `''` | Subject under which an output record schema is registered; required for avro_confluent output. |
| `avro_missing_as_default` | `Bool` | `0` | Give target fields absent from the input schema their SQL DEFAULT or native type default; otherwise reject them. |
| `avro_null_as_default` | `Bool` | `0` | Replace input NULL in a non-nullable native target with its SQL DEFAULT or native type default; legacy SQL columns retain NULL. |
| `avro_string_columns` | `String` | `''` | Regular expression matching output String column paths to encode as UTF-8 string instead of bytes; empty matches none. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Export and import
Start a compatible schema registry first. Set the URL below to that registry; this example uses a writable subject named docs-example and a fresh destination table.
```sh
export COORDINATOR_SCHEMA_REGISTRY_URL=http://127.0.0.1:8081
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id SETTINGS avro_confluent_registry_url='$COORDINATOR_SCHEMA_REGISTRY_URL',avro_confluent_subject='docs-example' FORMAT avro_confluent" > sample.avro_confluent
./coordinator client --database data --query "CREATE TABLE registry_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO registry_import SETTINGS avro_confluent_registry_url='$COORDINATOR_SCHEMA_REGISTRY_URL' FORMAT avro_confluent" < sample.avro_confluent > /dev/null
./coordinator client --database data --query "SELECT id FROM registry_import FORMAT csv"
```
```text
7
```
---
Source: https://coordinatordb.com/docs/reference/formats/bson-each-row
Language: en
# bson_each_row
## Description
Consecutive binary BSON documents, one named document for each row.
Input and output. Select it with `FORMAT bson_each_row`. Names ignore ASCII case; use the snake_case name shown here.
Each row is one BSON document with a length and terminator. Documents follow one another without an outer array or separator. Field names identify columns; missing fields use defaults, and malformed lengths, unsupported tags or ambiguous fields are errors.
String output is binary by default; bson_strings selects BSON String for text and FixedString. Wide exact numbers use fixed-width binary coefficients rather than BSON decimal128. Use matching target declarations to recover their native types.
```text
SELECT expressions FORMAT bson_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT bson_each_row
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT bson_each_row" > sample.bson_each_row
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT bson_each_row" < sample.bson_each_row > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `bson_strings` | `Bool` | `0` | Write text and fixed-width strings as BSON String instead of Binary. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Value | BSON representation |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NULL | Null (`0x0a`). |
| Bool | Boolean (`0x08`), one byte containing 0 or 1. |
| INTEGER, UInt64 | Int64 (`0x12`). UInt64 retains all 64 bits. Top-level values do not retain narrow declared widths, so Int8/16/32 and UInt8/16 also write int64. Inside typed collections those widths use int32 (`0x10`); UInt32 uses int64. Input accepts either integer width and enforces the target range. |
| Enum8/16, Date/Date32, IPv4 | Int32 (`0x10`): enum code, epoch days, or address bits. |
| Float32/64 | Double (`0x01`). |
| DateTime | Int64 (`0x12`) epoch seconds. |
| DateTime64 | Datetime (`0x09`) containing the declared integer ticks. Read with the same precision; precision 3 uses standard BSON milliseconds. Input also accepts int64 ticks. |
| Decimal32/64 | Int32/int64 containing the coefficient; the target declaration supplies the scale. |
| Decimal128/256, Int128/UInt128/Int256/UInt256 | Generic binary (`0x05`, subtype 0) containing 16 or 32 little-endian coefficient bytes; signed values use two's complement. Input requires the exact byte width. |
| String/TEXT, FixedString | Generic binary by default; BSON String (`0x02`) with `bson_strings=1`. FixedString keeps padding bytes. Native String requires valid UTF-8 on input; use BLOB or FixedString for arbitrary bytes. |
| BLOB, IPv6 | Generic binary, preserving bytes; IPv6 requires 16 bytes. BLOB stays binary even when `bson_strings=1`. |
| UUID | Binary subtype 4, 16 bytes stored as two little-endian 64-bit halves. Input also accepts subtype 3. |
| Array, positional Tuple | BSON array (`0x04`); keys are zero-based for Array and one-based for Tuple, and input reads members positionally. |
| Named Tuple, Map | Embedded document (`0x03`). Tuple fields match exact member names; Map keys use their scalar text and preserve order and duplicate keys. |
---
Source: https://coordinatordb.com/docs/reference/formats/csv/csv
Language: en
# csv
## Description
Comma-separated fields, one row per line. Text output is double-quoted; the default NULL marker is \N. Quoted fields can contain delimiters and newlines.
Input and output. Select it with `FORMAT csv`. Names ignore ASCII case; use the snake_case name shown here.
Fields follow the result projection or INSERT column order. By default, commas separate fields and a line feed ends each row. Text is double-quoted, and embedded double quotes are doubled; quoted fields can contain commas and line breaks.
An unquoted NULL marker is distinct from quoted text containing the same characters. Plain csv has no header. Use a names variant when the input should identify columns rather than depend on position.
```text
SELECT expressions FORMAT csv;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT csv
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT csv;
```
```text
7,"Ada"
```
### Quoting and NULL
Quotes protect field content. SQL NULL uses the unquoted marker:
```sql
SELECT 'a,"b"' AS label, NULL AS missing
FORMAT csv;
```
```text
"a,""b""",\N
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ---------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `csv_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `csv_double_quotes` | `Bool` | `1` | Read a field that starts with a double quote as quoted text; when off, the quote is an ordinary character. |
| `csv_empty_as_default` | `Bool` | `1` | Give an empty unquoted field the column's DEFAULT; when off, read it as empty text. |
| `csv_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `csv_null_text` | `String` | `\N` | The unquoted text that stands for NULL when reading and writing; it must stay one untrimmed field under the current CSV settings. |
| `csv_separator` | `Char` | `,` | The character between fields when reading and writing: one ASCII character that is not a letter, digit, quote, backslash, or line break. Write a tab as \t. |
| `csv_single_quotes` | `Bool` | `0` | Also read a field that starts with a single quote as quoted text. |
| `csv_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `csv_trim_blanks` | `Bool` | `1` | Drop spaces and tabs around a field when reading; quotes keep the blanks inside them. |
| `csv_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/csv/csv-with-names
Language: en
# csv_with_names
## Description
CSV with a first row of column names. Input matches names by default. Disable csv_match_names to bind fields positionally.
Input and output. Select it with `FORMAT csv_with_names`. Names ignore ASCII case; use the snake_case name shown here.
The first record contains column names; all later records contain values using the ordinary CSV quoting rules. Input name matching is enabled by default, so a source can reorder fields while retaining their names.
Disable csv_match_names only when the header should be skipped and values bound in target order. Use ignore_unknown_fields when extra named fields are intentionally allowed.
```text
SELECT expressions FORMAT csv_with_names;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT csv_with_names
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT csv_with_names;
```
```text
"id","name"
7,"Ada"
```
### Reading reordered named fields
The input header names the columns in a different order from the table:
```sql
CREATE TABLE named_people(id UInt32, name String);
```
```sql
INSERT INTO named_people FORMAT csv_with_names
name,id
Ada,1
Grace,2
```
```sql
SELECT id, name FROM named_people ORDER BY id FORMAT csv;
```
```text
1,"Ada"
2,"Grace"
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `csv_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `csv_double_quotes` | `Bool` | `1` | Read a field that starts with a double quote as quoted text; when off, the quote is an ordinary character. |
| `csv_empty_as_default` | `Bool` | `1` | Give an empty unquoted field the column's DEFAULT; when off, read it as empty text. |
| `csv_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `csv_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `csv_null_text` | `String` | `\N` | The unquoted text that stands for NULL when reading and writing; it must stay one untrimmed field under the current CSV settings. |
| `csv_separator` | `Char` | `,` | The character between fields when reading and writing: one ASCII character that is not a letter, digit, quote, backslash, or line break. Write a tab as \t. |
| `csv_single_quotes` | `Bool` | `0` | Also read a field that starts with a single quote as quoted text. |
| `csv_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `csv_trim_blanks` | `Bool` | `1` | Drop spaces and tabs around a field when reading; quotes keep the blanks inside them. |
| `csv_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/csv/csv-with-names-and-types
Language: en
# csv_with_names_and_types
## Description
CSV with column names in its first row and runtime type names in its second row. Input checks the type header by default. Runtime output types can be wider than the original column declaration.
Input and output. Select it with `FORMAT csv_with_names_and_types`. Names ignore ASCII case; use the snake_case name shown here.
Two records precede the values: column names, then type names. The type record is checked against the bound target types by default. Both records use CSV quoting.
Output headers describe runtime values and can therefore show a wider integer type than the source column declaration. When round-tripping, choose compatible target types or explicitly configure the header policy.
```text
SELECT expressions FORMAT csv_with_names_and_types;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT csv_with_names_and_types
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT csv_with_names_and_types;
```
```text
"id","name"
"Int64","String"
7,"Ada"
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `csv_check_types` | `Bool` | `1` | Compare the input types header with the bound target column types; when off, skip that header. |
| `csv_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `csv_double_quotes` | `Bool` | `1` | Read a field that starts with a double quote as quoted text; when off, the quote is an ordinary character. |
| `csv_empty_as_default` | `Bool` | `1` | Give an empty unquoted field the column's DEFAULT; when off, read it as empty text. |
| `csv_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `csv_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `csv_null_text` | `String` | `\N` | The unquoted text that stands for NULL when reading and writing; it must stay one untrimmed field under the current CSV settings. |
| `csv_separator` | `Char` | `,` | The character between fields when reading and writing: one ASCII character that is not a letter, digit, quote, backslash, or line break. Write a tab as \t. |
| `csv_single_quotes` | `Bool` | `0` | Also read a field that starts with a single quote as quoted text. |
| `csv_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `csv_trim_blanks` | `Bool` | `1` | Drop spaces and tabs around a field when reading; quotes keep the blanks inside them. |
| `csv_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/custom-separated/custom-separated
Language: en
# custom_separated
## Description
Positional fields with configurable escaping and field, row and result delimiters. Set custom_separated_escaping and the delimiters to match the source.
Input and output. Select it with `FORMAT custom_separated`. Names ignore ASCII case; use the snake_case name shown here.
Choose this format when the source has fixed delimiters but is not ordinary CSV or TSV. Settings define result prefixes and suffixes, row prefixes and suffixes, the field delimiter and the escaping rule.
Input must match those literals. Choose escaping that distinguishes field content from delimiters. Missing fields without SQL defaults use implicit native defaults according to this format contract.
```text
SELECT expressions FORMAT custom_separated;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT custom_separated
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT custom_separated;
```
```text
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------- |
| `custom_separated_detect_header` | `Bool` | `1` | Recognize an input names header and an optional matching types header. |
| `custom_separated_escaping` | `String` | `Escaped` | Field grammar: Escaped, Quoted, CSV, JSON, XML (output only), or Raw. |
| `custom_separated_result_prefix` | `String` | `''` | Text before the entire input or output result. |
| `custom_separated_result_suffix` | `String` | `''` | Text after the entire input or output result. |
| `custom_separated_row_prefix` | `String` | `''` | Text before the first field of each input or output row. |
| `custom_separated_row_separator` | `String` | `''` | Text between input or output rows, excluding their own prefixes and suffixes. |
| `custom_separated_row_suffix` | `String` | `\n` | Text after the last field of each input or output row. |
| `custom_separated_separator` | `String` | `\t` | Text between input or output fields; may contain multiple bytes. |
| `custom_separated_skip_empty_lines` | `Bool` | `0` | Skip trailing CR and LF bytes after the result; one final LF is always accepted. |
| `custom_separated_uneven_rows` | `Bool` | `0` | Give omitted input fields their SQL or native defaults and validate then skip extra fields. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/custom-separated/custom-separated-with-names
Language: en
# custom_separated_with_names
## Description
Custom separated rows with a required first record of column names. Header names are literal text, including with raw escaping. Input matches names unless custom_separated_match_names is disabled.
Input and output. Select it with `FORMAT custom_separated_with_names`. Names ignore ASCII case; use the snake_case name shown here.
The first record identifies the fields, followed by value records with the configured delimiters. Header names remain literal field names even when field values use Raw escaping.
Name matching is enabled by default. Its positional mode skips name-based binding; unknown fields, omitted values and literal delimiters still follow the configured input rules.
```text
SELECT expressions FORMAT custom_separated_with_names;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT custom_separated_with_names
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT custom_separated_with_names;
```
```text
id name
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `custom_separated_escaping` | `String` | `Escaped` | Field grammar: Escaped, Quoted, CSV, JSON, XML (output only), or Raw. |
| `custom_separated_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `custom_separated_result_prefix` | `String` | `''` | Text before the entire input or output result. |
| `custom_separated_result_suffix` | `String` | `''` | Text after the entire input or output result. |
| `custom_separated_row_prefix` | `String` | `''` | Text before the first field of each input or output row. |
| `custom_separated_row_separator` | `String` | `''` | Text between input or output rows, excluding their own prefixes and suffixes. |
| `custom_separated_row_suffix` | `String` | `\n` | Text after the last field of each input or output row. |
| `custom_separated_separator` | `String` | `\t` | Text between input or output fields; may contain multiple bytes. |
| `custom_separated_skip_empty_lines` | `Bool` | `0` | Skip trailing CR and LF bytes after the result; one final LF is always accepted. |
| `custom_separated_uneven_rows` | `Bool` | `0` | Give omitted input fields their SQL or native defaults and validate then skip extra fields. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/form
Language: en
# form
## Description
One application/x-www-form-urlencoded record: key=value\&key=value. Percent escapes and plus-as-space decoding apply to values. file() can infer String columns when no explicit schema is supplied.
Only values are URL-decoded; keys retain their literal spelling, including dots
and percent sequences. Repeated keys are rejected, ignoring ASCII case. A final
LF or CRLF may terminate the record.
Input only. Select it with `FORMAT form`. Names ignore ASCII case; use the snake_case name shown here.
The input represents one row of key/value pairs, rather than a stream of several records. Values decode percent escapes and plus signs; keys keep their literal spelling. Repeated keys are rejected without regard to ASCII case.
A file() source can infer String fields from nonempty input. Supply an explicit schema to choose native conversions or to describe an empty form. The format has no output encoder.
```text
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT form
```
## Example usage
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='form' FORMAT csv;
```
```text
"form",1,0
```
Example input: `id=7&name=Ada+Lovelace`.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Load rows
Run the INSERT request separately; its remaining bytes are input data.
```sql
CREATE TABLE form_input(id UInt8,name String);
```
```text
OK
```
```sql
INSERT INTO form_input FORMAT form
id=7&name=Ada+Lovelace
```
```text
OK
```
```sql
SELECT * FROM form_input FORMAT csv;
```
```text
7,"Ada Lovelace"
```
---
Source: https://coordinatordb.com/docs/reference/formats/geo-json
Language: en
# geo_json
## Description
One GeoJSON FeatureCollection. Each SQL row becomes a Feature.
The output detects its native geometry column. Supported shapes are Point,
MultiPoint, LineString, MultiLineString, Polygon and MultiPolygon, using native
coordinate types. GeometryCollection is unsupported;
`geo_json_unsupported_geometry='null'` can replace it with NULL on input.
Input and output. Select it with `FORMAT geo_json`. Names ignore ASCII case; use the snake_case name shown here.
Output detects exactly one column containing a native geometry alias; there is no geometry-column setting. For an all-NULL geometry column, name it geometry. A column named id becomes the feature identifier; other columns become properties. A single object-valued column named properties can supply that object directly.
Input binds the fixed id, geometry and properties members. Coordinates must be finite. Geometry validation additionally checks line/ring sizes, ring closure and nonempty collections. GeometryCollection is not supported; the configured null policy can validate and replace it on input.
```text
SELECT expressions FORMAT geo_json;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT geo_json
```
## Example usage
```sql
SELECT CAST('[1,2]' AS Point) AS geometry, 'Ada' AS name FORMAT geo_json;
```
```text
{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[1,2]},"properties":{"name":"Ada"}}]}
```
Output has no trailing newline.
### Detecting the geometry by its value type
The geometry column can have an application-specific name:
```sql
SELECT CAST('[1,2]' AS Point) AS location, 'Depot' AS name
FORMAT geo_json;
```
```text
{"type":"FeatureCollection","features":[{"type":"Feature","geometry":{"type":"Point","coordinates":[1,2]},"properties":{"name":"Depot"}}]}
```
Output has no trailing newline.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `geo_json_unsupported_geometry` | `String` | `throw` | Reject unsupported geometry types on input; null validates them and stores NULL when geometry is requested. |
| `geo_json_validate_geometry` | `Bool` | `1` | Validate line lengths, ring lengths and closure, and nonempty geometry containers on input and output; coordinates must always be finite. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/hash
Language: en
# hash
## Description
One 128-bit lowercase hexadecimal fingerprint of the result values. It is useful for result comparisons, not cryptographic authentication.
Output only. Select it with `FORMAT hash`. Names ignore ASCII case; use the snake_case name shown here.
The fingerprint covers values in row and column order; column labels do not enter it. Define an ORDER BY when the comparison must use the same row sequence. Native types and NULL markers are significant to the representation.
A nonempty schema with no rows still produces the empty-result fingerprint. Use this format to compare query results, not to authenticate untrusted data.
```text
SELECT expressions FORMAT hash;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT hash;
```
```text
23ac1e3d42ef081779b2184ca4cb3049
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
There are no format-specific settings.
---
Source: https://coordinatordb.com/docs/reference/formats/hive-text
Language: en
# hive_text
## Description
Positional text with Hive separators for collections and maps. Input uses its configured field parsing; output does not add escaping for embedded separators.
Input and output. Select it with `FORMAT hive_text`. Names ignore ASCII case; use the snake_case name shown here.
Fields are positional. Separate settings define row fields, collection members and map keys/values. The intended input layout must agree with the destination schema.
Output does not escape separator bytes embedded in a field. Use another format if arbitrary text could be confused with its delimiters. Missing values follow the format defaults and configured NULL text.
```text
SELECT expressions FORMAT hive_text;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT hive_text
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT hive_text;
```
```text
7Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `hive_text_collection_separator` | `Char` | `\x02` | The byte between outermost Array and Tuple elements or Map entries on output; input uses bracketed values. |
| `hive_text_map_separator` | `Char` | `\x03` | The byte between outermost Map keys and values, also used at the next nested level on output. |
| `hive_text_row_separator` | `Char` | `\n` | The byte ending each output row; input always reads newline-delimited CSV records. |
| `hive_text_separator` | `Char` | `\x01` | The byte between top-level fields when reading and writing, with no output quoting or escaping. |
| `hive_text_uneven_rows` | `Bool` | `1` | Give omitted trailing input columns their DEFAULT and skip extra fields; off requires the exact field count. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json
Language: en
# json
## Description
One JSON document with runtime column metadata, named row objects and a row count. Input consumes its data rows and checks supported metadata.
Input and output. Select it with `FORMAT json`. Names ignore ASCII case; use the snake_case name shown here.
The document contains column metadata, a data array of named row objects and a row count. It is suited to a consumer that wants a complete result envelope rather than a row-at-a-time JSON stream.
Input reads the data rows and checks supported metadata against the target. JSON settings control quoting, named tuples, unknown fields and type checks. Use json_each_row for an envelope-free named row stream.
```text
SELECT expressions FORMAT json;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json;
```
```text
{
"meta":
[
{
"name": "id",
"type": "Int64"
},
{
"name": "name",
"type": "String"
}
],
"data":
[
{
"id": 7,
"name": "Ada"
}
],
"rows": 1
}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| --------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_check_types` | `Bool` | `1` | Compare input metadata or header types with the bound target column types. |
| `json_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric. |
| `json_quote_special_floats` | `Bool` | `0` | Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-as-object
Language: en
# json_as_object
## Description
Whole JSON objects as single-column JSON rows, optionally enclosed in an outer array. The target must have one compatible JSON column. Objects retain their JSON structure.
Input only. Select it with `FORMAT json_as_object`. Names ignore ASCII case; use the snake_case name shown here.
Each source object is the complete value of one JSON column. Its member names are not mapped to separate table columns. Input can contain consecutive objects or an outer array of objects.
The destination must select one compatible JSON column. Use a typed JSON declaration when selected paths inside each object need native validation. Ordinary row JSON settings do not apply to this whole-object codec.
```text
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_as_object
```
## Example usage
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='json_as_object' FORMAT csv;
```
```text
"json_as_object",1,0
```
Example input for a single target column:
```text
{"id":7}
{"id":8}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Load rows
Run the INSERT request separately; its remaining bytes are input data.
```sql
CREATE TABLE document_input(doc JSON);
```
```text
OK
```
```sql
INSERT INTO document_input FORMAT json_as_object
{"id":7}
```
```text
OK
```
```sql
SELECT doc FROM document_input FORMAT json_each_row;
```
```text
{"doc":{"id":7}}
```
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-as-string
Language: en
# json_as_string
## Description
Whole JSON objects as single-column text rows, optionally enclosed in an outer array. The object text is the value of a String column.
Input only. Select it with `FORMAT json_as_string`. Names ignore ASCII case; use the snake_case name shown here.
Each source object becomes the complete text value of one selected String column. An outer array can contain several objects; their fields are not expanded into destination columns.
Use json_as_object when the stored value should be native JSON. This codec validates object framing but preserves object text as text, and does not use the ordinary row JSON settings.
```text
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_as_string
```
## Example usage
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='json_as_string' FORMAT csv;
```
```text
"json_as_string",1,0
```
Example input for a single target column:
```text
{"id":7}
{"id":8}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Load rows
Run the INSERT request separately; its remaining bytes are input data.
```sql
CREATE TABLE document_input(doc String);
```
```text
OK
```
```sql
INSERT INTO document_input FORMAT json_as_string
{"id":7}
```
```text
OK
```
```sql
SELECT doc FROM document_input FORMAT json_each_row;
```
```text
{"doc":"{\"id\":7}"}
```
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-columns
Language: en
# json_columns
## Description
One JSON object mapping each column name to an array of values. Column arrays must have compatible row counts. json_columns_sql_defaults selects SQL defaults for omitted fields.
Input and output. Select it with `FORMAT json_columns`. Names ignore ASCII case; use the snake_case name shown here.
Each object key names a column, and its value is an array containing that column's rows. Corresponding positions across the arrays form one SQL row.
Column lengths must agree. Omitted target columns follow json_columns_sql_defaults and their declarations. Use json_each_row when the source provides objects per row rather than arrays per column.
```text
SELECT expressions FORMAT json_columns;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_columns
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_columns;
```
```text
{
"id": [7],
"name": ["Ada"]
}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| --------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_columns_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted input columns; off supplies only their native type defaults. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-compact
Language: en
# json_compact
## Description
One JSON document with ordered column names, positional row arrays and a row count. This format is output-only.
Output only. Select it with `FORMAT json_compact`. Names ignore ASCII case; use the snake_case name shown here.
The document contains ordered column metadata and positional row arrays, plus a row count. Consumers must interpret each row using that declared column order.
This variant is output-only and is distinct from the input/output json_compact_each_row stream. Output has no trailing newline.
```text
SELECT expressions FORMAT json_compact;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_compact;
```
```text
{"meta":[{"name":"id"},{"name":"name"}],"data":[[7,"Ada"]],"rows":1}
```
Output has no trailing newline.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
There are no format-specific settings.
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-compact-columns
Language: en
# json_compact_columns
## Description
One JSON array containing a value array for each positional column. Column arrays must describe the same row count.
Input and output. Select it with `FORMAT json_compact_columns`. Names ignore ASCII case; use the snake_case name shown here.
The outer array contains one value array per column. Position in the outer array identifies the destination column; matching positions within those arrays form rows.
All column arrays must describe the same row count. Omitted trailing columns use the configured defaults. There are no named field keys to reorder the source by name.
```text
SELECT expressions FORMAT json_compact_columns;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_compact_columns
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_compact_columns;
```
```text
[
[7],
["Ada"]
]
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `json_compact_columns_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted trailing input columns; off supplies only their native type defaults. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-compact-each-row
Language: en
# json_compact_each_row
## Description
One positional JSON array per row. Field order follows the INSERT column list or result projection. There is no header.
Input and output. Select it with `FORMAT json_compact_each_row`. Names ignore ASCII case; use the snake_case name shown here.
Every row is an independent JSON array with fields in projection or INSERT-column order. There is no names or types header, so the consumer must already know the schema.
NULL uses JSON null. By default rows must match the expected width; json_compact_uneven_rows can supply defaults for missing positions and validate then skip extras.
```text
SELECT expressions FORMAT json_compact_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_compact_each_row
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_compact_each_row;
```
```text
[7, "Ada"]
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
| `json_array_of_rows` | `Bool` | `0` | Wrap all output rows in one JSON array. |
| `json_arrays_as_strings` | `Bool` | `1` | Accept JSON arrays in string input columns and retain their JSON text. |
| `json_bools_as_numbers` | `Bool` | `1` | Accept JSON Boolean input in numeric columns as zero or one. |
| `json_bools_as_strings` | `Bool` | `1` | Accept JSON Boolean input in string columns as true or false text. |
| `json_compact_uneven_rows` | `Bool` | `0` | Give missing positional fields their SQL or native defaults and validate then skip extra fields. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_named_tuples_as_objects` | `Bool` | `1` | Read and write named Tuple values as objects; otherwise use positional arrays. |
| `json_numbers_as_strings` | `Bool` | `1` | Accept JSON numbers in string input columns and retain their exact spelling. |
| `json_objects_as_strings` | `Bool` | `1` | Accept JSON objects in string input columns and retain their JSON text. |
| `json_quote_decimals` | `Bool` | `0` | Write fixed-point decimal output values as JSON strings. |
| `json_quote_large_floats` | `Bool` | `0` | Write finite Float64 output values as JSON strings. |
| `json_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric. |
| `json_quote_special_floats` | `Bool` | `0` | Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_tuple_ignore_unknown_fields` | `Bool` | `0` | Validate then ignore object members outside a named Tuple declaration. |
| `json_tuple_missing_as_default` | `Bool` | `1` | Give missing named Tuple members their declared type defaults. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-compact-each-row-with-names-and-types
Language: en
# json_compact_each_row_with_names_and_types
## Description
Positional JSON arrays preceded by arrays of column names and runtime type names. Name matching and type checks use the corresponding JSON settings.
Input and output. Select it with `FORMAT json_compact_each_row_with_names_and_types`. Names ignore ASCII case; use the snake_case name shown here.
The first array contains names, the second contains runtime type names, and subsequent arrays contain values. Name matching and type checks are enabled by their JSON settings.
Header types describe runtime output rather than every original narrow declaration. Align the import target with those types or choose the documented matching/checking options explicitly.
```text
SELECT expressions FORMAT json_compact_each_row_with_names_and_types;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_compact_each_row_with_names_and_types
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_compact_each_row_with_names_and_types;
```
```text
["id", "name"]
["Int64", "String"]
[7, "Ada"]
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ---------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_array_of_rows` | `Bool` | `0` | Wrap all output rows in one JSON array. |
| `json_arrays_as_strings` | `Bool` | `1` | Accept JSON arrays in string input columns and retain their JSON text. |
| `json_bools_as_numbers` | `Bool` | `1` | Accept JSON Boolean input in numeric columns as zero or one. |
| `json_bools_as_strings` | `Bool` | `1` | Accept JSON Boolean input in string columns as true or false text. |
| `json_check_types` | `Bool` | `1` | Compare input metadata or header types with the bound target column types. |
| `json_compact_uneven_rows` | `Bool` | `0` | Give missing positional fields their SQL or native defaults and validate then skip extra fields. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_match_names` | `Bool` | `1` | Match input header names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `json_named_tuples_as_objects` | `Bool` | `1` | Read and write named Tuple values as objects; otherwise use positional arrays. |
| `json_numbers_as_strings` | `Bool` | `1` | Accept JSON numbers in string input columns and retain their exact spelling. |
| `json_objects_as_strings` | `Bool` | `1` | Accept JSON objects in string input columns and retain their JSON text. |
| `json_quote_decimals` | `Bool` | `0` | Write fixed-point decimal output values as JSON strings. |
| `json_quote_large_floats` | `Bool` | `0` | Write finite Float64 output values as JSON strings. |
| `json_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric. |
| `json_quote_special_floats` | `Bool` | `0` | Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_tuple_ignore_unknown_fields` | `Bool` | `0` | Validate then ignore object members outside a named Tuple declaration. |
| `json_tuple_missing_as_default` | `Bool` | `1` | Give missing named Tuple members their declared type defaults. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-compact-strings-each-row
Language: en
# json_compact_strings_each_row
## Description
Positional JSON row arrays containing complete native text as JSON strings.
SQL NULL is the string `"ᴺᵁᴸᴸ"`. Known input fields must be strings; bare JSON
null is rejected. Nullable targets also accept the string `"NULL"`, ignoring ASCII
case. Input converts text through the target column declarations.
Input and output. Select it with `FORMAT json_compact_strings_each_row`. Names ignore ASCII case; use the snake_case name shown here.
Position identifies each column, but every field is a JSON string containing the complete native text value. This includes numbers, collections and the SQL NULL marker.
Input validates string fields before converting them through the target type. JSON null is not a valid substitute for a known field; nullable targets accept the documented textual NULL markers.
```text
SELECT expressions FORMAT json_compact_strings_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_compact_strings_each_row
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_compact_strings_each_row;
```
```text
["7", "Ada"]
```
```sql
SELECT NULL AS value FORMAT json_compact_strings_each_row;
```
```text
["ᴺᵁᴸᴸ"]
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `json_array_of_rows` | `Bool` | `0` | Wrap all output rows in one JSON array. |
| `json_compact_strings_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for missing or defaulted positional whole-text JSON fields; off supplies their native type defaults. |
| `json_compact_uneven_rows` | `Bool` | `0` | Give missing positional fields their SQL or native defaults and validate then skip extra fields. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_validate_utf8` | `Bool` | `0` | Replace invalid UTF-8 sequences in whole-text JSON output with replacement characters; off preserves byte-string payloads. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-each-row
Language: en
# json_each_row
## Description
One named JSON object per row. Missing fields can use defaults; unknown fields error unless ignore_unknown_fields is enabled.
Input and output. Select it with `FORMAT json_each_row`. Names ignore ASCII case; use the snake_case name shown here.
Every row is a named JSON object. Object keys select destination columns, so their order does not need to match the target column order. Each value is converted to its declared type.
Missing fields use the configured SQL/native defaults. Unknown fields are rejected unless ignore_unknown_fields is enabled. Use aliases to produce stable output keys and a separate later request after inline INSERT data.
```text
SELECT expressions FORMAT json_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_each_row
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_each_row;
```
```text
{"id":7,"name":"Ada"}
```
### SQL NULL as JSON null
```sql
SELECT NULL AS value, 0 AS count
FORMAT json_each_row;
```
```text
{"value":null,"count":0}
```
This differs from json_strings_each_row, which writes the textual NULL marker as a JSON string.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-format-settings
Language: en
# JSON format settings
JSON settings control field conversion, quoting, header matching and document layout. Use a SETTINGS clause on the statement; the next statement starts from defaults again.
A setting applies only to the JSON layouts that support it. Whole-object json_as_object and json_as_string input does not use the ordinary row JSON options. The individual format pages list their applicable subset.
The ordinary json_each_row codec always writes numeric values as JSON numbers; the json_quote options do not change it. Choose a supported compact/object layout when quoted numeric output is required.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## json_array_of_rows
Type: `Bool`
Default value: `0`
Wrap all output rows in one JSON array.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`, `json_strings_each_row`.
## json_arrays_as_strings
Type: `Bool`
Default value: `1`
Accept JSON arrays in string input columns and retain their JSON text.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_bools_as_numbers
Type: `Bool`
Default value: `1`
Accept JSON Boolean input in numeric columns as zero or one.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_bools_as_strings
Type: `Bool`
Default value: `1`
Accept JSON Boolean input in string columns as true or false text.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_check_types
Type: `Bool`
Default value: `1`
Compare input metadata or header types with the bound target column types.
Applies to: `json`, `json_compact_each_row_with_names_and_types`.
## json_columns_sql_defaults
Type: `Bool`
Default value: `1`
Evaluate SQL DEFAULT expressions for omitted input columns; off supplies only their native type defaults.
Applies to: `json_columns`.
## json_compact_columns_sql_defaults
Type: `Bool`
Default value: `1`
Evaluate SQL DEFAULT expressions for omitted trailing input columns; off supplies only their native type defaults.
Applies to: `json_compact_columns`.
## json_compact_strings_each_row_sql_defaults
Type: `Bool`
Default value: `1`
Evaluate SQL DEFAULT expressions for missing or defaulted positional whole-text JSON fields; off supplies their native type defaults.
Applies to: `json_compact_strings_each_row`.
## json_compact_uneven_rows
Type: `Bool`
Default value: `0`
Give missing positional fields their SQL or native defaults and validate then skip extra fields.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`.
## json_empty_as_default
Type: `Bool`
Default value: `0`
Give empty JSON string fields their SQL or native type default.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`, `json_object_each_row`, `json_strings_each_row`.
## json_escape_slashes
Type: `Bool`
Default value: `1`
Escape unescaped forward slashes in JSON output strings.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`, `json_object_each_row`, `json_strings_each_row`.
## json_match_names
Type: `Bool`
Default value: `1`
Match input header names to target columns ignoring ASCII case; when off, skip the names header and read in target order.
Applies to: `json_compact_each_row_with_names_and_types`.
## json_named_tuples_as_objects
Type: `Bool`
Default value: `1`
Read and write named Tuple values as objects; otherwise use positional arrays.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_numbers_as_strings
Type: `Bool`
Default value: `1`
Accept JSON numbers in string input columns and retain their exact spelling.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_object_each_row_name_column
Type: `String`
Default value: `''`
Use this string column for outer row keys and omit it from row objects; empty generates row_1, row_2, and so on.
Applies to: `json_object_each_row`.
## json_object_each_row_sql_defaults
Type: `Bool`
Default value: `1`
Evaluate SQL DEFAULT expressions for omitted or defaulted row fields; off supplies only their native type defaults.
Applies to: `json_object_each_row`.
## json_objects_as_strings
Type: `Bool`
Default value: `1`
Accept JSON objects in string input columns and retain their JSON text.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_quote_decimals
Type: `Bool`
Default value: `0`
Write fixed-point decimal output values as JSON strings.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_quote_large_floats
Type: `Bool`
Default value: `0`
Write finite Float64 output values as JSON strings.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_quote_large_integers
Type: `Bool`
Default value: `0`
Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric.
Applies to: `json`, `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_quote_special_floats
Type: `Bool`
Default value: `0`
Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null.
Applies to: `json`, `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_strict_escapes
Type: `Bool`
Default value: `1`
Reject invalid JSON escapes; otherwise preserve their literal backslash spelling.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`, `json_object_each_row`, `json_strings_each_row`.
## json_strings_each_row_sql_defaults
Type: `Bool`
Default value: `1`
Evaluate SQL DEFAULT expressions for omitted or defaulted whole-text JSON fields; off supplies their native type defaults.
Applies to: `json_strings_each_row`.
## json_tuple_ignore_unknown_fields
Type: `Bool`
Default value: `0`
Validate then ignore object members outside a named Tuple declaration.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_tuple_missing_as_default
Type: `Bool`
Default value: `1`
Give missing named Tuple members their declared type defaults.
Applies to: `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_object_each_row`.
## json_validate_utf8
Type: `Bool`
Default value: `0`
Replace invalid UTF-8 sequences in whole-text JSON output with replacement characters; off preserves byte-string payloads.
Applies to: `json_compact_strings_each_row`, `json_strings_each_row`.
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-object-each-row
Language: en
# json_object_each_row
## Description
One JSON object whose outer keys identify named row objects. json_object_each_row_name_column can expose the key as a column.
Input and output. Select it with `FORMAT json_object_each_row`. Names ignore ASCII case; use the snake_case name shown here.
The document's outer keys identify rows; each associated object holds that row's fields. The configured name column can expose the outer key as an ordinary field.
This layout is distinct from json_each_row, whose top-level objects are already rows. Name-column collisions and field conversions follow the selected schema and settings.
```text
SELECT expressions FORMAT json_object_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_object_each_row
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_object_each_row;
```
```text
{
"row_1": {"id":7,"name":"Ada"}
}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_arrays_as_strings` | `Bool` | `1` | Accept JSON arrays in string input columns and retain their JSON text. |
| `json_bools_as_numbers` | `Bool` | `1` | Accept JSON Boolean input in numeric columns as zero or one. |
| `json_bools_as_strings` | `Bool` | `1` | Accept JSON Boolean input in string columns as true or false text. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_named_tuples_as_objects` | `Bool` | `1` | Read and write named Tuple values as objects; otherwise use positional arrays. |
| `json_numbers_as_strings` | `Bool` | `1` | Accept JSON numbers in string input columns and retain their exact spelling. |
| `json_object_each_row_name_column` | `String` | `''` | Use this string column for outer row keys and omit it from row objects; empty generates row_1, row_2, and so on. |
| `json_object_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted or defaulted row fields; off supplies only their native type defaults. |
| `json_objects_as_strings` | `Bool` | `1` | Accept JSON objects in string input columns and retain their JSON text. |
| `json_quote_decimals` | `Bool` | `0` | Write fixed-point decimal output values as JSON strings. |
| `json_quote_large_floats` | `Bool` | `0` | Write finite Float64 output values as JSON strings. |
| `json_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric. |
| `json_quote_special_floats` | `Bool` | `0` | Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_tuple_ignore_unknown_fields` | `Bool` | `0` | Validate then ignore object members outside a named Tuple declaration. |
| `json_tuple_missing_as_default` | `Bool` | `1` | Give missing named Tuple members their declared type defaults. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/json/json-strings-each-row
Language: en
# json_strings_each_row
## Description
One named JSON object per row with every field encoded as a JSON string.
SQL NULL is the string `"ᴺᵁᴸᴸ"`; collections use their complete native text
inside the string. Known input fields must be strings; bare JSON null is rejected.
Nullable targets also accept the string `"NULL"`, ignoring ASCII case.
Input converts the complete field text through the declared column type.
Input and output. Select it with `FORMAT json_strings_each_row`. Names ignore ASCII case; use the snake_case name shown here.
Objects retain named fields, but every value is a JSON string containing complete native text. Numeric digits do not pass through a JSON numeric representation, and collections remain text inside their field string.
SQL NULL uses the quoted marker shown above. Input known fields must be strings; their complete text is converted through each destination declaration. Use json_each_row when the consumer needs ordinary JSON value types.
```text
SELECT expressions FORMAT json_strings_each_row;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT json_strings_each_row
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT json_strings_each_row;
```
```text
{"id":"7","name":"Ada"}
```
```sql
SELECT NULL AS value FORMAT json_strings_each_row;
```
```text
{"value":"ᴺᵁᴸᴸ"}
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_array_of_rows` | `Bool` | `0` | Wrap all output rows in one JSON array. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_strings_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted or defaulted whole-text JSON fields; off supplies their native type defaults. |
| `json_validate_utf8` | `Bool` | `0` | Replace invalid UTF-8 sequences in whole-text JSON output with replacement characters; off preserves byte-string payloads. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/line-as-string/line-as-string
Language: en
# line_as_string
## Description
Each complete input line becomes one String field. Output writes unescaped tab-separated values and does not restore an input object or line envelope.
Input and output. Select it with `FORMAT line_as_string`. Names ignore ASCII case; use the snake_case name shown here.
Input takes a whole line as one String field, without splitting the line into columns. Use it for line-oriented text that an application will parse later.
Output is unescaped tab-separated rendering. It does not recreate a whole input document or protect embedded line breaks, so the input and output uses are not a symmetric object serializer.
```text
SELECT expressions FORMAT line_as_string;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT line_as_string
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT line_as_string;
```
```text
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/markdown
Language: en
# markdown
## Description
A pipe-delimited Markdown table with column names and an alignment row. This is output-only.
Output only. Select it with `FORMAT markdown`. Names ignore ASCII case; use the snake_case name shown here.
The first row contains column labels and the next row defines table alignment. Each subsequent row contains rendered values between pipes.
This output is intended for a Markdown reader. It carries display text rather than a lossless typed import representation, and has no input decoder.
```text
SELECT expressions FORMAT markdown;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT markdown;
```
```text
| id | name |
|-:|:-|
| 7 | Ada |
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `markdown_escape_special_characters` | `Bool` | `0` | Escape ASCII punctuation in text and byte-string values with a backslash; when off, escape controls, backslashes, and single quotes. |
---
Source: https://coordinatordb.com/docs/reference/formats/msg-pack
Language: en
# msg_pack
## Description
Consecutive positional MessagePack fields. The target column count determines row boundaries; this is not an outer array of row arrays.
Input and output. Select it with `FORMAT msg_pack`. Names ignore ASCII case; use the snake_case name shown here.
Fields are consecutive MessagePack objects in column order; every target column count groups the next objects into one row. There is no header or outer array of row arrays. Incomplete rows are rejected.
Native collection members use MessagePack containers. Exact wide numbers need matching destination types to interpret their binary coefficients. Numeric payloads and lengths use the MessagePack byte order; see the mappings below.
```text
SELECT expressions FORMAT msg_pack;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT msg_pack
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT msg_pack" > sample.msg_pack
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT msg_pack" < sample.msg_pack > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `msg_pack_uuid_encoding` | `String` | `EXT` | Write UUID as EXT (extension type 2), BIN (16 binary bytes), or STR (canonical text). |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Native value | MessagePack representation |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| NULL | Nil (`0xc0`). |
| INTEGER, UInt64, Enum8/16 | The smallest signed or unsigned integer tag that holds the value, including positive and negative fixint. |
| Bool | Integer 0 or 1 on output; input also accepts the boolean tags. |
| Float32/64 | Float32/64 tags with exact big-endian IEEE payloads, including negative zero and infinities. Native target conversion stores NaN input as NULL. |
| String/TEXT, FixedString, BLOB | Bin8/16/32; input also accepts Fixstr and Str8/16/32. BLOB and FixedString retain arbitrary bytes and padding; native String requires valid UTF-8. |
| Date/Date32, DateTime | Integer epoch days or epoch seconds. |
| DateTime64 | Unsigned integer carrying the raw signed tick bits; the target declaration supplies precision and timezone. |
| Decimal32/64 | Integer coefficient; the target declaration supplies the scale. |
| Decimal128/256, Int128/UInt128/Int256/UInt256 | Bin8 with exactly 16 or 32 little-endian coefficient bytes; signed coefficients use two's complement. |
| IPv4, IPv6 | Unsigned address integer or 16 binary address bytes. |
| UUID | Extension type 2 with 16 canonical bytes by default; the UUID setting can instead write 16 bytes as two little-endian halves or 36-character canonical text. Input accepts all three. |
| Array, Tuple | Fixarray/Array16/Array32 with recursively encoded members. Named Tuple fields remain positional. |
| Map | Fixmap/Map16/Map32 with recursively encoded keys and values; order and duplicate keys are retained. |
| Nullable, LowCardinality | The inner representation. |
---
Source: https://coordinatordb.com/docs/reference/formats/npy
Language: en
# npy
## Description
One homogeneous NumPy array. Its first dimension supplies single-column rows; remaining dimensions become rectangular Array values. Mixed incompatible scalar types and ragged arrays are rejected.
Input and output. Select it with `FORMAT npy`. Names ignore ASCII case; use the snake_case name shown here.
Exactly one selected or target column is required. The first array dimension is the row count and later dimensions become nested Array values. Shapes must be rectangular and leaf types homogeneous.
Input accepts NPY 1.0, 2.0 and 3.0 in C order; output writes NPY 2.0 with little-endian numeric data. Output NULLs, ragged arrays and a SELECT with no rows are unsupported. A zero-row input with a valid header is accepted.
```text
SELECT expressions FORMAT npy;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT npy
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT npy" > sample.npy
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT npy" < sample.npy > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Input dtype | Native leaf | Output dtype |
| ---------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `i1`, `i2`, `i4`, `i8` | Signed integers of 8, 16, 32, or 64 bits. | `i8` for scalar results; declared width for Array members. |
| `u1`, `u2`, `u4`, `u8` | Unsigned integers of 8, 16, 32, or 64 bits; Bool accepts 0/1. | `u8` for scalar integers; declared width for Array members; `u1` for Bool. |
| `b1` | UInt8 retains the stored byte; Bool reads zero as false and any nonzero byte as true. | `u8` for scalar integers; declared width for Array members; `u1` for Bool. |
| `f2`, `f4` | Float32; binary16 expands exactly to binary32. | `f4`. |
| `f8` | Float64. | `f8`. |
| `S` | String/TEXT, BLOB, or FixedString. | `S` with zero padding; text uses the longest encoded byte length and FixedString retains its width. |
| `U` | UTF-32 code points decoded to UTF-8 text. | `S` containing UTF-8 bytes. |
---
Source: https://coordinatordb.com/docs/reference/formats/null-output
Language: en
# null_output
## Description
Emits no result bytes. The statement still executes and its constraints and request limits still apply.
Output only. Select it with `FORMAT null_output`. Names ignore ASCII case; use the snake_case name shown here.
No result payload is written, but SQL still executes. Use it when the result itself is unnecessary and only execution success or failure matters.
The format does not skip reads or writes, suppress constraint errors or bypass request limits. It is output-only.
```text
SELECT expressions FORMAT null_output;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT null_output;
```
The result body is empty.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
There are no format-specific settings.
---
Source: https://coordinatordb.com/docs/reference/formats/parquet/parquet
Language: en
# parquet
## Description
A Parquet file with column schema, row groups, data pages and footer. Use explicit target declarations when importing. Compression and row-group controls are statement settings.
Input and output. Select it with `FORMAT parquet`. Names ignore ASCII case; use the snake_case name shown here.
The file stores a column schema, row groups, data pages and a footer. Output types are inferred from runtime values; native collection members retain their declared types.
Create an explicit compatible destination before import, including when using file(). Missing, unknown and case-mismatched fields follow the listed options. The parquet_metadata format reads the footer as rows instead of decoding data columns.
```text
SELECT expressions FORMAT parquet;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT parquet
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT parquet" > sample.parquet
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT parquet" < sample.parquet > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ---------------------------- | -------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `parquet_compression` | `String` | `zstd` | Compress column pages with snappy, lz4, brotli, zstd, gzip, or none. |
| `parquet_detect_variant` | `Bool` | `1` | Recognize unannotated metadata/value binary structs as Variant values. |
| `parquet_fixed_strings` | `Bool` | `1` | Write FixedString as fixed-width bytes instead of variable-width Binary. |
| `parquet_ignore_case` | `Bool` | `0` | Ignore ASCII case when matching input fields to target column names. |
| `parquet_missing_as_default` | `Bool` | `1` | Give missing input fields their SQL DEFAULT or native type default. |
| `parquet_page_bytes` | `UInt64` | `1048576` | Target uncompressed bytes per output data page. |
| `parquet_page_index` | `Bool` | `1` | Write column and offset indexes for individual data pages. |
| `parquet_parse_json` | `Bool` | `1` | Decode JSON-annotated input fields as native JSON instead of text. |
| `parquet_read_bytes` | `UInt64` | `16744704` | Target decoded batch bytes estimated from uncompressed row-group metadata. |
| `parquet_read_geo` | `Bool` | `1` | Decode WKB or WKT columns identified by GeoParquet metadata; text and binary targets retain raw payloads. |
| `parquet_read_rows` | `UInt64` | `65409` | Maximum rows per decoded input batch. |
| `parquet_row_group_bytes` | `UInt64` | `536870912` | Target output row-group bytes before compression. |
| `parquet_row_group_rows` | `UInt64` | `1000000` | Maximum rows per output row group. |
| `parquet_strings_as_text` | `Bool` | `1` | Annotate text strings as UTF-8; BLOB keeps its exact binary representation. |
| `parquet_wide_as_decimal` | `Bool` | `0` | Write 128/256-bit integers as big-endian DECIMAL instead of little-endian fixed-width bytes. |
| `parquet_write_batch_rows` | `UInt64` | `1024` | Check output data-page size after this many rows. |
| `parquet_write_geo` | `Bool` | `1` | Encode geometry as WKB and include GeoParquet column metadata. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Type mappings
| Native value | Parquet representation |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bool, integers through 64 bits, Float32/64 | BOOLEAN, signed/unsigned INT32 or INT64, FLOAT/DOUBLE. Top-level narrow integers retain their runtime 64-bit class; collection members retain declared widths. |
| String, BLOB, FixedString | UTF-8 BYTE_ARRAY, raw BYTE_ARRAY, FIXED_LEN_BYTE_ARRAY. Settings can remove text annotations or fixed widths. Native String requires UTF-8; use BLOB for arbitrary bytes. |
| Enum8/16, IPv4, IPv6, UUID | Signed integer codes, UINT32, fixed 16-byte address, fixed 16-byte identifier. Input also accepts the UUID logical annotation. |
| Date/Date32, DateTime/DateTime64, Time/Time64 | DATE, TIMESTAMP, TIME. Second-resolution timestamps/clocks use milliseconds; fractional values use the next exact supported unit. Clocks outside one day and overflowing conversions are rejected. |
| Decimal through precision 76 | Standard DECIMAL with exact signed coefficients and scale. |
| Int128/UInt128/Int256/UInt256 | Little-endian fixed 16/32-byte integers by default. `parquet_wide_as_decimal=1` writes signed big-endian DECIMAL with 17/33 bytes and precision 39/77/78. Input accepts both representations; precision above 76 requires an explicit compatible integer target. |
| Array, Tuple, Map | LIST, struct, MAP, including nested values and NULL members. Named Tuple fields retain their names. |
| JSON | JSON-annotated binary JSON; `parquet_parse_json=0` reads it as text before target conversion. |
| Nullable, LowCardinality, SimpleAggregateFunction | Inner representation; scalar dictionary values are expanded before Parquet's own encoding. |
| Geometry aliases | GeoParquet WKB plus `geo` metadata; input also accepts WKT. See the restrictions below. |
---
Source: https://coordinatordb.com/docs/reference/formats/parquet/parquet-metadata
Language: en
# parquet_metadata
## Description
One input row describing a Parquet file footer, including file, column and row-group metadata. With file(), the format supplies its fixed metadata schema without a third argument.
Input only. Select it with `FORMAT parquet_metadata`. Names ignore ASCII case; use the snake_case name shown here.
The input is a complete Parquet file, but the output relation describes its footer rather than its data rows. It includes file-level counts and nested column and row-group records.
file() can supply the fixed schema automatically. With an explicit target, only known metadata fields are accepted and ordinary target conversions apply. This format has no result encoder.
```text
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT parquet_metadata
```
## Example usage
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='parquet_metadata' FORMAT csv;
```
```text
"parquet_metadata",1,0
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Inspect a file
Run these commands from the server configuration directory with the default user_files_path. They create a one-column, one-row Parquet file under the server file root and inspect its footer.
```sh
mkdir -p user_files
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT parquet" > user_files/sample.parquet
./coordinator client --database data --query "SELECT num_rows,num_columns,num_row_groups FROM file('sample.parquet',parquet_metadata) FORMAT csv"
```
```text
1,1,1
```
---
Source: https://coordinatordb.com/docs/reference/formats/png
Language: en
# png
## Description
An 8-bit grayscale, RGB or RGBA image from pixel rows. Coordinates x and y place pixels; integer t groups animated frames. Set png_width and png_height for the required dimensions; both default to 1024.
Output only. Select it with `FORMAT png`. Names ignore ASCII case; use the snake_case name shown here.
Rows describe pixels through x and y coordinates and grayscale, RGB or RGBA channel values. An integer t value can group rows into animation frames; timing uses the numerator and denominator settings.
Set dimensions explicitly for a small image. Export in native exact-byte mode and redirect stdout; image bytes are not terminal text. The format does not accept input images.
```text
SELECT expressions FORMAT png;
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT 0 AS x, 0 AS y, 255 AS r, 0 AS g, 0 AS b SETTINGS png_width=1,png_height=1 FORMAT png" > pixel.png
```
The result is one red pixel in a 1 × 1 image.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ---------------------- | -------- | ------- | ---------------------------------------------------------------------- |
| `png_height` | `UInt64` | `1024` | Height of the image in pixels, from 1 through 2147483647. |
| `png_time_denominator` | `UInt64` | `60` | Positive denominator of the duration in seconds of one integer t unit. |
| `png_time_numerator` | `UInt64` | `1` | Positive numerator of the duration in seconds of one integer t unit. |
| `png_width` | `UInt64` | `1024` | Width of the image in pixels, from 1 through 2147483647. |
---
Source: https://coordinatordb.com/docs/reference/formats/pretty/pretty-compact
Language: en
# pretty_compact
## Description
A compact Unicode bordered table for interactive results. This is the default output format.
Output only. Select it with `FORMAT pretty_compact`. Names ignore ASCII case; use the snake_case name shown here.
A Unicode border surrounds a table with a name header and one display row per SQL row, followed by the row count. It is the default server output for interactive inspection.
Use a data interchange format when a consumer needs a stable row encoding or binary values. Pretty output has no input decoder.
```text
SELECT expressions FORMAT pretty_compact;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT pretty_compact;
```
```text
┌─id─┬─name─┐
│ 7 │ Ada │
└────┴──────┘
(1 rows)
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------- |
| `pretty_borders` | `String` | `unicode` | The characters that draw the table: unicode for box-drawing lines, ascii for plus, minus, and bar. |
| `pretty_footer_from_rows` | `UInt64` | `0` | Repeat the column names in the bottom border when the table shows at least this many rows; 0 never repeats them. |
| `pretty_max_cell_width` | `UInt64` | `0` | Cut a value wider than this many terminal columns and mark the cut; 0 never cuts. |
| `pretty_max_padding` | `UInt64` | `0` | Align a column to at most this many terminal columns; wider values extend their own row. 0 aligns to the widest value. |
| `pretty_max_rows` | `UInt64` | `0` | Show at most this many rows and report how many were left out; 0 shows every row. |
| `pretty_row_numbers` | `Bool` | `0` | Add a first column that numbers the rows from 1. |
---
Source: https://coordinatordb.com/docs/reference/formats/protobuf/protobuf
Language: en
# protobuf
## Description
Binary messages with a varint length prefix before each row. Use a supported literal protobuf_schema and protobuf_message, or the column-derived schema with protobuf_auto_schema. This format does not read arbitrary schema files.
Input and output. Select it with `FORMAT protobuf`. Names ignore ASCII case; use the snake_case name shown here.
Each row is a length-prefixed Protocol Buffers message. Choose a literal proto2/proto3 schema and message, or let protobuf_auto_schema derive a message from the columns.
protobuf_schema contains schema text, not a filename. Imports are limited to bundled Google definitions. The message, field mappings, wrappers and defaults must agree with the chosen destination declarations.
```text
SELECT expressions FORMAT protobuf;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT protobuf
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id SETTINGS protobuf_auto_schema=1 FORMAT protobuf" > sample.protobuf
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import SETTINGS protobuf_auto_schema=1 FORMAT protobuf" < sample.protobuf > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `protobuf_auto_schema` | `Bool` | `1` | Derive a message schema from columns when protobuf_schema is empty. |
| `protobuf_keep_default_wrappers` | `Bool` | `0` | Write present Google wrappers for default scalar values; NULL wrappers remain absent. |
| `protobuf_message` | `String` | `''` | Fully qualified message name in protobuf_schema; empty selects Row for an automatically derived schema. |
| `protobuf_missing_as_default` | `Bool` | `1` | Apply SQL DEFAULT to target columns outside the message schema; when off use their native type defaults. |
| `protobuf_oneof_tag` | `Bool` | `0` | Read the selected oneof field number into a column named after that oneof; unmatched branches yield zero. |
| `protobuf_schema` | `String` | `''` | Literal proto2 or proto3 schema; imports are limited to bundled Google definitions. |
| `protobuf_unwrap_google` | `Bool` | `0` | Read Google scalar wrappers directly into scalar columns; absent nullable wrappers become NULL. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/regexp
Language: en
# regexp
## Description
Each input line is matched by regexp_pattern. Captures map positionally to target columns and convert to their types. regexp_skip_unmatched controls lines that do not match.
Input only. Select it with `FORMAT regexp`. Names ignore ASCII case; use the snake_case name shown here.
One complete physical line is matched at a time. Each capture group supplies the next target field; the capture's text is then decoded using regexp_escaping and converted to the target type.
The pattern must be supplied because its default is empty. A nonmatching line is an error unless regexp_skip_unmatched is enabled. This format has no output encoder.
```text
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT regexp
```
## Example usage
```sql
SELECT name,is_input,is_output FROM system.formats WHERE name='regexp' FORMAT csv;
```
```text
"regexp",1,0
```
For lines such as `id: 7`, use `SETTINGS regexp_pattern='id: ([0-9]+)'` and one integer target column.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `regexp_escaping` | `String` | `Raw` | Read captured fields as Raw text, Escaped text, Quoted literals, CSV fields, or JSON values. |
| `regexp_pattern` | `String` | `''` | Match every complete input line; one capture group supplies each target column. Empty requires a statement override. |
| `regexp_skip_unmatched` | `Bool` | `0` | Skip lines that do not match the expression; otherwise report their physical line number. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
## Load rows
Run the INSERT request separately; its remaining bytes are input data.
```sql
CREATE TABLE regexp_input(id UInt8);
```
```text
OK
```
```sql
INSERT INTO regexp_input SETTINGS regexp_pattern='id: ([0-9]+)' FORMAT regexp
id: 7
```
```text
OK
```
```sql
SELECT * FROM regexp_input FORMAT csv;
```
```text
7
```
---
Source: https://coordinatordb.com/docs/reference/formats/row-binary/row-binary
Language: en
# row_binary
## Description
Consecutive positional binary rows without headers. Fixed-width numeric fields are little-endian; lengths use unsigned LEB128. Import requires the same field order and compatible types.
Input and output. Select it with `FORMAT row_binary`. Names ignore ASCII case; use the snake_case name shown here.
Rows contain only positional field bytes. Both ends must agree on field order and types because no schema or name information is included. Fixed-width numbers are little-endian; variable lengths use unsigned LEB128.
A Nullable field has a NULL marker, and collections encode their members recursively. For inline binary input, use exactly the required line separator after FORMAT; attached binary input needs no separator.
```text
SELECT expressions FORMAT row_binary;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT row_binary
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT row_binary" > sample.row_binary
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT row_binary" < sample.row_binary > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `row_binary_max_string_bytes` | `UInt64` | `1073741824` | Maximum bytes in an input variable-length string, including header names and type parameters; 0 disables the limit. |
| `row_binary_read_json_strings` | `Bool` | `0` | Read JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `row_binary_write_json_strings` | `Bool` | `0` | Write JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/row-binary/row-binary-with-names
Language: en
# row_binary_with_names
## Description
A binary column count and column-name header followed by positional binary rows. Input can bind header names to target columns.
Input and output. Select it with `FORMAT row_binary_with_names`. Names ignore ASCII case; use the snake_case name shown here.
A column count and name strings precede the ordinary row_binary payload. The default name matching binds fields without regard to ASCII case; its positional mode reads in target order.
Names alone do not describe value widths. The import must still have compatible target types. Use the names-and-types variant when type declarations should travel in the header too.
```text
SELECT expressions FORMAT row_binary_with_names;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT row_binary_with_names
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT row_binary_with_names" > sample.row_binary_with_names
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT row_binary_with_names" < sample.row_binary_with_names > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `row_binary_match_names` | `Bool` | `1` | Match input header names ignoring ASCII case; when off read in target column order. |
| `row_binary_max_string_bytes` | `UInt64` | `1073741824` | Maximum bytes in an input variable-length string, including header names and type parameters; 0 disables the limit. |
| `row_binary_read_json_strings` | `Bool` | `0` | Read JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `row_binary_write_json_strings` | `Bool` | `0` | Write JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/row-binary/row-binary-with-names-and-types
Language: en
# row_binary_with_names_and_types
## Description
A binary column count, names and type declarations followed by positional binary rows. Input validates names and types with the configured header settings. JSON fields require the explicit JSON-string mode.
Input and output. Select it with `FORMAT row_binary_with_names_and_types`. Names ignore ASCII case; use the snake_case name shown here.
The header carries a column count, names and types before the row_binary values. Type names are textual by default; the binary-type options select tags and binary parameters instead.
Input checks header types by default. Disabling the check decodes matched fields using the target widths, so compatibility is still required. JSON fields need the explicit read/write JSON-string modes.
```text
SELECT expressions FORMAT row_binary_with_names_and_types;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT row_binary_with_names_and_types
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT row_binary_with_names_and_types" > sample.row_binary_with_names_and_types
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT row_binary_with_names_and_types" < sample.row_binary_with_names_and_types > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `row_binary_check_types` | `Bool` | `1` | Compare input header types with target types; when off decode matched fields with target widths. |
| `row_binary_match_names` | `Bool` | `1` | Match input header names ignoring ASCII case; when off read in target column order. |
| `row_binary_max_string_bytes` | `UInt64` | `1073741824` | Maximum bytes in an input variable-length string, including header names and type parameters; 0 disables the limit. |
| `row_binary_read_binary_types` | `Bool` | `0` | Read type tags and their binary parameters instead of textual type names in the input header. |
| `row_binary_read_json_strings` | `Bool` | `0` | Read JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `row_binary_write_binary_types` | `Bool` | `0` | Write type tags and their binary parameters instead of textual type names in the output header. |
| `row_binary_write_json_strings` | `Bool` | `0` | Write JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/sql-insert
Language: en
# sql_insert
## Description
SQL INSERT or REPLACE statements containing literal rows. Configure sql_insert_table for the destination. Import the resulting text as SQL, not as INSERT ... FORMAT sql_insert.
Output only. Select it with `FORMAT sql_insert`. Names ignore ASCII case; use the snake_case name shown here.
The output is executable SQL with column names and literal row values. sql_insert_table names its destination, and other settings choose statement grouping and INSERT/REPLACE behavior.
Run the generated text as SQL to import it into a compatible existing table. It cannot be passed back through FORMAT sql_insert because this format has no input decoder.
```text
SELECT expressions FORMAT sql_insert;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT sql_insert;
```
```text
INSERT INTO table (`id`, `name`) VALUES (7, 'Ada');
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `sql_insert_batch_rows` | `UInt64` | `65505` | Write at most this many rows per INSERT or REPLACE statement; 0 writes one row per statement. |
| `sql_insert_column_names` | `Bool` | `1` | Include the result column names before VALUES in each written statement. |
| `sql_insert_quote_names` | `Bool` | `1` | Surround each written column name with backticks; names and the table text are otherwise written verbatim. |
| `sql_insert_replace` | `Bool` | `0` | Write REPLACE INTO instead of INSERT INTO. |
| `sql_insert_table` | `String` | `table` | The table text written verbatim after INSERT INTO or REPLACE INTO; include any desired qualification or quoting. |
---
Source: https://coordinatordb.com/docs/reference/formats/sql-values
Language: en
# sql_values
## Description
Comma-separated parenthesized literal rows. Input accepts SQL literals but does not evaluate arbitrary SQL expressions or functions.
Output has no trailing newline.
Input and output. Select it with `FORMAT sql_values`. Names ignore ASCII case; use the snake_case name shown here.
Each row is a parenthesized list of SQL literals; commas separate the rows. There is no INSERT prefix or column-name header.
Input decodes supported literals rather than evaluating expressions or functions. Supply a compatible destination column list and use ordinary INSERT VALUES when expression evaluation is needed. Output has no trailing newline.
```text
SELECT expressions FORMAT sql_values;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT sql_values
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT sql_values;
```
```text
(7,'Ada')
```
### Several literal rows
```sql
CREATE TABLE people (id UInt32, name String);
INSERT INTO people VALUES (1, 'Ada'), (2, 'Grace');
```
```sql
SELECT id, name FROM people ORDER BY id
FORMAT sql_values;
```
```text
(1,'Ada'),(2,'Grace')
```
Output has no trailing newline.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/sqlite
Language: en
# sqlite
## Description
A standalone SQLite database containing one selected table. sqlite_read_table chooses an input table; sqlite_write_table names the exported table, default table. This is an exchange format, not a copy of the active CoordinatorDB database.
Input and output. Select it with `FORMAT sqlite`. Names ignore ASCII case; use the snake_case name shown here.
Input selects one user table by sqlite_read_table, or the first table in catalog order by default. Target names match without regard to ASCII case, and missing requested columns are errors. Other tables, indexes and triggers are not imported.
Output writes one standalone table named by sqlite_write_table. Signed integers and Bool use INTEGER, floating-point values use REAL, and many other native values use TEXT. Supply a standalone committed input database: external WAL or journal contents are not part of the exchange file.
```text
SELECT expressions FORMAT sqlite;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT sqlite
```
## Example usage
Use the native client's `--query` mode to preserve binary output bytes. The server must be running, the executable available as `./coordinator`, and database `data` selected.
```sh
./coordinator client --database data --query "SELECT CAST(7 AS Int64) AS id FORMAT sqlite" > sample.sqlite
./coordinator client --database data --query "CREATE TABLE format_import(id Int64)" > /dev/null
./coordinator client --database data --query "INSERT INTO format_import FORMAT sqlite" < sample.sqlite > /dev/null
./coordinator client --database data --query "SELECT id FROM format_import FORMAT csv"
```
```text
7
```
Create `format_import` in a fresh database before running this example.
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `sqlite_read_table` | `String` | `''` | Read this table from the input database; empty selects its first user table. |
| `sqlite_write_table` | `String` | `table` | Name of the single table written to the output database. |
---
Source: https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated
Language: en
# tab_separated
## Description
Tab-separated fields, one row per line, with backslash escapes for control characters and the default NULL marker \N.
Input and output. Select it with `FORMAT tab_separated`. Names ignore ASCII case; use the snake_case name shown here.
Fields use literal tabs as separators and one line per row. Backslash escapes distinguish tabs, line breaks, backslashes and other control data from delimiters. The default NULL text is backslash-N.
This positional format has no names or types header. Use the same field order on import and choose the matching header variant when column identification is needed.
```text
SELECT expressions FORMAT tab_separated;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT tab_separated
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT tab_separated;
```
```text
7 Ada
```
### Escaping an embedded tab
The field contains a tab, but the output represents it with a backslash escape rather than a second field delimiter:
```sql
SELECT 'a' || char(9) || 'b' AS label, NULL AS missing
FORMAT tab_separated;
```
```text
a\tb \N
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `tab_separated_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `tab_separated_empty_as_default` | `Bool` | `0` | Give an empty field the column's DEFAULT instead of reading it as empty text. |
| `tab_separated_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `tab_separated_null_text` | `String` | `\N` | The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks. |
| `tab_separated_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `tab_separated_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
---
Source: https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-raw
Language: en
# tab_separated_raw
## Description
Tab-separated fields without outer escaping or an output header. Literal tabs and newlines in data can change record boundaries; choose an escaped format for such values.
Input and output. Select it with `FORMAT tab_separated_raw`. Names ignore ASCII case; use the snake_case name shown here.
The outer field values are written without tab-separated escaping. This is suitable only when the consumer can interpret those bytes and embedded delimiters are controlled.
Literal tabs or newlines can change the apparent field and row boundaries. Choose tab_separated when values can contain those characters and must round-trip through an escaped representation.
```text
SELECT expressions FORMAT tab_separated_raw;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT tab_separated_raw
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT tab_separated_raw;
```
```text
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `tab_separated_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `tab_separated_detect_header` | `Bool` | `1` | Recognize a raw TSV names header and optional matching types header before reading data. |
| `tab_separated_empty_as_default` | `Bool` | `0` | Give an empty field the column's DEFAULT instead of reading it as empty text. |
| `tab_separated_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `tab_separated_null_text` | `String` | `\N` | The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks. |
| `tab_separated_read_crlf` | `Bool` | `0` | Accept carriage-return/line-feed endings in raw TSV input, removing the carriage return from each record. |
| `tab_separated_skip_empty_lines` | `Bool` | `0` | Ignore empty lines at the end of raw TSV input; empty lines inside the data remain records. |
| `tab_separated_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `tab_separated_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
---
Source: https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-with-names
Language: en
# tab_separated_with_names
## Description
Escaped tab-separated fields with a first row of column names.
Input and output. Select it with `FORMAT tab_separated_with_names`. Names ignore ASCII case; use the snake_case name shown here.
The first escaped tab-separated row contains names, followed by ordinary data rows. Input can match names to destination columns using the format's header settings.
There is no type row. Use the names-and-types variant when type metadata must be checked as part of the import.
```text
SELECT expressions FORMAT tab_separated_with_names;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT tab_separated_with_names
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT tab_separated_with_names;
```
```text
id name
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `tab_separated_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `tab_separated_empty_as_default` | `Bool` | `0` | Give an empty field the column's DEFAULT instead of reading it as empty text. |
| `tab_separated_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `tab_separated_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `tab_separated_null_text` | `String` | `\N` | The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks. |
| `tab_separated_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `tab_separated_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
---
Source: https://coordinatordb.com/docs/reference/formats/tab-separated/tab-separated-with-names-and-types
Language: en
# tab_separated_with_names_and_types
## Description
Escaped tab-separated fields with column names followed by runtime type names.
Input and output. Select it with `FORMAT tab_separated_with_names_and_types`. Names ignore ASCII case; use the snake_case name shown here.
Names and runtime types occupy the first two escaped tab-separated rows. Later rows carry field values in the corresponding order.
The header settings control name matching and type validation. Runtime types can be wider than the original scalar declarations, so choose an import schema compatible with the emitted type row.
```text
SELECT expressions FORMAT tab_separated_with_names_and_types;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT tab_separated_with_names_and_types
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT tab_separated_with_names_and_types;
```
```text
id name
Int64 String
7 Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| -------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `tab_separated_check_types` | `Bool` | `1` | Compare the input types header with the bound target column types; when off, skip that header. |
| `tab_separated_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `tab_separated_empty_as_default` | `Bool` | `0` | Give an empty field the column's DEFAULT instead of reading it as empty text. |
| `tab_separated_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `tab_separated_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `tab_separated_null_text` | `String` | `\N` | The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks. |
| `tab_separated_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `tab_separated_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
---
Source: https://coordinatordb.com/docs/reference/formats/tab-separated/tskv
Language: en
# tskv
## Description
Tab-separated escaped name=value fields. Field names identify columns rather than relying on position.
Input and output. Select it with `FORMAT tskv`. Names ignore ASCII case; use the snake_case name shown here.
Each row contains escaped name=value fields separated by tabs. Field names identify the destination columns rather than relying on a fixed position.
Values follow the configured tab-separated escaping and default rules. Use the named layout when field order can vary, and inspect the unknown-field policy before accepting extra keys.
```text
SELECT expressions FORMAT tskv;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT tskv
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT tskv;
```
```text
id=7 name=Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ----------------------- | -------- | ------- | ---------------------------------------------------------------------------------------- |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
---
Source: https://coordinatordb.com/docs/reference/formats/template/template
Language: en
# template
## Description
Literal row and result templates with indexed or named placeholders and a per-field escaping rule. Set template_row and, when required, template_result. Unmatched literal text is an input error.
The row separator is written between rows. The example has no trailing newline;
include a newline in the row or result template when one is required.
Input and output. Select it with `FORMAT template`. Names ignore ASCII case; use the snake_case name shown here.
A template combines literal bytes with zero-based positional or named placeholders. Each placeholder states an escaping rule for that field. template_result can wrap the rows and include result placeholders.
Literal separators must match on input. The row separator is written only between rows; any final newline must come from a literal in the row or result template.
```text
SELECT expressions FORMAT template;
INSERT INTO table [(columns)] [SETTINGS ...] FORMAT template
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name SETTINGS template_row='${0:Raw}|${1:Raw}',template_row_separator='\n' FORMAT template;
```
```text
7|Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
| Setting | Type | Default | Meaning |
| ------------------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `template_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as strings in JSON template fields; retained narrow types stay numeric. |
| `template_result` | `String` | `''` | Literal result template; empty means `${data}`. Output supports data and rows; input may skip prefix or suffix fields. |
| `template_row` | `String` | `''` | Literal row template with named or zero-based column placeholders and per-field escaping; empty requires an override. |
| `template_row_separator` | `String` | `\n` | Text between template rows, excluding their own literals; never written after the final row. |
---
Source: https://coordinatordb.com/docs/reference/formats/vertical
Language: en
# vertical
## Description
Numbered rows with one labeled value on each line. This is output-only.
Output only. Select it with `FORMAT vertical`. Names ignore ASCII case; use the snake_case name shown here.
Each result row is numbered and displayed as a sequence of labelled values. This can make a wide result easier to inspect because every column has its own line.
It is a display format without an input decoder. Use a row or binary interchange format for round-trip storage.
```text
SELECT expressions FORMAT vertical;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT vertical;
```
```text
Row 1:
──────
id: 7
name: Ada
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
There are no format-specific settings.
---
Source: https://coordinatordb.com/docs/reference/formats/xml
Language: en
# xml
## Description
One XML document containing runtime column metadata, nested values and a row count. This is output-only.
Output only. Select it with `FORMAT xml`. Names ignore ASCII case; use the snake_case name shown here.
One document contains runtime column metadata, nested value representations and the result row count. Names and text are escaped according to the XML output rules.
The format is output-only. It is a result envelope rather than an XML import parser; use another supported input format to load rows.
```text
SELECT expressions FORMAT xml;
```
## Example usage
```sql
SELECT CAST(7 AS Int64) AS id, 'Ada' AS name FORMAT xml;
```
```text
id
Int64
name
String
7
Ada
1
```
## Format settings
Use a statement `SETTINGS` clause; these options are not persisted by `SET`.
There are no format-specific settings.
---
Source: https://coordinatordb.com/docs/reference/formats/yaml
Language: en
# yaml
## Description
The `yaml` format represents a result as one YAML document containing a sequence
of named mappings. Each mapping is one row, and its keys are column names.
The format supports input and output. Input keys select destination columns by
name, and target declarations validate the values. Missing fields use the
configured defaults. Unknown names raise an error unless
`ignore_unknown_fields = true`.
YAML Core Schema scalars are supported, including strings, numbers, booleans,
and `null`. Quote text that could otherwise be read as a number, boolean, or
missing value. Anchors, aliases, and non-Core tags are rejected. Native array,
tuple, map, and JSON targets validate nested sequences and mappings according
to their declared types.
## Example usage
Create a destination table:
```sql
CREATE TABLE people (id UInt32, name String);
```
Send this input as a separate request:
```sql
INSERT INTO people FORMAT yaml
- id: 1
name: Ada
- id: 2
name: Grace
```
Export the rows:
```sql
SELECT id, name FROM people ORDER BY id FORMAT yaml;
```
```text
- "id": 1
"name": "Ada"
- "id": 2
"name": "Grace"
```
## Format settings
There are no YAML-specific settings. Set the common
`ignore_unknown_fields` option on an input statement when extra mapping keys
should be skipped:
```text
INSERT INTO people SETTINGS ignore_unknown_fields = true FORMAT yaml
```
---
Source: https://coordinatordb.com/docs/reference/functions
Language: en
# Functions
Functions calculate values or provide rows to a query. Their role determines how they are called:
| Family | Role |
| --------- | -------------------------------------------------------------------- |
| Scalar | Calculate one value from expressions in the current row. |
| Aggregate | Calculate one result from several input rows or each GROUP BY group. |
| Table | Provide rows in a FROM clause. |
| Window | Calculate a value using related rows without collapsing the input. |
Names ignore ASCII case; use each documented snake_case spelling. Argument counts, accepted types, NULL behavior and errors are defined per function.
The server exposes descriptive metadata in [`system.functions`](https://coordinatordb.com/docs/reference/system-tables/functions), including before a database is selected. That catalog is descriptive, so a missing legacy entry is not proof that a function is unavailable.
## Reference
* [Aggregate functions](https://coordinatordb.com/docs/reference/functions/aggregate-functions)
* [Scalar functions](https://coordinatordb.com/docs/reference/functions/regular-functions/overview)
* [Table functions](https://coordinatordb.com/docs/reference/functions/table-functions)
* [Window functions](https://coordinatordb.com/docs/reference/functions/window-functions)
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions
Language: en
# Aggregate Functions
Aggregate functions calculate one result from several input rows. Without a
[`GROUP BY`](https://coordinatordb.com/docs/reference/statements/select/group-by) clause, they aggregate the
whole input. With `GROUP BY`, they calculate one result for each group.
CoordinatorDB also supports:
* [Combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators), which add
a condition or produce and combine intermediate aggregate states.
* `DISTINCT`, which removes duplicate argument values before aggregation.
* `FILTER (WHERE condition)`, which selects the rows admitted to an aggregate.
* `ORDER BY` inside an aggregate call, which determines the order of its input.
* [Window functions](https://coordinatordb.com/docs/reference/functions/window-functions), which apply
aggregates to a window while keeping individual result rows.
## NULL processing
Numeric and statistical aggregates skip `NULL` arguments. An aggregate with two
numeric arguments, such as `covar_pop(y, x)`, skips a row if either argument is
`NULL`. The remaining complete pairs determine both means and the count.
Collection aggregates have their own rules. In particular, `array_agg` and
`json_agg` retain `NULL` values. `count(*)` counts every row, whereas
`count(column)` counts only rows in which that column is not `NULL`.
**Examples:**
Create a table containing both present and missing values:
```sql
CREATE TABLE t_null_big (x Int32, y Int32);
INSERT INTO t_null_big VALUES
(1, 2),
(2, NULL),
(3, 2),
(3, 3),
(3, NULL);
```
The table contains:
```sql
SELECT x, y FROM t_null_big ORDER BY rowid FORMAT csv;
```
```text
1,2
2,\N
3,2
3,3
3,\N
```
To total the values in the `y` column, use [`sum`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum):
```sql
SELECT sum(y) FROM t_null_big FORMAT csv;
```
```text
7
```
Use [`array_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg) to collect the values into an array. Unlike
numeric aggregates, it retains missing values:
```sql
SELECT array_agg(y ORDER BY rowid) FROM t_null_big FORMAT csv;
```
```text
"[2,null,2,3,null]"
```
Use `FILTER` when the collection should contain only present values:
```sql
SELECT array_agg(y ORDER BY rowid) FILTER (WHERE y IS NOT NULL)
FROM t_null_big
FORMAT csv;
```
```text
"[2,2,3]"
```
Use [`coalesce`](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls#coalesce)
to replace `NULL` with a value appropriate for the calculation. Replacing a
missing measurement with zero makes it contribute to both the sum and the
number of measurements in the average:
```sql
SELECT round(avg(y), 6), avg(coalesce(y, 0))
FROM t_null_big
FORMAT csv;
```
```text
2.333333,1.4
```
An [`Array`](https://coordinatordb.com/docs/reference/data-types/array) or
[`Tuple`](https://coordinatordb.com/docs/reference/data-types/tuple) containing `NULL` is not itself SQL
`NULL`. Collection and tuple functions preserve those member values according
to the declared member types. There is no need to wrap a value in a tuple to
make `array_agg` retain it.
`count()` and `count(1)` count rows independently of their column values.
`count(y)` counts only present values, including when missing values form their
own group:
```sql
SELECT y, count(1), count(y)
FROM t_null_big
GROUP BY y
ORDER BY y NULLS FIRST
FORMAT csv;
```
```text
\N,2,0
2,2,2
3,1,1
```
The window functions [`first_value`](https://coordinatordb.com/docs/reference/functions/window-functions/first-value)
and [`last_value`](https://coordinatordb.com/docs/reference/functions/window-functions/last-value) select a row
from their window frame and retain `NULL` when the selected row contains it.
They do not accept `IGNORE NULLS` or `RESPECT NULLS` modifiers.
## Empty input
Most aggregates, including `sum`, `avg`, `min`, `max`, and `array_agg`, return
`NULL` when no value contributes. `count` returns zero and `total` returns
`0.0`. Conditional aggregates have their own empty-input behavior:
`count_if` and `sum_if` return zero, while `avg_if` returns `NULL`.
```sql
SELECT count(y), sum(y), avg(y), total(y)
FROM t_null_big
WHERE x > 100
FORMAT csv;
```
```text
0,\N,\N,0.0
```
A grouped query produces no result rows if its input contains no groups.
## Aggregate reference
See the [aggregate function reference](https://coordinatordb.com/docs/reference/functions/aggregate-functions/reference-index) for the supported
functions and their argument, result, and empty-input rules.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/any-value
Language: en
# any_value
Selects one non-`NULL` value from the input rows. Use this function when any member of the group is an acceptable result.
The selected value is unspecified unless an aggregate `ORDER BY` determines the admission order. Use [`min`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/min) or [`max`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/max) when the smallest or largest value is required.
**Syntax**
```text
any_value(value [ORDER BY expression])
```
**Arguments**
* `value` — An expression of any supported value type. `NULL` values are skipped.
**Returned value**
One original input value, with its native type preserved. Empty and all-`NULL` inputs return `NULL`.
**Examples**
**Selecting a representative value**
```sql
CREATE TABLE sessions (account TEXT, browser TEXT);
INSERT INTO sessions VALUES ('Acme', 'Firefox'), ('Acme', 'Chrome'), ('Beta', NULL);
```
```sql
SELECT account, any_value(browser ORDER BY browser) AS browser
FROM sessions
GROUP BY account
ORDER BY account
FORMAT csv;
```
```text
"Acme","Chrome"
"Beta",\N
```
**Preserving a native value**
```sql
CREATE TABLE values_to_choose (value Date);
INSERT INTO values_to_choose VALUES (CAST('2025-01-15' AS Date)), (NULL);
```
```sql
SELECT any_value(value)
FROM values_to_choose
FORMAT csv;
```
```text
"2025-01-15"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg
Language: en
# array_agg
Creates an array of the argument values. The array retains `NULL` elements; use `FILTER` to exclude them.
Specify an aggregate `ORDER BY` when the order of elements matters. Without it, the element order follows the rows admitted by the query and should not be relied on.
**Syntax**
```text
array_agg(value [ORDER BY expression])
```
**Arguments**
* `value` — A column or expression. The element type follows native collection type inference; nullable members are retained.
**Returned value**
A native [`Array`](https://coordinatordb.com/docs/reference/data-types/array) containing one element per admitted row. No input rows returns SQL `NULL`, rather than an empty array.
**Examples**
**Collecting names by department**
```sql
CREATE TABLE employees (department TEXT, name TEXT);
INSERT INTO employees VALUES ('Engineering', 'Ada'), ('Engineering', 'Grace'), ('Sales', 'Sam');
```
```sql
SELECT department, array_agg(name ORDER BY name) AS names
FROM employees
GROUP BY department
ORDER BY department
FORMAT csv;
```
```text
"Engineering","[""Ada"",""Grace""]"
"Sales","[""Sam""]"
```
**Keeping or removing NULL elements**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (10), (NULL), (20);
```
```sql
SELECT array_agg(value ORDER BY value NULLS LAST),
array_agg(value ORDER BY value) FILTER (WHERE value IS NOT NULL)
FROM readings
FORMAT csv;
```
```text
"[10,20,null]","[10,20]"
```
**Collecting distinct values**
```sql
CREATE TABLE tags (value TEXT);
INSERT INTO tags VALUES ('sql'), ('rust'), ('sql');
```
```sql
SELECT array_agg(DISTINCT value ORDER BY value)
FROM tags
FORMAT csv;
```
```text
"[""rust"",""sql""]"
```
See [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions) for reading and transforming the result.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg
Language: en
# avg
Calculates the arithmetic mean of numeric values. `NULL` values are skipped.
**Syntax**
```text
avg(x)
```
**Arguments**
* `x` — A numeric column or expression. Integers, floating-point numbers, and
decimals are supported. Legacy text and blob inputs use SQL numeric conversion.
Convert native dates, times, intervals, and other nonnumeric values explicitly
before averaging them.
**Returned value**
Returns a `REAL` mean for ordinary numeric inputs, or an exact decimal mean for
native decimal inputs. Empty or all-`NULL` input returns `NULL`.
Do not mix native decimals with approximate inputs without an explicit cast.
Exact overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Basic usage**
```sql
CREATE TABLE measurements (x Int8);
INSERT INTO measurements VALUES (0), (1), (2), (3), (4), (5);
```
```sql
SELECT avg(x) FROM measurements FORMAT csv;
```
```text
2.5
```
**Empty table returns NULL**
```sql
CREATE TABLE test (t UInt8);
```
```sql
SELECT avg(t) FROM test FORMAT csv;
```
```text
\N
```
**Average request duration**
Use a numeric duration in a known unit:
```sql
CREATE TABLE requests (req_id Int64, duration_ms UInt32);
INSERT INTO requests VALUES (1, 100), (2, 200), (3, 300);
```
```sql
SELECT avg(duration_ms) AS avg_duration_ms FROM requests FORMAT csv;
```
```text
200.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg-if
Language: en
# avg_if
Average non-NULL values from rows whose condition is SQL true.
**Syntax**
```text
avg_if(value, condition)
```
**Arguments**
value: numeric expression. condition: SQL truth expression. False and NULL conditions skip numeric accumulation; selected NULL values do not enter the divisor.
**Returned value**
The same REAL or native decimal result as avg; NULL when no non-NULL selected value exists.
**Examples**
```sql
CREATE TABLE orders (amount INTEGER);
INSERT INTO orders VALUES (1),(NULL),(2);
```
```sql
SELECT avg_if(amount,amount > 1) FROM orders FORMAT csv;
```
```text
2.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-and
Language: en
# bit_and
Applies bitwise AND to a sequence of integer values. `NULL` inputs are skipped.
**Syntax**
```text
bit_and(value)
```
**Arguments**
* `value` — An exact signed or unsigned integer, including native widths through 256 bits. Floating-point values, decimals and text raise `TYPE_MISMATCH`.
**Returned value**
The exact integer formed by applying AND to every admitted value. A declared integer width is retained; mixed runtime integer classes widen within native bounds. A result outside the supported native range raises `NUMERIC_OVERFLOW`.
An empty input, or an input containing only `NULL`, returns `NULL`.
**Examples**
**Combining bit masks**
In binary, `1100 AND 1010 = 1000`:
```sql
CREATE TABLE masks (value INTEGER);
INSERT INTO masks VALUES (12), (10), (NULL);
```
```sql
SELECT bit_and(value) AS combined_mask
FROM masks
FORMAT csv;
```
```text
8
```
**No non-NULL masks**
```sql
CREATE TABLE null_masks (value INTEGER);
INSERT INTO null_masks VALUES (NULL), (NULL);
```
```sql
SELECT bit_and(value)
FROM null_masks
FORMAT csv;
```
```text
\N
```
See [bit functions](https://coordinatordb.com/docs/reference/functions/regular-functions/bit-functions) for scalar bit operations.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-or
Language: en
# bit_or
Applies bitwise OR to a sequence of integer values. `NULL` inputs are skipped.
**Syntax**
```text
bit_or(value)
```
**Arguments**
* `value` — An exact signed or unsigned integer, including native widths through 256 bits. Floating-point values, decimals and text raise `TYPE_MISMATCH`.
**Returned value**
The exact integer formed by applying OR to every admitted value. A declared integer width is retained; mixed runtime integer classes widen within native bounds. A result outside the supported native range raises `NUMERIC_OVERFLOW`.
An empty input, or an input containing only `NULL`, returns `NULL`.
**Examples**
**Combining bit masks**
In binary, `1100 OR 1010 = 1110`:
```sql
CREATE TABLE masks (value INTEGER);
INSERT INTO masks VALUES (12), (10), (NULL);
```
```sql
SELECT bit_or(value) AS combined_mask
FROM masks
FORMAT csv;
```
```text
14
```
**No non-NULL masks**
```sql
CREATE TABLE null_masks (value INTEGER);
INSERT INTO null_masks VALUES (NULL), (NULL);
```
```sql
SELECT bit_or(value)
FROM null_masks
FORMAT csv;
```
```text
\N
```
See [bit functions](https://coordinatordb.com/docs/reference/functions/regular-functions/bit-functions) for scalar bit operations.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-xor
Language: en
# bit_xor
Applies bitwise XOR to a sequence of integer values. `NULL` inputs are skipped.
**Syntax**
```text
bit_xor(value)
```
**Arguments**
* `value` — An exact signed or unsigned integer, including native widths through 256 bits. Floating-point values, decimals and text raise `TYPE_MISMATCH`.
**Returned value**
The exact integer formed by applying XOR to every admitted value. A declared integer width is retained; mixed runtime integer classes widen within native bounds. A result outside the supported native range raises `NUMERIC_OVERFLOW`.
An empty input, or an input containing only `NULL`, returns `NULL`.
**Examples**
**Combining bit masks**
In binary, `1100 XOR 1010 = 0110`:
```sql
CREATE TABLE masks (value INTEGER);
INSERT INTO masks VALUES (12), (10), (NULL);
```
```sql
SELECT bit_xor(value) AS combined_mask
FROM masks
FORMAT csv;
```
```text
6
```
**No non-NULL masks**
```sql
CREATE TABLE null_masks (value INTEGER);
INSERT INTO null_masks VALUES (NULL), (NULL);
```
```sql
SELECT bit_xor(value)
FROM null_masks
FORMAT csv;
```
```text
\N
```
See [bit functions](https://coordinatordb.com/docs/reference/functions/regular-functions/bit-functions) for scalar bit operations.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/bool-and
Language: en
# bool_and
Return whether every non-NULL boolean input is true.
**Syntax**
```text
bool_and(value) [FILTER (WHERE ...)]
```
**Arguments**
Bool-convertible values: true, false, 0, 1, and corresponding text; other values error; Aggregate DISTINCT, FILTER, ORDER BY and ordinary windows are supported.
**Returned value**
Native Bool, or NULL for no non-NULL inputs.
**Examples**
```sql
CREATE TABLE checks (passed Bool);
INSERT INTO checks VALUES (true),(false),(NULL);
```
```sql
SELECT bool_and(passed) FROM checks FORMAT csv;
```
```text
false
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/bool-or
Language: en
# bool_or
Return whether any non-NULL boolean input is true.
**Syntax**
```text
bool_or(value) [FILTER (WHERE ...)]
```
**Arguments**
Bool-convertible values: true, false, 0, 1, and corresponding text; other values error; Aggregate DISTINCT, FILTER, ORDER BY and ordinary windows are supported.
**Returned value**
Native Bool, or NULL for no non-NULL inputs.
**Examples**
```sql
CREATE TABLE checks (passed Bool);
INSERT INTO checks VALUES (true),(false),(NULL);
```
```sql
SELECT bool_or(passed) FROM checks FORMAT csv;
```
```text
true
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators
Language: en
# Aggregate combinators
Aggregate combinators are named variants of an aggregate. A suffix changes whether the function filters input rows, returns an intermediate state, or combines previously calculated states.
CoordinatorDB provides the specific variants listed on this page. Names use underscores, such as `sum_if` and `avg_merge_state`.
## \_if
Conditional aggregates process only rows whose condition is SQL true. They let one query calculate totals for several segments without separate subqueries or joins.
```text
count_if(condition)
sum_if(value, condition)
avg_if(value, condition)
```
`count_if` counts matching rows. `sum_if` and `avg_if` use the same numeric conversion and overflow rules as [`sum`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum) and [`avg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg); selected `NULL` values are skipped. False and `NULL` conditions do not contribute.
If no non-`NULL` value contributes, `count_if` and `sum_if` return `0`, while `avg_if` returns `NULL`.
The arguments are evaluated before the aggregate tests the condition. A false condition does not protect a value expression from an evaluation error.
### Comparing order segments
```sql
CREATE TABLE orders (status String, amount UInt32);
INSERT INTO orders VALUES
('paid', 100), ('paid', 60), ('pending', 40), ('cancelled', 20);
```
```sql
SELECT count_if(status = 'paid') AS paid_orders,
sum_if(amount, status = 'paid') AS paid_amount,
sum_if(amount, status = 'pending') AS pending_amount,
avg_if(amount, status = 'paid') AS average_paid_order
FROM orders
FORMAT csv;
```
```text
2,160,40,80.0
```
Use the SQL `FILTER (WHERE condition)` clause for other aggregates. `sum(value) FILTER (...)` returns `NULL` when no value contributes; `sum_if` returns `0`.
## \_state
The `_state` variant returns the information needed to continue an aggregation, rather than only its final answer. The state has an [`AggregateFunction`](https://coordinatordb.com/docs/reference/data-types/aggregatefunction) type containing the aggregate name and its argument types.
For example, an average state retains both a total and a count. Combining these states weights each batch by its number of observations; averaging batch averages would lose that information.
| Aggregate | Build a state | Combine states and return a value | Combine states and return a state |
| --------- | --------------------------------------- | --------------------------------- | --------------------------------- |
| `sum` | `sum_state(value)` | `sum_merge(state)` | `sum_merge_state(state)` |
| `count` | `count_state()` or `count_state(value)` | `count_merge(state)` | `count_merge_state(state)` |
| `avg` | `avg_state(value)` | `avg_merge(state)` | `avg_merge_state(state)` |
| `min` | `min_state(value)` | `min_merge(state)` | `min_merge_state(state)` |
| `max` | `max_state(value)` | `max_merge(state)` | `max_merge_state(state)` |
`finalize_aggregation(state)` is a scalar function that reads the final value of one state. It does not combine several rows.
### Combining average states
```sql
CREATE TABLE readings(batch UInt8, value Int64);
INSERT INTO readings VALUES (1, 10), (1, 20), (2, 90);
CREATE TABLE batch_averages(batch UInt8, state AggregateFunction(avg, Int64));
INSERT INTO batch_averages
SELECT batch, avg_state(value)
FROM readings
GROUP BY batch;
```
Read each batch's average:
```sql
SELECT batch, finalize_aggregation(state) AS average_value
FROM batch_averages
ORDER BY batch
FORMAT csv;
```
```text
1,15.0
2,90.0
```
## \_merge
The `_merge` variant combines matching intermediate states and returns their
final aggregate value. Combine the states from the previous example to calculate
the mean of all three observations:
```sql
SELECT avg_merge(state) AS overall_average
FROM batch_averages
FORMAT csv;
```
```text
40.0
```
## \_merge_state
The `_merge_state` variant combines matching states and returns another state
instead of a final value. Use `avg_merge_state` to retain a combined average for
another stage:
```sql
SELECT finalize_aggregation(avg_merge_state(state))
FROM batch_averages
FORMAT csv;
```
```text
40.0
```
### State signatures and empty input
States can be merged only when the aggregate name and every argument type match exactly. A mismatched signature raises `TYPE_MISMATCH`. Declared column and cast types are retained even for an empty input.
Empty count and sum states finalize to zero. Empty minimum and maximum states finalize to their argument type's default. An empty average state finalizes to `NULL`. These state results differ from ordinary `sum`, `min` and `max` on empty input, which return `NULL`.
States use CoordinatorDB's native representation. They cannot be exchanged with ClickHouse aggregate-state bytes.
## \_simple_state
`_simple_state` returns a scalar partial result wrapped in a [`SimpleAggregateFunction`](https://coordinatordb.com/docs/reference/data-types/simpleaggregatefunction) type:
```text
sum_simple_state(value)
min_simple_state(value)
max_simple_state(value)
```
The partial value can be read directly and combined with ordinary `sum`, `min` or `max`; no `_merge` or finalization call is required. Inserting a partial result does not automatically combine table rows.
### Combining partial totals
```sql
CREATE TABLE partials
(
batch UInt8,
subtotal SimpleAggregateFunction(sum, Int64)
);
INSERT INTO partials
SELECT batch, sum_simple_state(value)
FROM readings
GROUP BY batch;
```
```sql
SELECT sum(subtotal) AS total_value
FROM partials
FORMAT csv;
```
```text
120
```
Use full intermediate states for averages and counts. Arbitrary suffix combinations, such as array or map combinators, are not supported.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr
Language: en
# corr
Calculates the Pearson correlation coefficient.
Correlation measures the strength and direction of a linear relationship. A value near 1 indicates that both variables rise together; a value near -1 indicates that one falls as the other rises.
**Syntax**
```text
corr(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy / sqrt(Sxx * Syy)
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
A `REAL` value between -1 and 1. Fewer than two complete pairs, or zero variance in either variable, returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(corr(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
1.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT corr(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/count
Language: en
# count
Counts the number of rows or non-`NULL` values.
CoordinatorDB supports:
* `count(expr)` and `count(DISTINCT expr)`.
* `count()` and `count(*)`.
**Details**
`count(*)`, `count()`, and `count(1)` count every admitted row, including rows
containing `NULL`. `count(expr)` evaluates the expression for each row and
counts its non-`NULL` results. `DISTINCT` counts distinct non-`NULL` values using
SQL comparison and the applicable collation.
Use `FILTER (WHERE condition)` to select which rows an aggregate counts, or
[`count_if`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) to count rows satisfying a condition.
**Syntax**
```text
count()
count(*)
count(expr)
count(DISTINCT expr)
```
**Arguments**
* `expr` — Optional. Any SQL expression. When supplied, only its non-`NULL`
results contribute to the count.
**Returned value**
A nonnegative signed `INTEGER`. Empty input returns zero.
**Examples**
**Basic row count**
```sql
CREATE TABLE t (num UInt8);
INSERT INTO t VALUES (1), (1), (2), (2), (3);
```
```sql
SELECT count() FROM t FORMAT csv;
```
```text
5
```
**COUNT(DISTINCT) example**
```sql
SELECT count(DISTINCT num) FROM t FORMAT csv;
```
```text
3
```
**Counting missing values**
```sql
INSERT INTO t VALUES (NULL);
```
```sql
SELECT count(*), count(num), count(*) FILTER (WHERE num IS NULL)
FROM t
FORMAT csv;
```
```text
6,5,1
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/count-if
Language: en
# count_if
Count rows whose condition is SQL true; skip false and NULL conditions.
**Syntax**
```text
count_if(condition)
```
**Arguments**
condition: one SQL expression per row. Nonzero numeric truth selects the row; ordinary SQL truth conversion applies.
**Returned value**
Nonnegative signed INTEGER count; 0 for empty input or no true conditions, saturating at 9223372036854775807.
**Examples**
```sql
CREATE TABLE orders (amount INTEGER);
INSERT INTO orders VALUES (1),(NULL),(2);
```
```sql
SELECT count_if(amount > 1) FROM orders FORMAT csv;
```
```text
1
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop
Language: en
# covar_pop
Calculates the population covariance.
Use population covariance when the input contains the entire population you want to describe. The denominator is the number of complete pairs.
**Syntax**
```text
covar_pop(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy / n
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
A `REAL` covariance. No complete pairs returns `NULL`; a single complete pair returns `0.0`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(covar_pop(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
2.5
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT covar_pop(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp
Language: en
# covar_samp
Calculates the sample covariance.
Use sample covariance when the input is a sample from a larger population. The denominator is one less than the number of complete pairs.
**Syntax**
```text
covar_samp(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy / (n - 1)
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
A `REAL` covariance. Fewer than two complete pairs returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(covar_samp(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
3.333333
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT covar_samp(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/group-concat
Language: en
# group_concat and string_agg
Calculates a string from the non-`NULL` values in a group, separated by a delimiter.
`group_concat` uses a comma when the delimiter is omitted. `string_agg` is the two-argument alias and requires an explicit delimiter.
**Syntax**
```text
group_concat(value [, separator] [ORDER BY expression])
string_agg(value, separator [ORDER BY expression])
```
**Arguments**
* `value` — The value to concatenate. Non-text values are converted to their text representation. `NULL` values are skipped.
* `separator` — The text placed between contributing values. The default for `group_concat` is `','`. A `NULL` separator adds no bytes.
When the separator is an expression that varies by row, each contributing row after the first uses its own separator. No separator is written before the first value.
**Returned value**
A text string. Empty and all-`NULL` inputs return `NULL`. A contributing empty string produces an empty string, rather than `NULL`.
**Examples**
**Joining employee names**
```sql
CREATE TABLE employees (name TEXT);
INSERT INTO employees VALUES ('Grace'), ('Ada'), (NULL), ('Linus');
```
```sql
SELECT group_concat(name, ', ' ORDER BY name) AS names
FROM employees
FORMAT csv;
```
```text
"Ada, Grace, Linus"
```
**Using the default separator and an explicit separator**
```sql
CREATE TABLE items (value TEXT);
INSERT INTO items VALUES ('b'), ('a'), ('c');
```
```sql
SELECT group_concat(value ORDER BY value),
string_agg(value, ' | ' ORDER BY value)
FROM items
FORMAT csv;
```
```text
"a,b,c","a | b | c"
```
**Removing duplicate values**
```sql
CREATE TABLE tags (value TEXT);
INSERT INTO tags VALUES ('sql'), ('rust'), ('sql');
```
```sql
SELECT group_concat(DISTINCT value ORDER BY value)
FROM tags
FORMAT csv;
```
```text
"rust,sql"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-agg
Language: en
# json_agg
Collect group inputs, including NULL, into a JSON array.
**Syntax**
```text
json_agg(value)
```
**Arguments**
One SQL expression per row, converted to a JSON value. FILTER, DISTINCT, ordering and windows are supported.
**Returned value**
JSON-tagged TEXT array, or NULL when no input row exists.
**Examples**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1),(NULL),(2);
```
```sql
SELECT json_agg(value) FROM readings FORMAT csv;
```
```text
"[1,null,2]"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-agg-strict
Language: en
# json_agg_strict
Collect rows into a native JSON array.
**Syntax**
```text
json_agg_strict(value)
```
**Arguments**
One SQL value per row. Skip SQL NULL values; retain a JSON null value. Plain JSON preserves object input order and nested duplicates. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1),(NULL),(2);
```
```sql
SELECT json_agg_strict(value) FROM readings FORMAT csv;
```
```text
"[1,2]"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-group-array
Language: en
# json_group_array
Collects input values into a JSON text array. SQL `NULL` becomes a JSON `null`
element. Text values are quoted as JSON strings; use `json(value)` to parse
JSON text before including it as a structured value.
**Syntax**
```text
json_group_array(value [ORDER BY expression])
```
**Arguments**
* `value` — One SQL value per row. Binary blobs are rejected.
`DISTINCT`, `FILTER`, aggregate ordering, and ordinary window calls are supported.
**Returned value**
A JSON text array. Empty input returns `[]`. The related
[`json_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-agg) returns `NULL` for empty input.
**Examples**
```sql
CREATE TABLE readings (value Int32);
INSERT INTO readings VALUES (1), (NULL), (3);
```
```sql
SELECT json_group_array(value ORDER BY rowid) FROM readings FORMAT csv;
```
```text
"[1,null,3]"
```
```sql
SELECT json_group_array(value) FROM readings WHERE value > 100 FORMAT csv;
```
```text
"[]"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-group-object
Language: en
# json_group_object
Collects name/value pairs into a JSON text object. Missing values become JSON
`null`; duplicate names are retained.
**Syntax**
```text
json_group_object(name, value [ORDER BY expression])
```
**Arguments**
* `name` — A non-`NULL` object key. Other SQL values are converted to text.
A `NULL` key raises an error.
* `value` — A SQL value. Text is quoted as a JSON string; `json(value)` parses
text before including it as a structured value. Binary blobs are rejected.
`FILTER`, aggregate ordering, and ordinary window calls are supported.
**Returned value**
A JSON text object. Empty input returns `{}`.
**Examples**
```sql
CREATE TABLE attributes (name String, value Int32);
INSERT INTO attributes VALUES ('available', 12), ('reserved', NULL);
```
```sql
SELECT json_group_object(name, value ORDER BY name)
FROM attributes
FORMAT csv;
```
```text
"{""available"":12,""reserved"":null}"
```
```sql
SELECT json_group_object(name, value)
FROM attributes
WHERE value > 100
FORMAT csv;
```
```text
"{}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg
Language: en
# json_object_agg
Aggregate key/value pairs into native JSON, including NULL values and retaining duplicate keys.
**Syntax**
```text
json_object_agg(key, value [ORDER BY ...]) [FILTER (WHERE ...)]
```
**Arguments**
Scalar non-NULL keys and SQL values; DISTINCT, FILTER, ordering, and ordinary windows are supported.
**Returned value**
Native JSON object; empty input returns NULL.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT json_object_agg(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1,""b"":null}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-strict
Language: en
# json_object_agg_strict
Collect rows into a native JSON object.
**Syntax**
```text
json_object_agg_strict(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Skip SQL NULL values; retain a JSON null value. Plain JSON preserves object input order and nested duplicates. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT json_object_agg_strict(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-unique
Language: en
# json_object_agg_unique
Collect rows into a native JSON object.
**Syntax**
```text
json_object_agg_unique(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Retain SQL NULL values as JSON null. All keys, including skipped NULL-value keys, must be unique; duplicates raise DUPLICATE_JSON_KEY. Plain JSON preserves object input order and nested duplicates. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT json_object_agg_unique(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1,""b"":null}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-unique-strict
Language: en
# json_object_agg_unique_strict
Collect rows into a native JSON object.
**Syntax**
```text
json_object_agg_unique_strict(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Skip SQL NULL values; retain a JSON null value. All keys, including skipped NULL-value keys, must be unique; duplicates raise DUPLICATE_JSON_KEY. Plain JSON preserves object input order and nested duplicates. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT json_object_agg_unique_strict(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-agg
Language: en
# jsonb_agg
Aggregate values into a canonical native JSON array.
**Syntax**
```text
jsonb_agg(value [ORDER BY ...])
```
**Arguments**
Includes NULL as JSON null; canonicalizes nested objects. FILTER, DISTINCT and ordinary windows apply. Retains encoded values; repeated finalization preserves state.
**Returned value**
Native JSON array, or SQL NULL for an empty input.
**Examples**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1),(NULL),(2);
```
```sql
SELECT jsonb_agg(value) FROM readings FORMAT csv;
```
```text
"[1,null,2]"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-agg-strict
Language: en
# jsonb_agg_strict
Collect rows into a native JSON array.
**Syntax**
```text
jsonb_agg_strict(value)
```
**Arguments**
One SQL value per row. Skip SQL NULL values; retain a JSON null value. JSONB forms recursively normalize keys and final values. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1),(NULL),(2);
```
```sql
SELECT jsonb_agg_strict(value) FROM readings FORMAT csv;
```
```text
"[1,2]"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg
Language: en
# jsonb_object_agg
Aggregate key/value pairs with final-key-wins semantics.
**Syntax**
```text
jsonb_object_agg(key,value [ORDER BY ...])
```
**Arguments**
Non-NULL scalar keys; NULL values are retained. Only final values per unique key are retained. FILTER, DISTINCT and ordinary windows apply; specify ORDER BY when duplicate-key order matters.
**Returned value**
Canonical native JSON object, or SQL NULL for empty input.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('a',2);
```
```sql
SELECT jsonb_object_agg(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":2}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-strict
Language: en
# jsonb_object_agg_strict
Collect rows into a native JSON object.
**Syntax**
```text
jsonb_object_agg_strict(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Skip SQL NULL values; retain a JSON null value. JSONB forms recursively normalize keys and final values. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT jsonb_object_agg_strict(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-unique
Language: en
# jsonb_object_agg_unique
Collect rows into a native JSON object.
**Syntax**
```text
jsonb_object_agg_unique(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Retain SQL NULL values as JSON null. All keys, including skipped NULL-value keys, must be unique; duplicates raise DUPLICATE_JSON_KEY. JSONB forms recursively normalize keys and final values. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT jsonb_object_agg_unique(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1,""b"":null}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-unique-strict
Language: en
# jsonb_object_agg_unique_strict
Collect rows into a native JSON object.
**Syntax**
```text
jsonb_object_agg_unique_strict(key,value)
```
**Arguments**
Scalar non-NULL keys and native values. Skip SQL NULL values; retain a JSON null value. All keys, including skipped NULL-value keys, must be unique; duplicates raise DUPLICATE_JSON_KEY. JSONB forms recursively normalize keys and final values. Tuple values use named/fN fields. FILTER, DISTINCT, aggregate ordering, and ordinary windows apply.
**Returned value**
Native JSON. No input rows returns SQL NULL; rows containing only skipped SQL NULL values produce an empty container.
**Examples**
```sql
CREATE TABLE attributes (name TEXT, value INTEGER);
INSERT INTO attributes VALUES ('a',1),('b',NULL);
```
```sql
SELECT jsonb_object_agg_unique_strict(name,value) FROM attributes FORMAT csv;
```
```text
"{""a"":1}"
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/max
Language: en
# max
Calculates the maximum of the non-`NULL` input values. The selected value keeps its original native type.
With one argument, `max` is an aggregate over rows. With two or more arguments, it is a scalar function comparing the arguments of one row.
**Syntax**
```text
max(value)
max(value1, value2, ...)
```
**Arguments**
* `value` — An expression to compare across input rows. SQL value ordering and the selected collation determine the result.
* `value1, value2, ...` — Two or more values for the scalar form.
**Returned value**
The largest input value. The aggregate skips `NULL` and returns `NULL` for empty or all-`NULL` input. The scalar form returns `NULL` if any argument is `NULL`.
**Examples**
**Finding the largest salary**
```sql
CREATE TABLE employees (salary INTEGER);
INSERT INTO employees VALUES (46000), (NULL), (59000), (72000);
```
```sql
SELECT max(salary)
FROM employees
FORMAT csv;
```
```text
72000
```
**Comparing native dates**
```sql
CREATE TABLE events (day Date);
INSERT INTO events VALUES (CAST('2025-03-10' AS Date)), (CAST('2025-01-05' AS Date));
```
```sql
SELECT max(day)
FROM events
FORMAT csv;
```
```text
"2025-03-10"
```
**Comparing values within one row**
```sql
SELECT max(8, 3, 12), max(8, NULL, 12)
FORMAT csv;
```
```text
12,\N
```
**Related functions**
* [`min`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/min) selects the smallest value.
* [`any_value`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/any-value) selects a representative non-`NULL` value.
* [`max_state` and `max_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) store and combine intermediate extrema.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/min
Language: en
# min
Calculates the minimum of the non-`NULL` input values. The selected value keeps its original native type.
With one argument, `min` is an aggregate over rows. With two or more arguments, it is a scalar function comparing the arguments of one row.
**Syntax**
```text
min(value)
min(value1, value2, ...)
```
**Arguments**
* `value` — An expression to compare across input rows. SQL value ordering and the selected collation determine the result.
* `value1, value2, ...` — Two or more values for the scalar form.
**Returned value**
The smallest input value. The aggregate skips `NULL` and returns `NULL` for empty or all-`NULL` input. The scalar form returns `NULL` if any argument is `NULL`.
**Examples**
**Finding the smallest salary**
```sql
CREATE TABLE employees (salary INTEGER);
INSERT INTO employees VALUES (46000), (NULL), (59000), (72000);
```
```sql
SELECT min(salary)
FROM employees
FORMAT csv;
```
```text
46000
```
**Comparing native dates**
```sql
CREATE TABLE events (day Date);
INSERT INTO events VALUES (CAST('2025-03-10' AS Date)), (CAST('2025-01-05' AS Date));
```
```sql
SELECT min(day)
FROM events
FORMAT csv;
```
```text
"2025-01-05"
```
**Comparing values within one row**
```sql
SELECT min(8, 3, 12), min(8, NULL, 12)
FORMAT csv;
```
```text
3,\N
```
**Related functions**
* [`max`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/max) selects the largest value.
* [`any_value`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/any-value) selects a representative non-`NULL` value.
* [`min_state` and `min_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators) store and combine intermediate extrema.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/mode
Language: en
# mode
Select the most frequent non-NULL native value using the selected collation.
**Syntax**
```text
mode() WITHIN GROUP(ORDER BY value [ASC|DESC]) or mode(value[,descending])
```
**Returned value**
Original native value; empty input gives NULL; FILTER/DISTINCT supported.
**Examples**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1),(2),(2),(3);
```
```sql
SELECT mode() WITHIN GROUP(ORDER BY value) FROM readings FORMAT csv;
```
```text
2
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/percentile-cont
Language: en
# percentile_cont
Calculates a continuous numeric percentile. When the requested position falls
between two values, the result is interpolated between them. `NULL` values are
skipped.
**Syntax**
```text
percentile_cont(fraction) WITHIN GROUP (ORDER BY value [ASC|DESC])
percentile_cont(fraction, value[, descending])
```
**Arguments**
* `fraction` — A number from zero through one, independent of the group's input
rows. It is validated even when the input is empty.
* `value` — A numeric expression. `NULL` values are skipped.
* `descending` — An optional constant boolean selecting descending order in
the direct form. The default order is ascending.
Use `FILTER` to select input rows. Array fractions, interval values, and window
calls with `OVER` are not supported.
**Returned value**
A `REAL` percentile, or `NULL` for a `NULL` fraction or no non-`NULL` inputs.
**Examples**
```sql
CREATE TABLE readings (value Int32);
INSERT INTO readings VALUES (10), (20), (30), (40), (NULL);
```
```sql
SELECT percentile_cont(0.5) WITHIN GROUP (ORDER BY value)
FROM readings
FORMAT csv;
```
```text
25.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/percentile-disc
Language: en
# percentile_disc
Selects an actual input value at the requested percentile. Unlike
[`percentile_cont`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/percentile-cont), this function does not interpolate
between values. `NULL` values are skipped.
**Syntax**
```text
percentile_disc(fraction) WITHIN GROUP (ORDER BY value [ASC|DESC])
percentile_disc(fraction, value[, descending])
```
**Arguments**
* `fraction` — A number from zero through one, independent of the group's input
rows. It is validated even when the input is empty.
* `value` — An ordered SQL value. Comparison uses its type and collation;
`NULL` values are skipped.
* `descending` — An optional constant boolean selecting descending order in
the direct form. The default order is ascending.
Use `FILTER` to select input rows. Window calls with `OVER` are not supported.
**Returned value**
The original input value at position `ceil(fraction * count)`, counting from
one. A fraction of zero selects the first value. A `NULL` fraction or no
non-`NULL` inputs returns `NULL`.
**Examples**
```sql
CREATE TABLE readings (value Int32);
INSERT INTO readings VALUES (10), (20), (30), (40), (NULL);
```
```sql
SELECT percentile_disc(0.5) WITHIN GROUP (ORDER BY value)
FROM readings
FORMAT csv;
```
```text
20
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/reference-index
Language: en
# Aggregate Function Reference
Aggregate functions combine several input rows into one result. See the
[overview](https://coordinatordb.com/docs/reference/functions/aggregate-functions) for NULL handling and aggregate modifiers, or follow an
individual function for its syntax, result type, and examples.
## Counting, totals, and extrema
* [`count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/count)
* [`sum`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum)
* [`total`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/total)
* [`avg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg)
* [`min`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/min)
* [`max`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/max)
* [`any_value`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/any-value)
## Conditional aggregates
* [`count_if`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/count-if)
* [`sum_if`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum-if)
* [`avg_if`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg-if)
## Statistics
* [`stddev_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-pop)
* [`stddev_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-samp)
* [`var_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-pop)
* [`var_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-samp)
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop)
* [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp)
* [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr)
* [`regr_avgx`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgx)
* [`regr_avgy`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgy)
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count)
* [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept)
* [`regr_r2`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-r2)
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope)
* [`regr_sxx`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxx)
* [`regr_sxy`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxy)
* [`regr_syy`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-syy)
* [`mode`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/mode)
* [`percentile_cont`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/percentile-cont)
* [`percentile_disc`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/percentile-disc)
## Boolean and bitwise aggregates
* [`bool_and`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bool-and)
* [`bool_or`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bool-or)
* [`bit_and`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-and)
* [`bit_or`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-or)
* [`bit_xor`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-xor)
## Arrays and strings
* [`array_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg)
* [`group_concat`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/group-concat)
* [`string_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/group-concat)
## JSON aggregates
* [`json_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-agg)
* [`json_agg_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-agg-strict)
* [`json_group_array`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-group-array)
* [`json_group_object`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-group-object)
* [`json_object_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg)
* [`json_object_agg_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-strict)
* [`json_object_agg_unique`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-unique)
* [`json_object_agg_unique_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/json-object-agg-unique-strict)
* [`jsonb_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-agg)
* [`jsonb_agg_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-agg-strict)
* [`jsonb_object_agg`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg)
* [`jsonb_object_agg_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-strict)
* [`jsonb_object_agg_unique`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-unique)
* [`jsonb_object_agg_unique_strict`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/jsonb-object-agg-unique-strict)
## Intermediate aggregate states
* [`avg_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge)
* [`avg_merge_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge_state)
* [`avg_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_state)
* [`count_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge)
* [`count_merge_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge_state)
* [`count_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_state)
* [`max_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge)
* [`max_merge_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge_state)
* [`max_simple_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_simple_state)
* [`max_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_state)
* [`min_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge)
* [`min_merge_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge_state)
* [`min_simple_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_simple_state)
* [`min_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_state)
* [`sum_merge`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge)
* [`sum_merge_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_merge_state)
* [`sum_simple_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_simple_state)
* [`sum_state`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators#_state)
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgx
Language: en
# regr_avgx
Calculates the mean of the independent variable over complete pairs.
Rows with a missing `y` are excluded even when `x` is present. Consequently, this function can differ from `avg(x)` on the same table.
**Syntax**
```text
regr_avgx(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
sum(x) / n
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The paired mean of `x` as `REAL`. No complete pairs returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_avgx(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
2.5
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_avgx(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgy
Language: en
# regr_avgy
Calculates the mean of the dependent variable over complete pairs.
Rows with a missing `x` are excluded even when `y` is present. Consequently, this function can differ from `avg(y)` on the same table.
**Syntax**
```text
regr_avgy(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
sum(y) / n
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The paired mean of `y` as `REAL`. No complete pairs returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_avgy(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
6.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_avgy(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count
Language: en
# regr_count
Counts input pairs for which both numeric arguments are non-`NULL`. Use it to find the number of observations admitted by the covariance, correlation and regression aggregates.
**Syntax**
```text
regr_count(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row with either argument `NULL` is excluded. Nonfinite numeric pairs are counted.
**Returned value**
A nonnegative `INTEGER` pair count. Empty input, or input with no complete pairs, returns `0`.
**Examples**
**Counting complete observations**
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, NULL), (NULL, 9);
```
```sql
SELECT count(*) AS rows,
count(hour) AS hours,
count(reading) AS readings,
regr_count(reading, hour) AS complete_pairs
FROM measurements
FORMAT csv;
```
```text
4,3,3,2
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_count(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
0
```
See [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope), [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) for calculations over the admitted pairs.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept
Language: en
# regr_intercept
Calculates the intercept of a least-squares regression line.
For a fitted line `y = slope * x + intercept`, the intercept is the predicted value of `y` when `x` is zero.
**Syntax**
```text
regr_intercept(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
mean_y - regr_slope(y, x) * mean_x
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The intercept as `REAL`. Fewer than two complete pairs, or zero variation in `x`, returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_intercept(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
1.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_intercept(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-r2
Language: en
# regr_r2
Calculates the coefficient of determination of a linear regression.
The result describes how much of the variation in `y` is explained by a straight-line relationship with `x`. A result of 1 indicates a perfect fit.
**Syntax**
```text
regr_r2(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy * Sxy / (Sxx * Syy)
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
A `REAL` value between 0 and 1. No complete pairs or zero variation in `x` returns `NULL`. If `x` varies and `y` is constant, the result is `1.0`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_r2(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
1.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_r2(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope
Language: en
# regr_slope
Calculates the slope of a least-squares regression line.
For a fitted line `y = slope * x + intercept`, the slope is the change in the predicted `y` for a one-unit increase in `x`.
**Syntax**
```text
regr_slope(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy / Sxx
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The slope as `REAL`. Fewer than two complete pairs, or zero variation in `x`, returns `NULL`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_slope(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
2.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_slope(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxx
Language: en
# regr_sxx
Calculates the sum of squared deviations of the independent variable.
This is the denominator used by `regr_slope`. It is zero when every admitted `x` value is the same.
**Syntax**
```text
regr_sxx(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxx = sum((x - mean_x) * (x - mean_x))
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The nonnegative centered sum of squares as `REAL`. No complete pairs returns `NULL`; one complete pair returns `0.0`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_sxx(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
5.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_sxx(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxy
Language: en
# regr_sxy
Calculates the sum of products of centered input pairs.
Dividing this sum by the pair count gives population covariance. Dividing by one less than the pair count gives sample covariance.
**Syntax**
```text
regr_sxy(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Sxy = sum((x - mean_x) * (y - mean_y))
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The centered cross-product sum as `REAL`. No complete pairs returns `NULL`; one complete pair returns `0.0`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_sxy(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
10.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_sxy(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-syy
Language: en
# regr_syy
Calculates the sum of squared deviations of the dependent variable.
This measures the total squared variation in the admitted `y` values before dividing by a population or sample count.
**Syntax**
```text
regr_syy(y, x)
```
**Arguments**
* `y` — The dependent numeric variable.
* `x` — The independent numeric variable.
A row contributes only when both arguments are non-`NULL`. The means and the count in the formulas below use these complete pairs, rather than each column separately.
**Calculation**
```text
Syy = sum((y - mean_y) * (y - mean_y))
```
Here `n` is the number of complete pairs, `mean_x` and `mean_y` are their arithmetic means, `Sxx` and `Syy` are their centered sums of squares, and `Sxy` is their centered cross-product sum.
**Returned value**
The nonnegative centered sum of squares as `REAL`. No complete pairs returns `NULL`; one complete pair returns `0.0`.
The result is approximate, including when the inputs are exact integers or decimals. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measurements with a linear relationship**
The complete observations below follow `reading = 2 * hour + 1`. The two incomplete observations are excluded.
```sql
CREATE TABLE measurements (hour INTEGER, reading INTEGER);
INSERT INTO measurements VALUES (1, 3), (2, 5), (3, 7), (4, 9), (5, NULL), (NULL, 100);
```
```sql
SELECT round(regr_syy(reading, hour), 6) AS result
FROM measurements
FORMAT csv;
```
```text
20.0
```
**No complete observations**
```sql
CREATE TABLE incomplete_measurements (hour INTEGER, reading INTEGER);
INSERT INTO incomplete_measurements VALUES (1, NULL), (NULL, 5);
```
```sql
SELECT regr_syy(reading, hour)
FROM incomplete_measurements
FORMAT csv;
```
```text
\N
```
**Related functions**
* [`regr_count`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count) counts the pairs used by the calculation.
* [`regr_slope`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope) and [`regr_intercept`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept) describe the fitted line.
* [`covar_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop), [`covar_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp) and [`corr`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr) describe the relationship between the variables.
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-pop
Language: en
# stddev_pop
Calculates the population standard deviation.
The result is the square root of the population variance, [`var_pop`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-pop). It has the same units as the observations.
**Syntax**
```text
stddev_pop(x)
```
**Arguments**
* `x` — A numeric column or expression. `NULL` values are skipped.
**Calculation**
```text
sqrt(sum((x - mean) * (x - mean)) / (n))
```
`mean` is the arithmetic mean of the non-`NULL` values, and `n` is their count. The population calculation uses `n` because the observations describe the entire population.
**Returned value**
An approximate `REAL` value. Empty or all-`NULL` input returns `NULL`; one non-`NULL` input returns `0.0`. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measuring the spread of readings**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1), (3), (5), (7), (9), (NULL);
```
```sql
SELECT round(stddev_pop(value), 6) AS result
FROM readings
FORMAT csv;
```
```text
2.828427
```
**A single observation**
```sql
CREATE TABLE single_reading (value INTEGER);
INSERT INTO single_reading VALUES (7), (NULL);
```
```sql
SELECT stddev_pop(value)
FROM single_reading
FORMAT csv;
```
```text
0.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-samp
Language: en
# stddev_samp
Calculates the sample standard deviation.
The result is the square root of the sample variance, [`var_samp`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-samp). It has the same units as the observations.
**Syntax**
```text
stddev_samp(x)
```
**Arguments**
* `x` — A numeric column or expression. `NULL` values are skipped.
**Calculation**
```text
sqrt(sum((x - mean) * (x - mean)) / (n - 1))
```
`mean` is the arithmetic mean of the non-`NULL` values, and `n` is their count. The sample calculation uses `n - 1` because the observations estimate a larger population.
**Returned value**
An approximate `REAL` value. Fewer than two non-`NULL` inputs returns `NULL`. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measuring the spread of readings**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1), (3), (5), (7), (9), (NULL);
```
```sql
SELECT round(stddev_samp(value), 6) AS result
FROM readings
FORMAT csv;
```
```text
3.162278
```
**A single observation**
```sql
CREATE TABLE single_reading (value INTEGER);
INSERT INTO single_reading VALUES (7), (NULL);
```
```sql
SELECT stddev_samp(value)
FROM single_reading
FORMAT csv;
```
```text
\N
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum
Language: en
# sum
Calculates the sum of numeric values. `NULL` values do not contribute to the sum.
**Syntax**
```text
sum(num)
```
**Arguments**
* `num` — A numeric column or expression. Integers, floating-point numbers, and
decimals are supported. Legacy text and blob values use SQL numeric conversion.
Native dates, times, intervals, addresses, and collections require an explicit
numeric conversion.
**Returned value**
Returns the sum of the non-`NULL` values, or `NULL` for empty or all-`NULL` input.
* Ordinary integers produce an `INTEGER` result. Exact overflow raises
`NUMERIC_OVERFLOW`.
* Floating-point inputs produce a `REAL` result.
* Native unsigned and wide integers retain an exact numeric result within their
supported range.
* Decimals produce an exact decimal total. Mixing decimals with approximate
inputs raises `TYPE_MISMATCH`; cast the inputs to one numeric family first.
Use `coalesce(sum(num), 0)` when an empty result should be zero. `total(num)`
always produces a floating-point total and returns `0.0` for empty input.
**Examples**
**Computing sum of employee salaries**
```sql
CREATE TABLE employees
(
id UInt32,
name String,
salary UInt32
);
INSERT INTO employees VALUES
(87432, 'John Smith', 45680),
(59018, 'Jane Smith', 72350),
(20376, 'Ivan Ivanovich', 58900),
(71245, 'Anastasia Ivanovna', 89210);
```
```sql
SELECT sum(salary) FROM employees FORMAT csv;
```
```text
266140
```
**Total time spent on requests**
Store the duration as a numeric number of milliseconds:
```sql
CREATE TABLE requests (req_id UInt32, duration_ms UInt32);
INSERT INTO requests VALUES (1, 100), (2, 200), (3, 300);
```
```sql
SELECT sum(duration_ms) AS total_duration_ms FROM requests FORMAT csv;
```
```text
600
```
**Missing values and empty input**
```sql
INSERT INTO requests VALUES (4, NULL);
```
```sql
SELECT sum(duration_ms) FROM requests FORMAT csv;
```
```text
600
```
```sql
SELECT sum(duration_ms), coalesce(sum(duration_ms), 0)
FROM requests
WHERE req_id > 100
FORMAT csv;
```
```text
\N,0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum-if
Language: en
# sum_if
Sum non-NULL values from rows whose condition is SQL true.
**Syntax**
```text
sum_if(value, condition)
```
**Arguments**
value: numeric expression. condition: SQL truth expression. False and NULL conditions skip numeric accumulation; selected NULL values are ignored.
**Returned value**
The same numeric total and overflow behavior as sum; INTEGER 0 when no non-NULL selected value exists.
**Examples**
```sql
CREATE TABLE orders (amount INTEGER);
INSERT INTO orders VALUES (1),(NULL),(2);
```
```sql
SELECT sum_if(amount,amount > 1) FROM orders FORMAT csv;
```
```text
2
```
* [group_concat and string_agg](https://coordinatordb.com/docs/reference/functions/aggregate-functions/group-concat)
* [any_value](https://coordinatordb.com/docs/reference/functions/aggregate-functions/any-value)
* [avg](https://coordinatordb.com/docs/reference/functions/aggregate-functions/avg)
* [Aggregate combinators](https://coordinatordb.com/docs/reference/functions/aggregate-functions/combinators)
* [corr](https://coordinatordb.com/docs/reference/functions/aggregate-functions/corr)
* [count](https://coordinatordb.com/docs/reference/functions/aggregate-functions/count)
* [covar_pop](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-pop)
* [covar_samp](https://coordinatordb.com/docs/reference/functions/aggregate-functions/covar-samp)
* [array_agg](https://coordinatordb.com/docs/reference/functions/aggregate-functions/array-agg)
* [bit_and](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-and)
* [bit_or](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-or)
* [bit_xor](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-xor)
* [max](https://coordinatordb.com/docs/reference/functions/aggregate-functions/max)
* [min](https://coordinatordb.com/docs/reference/functions/aggregate-functions/min)
* [regr_avgx](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgx)
* [regr_avgy](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-avgy)
* [regr_count](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-count)
* [regr_intercept](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-intercept)
* [regr_r2](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-r2)
* [regr_slope](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-slope)
* [regr_sxx](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxx)
* [regr_sxy](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-sxy)
* [regr_syy](https://coordinatordb.com/docs/reference/functions/aggregate-functions/regr-syy)
* [stddev_pop](https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-pop)
* [stddev_samp](https://coordinatordb.com/docs/reference/functions/aggregate-functions/stddev-samp)
* [sum](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum)
* [var_pop](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-pop)
* [var_samp](https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-samp)
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/total
Language: en
# total
Calculates an approximate floating-point sum. Unlike `sum`, it returns `0.0` when no non-`NULL` value contributes.
```text
total(value)
```
The argument is a numeric expression. `NULL` values are skipped, and legacy text or blob inputs follow SQL numeric conversion. Native nonnumeric values require an explicit numeric cast.
The result is `REAL`, including when every input is an integer or decimal. Use [`sum`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/sum) when the total must remain exact. Nonfinite arithmetic can produce infinity; an indeterminate NaN result becomes SQL `NULL`.
**Empty input**
```sql
SELECT sum(generate_series), total(generate_series)
FROM generate_series(1, 3)
WHERE generate_series > 10
FORMAT csv;
```
```text
\N,0.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-pop
Language: en
# var_pop
Calculates the population variance.
Variance describes the spread of the observations around their arithmetic mean. Its units are the square of the input units.
**Syntax**
```text
var_pop(x)
```
**Arguments**
* `x` — A numeric column or expression. `NULL` values are skipped.
**Calculation**
```text
sum((x - mean) * (x - mean)) / (n)
```
`mean` is the arithmetic mean of the non-`NULL` values, and `n` is their count. The population calculation uses `n` because the observations describe the entire population.
**Returned value**
An approximate `REAL` value. Empty or all-`NULL` input returns `NULL`; one non-`NULL` input returns `0.0`. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measuring the spread of readings**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1), (3), (5), (7), (9), (NULL);
```
```sql
SELECT round(var_pop(value), 6) AS result
FROM readings
FORMAT csv;
```
```text
8.0
```
**A single observation**
```sql
CREATE TABLE single_reading (value INTEGER);
INSERT INTO single_reading VALUES (7), (NULL);
```
```sql
SELECT var_pop(value)
FROM single_reading
FORMAT csv;
```
```text
0.0
```
---
Source: https://coordinatordb.com/docs/reference/functions/aggregate-functions/var-samp
Language: en
# var_samp
Calculates the sample variance.
Variance describes the spread of the observations around their arithmetic mean. Its units are the square of the input units.
**Syntax**
```text
var_samp(x)
```
**Arguments**
* `x` — A numeric column or expression. `NULL` values are skipped.
**Calculation**
```text
sum((x - mean) * (x - mean)) / (n - 1)
```
`mean` is the arithmetic mean of the non-`NULL` values, and `n` is their count. The sample calculation uses `n - 1` because the observations estimate a larger population.
**Returned value**
An approximate `REAL` value. Fewer than two non-`NULL` inputs returns `NULL`. Nonfinite inputs return `NULL`; finite arithmetic overflow raises `NUMERIC_OVERFLOW`.
**Examples**
**Measuring the spread of readings**
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1), (3), (5), (7), (9), (NULL);
```
```sql
SELECT round(var_samp(value), 6) AS result
FROM readings
FORMAT csv;
```
```text
10.0
```
**A single observation**
```sql
CREATE TABLE single_reading (value INTEGER);
INSERT INTO single_reading VALUES (7), (NULL);
```
```sql
SELECT var_samp(value)
FROM single_reading
FORMAT csv;
```
```text
\N
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/arithmetic-functions
Language: en
# Arithmetic functions
Arithmetic operators calculate numeric values. Their result and overflow behavior depend on whether the operands are legacy SQL numbers or exact native integers and decimals.
## Operators
| Operator | Calculation |
| -------- | ----------------------------------------------------------------------------------- |
| `a + b` | Addition. |
| `a - b` | Subtraction. |
| `a * b` | Multiplication. |
| `a / b` | Division; ordinary integer operands give an integer quotient truncated toward zero. |
| `a % b` | Remainder. |
| `-a` | Negation. |
SQL NULL operands propagate. Ordinary numeric division or remainder by zero returns NULL. Decimal division and remainder by zero instead raise `INVALID_ARGUMENT`.
Exact native numeric overflow raises an error. Legacy INTEGER arithmetic can promote an overflowing result to REAL. Cast explicitly when the exact numeric family matters.
## abs
Returns a number's magnitude:
```text
abs(value)
```
```sql
SELECT abs(-5), abs(CAST('-1.20' AS Decimal(18, 2)))
FORMAT csv;
```
```text
5,1.20
```
## mod and div
```text
mod(value, divisor)
div(value, divisor)
```
`mod` returns a remainder; ordinary numeric inputs return REAL, while Decimal inputs use exact decimal remainder. `div` returns an exact decimal integral quotient and rejects a zero divisor.
```sql
SELECT 7 / 2, 7 % 2, mod(7, 3), div(7, 2)
FORMAT csv;
```
```text
3,1,1.0,3
```
## Decimal arithmetic
Decimal addition and subtraction use the larger operand scale, multiplication adds scales, and division retains the left scale. Excess division digits are discarded toward zero. Convert approximate operands before combining them with Decimal.
```sql
SELECT CAST('7.00' AS Decimal(18, 2)) / 2
FORMAT csv;
```
```text
3.50
```
See [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal) for ranges and conversions, and [mathematical functions](https://coordinatordb.com/docs/reference/functions/regular-functions/math-functions) for roots, powers and trigonometry.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions
Language: en
# Array functions
Array functions create and transform ordered collections. Use them to append or remove members, inspect dimensions, locate values, or turn a collection into rows or text.
Arrays retain their declared member type. Functions that add values validate the new members; nullable members and a NULL array follow the individual function contracts. Array positions are generally one-based, while negative positions are supported only where stated.
## Example: Removing an unwanted label
```sql
SELECT array_to_string(array_remove(array('new', 'paid', 'new'), 'new'), ',') AS remaining
FORMAT csv;
```
```text
"paid"
```
## array_append
Append one member while retaining the native array member type; adding NULL permits nullable members.
### Syntax
```text
array_append(array, value)
```
### Arguments
Native Array and one convertible member; NULL array becomes a one-element array; incompatible or out-of-range members error.
### Returned value
Native Array with the retained member type, including empty arrays and exact numeric widths.
### Example
```sql
SELECT array_to_string(array_append(array(1,2),3),',') FORMAT csv;
```
```text
"1,2,3"
```
## array_cat
Concatenate native arrays, preserving the first non-NULL array member contract.
### Syntax
```text
array_cat(left_array,right_array)
```
### Arguments
NULL array acts as empty; both NULL yields NULL; right members coerce to the left contract; nested arrays retain their shape.
### Returned value
Native Array with the retained definition.
### Example
```sql
SELECT array_to_string(array_cat(array(1,2),array(3)),',') FORMAT csv;
```
```text
"1,2,3"
```
## array_dims
Describe all native array dimension bounds as text.
### Syntax
```text
array_dims(array)
```
### Arguments
Validates rectangular shape up to 16 dimensions. Native lower bounds are one; nested empty dimensions retain their native shape.
### Returned value
Bounds TEXT, or SQL NULL for an empty top-level array/NULL input.
### Example
```sql
SELECT array_dims(array(array(1,2),array(3,4))) FORMAT csv;
```
```text
"[1:2][1:2]"
```
## array_fill
Construct a native array filled with copies of a value.
### Syntax
```text
array_fill(value,dimensions[,lower_bounds])
```
### Arguments
Nonnegative dimensions up to 16 levels and one million logical members including containers. Optional lower bounds must all be one. NULL element values are supported.
### Returned value
Native typed Array, retaining nested dimensions; NULL dimensions/bounds give SQL NULL.
### Example
```sql
SELECT to_json(array_fill(7,array(3))) FORMAT csv;
```
```text
"[7,7,7]"
```
## array_length
Read the top-level Array length, QBit dimension, or a rectangular native array dimension.
### Syntax
```text
array_length(value[,dimension])
```
### Arguments
Without dimension, value is an Array or QBit; empty Arrays return 0. With a one-based dimension, require an Array with rectangular nesting up to 16 levels; missing subarrays and inconsistent shapes error. Native lower bounds are one.
### Returned value
Int64; NULL for SQL NULL input, or for empty or absent/nonpositive dimensions in the two-argument form.
### Example
```sql
SELECT array_length(array()),array_length(array(1,2,3),1) FORMAT csv;
```
```text
0,3
```
## array_lower
Return the lower bound of one native array dimension.
### Syntax
```text
array_lower(array,dimension)
```
### Arguments
Positive one-based dimension; validates rectangular shape up to 16 dimensions. Native lower bounds are one. Empty, missing and zero-length dimensions return NULL.
### Returned value
INTEGER one, or SQL NULL.
### Example
```sql
SELECT array_lower(array(10,20),1) FORMAT csv;
```
```text
1
```
## array_ndims
Read the number of rectangular native array dimensions.
### Syntax
```text
array_ndims(array)
```
### Arguments
Same shape validation as array_length; native nested empty arrays retain their shape.
### Returned value
Int64; empty top-level arrays and SQL NULL give NULL.
### Example
```sql
SELECT array_ndims(array(array(1,2),array(3,4))) FORMAT csv;
```
```text
2
```
## array_position
Find the first matching native array member at or after a one-based start; NULL equals NULL.
### Syntax
```text
array_position(array, value[, start])
```
### Arguments
Native Array, comparison value, and optional signed start; starts below 1 begin at 1; NULL start errors.
### Returned value
INTEGER one-based position, or NULL for no match or NULL array.
### Example
```sql
SELECT array_position(array(1,NULL,3),NULL) FORMAT csv;
```
```text
2
```
## array_positions
Find all one-based positions of equal native array members.
### Syntax
```text
array_positions(array,needle)
```
### Arguments
NULL equals NULL; native comparison conversion and selected collation apply; only immediate members are searched.
### Returned value
Array(Int64); empty for no match; NULL for NULL array.
### Example
```sql
SELECT array_to_string(array_positions(array(1,2,1),1),',') FORMAT csv;
```
```text
"1,3"
```
## array_prepend
Prepend a member to a native array.
### Syntax
```text
array_prepend(value,array)
```
### Arguments
NULL array creates a singleton; NULL member widens member nullability; other members obey the retained native type.
### Returned value
Native Array.
### Example
```sql
SELECT array_to_string(array_prepend(1,array(2,3)),',') FORMAT csv;
```
```text
"1,2,3"
```
## array_remove
Remove every matching member using native comparison conversion and selected SQL collation; NULL equals NULL.
### Syntax
```text
array_remove(array, value)
```
### Arguments
Native Array and comparison value; members are compared without rounding numeric comparison boundaries.
### Returned value
Native Array with the original member type and retained input order; NULL array returns NULL.
### Example
```sql
SELECT array_to_string(array_remove(array(1,2,1),1),',') FORMAT csv;
```
```text
"2"
```
## array_replace
Replace every native array member equal to a searched value.
### Syntax
```text
array_replace(array,needle,replacement)
```
### Arguments
NULL equals NULL; selected collation applies; replacement coerces to member type; replacing with NULL widens nullability.
### Returned value
Native Array preserving order and nested shape; NULL input gives NULL.
### Example
```sql
SELECT array_to_string(array_replace(array(1,2,1),1,9),',') FORMAT csv;
```
```text
"9,2,9"
```
## array_reverse
Reverse immediate native array members.
### Syntax
```text
array_reverse(array)
```
### Arguments
Nested arrays move as whole members; their member order is unchanged; NULL propagates.
### Returned value
Native Array preserving its definition.
### Example
```sql
SELECT array_to_string(array_reverse(array(1,2,3)),',') FORMAT csv;
```
```text
"3,2,1"
```
## array_sample
Uniformly sample first-dimension items without replacement.
### Syntax
```text
array_sample(array,count)
```
### Arguments
Rectangular native Array; count must be an integer from zero through the first dimension length. Multidimensional items are complete subarrays. Random calls are nondeterministic.
### Returned value
Native Array preserving its element contract; SQL NULL propagates.
### Example
```sql
SELECT array_length(array_sample(array(1,2,3),2)) FORMAT csv;
```
```text
2
```
## array_shuffle
Uniformly shuffle the first dimension of a native array.
### Syntax
```text
array_shuffle(array)
```
### Arguments
Rectangular native Array; preserves every item, including NULL members and complete subarrays. Random calls are nondeterministic.
### Returned value
Native Array preserving its element contract; SQL NULL propagates.
### Example
```sql
SELECT array_length(array_shuffle(array(1,2,3))) FORMAT csv;
```
```text
3
```
## array_sort
Sort immediate array members using native comparisons and the selected collation.
### Syntax
```text
array_sort(array[,descending[,nulls_first]])
```
### Arguments
Default ascending with NULL last; descending defaults NULL first; explicit Bool options override; equivalent ties have no stable-order guarantee.
### Returned value
Native Array preserving its definition and nested shapes; NULL propagates.
### Example
```sql
SELECT array_to_string(array_sort(array(3,1,2)),',') FORMAT csv;
```
```text
"1,2,3"
```
## array_to_string
Join native array members in depth-first order, skipping NULL unless a replacement is supplied.
### Syntax
```text
array_to_string(array, delimiter[, null_string])
```
### Arguments
Native Array, delimiter text, optional NULL-member replacement; nested arrays are flattened.
### Returned value
TEXT; empty array gives empty text; NULL array or delimiter gives NULL.
### Example
```sql
SELECT array_to_string(array(1,NULL,2),',','?') FORMAT csv;
```
```text
"1,?,2"
```
## array_upper
Return the upper bound of one native array dimension.
### Syntax
```text
array_upper(array,dimension)
```
### Arguments
Positive one-based dimension and rectangular native arrays. Bounds start at one; the upper bound equals the dimension length. Empty/missing dimensions return NULL.
### Returned value
INTEGER upper bound, or SQL NULL.
### Example
```sql
SELECT array_upper(array(10,20),1) FORMAT csv;
```
```text
2
```
## cardinality
Count scalar members across nested native arrays.
### Syntax
```text
cardinality(array)
```
### Arguments
Depth-first traversal counts NULL scalar members; empty nested arrays add zero; NULL input gives NULL.
### Returned value
Nonnegative INTEGER.
### Example
```sql
SELECT cardinality(array(array(1,2),array(3,4))) FORMAT csv;
```
```text
4
```
## parse_ident
Parse a dotted SQL identifier into an array of components without truncation.
### Syntax
```text
parse_ident(text[,strict])
```
### Arguments
Strict defaults to true; false ignores trailing text after the final identifier. Quoted names retain spelling and doubled double quotes; unquoted names fold ASCII case. Empty/malformed components and NUL error.
### Returned value
Native Array(String), or NULL for a NULL argument.
### Example
```sql
SELECT array_to_string(parse_ident('"SomeSchema".SomeTable'),'/') FORMAT csv;
```
```text
"SomeSchema/sometable"
```
## string_to_array
Split text into a native Array(String), replacing exact null_string fields with NULL.
### Syntax
```text
string_to_array(text, delimiter[, null_string])
```
### Arguments
NULL delimiter splits Unicode characters; empty delimiter retains one field; empty input gives an empty array.
### Returned value
Native text array; nullable members when a non-NULL null_string is supplied; NULL for NULL input.
### Example
```sql
SELECT array_to_string(string_to_array('a,b,c',','),'|') FORMAT csv;
```
```text
"a|b|c"
```
## trim_array
Remove trailing members from the first array dimension.
### Syntax
```text
trim_array(array,count)
```
### Arguments
Nonnegative count no greater than the first dimension length.
### Returned value
Native Array preserving the original member contract; SQL NULL propagates.
### Example
```sql
SELECT to_json(trim_array(array(1,2,3),1)) FORMAT csv;
```
```text
"[1,2]"
```
## Constructors and element access
array(...) constructs a typed Array. array_element(array,index) uses one-based or negative positions, returning the element type default for an out-of-range nonzero position. Index zero raises INVALID_ARGUMENT. has(array,value) tests immediate members. array_length reads the top-level length; its two-argument form reads a rectangular dimension.
```sql
SELECT array_element(array(10,20),-1),array_element(array(10,20),9),has(array(10,20),20) FORMAT csv;
```
```text
20,0,true
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/bit-functions
Language: en
# Bit functions
Bit operations treat values as bit patterns. Integer operators act on numeric values; byte-string functions act on the bytes of text or BLOB input.
## Integer operators
```text
value & mask
value | mask
~value
value << positions
value >> positions
```
`&` is bitwise AND, `|` is bitwise OR and `~` inverts bits. Shifts move the pattern left or right. Native wide integer operations retain their full width rather than converting the value through floating point.
```sql
SELECT 6 & 3, 6 | 3, 1 << 4
FORMAT csv;
```
```text
2,7,16
```
## Binary-string functions
`get_bit(value, offset)` and `set_bit(value, offset, bit)` read or replace a bit. `get_byte` and `set_byte` address bytes. `bit_count` counts set bits, including bytes after an embedded zero.
```sql
SELECT bit_count(X'0F'), bit_count(X'00FF')
FORMAT csv;
```
```text
4,8
```
See the [encoding and binary reference](https://coordinatordb.com/docs/reference/functions/regular-functions/encoding-functions) for offsets, accepted values and out-of-range errors. To fold integer bit patterns across rows, use [bit_and](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-and), [bit_or](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-or) or [bit_xor](https://coordinatordb.com/docs/reference/functions/aggregate-functions/bit-xor).
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/comparison-functions
Language: en
# Comparison functions
Comparison functions select extrema from a list of expressions. They return one of the original values, preserving its type.
`greatest` and `least` skip NULL arguments. The scalar forms of `min` and `max` return NULL if any argument is NULL; their one-argument aggregate forms instead skip NULL rows. Choose the function according to the missing-value behavior you need.
## Example: Comparing optional values
```sql
SELECT greatest(10, NULL, 20), least(10, NULL, 20), max(10, NULL, 20)
FORMAT csv;
```
```text
20,10,\N
```
## greatest
Return the largest non-NULL argument using SQL value ordering and the selected collation.
### Syntax
```text
greatest(value1, ...)
```
### Arguments
One or more SQL values; NULL arguments are skipped. Comparisons follow local SQL value ordering rather than PostgreSQL implicit common-type coercion.
### Returned value
Selected argument with its type preserved; NULL if every argument is NULL.
### Example
```sql
SELECT greatest(1,NULL,3) FORMAT csv;
```
```text
3
```
## least
Return the smallest non-NULL argument using SQL value ordering and the selected collation.
### Syntax
```text
least(value1, ...)
```
### Arguments
One or more SQL values; NULL arguments are skipped. Comparisons follow local SQL value ordering rather than PostgreSQL implicit common-type coercion.
### Returned value
Selected argument with its type preserved; NULL if every argument is NULL.
### Example
```sql
SELECT least(1,NULL,-2) FORMAT csv;
```
```text
-2
```
## max
Return the largest of two or more values using SQL value ordering and collation.
### Syntax
```text
max(value1, value2, ...)
```
### Arguments
Two or more SQL values. Any NULL argument makes the result NULL; one argument selects the aggregate form.
### Returned value
The selected input value with its type preserved, or NULL when any argument is NULL.
### Example
```sql
SELECT max(3,1,2) FORMAT csv;
```
```text
3
```
## min
Return the smallest of two or more values using SQL value ordering and collation.
### Syntax
```text
min(value1, value2, ...)
```
### Arguments
Two or more SQL values. Any NULL argument makes the result NULL; one argument selects the aggregate form.
### Returned value
The selected input value with its type preserved, or NULL when any argument is NULL.
### Example
```sql
SELECT min(3,1,2) FORMAT csv;
```
```text
1
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/conditional-functions
Language: en
# Conditional functions and CASE
Conditional expressions select one result from several alternatives. CASE, `iif`/`if` and `coalesce` evaluate only the alternatives needed to choose their result.
## CASE
```text
CASE
WHEN condition THEN value
[WHEN condition THEN value ...]
[ELSE fallback]
END
CASE expression
WHEN candidate THEN value
[WHEN candidate THEN value ...]
[ELSE fallback]
END
```
The first form selects the first SQL-true condition. The second compares one base expression with candidate values. When no branch matches, ELSE is returned; omitting ELSE returns NULL.
### Classifying order amounts
```sql
CREATE TABLE orders (id INTEGER, amount INTEGER);
INSERT INTO orders VALUES (1, 20), (2, 150), (3, NULL);
```
```sql
SELECT id,
CASE
WHEN amount IS NULL THEN 'unknown'
WHEN amount >= 100 THEN 'large'
ELSE 'standard'
END AS category
FROM orders
ORDER BY id
FORMAT csv;
```
```text
1,"standard"
2,"large"
3,"unknown"
```
## iif and if
```text
iif(condition, value, ... [, fallback])
if(condition, value, ... [, fallback])
```
These aliases accept one or more condition/value pairs and an optional final fallback. The first true condition selects its value. If nothing matches and no fallback is present, the result is NULL.
### Skipping an unselected expression
The decimal division is not evaluated because the first condition is true:
```sql
SELECT iif(1, 'safe', CAST(1 AS Decimal(18, 2)) / 0),
if(0, 'unused')
FORMAT csv;
```
```text
"safe",\N
```
## Missing-value functions
| Function | Result |
| ------------------------------- | ------------------------------------------------------------------------------- |
| `coalesce(value1, value2, ...)` | The first non-NULL value; requires at least two arguments. |
| `ifnull(value, fallback)` | The fallback when value is NULL; exactly two arguments. |
| `nullif(value, other)` | NULL when the two values compare equal, otherwise value; exactly two arguments. |
```sql
SELECT coalesce(NULL, NULL, 'anonymous'),
ifnull(NULL, 'fallback'),
nullif(0, 0)
FORMAT csv;
```
```text
"anonymous","fallback",\N
```
See [functions for NULL values](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls) for detailed missing-value contracts.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/date-time-functions
Language: en
# Date and time functions
Date and time functions construct values, extract calendar fields, truncate or bin timestamps, convert timezones and format values as text.
Use Date/Date32 for calendar days, DateTime/DateTime64 for instants and Time/Time64 for date-independent seconds. Calendar arithmetic and elapsed-second arithmetic have different timezone behavior; each function below states its accepted inputs and result type.
## Example: Constructing a date and reading a field
```sql
SELECT make_date(2025, 3, 15), date_part('year', make_date(2025, 3, 15))
FORMAT csv;
```
```text
"2025-03-15",2025.0
```
## age
Subtract UTC calendar fields, retaining symbolic year/month/day and clock components in a named Tuple.
### Syntax
```text
age(later, earlier) or age(value)
```
### Arguments
Native dates/timestamps or ISO text; one argument subtracts from current UTC midnight; partial-month days use the earlier month.
### Returned value
Named Tuple(years,months,days,hours,minutes,seconds); seconds is exact Decimal(18,9); NULL propagates. This is not a PostgreSQL Interval.
### Example
```sql
SELECT tuple_element(age('2004-06-01','2004-04-30'),'months') FORMAT csv;
```
```text
1
```
## clock_timestamp
Read the changing wall clock at the instant of this call.
### Syntax
```text
clock_timestamp()
```
### Arguments
No arguments.
### Returned value
Native UTC DateTime64(6), read when the function is called. Calls within one statement can return different instants.
### Example
```sql
SELECT clock_timestamp() IS NOT NULL FORMAT csv;
```
```text
1
```
## date_add
Add calendar months/days and elapsed seconds to an instant.
### Syntax
```text
date_add(timestamp,interval[,timezone])
```
### Arguments
Native timestamp or ISO calendar text; single-unit native interval/text or make_interval tuple. Month ends clamp; DST folds use later instants and gaps use pre-transition offsets.
### Returned value
Native DateTime64 at least microsecond precision in the calculation zone; SQL NULL propagates.
### Example
```sql
SELECT to_char(date_add('2024-01-31 10:00:00','1 month'),'YYYY-MM-DD HH24:MI:SS') FORMAT csv;
```
```text
"2024-02-29 10:00:00"
```
## date_bin
Return the beginning of a positive elapsed-time bin aligned to an origin, flooring values before that origin.
### Syntax
```text
date_bin(stride, source, origin)
```
### Arguments
Positive native Interval or quantity-unit text without calendar months; source/origin native dates, timestamps, or ISO calendar text.
### Returned value
Native timestamp in the source zone, retaining source/origin/stride precision within native ranges; NULL propagates.
### Example
```sql
SELECT to_char(date_bin('15 minutes','2020-02-11 15:44:17','2001-01-01'),'HH24:MI:SS') FORMAT csv;
```
```text
"15:30:00"
```
## date_part
Extract a numeric field from a date, timestamp, time, or interval.
### Syntax
```text
date_part(field, value)
```
### Arguments
Fields include year, month, day, hour, minute, second, epoch, quarter, ISO week/day/year, and native timezone fields.
### Returned value
REAL field value, or NULL for NULL input.
### Example
```sql
SELECT date_part('year','2026-10-12') FORMAT csv;
```
```text
2026.0
```
## date_subtract
Subtract a calendar span from an instant.
### Syntax
```text
date_subtract(timestamp,interval[,timezone])
```
### Arguments
Same calendar/elapsed and zone rules as date_add; component negation is checked.
### Returned value
Native DateTime64 in the calculation zone; SQL NULL propagates.
### Example
```sql
SELECT to_char(date_subtract('2024-03-31 10:00:00','1 month'),'YYYY-MM-DD') FORMAT csv;
```
```text
"2024-02-29"
```
## date_trunc
Truncate a date or timestamp to a calendar unit, or truncate a native interval.
### Syntax
```text
date_trunc(unit, value[, timezone])
```
### Arguments
Calendar text uses UTC; native timestamps retain their zone unless overridden. Supported units range from microseconds through millennium.
### Returned value
Native timestamp retaining fractional precision and the selected zone; native interval for interval input; NULL propagates.
### Example
```sql
SELECT to_char(date_trunc('month','2026-10-12'),'YYYY-MM-DD') FORMAT csv;
```
```text
"2026-10-01"
```
## jsonb_path_exists_tz
Test timezone-aware JSONPath selection.
### Syntax
```text
jsonb_path_exists_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL propagates.
### Returned value
Bool or NULL
### Example
```sql
SELECT jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
true
```
## jsonb_path_query_first_tz
Retain the first timezone-aware JSONPath item.
### Syntax
```text
jsonb_path_query_first_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL propagates.
### Returned value
JSON or NULL
### Example
```sql
SELECT jsonb_path_query_first_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
"""2015-08-01 12:00:00-05"""
```
## jsonb_path_query_tz
Expand timezone-aware JSONPath selections in FROM.
### Syntax
```text
jsonb_path_query_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL input yields no rows.
### Returned value
JSON rows
### Example
```sql
SELECT * FROM jsonb_path_query_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
"""2015-08-01 12:00:00-05"""
```
## justify_days
Normalize fixed thirty-day portions into months.
### Syntax
```text
justify_days(interval)
```
### Arguments
Accepts a native/text single-unit interval or make_interval mixed span. Thirty days make one month; month/day signs normalize. This conversion does not imply calendar-duration equivalence.
### Returned value
Named native months/days/seconds Tuple, retaining microsecond or nanosecond precision; NULL propagates.
### Example
```sql
SELECT tuple_element(justify_days('65 days'),'months') FORMAT csv;
```
```text
2
```
## justify_hours
Normalize fixed twenty-four-hour portions into days.
### Syntax
```text
justify_hours(interval)
```
### Arguments
Same native interval/span inputs as justify_days. Twenty-four elapsed hours make one day; day/second signs normalize.
### Returned value
Named native months/days/seconds Tuple or SQL NULL.
### Example
```sql
SELECT tuple_element(justify_hours('50 hours'),'days') FORMAT csv;
```
```text
2
```
## justify_interval
Normalize hours, days and mixed signs across a span.
### Syntax
```text
justify_interval(interval)
```
### Arguments
Combines fixed twenty-four-hour day and thirty-day month normalization, making component signs agree. Widened checked arithmetic protects native range boundaries.
### Returned value
Named native months/days/seconds Tuple or SQL NULL.
### Example
```sql
SELECT tuple_element(justify_interval(make_interval(0,1,0,0,-1)),'days') FORMAT csv;
```
```text
29
```
## make_date
Construct a native Date32 from validated year/month/day fields.
### Syntax
```text
make_date(year, month, day)
```
### Arguments
Signed integer fields; invalid dates error; native Date32 range applies.
### Returned value
Native Date32, or NULL for a NULL field.
### Example
```sql
SELECT to_char(make_date(2024,2,29),'YYYY-MM-DD') FORMAT csv;
```
```text
"2024-02-29"
```
## make_interval
Construct a mixed calendar span without approximating months or days as seconds.
### Syntax
```text
make_interval([years[,months[,weeks[,days[,hours[,minutes[,seconds]]]]]]])
```
### Arguments
Positional arguments default zero. Integer components are checked; finite seconds round to microseconds with ties to even. Native mixed-span representation is a named Tuple.
### Returned value
Tuple(months Int64,days Int64,seconds Decimal(38,6)); any explicit SQL NULL gives NULL.
### Example
```sql
SELECT to_json(make_interval(1,2,0,3,4,5,6.25)) FORMAT csv;
```
```text
"{""months"":14,""days"":3,""seconds"":14706.250000}"
```
## make_time
Construct a native clock from hour/minute/second fields.
### Syntax
```text
make_time(hour,minute,seconds)
```
### Arguments
Hour 0..24, minute 0..59, seconds 0..60; hour 24 requires zero minute/seconds. Fractional seconds round independently to microseconds.
### Returned value
Native Time64(6); SQL NULL propagates.
### Example
```sql
SELECT CAST(make_time(8,15,23.5) AS TEXT) FORMAT csv;
```
```text
"08:15:23.500000"
```
## make_timestamp
Construct a UTC native DateTime64(6), rounding seconds independently of clock offsets with ties to even and calendar carry.
### Syntax
```text
make_timestamp(year, month, day, hour, minute, seconds)
```
### Arguments
Integer date/hour/minute fields and numeric seconds 0 through 60; hour 24 requires minute/seconds zero; native range applies.
### Returned value
Native UTC timestamp with microsecond precision, or NULL for any NULL field.
### Example
```sql
SELECT to_char(make_timestamp(2024,2,29,12,30,0.5),'HH24:MI:SS.US') FORMAT csv;
```
```text
"12:30:00.500000"
```
## make_timestamptz
Construct a native timestamp in an explicit display zone.
### Syntax
```text
make_timestamptz(year,month,day,hour,minute,seconds[,timezone])
```
### Arguments
Default zone is UTC; explicit zones use IANA names. Same clock/date validation and ties-to-even microsecond rounding as make_timestamp. Gaps use the preceding offset and folds choose the later instant. Native ranges apply.
### Returned value
Native DateTime64(6,zone) or SQL NULL.
### Example
```sql
SELECT to_char(make_timestamptz(2024,1,1,12,0,0,'Europe/Moscow'),'HH24:MI:SS OF') FORMAT csv;
```
```text
"12:00:00 +03:00"
```
## now
Read the explicit transaction start or autocommit statement start.
### Syntax
```text
now()
```
### Arguments
No arguments. Equivalent to transaction_timestamp using native UTC clock scopes.
### Returned value
Native UTC DateTime64(6).
### Example
```sql
SELECT now() IS NOT NULL FORMAT csv;
```
```text
1
```
## statement_timestamp
Read the fixed start of the enclosing SQL statement.
### Syntax
```text
statement_timestamp()
```
### Arguments
No arguments.
### Returned value
Native UTC DateTime64(6), fixed for the enclosing SQL statement.
### Example
```sql
SELECT statement_timestamp() IS NOT NULL FORMAT csv;
```
```text
1
```
## timezone
Convert a native instant to an IANA display zone, or interpret zone-free ISO local text/date in that zone and return UTC.
### Syntax
```text
timezone(zone, value)
```
### Arguments
IANA zone and native timestamp/date or ISO text; offset-bearing text identifies an instant; ambiguous/nonexistent local times error.
### Returned value
Native timestamp retaining an instant and explicit display zone; NULL propagates. Native timestamps have no zone-free runtime class.
### Example
```sql
SELECT to_char(timezone('Europe/Moscow',to_timestamp(0)),'HH24:MI:SS') FORMAT csv;
```
```text
"03:00:00"
```
## to_char
Format a calendar value or an exact numeric value using supported PostgreSQL template fields.
### Syntax
```text
to_char(value, template)
```
### Arguments
Calendar fields include YYYY, MM, DD, MON, MONTH, HH24, MI, SS, MS, US, and timezone fields; numeric fields include 9, 0, D, G, S, MI and FM. Unsupported fields raise INVALID_ARGUMENT.
### Returned value
Formatted TEXT with English calendar names and locale-independent punctuation; NULL propagates.
### Example
```sql
SELECT to_char(12.345,'FM9990.00') FORMAT csv;
```
```text
"12.35"
```
## to_date
Parse calendar text with a supported PostgreSQL date template.
### Syntax
```text
to_date(value, template)
```
### Arguments
Supported input fields include YYYY, YY, MM, DD, DDD, MON, MONTH, DY and DAY. Separators match the supplied template.
### Returned value
Native date, or NULL for NULL input. Invalid dates and unsupported template fields raise INVALID_ARGUMENT.
### Example
```sql
SELECT to_char(to_date('05 Dec 2000','DD Mon YYYY'),'YYYY-MM-DD') FORMAT csv;
```
```text
"2000-12-05"
```
## to_timestamp
Convert Unix epoch seconds or parse calendar text into a UTC timestamp.
### Syntax
```text
to_timestamp(epoch), to_timestamp(value, template)
```
### Arguments
One numeric argument uses epoch seconds. Two arguments parse supported calendar fields including HH24, MI, SS, MS and US.
### Returned value
Native UTC timestamp with microsecond precision; NULL propagates. Invalid templates or dates raise INVALID_ARGUMENT.
### Example
```sql
SELECT to_char(to_timestamp(0),'YYYY-MM-DD HH24:MI:SS') FORMAT csv;
```
```text
"1970-01-01 00:00:00"
```
## transaction_timestamp
Read the fixed explicit BEGIN/outer SAVEPOINT start, or the statement start in autocommit.
### Syntax
```text
transaction_timestamp()
```
### Arguments
No arguments.
### Returned value
Native UTC DateTime64(6), fixed for the explicit transaction. In autocommit, it uses the current statement start.
### Example
```sql
SELECT transaction_timestamp() IS NOT NULL FORMAT csv;
```
```text
1
```
## uuid_extract_timestamp
Extract the UTC timestamp carried by an RFC 9562 UUID version 1 or 7.
### Syntax
```text
uuid_extract_timestamp(uuid)
```
### Arguments
Native UUID or accepted UUID text. Version 1 drops submicrosecond digits; version 7 exposes its millisecond timestamp. Other versions/variants and SQL NULL return NULL.
### Returned value
Native UTC DateTime64(6), or NULL when no supported timestamp is present.
### Example
```sql
SELECT date_part('year',uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e')) FORMAT csv;
```
```text
2025.0
```
## Legacy calendar functions
CURRENT_DATE, CURRENT_TIME and CURRENT_TIMESTAMP are SQL keywords without
parentheses. They return UTC TEXT in `YYYY-MM-DD`, `HH:MM:SS` and
`YYYY-MM-DD HH:MM:SS` form. Native timestamp functions have their own typed results
and clock scopes.
```sql
SELECT typeof(CURRENT_DATE),length(CURRENT_TIME),length(CURRENT_TIMESTAMP) FORMAT csv;
```
```text
"text",8,19
```
`date`, `time`, `datetime`, `julianday` and `unixepoch` accept an optional time value and modifiers. strftime(format,time_value,...) formats a date; timediff(later,earlier) returns a calendar span. ISO date/time text is supported, and the unixepoch modifier interprets numeric Unix seconds. These functions follow their SQLite-style contracts, separate from native DateTime declarations; invalid or out-of-range calendar results return NULL.
```sql
SELECT date('2024-03-05','+1 day'),datetime(0,'unixepoch'),strftime('%Y-%m','2024-03-05') FORMAT csv;
```
```text
"2024-03-06","1970-01-01 00:00:00","2024-03"
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/distance-functions
Language: en
# Vector distances
Vector distance functions compare a fixed-dimensional QBit value with a reference Array. The precision argument lets the query use all or part of the vector element precision.
## Syntax
```text
l2_distance_transposed(vector, reference, precision [, used_dims])
cosine_distance_transposed(vector, reference, precision [, used_dims])
dot_product_transposed(vector, reference, precision [, used_dims])
```
`distance_l2_transposed` is an alias for `l2_distance_transposed`. `scalar_product_transposed` is an alias for `dot_product_transposed`.
## Arguments
* `vector` — A native QBit value.
* `reference` — An Array containing the reference coordinates.
* `precision` — A number from 1 through the QBit element bit width. Full precision reconstructs the stored coordinates exactly.
* `used_dims` — An optional positive number of coordinates, no greater than the dimension and divisible by the QBit stride. Without it, the reference must cover the full vector dimension.
Nonfinite coordinates raise an error. SQL NULL propagates.
## Returned value
A Float64 distance or product. L2 is Euclidean distance. Cosine distance compares directions; it returns NULL when either vector has zero norm. Dot product is the sum of coordinate products.
## Examples
### A one-unit Euclidean distance
```sql
SELECT l2_distance_transposed(
CAST('[1,2,3]' AS QBit(Float32, 3)),
array(1, 2, 4),
32
)
FORMAT csv;
```
```text
1.0
```
### Dot product
```sql
SELECT dot_product_transposed(
CAST('[1,2,3]' AS QBit(Float32, 3)),
array(4, 5, 6),
32
)
FORMAT csv;
```
```text
32.0
```
See [QBit](https://coordinatordb.com/docs/reference/data-types/qbit) for element types, dimensions and stride rules.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/encoding-functions
Language: en
# Encoding and binary functions
Encoding functions convert between text, binary data and textual encodings such as hexadecimal or Base64. They also inspect or change individual bits and bytes.
A character encoding interprets bytes as characters; a representation encoding such as hex renders bytes for display. Use `convert_to`/`convert_from` for the former and `encode`/`decode` for the latter.
## Example: Converting text to bytes and back
```sql
SELECT encode(convert_to('café', 'UTF8'), 'hex'),
convert_from(decode('636166c3a9', 'hex'), 'UTF8')
FORMAT csv;
```
```text
"636166c3a9","café"
```
## bit_count
Count set bits in binary input.
### Syntax
```text
bit_count(bytes)
```
### Arguments
Native BLOB or UTF-8 text; embedded zero bytes are retained. SQL NULL propagates.
### Returned value
Nonnegative INTEGER count; empty input yields zero.
### Example
```sql
SELECT bit_count(x'0fff') FORMAT csv;
```
```text
12
```
## bit_length
Return UTF-8 text or exact BLOB length in bits.
### Syntax
```text
bit_length(value)
```
### Arguments
Text conversions use native scalar rules; BLOB counts raw bytes without decoding. Embedded NUL bytes are included.
### Returned value
INTEGER bit count or SQL NULL.
### Example
```sql
SELECT bit_length('é') FORMAT csv;
```
```text
16
```
## convert
Convert bytes from one supported character encoding to another.
### Syntax
```text
convert(bytes,source_encoding,destination_encoding)
```
### Arguments
BLOB or UTF-8 text. Reuses UTF8/SQL_ASCII, LATIN1, WIN1250..1258, KOI8R/U mappings. Native SQL_ASCII follows strict UTF8. Undefined bytes, NUL, unsupported encodings and unrepresentable characters error. SQL NULL propagates.
### Returned value
BLOB destination bytes.
### Example
```sql
SELECT encode(convert(decode('e9','hex'),'LATIN1','UTF8'),'hex') FORMAT csv;
```
```text
"c3a9"
```
## convert_from
Decode bytes into native UTF-8 text without replacements.
### Syntax
```text
convert_from(bytes,encoding)
```
### Arguments
Same encoding set as convert_to. Text arguments provide UTF-8 input bytes; BLOB retains exact bytes. Undefined bytes, invalid UTF8 and NUL error. SQL_ASCII still requires valid native UTF8 output.
### Returned value
TEXT or SQL NULL.
### Example
```sql
SELECT convert_from(x'48656c6c6f','WIN1251') FORMAT csv;
```
```text
"Hello"
```
## convert_to
Encode text into bytes without replacement characters.
### Syntax
```text
convert_to(text,encoding)
```
### Arguments
Supported: UTF8, SQL_ASCII, LATIN1, WIN1250 through WIN1258, KOI8R and KOI8U. Names ignore case, hyphens and underscores; WINDOWS aliases are accepted. Native text is UTF-8. NUL and unrepresentable characters error.
### Returned value
BLOB or SQL NULL.
### Example
```sql
SELECT encode(convert_to('Hello','WIN1251'),'hex') FORMAT csv;
```
```text
"48656c6c6f"
```
## decode
Decode text representations into bytes.
### Syntax
```text
decode(text,format)
```
### Arguments
Formats: base64, hex, escape. Invalid encodings error; permitted Base64/hex whitespace follows PostgreSQL forms.
### Returned value
BLOB; SQL NULL propagates.
### Example
```sql
SELECT encode(decode('YWJj','base64'),'hex') FORMAT csv;
```
```text
"616263"
```
## encode
Represent exact input bytes as text.
### Syntax
```text
encode(bytes,format)
```
### Arguments
Text supplies UTF-8 bytes; BLOB retains bytes. Formats: base64, hex, escape. Base64 wraps at 76 columns.
### Returned value
TEXT; SQL NULL propagates.
### Example
```sql
SELECT encode(x'616263','base64') FORMAT csv;
```
```text
"YWJj"
```
## get_bit
Read one bit using zero-based positions and low-bit-first order inside each byte.
### Syntax
```text
get_bit(bytes,index)
```
### Arguments
Native BLOB or UTF-8 text. Signed integer index must identify an existing bit. SQL NULL propagates.
### Returned value
INTEGER zero or one; invalid positions raise INVALID_ARGUMENT.
### Example
```sql
SELECT get_bit(x'01',0) FORMAT csv;
```
```text
1
```
## get_byte
Read a byte at a zero-based position.
### Syntax
```text
get_byte(bytes,index)
```
### Arguments
Text supplies UTF-8 bytes; BLOB supplies exact bytes. Index is a signed integer and must identify an existing byte; NULL propagates.
### Returned value
INTEGER from zero through 255.
### Example
```sql
SELECT get_byte(x'00ff',1) FORMAT csv;
```
```text
255
```
## set_bit
Return a copied binary value with one existing bit replaced.
### Syntax
```text
set_bit(bytes,index,value)
```
### Arguments
Native BLOB or UTF-8 text; zero-based bit index and replacement zero/one. Low-bit-first order within bytes. SQL NULL propagates.
### Returned value
BLOB preserving all other bytes/bits; invalid position/value raises INVALID_ARGUMENT.
### Example
```sql
SELECT encode(set_bit(x'00',7,1),'hex') FORMAT csv;
```
```text
"80"
```
## set_byte
Copy bytes and replace one zero-based byte.
### Syntax
```text
set_byte(bytes,index,new_value)
```
### Arguments
Same byte/index contract as get_byte. New value is an Int32 whose low eight bits are used; source remains unchanged. Output is subject to request limits.
### Returned value
BLOB or SQL NULL.
### Example
```sql
SELECT encode(set_byte(x'00ff',1,65),'hex') FORMAT csv;
```
```text
"0041"
```
## to_bin
Format an integer in binary.
### Syntax
```text
to_bin(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement binary representation.
### Example
```sql
SELECT to_bin(10) FORMAT csv;
```
```text
"1010"
```
## to_hex
Render an exact signed Int64 or unsigned UInt64 in hexadecimal.
### Syntax
```text
to_hex(integer)
```
### Arguments
Negative signed arguments use 64-bit two's complement; oversized signed fields error; NULL propagates.
### Returned value
Lowercase hexadecimal TEXT without a prefix.
### Example
```sql
SELECT to_hex(2147483647) FORMAT csv;
```
```text
"7fffffff"
```
## to_oct
Format an integer in octal.
### Syntax
```text
to_oct(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement octal representation.
### Example
```sql
SELECT to_oct(10) FORMAT csv;
```
```text
"12"
```
## Hexadecimal and Unicode conversion
hex(value) returns uppercase hexadecimal bytes; unhex(text\[,ignored_characters]) decodes hexadecimal text and returns NULL for malformed input. char(codepoint,...) constructs text; unicode(text) reads its first Unicode code point. zeroblob(length) constructs zero bytes.
```sql
SELECT hex('AB'),hex(unhex('4142')),unicode('A'),char(65,66),length(zeroblob(3)) FORMAT csv;
```
```text
"4142","4142",65,"AB",3
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls
Language: en
# Functions for NULL values
These functions replace missing values or count which arguments are present. SQL NULL is distinct from empty text, numeric zero and a JSON null document.
Use `coalesce` for a fallback value and `num_nulls`/`num_nonnulls` to inspect a row. Use `IS NULL` when the result should be a missing-value predicate.
## Example: Supplying a display fallback
```sql
SELECT coalesce(NULL, 'anonymous') AS display_name,
num_nulls(NULL, '', 0) AS missing_fields
FORMAT csv;
```
```text
"anonymous",1
```
## coalesce
Return the first non-NULL argument and stop evaluating later arguments.
### Syntax
```text
coalesce(value1, value2, ...)
```
### Arguments
Two or more SQL expressions evaluated from left to right until a non-NULL result is found.
### Returned value
The first non-NULL value with its type preserved; NULL when every argument is NULL.
### Example
```sql
SELECT coalesce(NULL,'fallback') FORMAT csv;
```
```text
"fallback"
```
## num_nonnulls
Count non-NULL arguments.
### Syntax
```text
num_nonnulls(value,...)
```
### Arguments
One or more arguments. Only the outer SQL NULL value is counted as missing.
### Returned value
INTEGER number of non-NULL arguments.
### Example
```sql
SELECT num_nonnulls(1,NULL,2) FORMAT csv;
```
```text
2
```
## num_nulls
Count SQL NULL arguments.
### Syntax
```text
num_nulls(value,...)
```
### Arguments
One or more arguments. Native JSON null and collection members are ordinary non-NULL argument values.
### Returned value
INTEGER number of NULL arguments.
### Example
```sql
SELECT num_nulls(1,NULL,2) FORMAT csv;
```
```text
1
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/geo
Language: en
# Geographic functions
Geographic functions work with coordinate pairs and typed coordinate collections. Use a consistent coordinate system for each calculation.
## Function families
* [Geographic distances](https://coordinatordb.com/docs/reference/functions/regular-functions/geo/coordinates) measures a spherical arc from longitude/latitude coordinates and returns metres.
* [Geometry construction](https://coordinatordb.com/docs/reference/functions/regular-functions/geo/geometry) creates Point, Ring, Polygon and related aliases with validated nesting.
* [Point in polygon](https://coordinatordb.com/docs/reference/functions/regular-functions/geo/polygon) tests containment with defined outer-boundary and hole rules.
The geometry aliases do not assign a coordinate reference system or validate polygon topology. See [geometry types](https://coordinatordb.com/docs/reference/data-types/geometry-types) for shapes and [GeoJSON](https://coordinatordb.com/docs/reference/formats/geo-json) for importing and exporting features.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/geo/coordinates
Language: en
# Geographic distances
`great_circle_distance` calculates the shortest spherical surface distance between two longitude/latitude positions. It returns metres using a sphere with radius 6,371,000 metres.
The result describes a geographic arc, rather than a road route or an ellipsoidal distance.
## Syntax
```text
great_circle_distance(longitude1, latitude1, longitude2, latitude2)
```
## Arguments
Longitudes are in degrees from -180 through 180. Latitudes are in degrees from -90 through 90. Coordinates must satisfy those ranges; SQL NULL propagates.
## Returned value
An approximate floating-point distance in metres. Identical positions return zero.
## Examples
### One degree north along a meridian
```sql
SELECT round(great_circle_distance(0, 0, 0, 1)) AS metres
FORMAT csv;
```
```text
111195.0
```
### Identical positions
```sql
SELECT great_circle_distance(10, 20, 10, 20)
FORMAT csv;
```
```text
0.0
```
See [geometry construction](https://coordinatordb.com/docs/reference/functions/regular-functions/geo/geometry) for typed coordinate collections.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/geo/geometry
Language: en
# Geometry construction
Construct geometry values with CAST or write JSON coordinate arrays to a geometry column. The aliases define how coordinates nest and validate the resulting shape.
## Shapes
A Point is a pair of Float64 coordinates. MultiPoint, Ring and LineString are arrays of Points. A Polygon is an array of Rings, a MultiLineString is an array of LineStrings, and a MultiPolygon is an array of Polygons.
The declarations validate field types and nesting, not topological correctness. They do not detect self-intersections or assign a coordinate reference system.
## Examples
### A point and independent points
```sql
SELECT CAST('[1,2]' AS Point),
CAST('[[1,2],[3,4]]' AS MultiPoint)
FORMAT csv;
```
```text
"[1,2]","[[1,2],[3,4]]"
```
### A polygon boundary
```sql
SELECT CAST('[[[0,0],[2,0],[2,2],[0,2]]]' AS Polygon)
FORMAT csv;
```
```text
"[[[0,0],[2,0],[2,2],[0,2]]]"
```
Use [point_in_polygon](https://coordinatordb.com/docs/reference/functions/regular-functions/geo/polygon) to test containment. See [geometry types](https://coordinatordb.com/docs/reference/data-types/geometry-types) for the alias table and [GeoJSON](https://coordinatordb.com/docs/reference/formats/geo-json) for interchange.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/geo/polygon
Language: en
# point_in_polygon
Tests whether a point lies in a polygon. The outer boundary is included; a hole and its boundary are excluded.
## Syntax
```text
point_in_polygon(point, outer_ring [, hole, ...])
point_in_polygon(point, polygon)
```
## Arguments
* `point` — A two-coordinate Float64 pair.
* `outer_ring` — An outer Ring containing at least three finite points.
* `hole` — An optional hole Ring, with the same shape requirements.
* `polygon` — A Polygon whose first Ring is the outer boundary and whose later Rings are holes.
All coordinates must use one consistent space, such as longitude/latitude or projected coordinates. Geometry declarations validate shapes without validating topology.
## Returned value
A Bool indicating whether the point is inside under these boundary rules. SQL NULL propagates.
## Examples
### Inside an outer ring
```sql
SELECT point_in_polygon(
tuple(1, 1),
CAST('[[0,0],[2,0],[2,2],[0,2]]' AS Ring)
)
FORMAT csv;
```
```text
true
```
### A hole and an outer boundary
```sql
CREATE TABLE regions (area Polygon);
INSERT INTO regions VALUES (CAST(
'[[[0,0],[4,0],[4,4],[0,4]],[[1,1],[3,1],[3,3],[1,3]]]'
AS Polygon
));
```
```sql
SELECT point_in_polygon(tuple(2, 2), area) AS in_hole,
point_in_polygon(tuple(0, 2), area) AS on_outer_boundary
FROM regions
FORMAT csv;
```
```text
false,true
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/hash-functions
Language: en
# Hash and digest functions
Checksum and digest functions summarize text or binary input. CRC functions return integer checksums, named SHA/MD5 functions return hexadecimal text, and `digest`/`hmac` expose binary results for a chosen algorithm.
SQL NULL and binary zero bytes follow the individual contracts below. Use `encode` to display a binary digest in hex.
## Example: Comparing checksums and digests
```sql
SELECT crc32('123456789'), md5('hello') = md5('hello')
FORMAT csv;
```
```text
3421780262,1
```
## crc32
Compute the IEEE CRC-32 checksum.
### Syntax
```text
crc32(bytes)
```
### Arguments
Native BLOB or UTF-8 text; includes embedded zero bytes. SQL NULL propagates.
### Returned value
Nonnegative INTEGER unsigned 32-bit checksum; empty input gives zero.
### Example
```sql
SELECT crc32('123456789') FORMAT csv;
```
```text
3421780262
```
## crc32c
Compute the Castagnoli CRC-32C checksum.
### Syntax
```text
crc32c(bytes)
```
### Arguments
Native BLOB or UTF-8 text; includes embedded zero bytes. SQL NULL propagates.
### Returned value
Nonnegative INTEGER unsigned 32-bit checksum; empty input gives zero.
### Example
```sql
SELECT crc32c('123456789') FORMAT csv;
```
```text
3808858755
```
## digest
Compute an algorithm-selected binary hash.
### Syntax
```text
digest(data,algorithm)
```
### Arguments
BLOB or UTF-8 text; md5/sha1/sha224/sha256/sha384/sha512, case-insensitive algorithm names. SQL NULL propagates.
### Returned value
BLOB digest.
### Example
```sql
SELECT encode(digest('abc','sha256'),'hex') FORMAT csv;
```
```text
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
```
## hmac
Compute an RFC 2104 keyed message authentication code.
### Syntax
```text
hmac(data,key,algorithm)
```
### Arguments
Same byte/algorithm rules as digest. SQL NULL propagates.
### Returned value
BLOB authentication code.
### Example
```sql
SELECT encode(hmac('data','key','sha256'),'hex') FORMAT csv;
```
```text
"5031fe3d989c6d1537a013fa6e739da23463fdaec3b70137d828e36ace221bd0"
```
## md5
Compute the lowercase hexadecimal MD5 digest of text bytes.
### Syntax
```text
md5(text)
```
### Arguments
Text conversion uses UTF-8 bytes; NULL propagates.
### Returned value
32-character lowercase hexadecimal TEXT.
### Example
```sql
SELECT md5('abc') FORMAT csv;
```
```text
"900150983cd24fb0d6963f7d28e17f72"
```
## sha224
Compute the SHA-224 digest of exact input bytes.
### Syntax
```text
sha224(bytes)
```
### Arguments
Text supplies UTF-8 bytes; BLOB supplies exact bytes. NULL propagates.
### Returned value
BLOB of 28 digest bytes.
### Example
```sql
SELECT length(sha224('abc')) FORMAT csv;
```
```text
28
```
## sha256
Compute SHA-256 over exact input bytes.
### Syntax
```text
sha256(bytes)
```
### Arguments
Text supplies UTF-8 bytes; BLOB retains every byte.
### Returned value
32-byte BLOB; use encode(...,hex) for hexadecimal text; SQL NULL propagates.
### Example
```sql
SELECT encode(sha256('abc'),'hex') FORMAT csv;
```
```text
"ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
```
## sha384
Compute the SHA-384 digest of exact input bytes.
### Syntax
```text
sha384(bytes)
```
### Arguments
Text supplies UTF-8 bytes; BLOB supplies exact bytes. NULL propagates.
### Returned value
BLOB of 48 digest bytes.
### Example
```sql
SELECT length(sha384('abc')) FORMAT csv;
```
```text
48
```
## sha512
Compute SHA-512 over exact input bytes.
### Syntax
```text
sha512(bytes)
```
### Arguments
Text supplies UTF-8 bytes; BLOB retains every byte.
### Returned value
64-byte BLOB; SQL NULL propagates.
### Example
```sql
SELECT length(sha512('abc')) FORMAT csv;
```
```text
64
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions
Language: en
# IP address and network functions
Network functions inspect addresses and subnet prefixes. `inet` can retain host bits with a prefix; `cidr` represents a network and validates its host bits. IPv4 and IPv6 native values can be used where the function admits an address.
Functions parse numeric addresses, not hostnames, and do not perform DNS lookups. Prefix lengths range from 0 through 32 for IPv4 and 0 through 128 for IPv6.
## Example: Separating a host from its network
```sql
SELECT CAST(network('192.0.2.17/24') AS TEXT),
host('192.0.2.17/24'), masklen('192.0.2.17/24')
FORMAT csv;
```
```text
"192.0.2.0/24","192.0.2.17",24
```
## broadcast
Set every host bit in an address.
### Syntax
```text
broadcast(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
inet
### Example
```sql
SELECT CAST(broadcast('192.168.1.5/24') AS TEXT) FORMAT csv;
```
```text
"192.168.1.255/24"
```
## family
Return 4 for IPv4 or 6 for IPv6.
### Syntax
```text
family(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
INTEGER
### Example
```sql
SELECT family('::1') FORMAT csv;
```
```text
6
```
## host
Return address text without its prefix.
### Syntax
```text
host(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
String
### Example
```sql
SELECT host('192.168.1.5/24') FORMAT csv;
```
```text
"192.168.1.5"
```
## hostmask
Return the inverse network mask as an address.
### Syntax
```text
hostmask(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
inet
### Example
```sql
SELECT CAST(hostmask('192.168.1.5/24') AS TEXT) FORMAT csv;
```
```text
"0.0.0.255"
```
## inet_merge
Find the smallest subnet covering both inputs.
### Syntax
```text
inet_merge(address,other)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
cidr
### Example
```sql
SELECT CAST(inet_merge('192.168.1.5/24','192.168.2.5/24') AS TEXT) FORMAT csv;
```
```text
"192.168.0.0/22"
```
## inet_same_family
Test whether both addresses have the same family.
### Syntax
```text
inet_same_family(address,other)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
Bool
### Example
```sql
SELECT inet_same_family('192.168.1.5','::1') FORMAT csv;
```
```text
false
```
## masklen
Return the prefix length in bits.
### Syntax
```text
masklen(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
INTEGER
### Example
```sql
SELECT masklen('192.168.1.5/24') FORMAT csv;
```
```text
24
```
## netmask
Return the network mask as an address.
### Syntax
```text
netmask(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
inet
### Example
```sql
SELECT CAST(netmask('192.168.1.5/24') AS TEXT) FORMAT csv;
```
```text
"255.255.255.0"
```
## network
Return the subnet with cleared host bits.
### Syntax
```text
network(address)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
cidr
### Example
```sql
SELECT CAST(network('192.168.1.5/24') AS TEXT) FORMAT csv;
```
```text
"192.168.1.0/24"
```
## set_masklen
Change a prefix, clearing host bits for cidr.
### Syntax
```text
set_masklen(address,prefix)
```
### Arguments
Native IPv4/IPv6/inet/cidr or bounded full IPv4/IPv6 text with optional /prefix. Preserve inet host bits, validate cidr host bits. Prefixes 0..32 or 0..128. No DNS. NULL propagates.
### Returned value
inet or cidr
### Example
```sql
SELECT CAST(set_masklen('192.168.1.5/24',16) AS TEXT) FORMAT csv;
```
```text
"192.168.1.5/16"
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions
Language: en
# JSON functions
JSON functions construct documents, extract paths, transform objects and arrays, and expand documents into table rows. Aggregate variants build one document from several input rows.
SQL NULL and JSON null are different values. The `_text` extraction forms return decoded text and can turn JSON null into SQL NULL; structured forms retain JSON values. JSONB functions normalize objects according to their documented contracts. Path syntax and zero-based JSON array indexes are separate from native Array indexing.
## Example: Extracting a nested document field
```sql
SELECT json_extract_path_text('{"user":{"name":"Ada"}}', 'user', 'name'),
json_typeof(CAST('[1,2,3]' AS JSON))
FORMAT csv;
```
```text
"Ada","array"
```
## array_to_json
Convert a native array into structural JSON.
### Syntax
```text
array_to_json(array[,pretty])
```
### Arguments
Recursively converts native members and retains exact numbers. Pretty defaults to false; true adds line breaks between top-level members. Native nested empty array shapes are retained.
### Returned value
Native JSON array, or SQL NULL.
### Example
```sql
SELECT array_to_json(array(1,NULL,2)) FORMAT csv;
```
```text
"[1,null,2]"
```
## json_array_elements
Expand top-level JSON array elements into native JSON FROM rows.
### Syntax
```text
FROM json_array_elements(json)
```
### Arguments
Requires an array; nested values and JSON null retain structural identity; SQL NULL gives no rows.
### Returned value
One value column containing native JSON.
### Example
```sql
SELECT json_typeof(value) FROM json_array_elements('[1,true]') FORMAT csv;
```
```text
"number"
"boolean"
```
## json_array_elements_text
Expand a JSON array into decoded text rows.
### Syntax
```text
FROM json_array_elements_text(json)
```
### Arguments
Requires an array; strings decode, other values render compactly, JSON null becomes SQL NULL. Plain nested object order/duplicates remain. SQL NULL produces no rows.
### Returned value
One nullable TEXT value column.
### Example
```sql
SELECT value FROM json_array_elements_text('["x",null]') FORMAT csv;
```
```text
"x"
\N
```
## json_build_array
Construct a native JSON array from SQL values.
### Syntax
```text
json_build_array([value,...])
```
### Arguments
Numbers/booleans retain their JSON types; SQL NULL becomes JSON null. Native collections recurse; BLOB becomes a hex byte string.
### Returned value
Native JSON; zero arguments return an empty array.
### Example
```sql
SELECT json_build_array(1,'two',CAST(1 AS Bool),NULL) FORMAT csv;
```
```text
"[1,""two"",true,null]"
```
## json_build_object
Build native JSON from scalar keys and SQL values, retaining duplicate keys and nested JSON structures.
### Syntax
```text
json_build_object([key, value, ...])
```
### Arguments
An even number of alternating scalar keys and values; NULL or composite keys error; value conversion follows native JSON rules.
### Returned value
Native JSON object; no arguments returns `{}`; NULL values become JSON null.
### Example
```sql
SELECT json_build_object('name','Ada','active',CAST(true AS Bool)) FORMAT csv;
```
```text
"{""name"":""Ada"",""active"":true}"
```
## json_each_text
Expand a JSON object into separate key and text value columns.
### Syntax
```text
FROM json_each_text(json)
```
### Arguments
Requires an object; decoded strings stay text, containers render compactly, JSON null becomes SQL NULL; duplicates and order remain.
### Returned value
TEXT key and nullable TEXT value columns.
### Example
```sql
SELECT key,value FROM json_each_text('{"a":"foo","b":null}') FORMAT csv;
```
```text
"a","foo"
"b",\N
```
## json_extract_path
Extract a native JSON value through literal path components.
### Syntax
```text
json_extract_path(json[,component,...])
```
### Arguments
Literal object keys or signed zero-based indexes; final duplicate key wins. Zero path components select the root.
### Returned value
Native JSON, including JSON null; missing/NULL path components and SQL NULL source give SQL NULL.
### Example
```sql
SELECT json_extract_path('{"a":{"b":1}}','a','b') FORMAT csv;
```
```text
"1"
```
## json_extract_path_text
Extract a JSON value using literal keys and signed array indexes.
### Syntax
```text
json_extract_path_text(json[,path_element,...])
```
### Arguments
Indexes are zero-based; negatives count from the end; duplicate keys select the last; NULL/missing paths give SQL NULL.
### Returned value
Decoded string or rendered value as TEXT; JSON null gives SQL NULL.
### Example
```sql
SELECT json_extract_path_text('{"a":{"b":"x"}}','a','b') FORMAT csv;
```
```text
"x"
```
## json_object_keys
Expand top-level JSON object keys into FROM rows.
### Syntax
```text
FROM json_object_keys(json)
```
### Arguments
Requires an object; input order and duplicate keys are retained; SQL NULL gives no rows.
### Returned value
One json_object_keys TEXT column.
### Example
```sql
SELECT * FROM json_object_keys('{"a":1,"b":2}') FORMAT csv;
```
```text
"a"
"b"
```
## json_populate_record
Fill a record from plain JSON using a native base.
### Syntax
```text
json_populate_record(base,json_object), FROM json_populate_record(base,json_object)
```
### Arguments
Base is a named native Tuple, including a typed NULL. FROM infers fields from a CAST or preceding typed column; an untyped NULL requires AS alias(column native_type,...). Missing fields retain base defaults recursively; JSON null replaces them with SQL NULL. Native field coercion applies. Plain nested JSON fields retain object order/duplicates. Scalar output enforces native Tuple NULL constraints; use Nullable members for missing/null fields.
### Returned value
Named native Tuple as a scalar, or typed FROM columns; SQL NULL JSON retains the base.
### Example
```sql
SELECT * FROM json_populate_record(CAST(tuple(7,'x') AS Tuple(a Int64,b String)),'{"a":1}') AS r FORMAT csv;
```
```text
1,"x"
```
## json_populate_recordset
Fill record rows from plain JSON using a native base.
### Syntax
```text
FROM json_populate_recordset(base,json_array)
```
### Arguments
Base is a named native Tuple, including a typed NULL. FROM infers fields from a CAST or preceding typed column; an untyped NULL requires AS alias(column native_type,...). Missing fields retain base defaults recursively; JSON null replaces them with SQL NULL. Native field coercion applies. Plain nested JSON fields retain object order/duplicates. Recordsets convert only the current row; LIMIT can stop before later-row conversion errors.
### Returned value
Typed FROM rows; SQL NULL JSON produces no rows.
### Example
```sql
SELECT * FROM json_populate_recordset(NULL,'[{"a":1},{"a":2}]') AS r(a INTEGER) FORMAT csv;
```
```text
1
2
```
## json_strip_nulls
Recursively remove null-valued object fields, optionally null array members.
### Syntax
```text
json_strip_nulls(json[,strip_in_arrays])
```
### Arguments
Bool option defaults false; root JSON null remains; existing JSON input contract; SQL NULL propagates.
### Returned value
Native JSON with remaining input member order.
### Example
```sql
SELECT json_strip_nulls('{"a":1,"b":null}') FORMAT csv;
```
```text
"{""a"":1}"
```
## json_to_record
Expand JSON objects into one typed row.
### Syntax
```text
json_to_record(document) AS alias(column native_type[, ...])
```
### Arguments
FROM only; one to 2000 explicitly typed columns. Field keys are case-sensitive; final duplicate keys win. Missing and JSON null fields give SQL NULL. Types follow native declarations, with strict INTEGER/REAL/TEXT conversions. JSON declarations retain strings; other types decode string contents before native coercion. Variant/Dynamic receive decoded scalars before native coercion.
### Returned value
Typed rows. SQL NULL produces one all-NULL row.
### Example
```sql
SELECT * FROM json_to_record('{"a":1,"b":"x"}') AS r(a INTEGER,b TEXT) FORMAT csv;
```
```text
1,"x"
```
## json_to_recordset
Expand JSON object arrays into typed rows.
### Syntax
```text
json_to_recordset(document) AS alias(column native_type[, ...])
```
### Arguments
FROM only; one to 2000 explicitly typed columns. Field keys are case-sensitive; final duplicate keys win. Missing and JSON null fields give SQL NULL. Types follow native declarations, with strict INTEGER/REAL/TEXT conversions. JSON declarations retain strings; other types decode string contents before native coercion. Variant/Dynamic receive decoded scalars before native coercion.
### Returned value
Typed rows. SQL NULL produces zero rows.
### Example
```sql
SELECT * FROM json_to_recordset('[{"a":1},{"a":2}]') AS r(a INTEGER) FORMAT csv;
```
```text
1
2
```
## json_to_tsvector
Build a search vector from selected JSON components.
### Syntax
```text
json_to_tsvector([configuration,]document,filter)
```
### Arguments
Same filters/configurations as jsonb_to_tsvector; original object order and duplicate keys are retained. NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(json_to_tsvector('simple','{"title":"fat cats"}','"string"') AS TEXT) FORMAT csv;
```
```text
"'cats':2 'fat':1"
```
## json_typeof
Report the PostgreSQL JSON type label of the top-level value.
### Syntax
```text
json_typeof(json)
```
### Arguments
Accepts the existing JSON input contract; JSON null is the text label null, distinct from SQL NULL.
### Returned value
TEXT: object, array, string, number, boolean, or null; SQL NULL propagates.
### Example
```sql
SELECT json_typeof('true') FORMAT csv;
```
```text
"boolean"
```
## jsonb_array_elements
Expand a JSONB array into native JSON rows.
### Syntax
```text
FROM jsonb_array_elements(json)
```
### Arguments
Requires an array; nested object keys canonicalize; JSON null remains structural. SQL NULL produces no rows.
### Returned value
One value native JSON column.
### Example
```sql
SELECT jsonb_typeof(value) FROM jsonb_array_elements('[1,null]') FORMAT csv;
```
```text
"number"
"null"
```
## jsonb_array_elements_text
Expand a JSONB array into decoded text rows.
### Syntax
```text
FROM jsonb_array_elements_text(json)
```
### Arguments
Requires an array; nested object keys canonicalize; strings decode, containers render compactly, JSON null becomes SQL NULL. SQL NULL produces no rows.
### Returned value
One nullable TEXT value column.
### Example
```sql
SELECT value FROM jsonb_array_elements_text('["x",null]') FORMAT csv;
```
```text
"x"
\N
```
## jsonb_array_length
Count top-level JSONB array elements.
### Syntax
```text
jsonb_array_length(json)
```
### Arguments
Requires an array; nested containers each count as one element.
### Returned value
INTEGER length; empty array gives zero; SQL NULL propagates.
### Example
```sql
SELECT jsonb_array_length('[1,[2,3],null]') FORMAT csv;
```
```text
3
```
## jsonb_build_array
Build a canonical native JSON array.
### Syntax
```text
jsonb_build_array([value[, ...]])
```
### Arguments
SQL NULL becomes JSON null. Recursive objects use canonical JSONB-style keys; native JSON and immediate legacy JSON subtypes remain structural.
### Returned value
Native JSON array; empty input returns an empty array.
### Example
```sql
SELECT jsonb_build_array(1,NULL,'x') FORMAT csv;
```
```text
"[1,null,""x""]"
```
## jsonb_build_object
Build a canonical native JSON object.
### Syntax
```text
jsonb_build_object(key,value[, ...])
```
### Arguments
Even key/value pairs; keys are non-NULL scalars. Values support recursive native values and directly consumed legacy JSON subtypes. Duplicate keys retain the final value.
### Returned value
Native JSON object; empty input returns an empty object.
### Example
```sql
SELECT jsonb_build_object('a',1,'a',2) FORMAT csv;
```
```text
"{""a"":2}"
```
## jsonb_each
Expand a JSONB object into key and native JSON value columns.
### Syntax
```text
FROM jsonb_each(json)
```
### Arguments
Requires an object; nested duplicate keys normalize; JSON null stays structural. SQL NULL produces no rows.
### Returned value
TEXT key and native JSON value columns.
### Example
```sql
SELECT key,jsonb_typeof(value) FROM jsonb_each('{"a":1}') FORMAT csv;
```
```text
"a","number"
```
## jsonb_each_text
Expand a JSONB object into key and text value columns.
### Syntax
```text
FROM jsonb_each_text(json)
```
### Arguments
Requires an object; final duplicates win. Strings decode; containers render compactly; JSON null becomes SQL NULL. SQL NULL produces no rows.
### Returned value
TEXT key and nullable TEXT value columns.
### Example
```sql
SELECT key,value FROM jsonb_each_text('{"a":"x","b":null}') FORMAT csv;
```
```text
"a","x"
"b",\N
```
## jsonb_extract_path
Extract canonical native JSON at a literal path.
### Syntax
```text
jsonb_extract_path(json[,path_element,...])
```
### Arguments
Literal object keys and signed zero-based Int32 indexes; leading ASCII whitespace is accepted and trailing/invalid indexes yield SQL NULL; negatives count from the end; final duplicate keys win. NULL/missing paths return SQL NULL.
### Returned value
Native JSON, including structural JSON null; objects canonicalize.
### Example
```sql
SELECT jsonb_extract_path('{"a":[1,2]}','a','-1') FORMAT csv;
```
```text
"2"
```
## jsonb_extract_path_text
Extract a canonical JSONB path value as text.
### Syntax
```text
jsonb_extract_path_text(json[,path_element,...])
```
### Arguments
Same literal path contract as jsonb_extract_path; strings decode and containers render compactly.
### Returned value
TEXT, or SQL NULL for missing paths, NULL path elements, or JSON null.
### Example
```sql
SELECT jsonb_extract_path_text('{"a":{"b":"x"}}','a','b') FORMAT csv;
```
```text
"x"
```
## jsonb_insert
Insert JSON at an existing parent without replacing an object field.
### Syntax
```text
jsonb_insert(json,path,replacement[,after])
```
### Arguments
Native Array path with literal keys/Int32 indexes; negative indexes supported. after defaults false. Missing parents unchanged; NULL path members and existing object keys error.
### Returned value
Native JSON with JSONB-style last-key-wins canonicalization; SQL NULL propagates.
### Example
```sql
SELECT jsonb_insert('{"a":[0,1,2]}',array('a','1'),'"new"') FORMAT csv;
```
```text
"{""a"":[0,""new"",1,2]}"
```
## jsonb_object
Construct a canonical JSONB-style object from native arrays.
### Syntax
```text
jsonb_object(pairs) or jsonb_object(keys,values)
```
### Arguments
Accepts an even alternating scalar array, an array of two-member arrays, or equal-length separate key/value arrays. Scalar members convert to text; keys cannot be NULL, NULL values become JSON null; duplicate keys keep the final value.
### Returned value
Canonical native JSON object; SQL NULL array argument propagates.
### Example
```sql
SELECT jsonb_object(array('a','1','b','2')) FORMAT csv;
```
```text
"{""a"":""1"",""b"":""2""}"
```
## jsonb_object_keys
Expand canonical JSONB object keys.
### Syntax
```text
FROM jsonb_object_keys(json)
```
### Arguments
Requires an object; duplicate keys keep the final value and keys sort by byte length/bytes. SQL NULL produces no rows.
### Returned value
One jsonb_object_keys TEXT column.
### Example
```sql
SELECT * FROM jsonb_object_keys('{"b":1,"a":2}') FORMAT csv;
```
```text
"a"
"b"
```
## jsonb_path_exists
Check whether a SQL/JSON Path expression selects any item.
### Syntax
```text
jsonb_path_exists(json,path[,vars[,silent]])
```
### Arguments
Lax/strict paths, filters, variables, exact numeric comparisons/arithmetic and supported methods; vars must be an object; silent suppresses structural/numeric/datetime errors; missing variables and resource limits remain errors. Paths are bounded to 16 KiB/128 punctuation tokens; numeric coefficients/exponents to 1024.
### Returned value
Native Bool; NULL on a suppressed error or SQL NULL argument.
### Example
```sql
SELECT jsonb_path_exists('{"a":[1,2,3]}','$.a[*] ? (@ > 2)') FORMAT csv;
```
```text
true
```
## jsonb_path_exists_tz
Test timezone-aware JSONPath selection.
### Syntax
```text
jsonb_path_exists_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL propagates.
### Returned value
Bool or NULL
### Example
```sql
SELECT jsonb_path_exists_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
true
```
## jsonb_path_match
Return the SQL truth of one JSONPath predicate result.
### Syntax
```text
jsonb_path_match(target,path[,vars[,silent]])
```
### Arguments
Uses the SQL/JSON Path, variable and request-limit rules of jsonb_path_exists. JSON null results return SQL NULL; empty, multiple and nonboolean results require silent mode or error. Silent errors retain completed prefixes before cardinality validation; missing variables and resource failures remain errors.
### Returned value
Bool or SQL NULL; empty/nonboolean/multiple results error unless silent.
### Example
```sql
SELECT jsonb_path_match('{"a":3}','$.a > 2') FORMAT csv;
```
```text
true
```
## jsonb_path_query
Return selected SQL/JSON Path items as native JSON FROM rows.
### Syntax
```text
FROM jsonb_path_query(json,path[,vars[,silent]])
```
### Arguments
Same path/vars/silent contract as jsonb_path_exists; silent retains fully selected rows before the first suppressed error; SQL NULL gives no rows.
### Returned value
One jsonb_path_query native JSON column; duplicate object keys normalize as JSONB.
### Example
```sql
SELECT * FROM jsonb_path_query('{"a":[1,2,3]}','$.a[*] ? (@ > 1)') FORMAT csv;
```
```text
"2"
"3"
```
## jsonb_path_query_array
Collect selected JSONPath items into one native JSON array.
### Syntax
```text
jsonb_path_query_array(json,path[,vars[,silent]])
```
### Arguments
Same bounded path/vars/silent contract as jsonb_path_query; silent retains completed items before the first suppressible error.
### Returned value
Native JSON array; empty selection gives \[]; SQL NULL propagates.
### Example
```sql
SELECT jsonb_path_query_array('{"a":[1,2,3]}','$.a[*] ? (@ > 1)') FORMAT csv;
```
```text
"[2,3]"
```
## jsonb_path_query_first
Return the first fully selected JSONPath item.
### Syntax
```text
jsonb_path_query_first(json,path[,vars[,silent]])
```
### Arguments
Same bounded path/vars/silent contract as jsonb_path_query. Validate later candidates but retain only the first completed item; silent preserves it before a suppressible error.
### Returned value
Native JSON; empty selection and SQL NULL arguments give SQL NULL.
### Example
```sql
SELECT jsonb_path_query_first('{"a":[1,2,3]}','$.a[*] ? (@ > 1)') FORMAT csv;
```
```text
"2"
```
## jsonb_path_query_first_tz
Retain the first timezone-aware JSONPath item.
### Syntax
```text
jsonb_path_query_first_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL propagates.
### Returned value
JSON or NULL
### Example
```sql
SELECT jsonb_path_query_first_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
"""2015-08-01 12:00:00-05"""
```
## jsonb_path_query_tz
Expand timezone-aware JSONPath selections in FROM.
### Syntax
```text
jsonb_path_query_tz(target,path[,vars[,silent]])
```
### Arguments
Same bounded paths, object vars, error suppression and completed-prefix handling as ordinary JSONPath functions. Honor explicit offsets; implicit timezone conversions use native UTC. Query is FROM-only; first validates subsequent candidates. NULL input yields no rows.
### Returned value
JSON rows
### Example
```sql
SELECT * FROM jsonb_path_query_tz('["2015-08-01 12:00:00-05"]','$[*] ? (@.datetime() < "2015-08-02".datetime())') FORMAT csv;
```
```text
"""2015-08-01 12:00:00-05"""
```
## jsonb_populate_record
Fill a record from canonical JSONB-style using a native base.
### Syntax
```text
jsonb_populate_record(base,json_object), FROM jsonb_populate_record(base,json_object)
```
### Arguments
Base is a named native Tuple, including a typed NULL. FROM infers fields from a CAST or preceding typed column; an untyped NULL requires AS alias(column native_type,...). Missing fields retain base defaults recursively; JSON null replaces them with SQL NULL. Native field coercion applies. Objects normalize final duplicate keys. Scalar output enforces native Tuple NULL constraints; use Nullable members for missing/null fields.
### Returned value
Named native Tuple as a scalar, or typed FROM columns; SQL NULL JSON retains the base.
### Example
```sql
SELECT * FROM jsonb_populate_record(CAST(tuple(7,'x') AS Tuple(a Int64,b String)),'{"a":1}') AS r FORMAT csv;
```
```text
1,"x"
```
## jsonb_populate_record_valid
Test JSONB record field conversion without throwing conversion errors.
### Syntax
```text
jsonb_populate_record_valid(base,json)
```
### Arguments
Named native Tuple base or typed NULL supplies the schema. Checks native Tuple NULL constraints. Wrong containers and field conversion errors return false; malformed JSON/base schemas and resource errors remain errors.
### Returned value
Native Bool; SQL NULL JSON is valid and gives true.
### Example
```sql
SELECT jsonb_populate_record_valid(CAST(tuple(0) AS Tuple(a UInt8)),'{"a":256}') FORMAT csv;
```
```text
false
```
## jsonb_populate_recordset
Fill record rows from canonical JSONB-style using a native base.
### Syntax
```text
FROM jsonb_populate_recordset(base,json_array)
```
### Arguments
Base is a named native Tuple, including a typed NULL. FROM infers fields from a CAST or preceding typed column; an untyped NULL requires AS alias(column native_type,...). Missing fields retain base defaults recursively; JSON null replaces them with SQL NULL. Native field coercion applies. Objects normalize final duplicate keys. Recordsets convert only the current row; LIMIT can stop before later-row conversion errors.
### Returned value
Typed FROM rows; SQL NULL JSON produces no rows.
### Example
```sql
SELECT * FROM jsonb_populate_recordset(NULL,'[{"a":1},{"a":2}]') AS r(a INTEGER) FORMAT csv;
```
```text
1
2
```
## jsonb_pretty
Render canonical native JSON with four-space indentation.
### Syntax
```text
jsonb_pretty(value)
```
### Arguments
Parses native JSON input and canonicalizes duplicate/order rules before rendering. Numeric token spelling follows native JSON.
### Returned value
Indented TEXT, or SQL NULL.
### Example
```sql
SELECT jsonb_pretty('1') FORMAT csv;
```
```text
"1"
```
## jsonb_set
Return native JSON with a path target replaced or added using JSONB-style object normalization.
### Syntax
```text
jsonb_set(json,path_array,new_json[,create_if_missing])
```
### Arguments
Native Array path uses literal keys and signed zero-based Int32 indexes; missing parents remain unchanged; create defaults true; NULL path members error.
### Returned value
Native JSON; duplicate keys keep the last and object keys sort by byte length/bytes; no separate PostgreSQL binary JSONB format.
### Example
```sql
SELECT jsonb_set('{"a":1}',array('a'),'2') FORMAT csv;
```
```text
"{""a"":2}"
```
## jsonb_set_lax
Update native JSON with explicit SQL NULL treatment.
### Syntax
```text
jsonb_set_lax(target,path,new_value[,create_if_missing[,null_value_treatment]])
```
### Arguments
Native Array path with signed zero-based Int32 indexes; leading ASCII whitespace is accepted. Deletion checks NULL components only when reached. Default create_if_missing is true. SQL NULL new values support use_json_null (default), delete_key, return_target or raise_exception. Non-NULL new values ignore the treatment argument.
### Returned value
Canonical native JSON, or SQL NULL for NULL target/path/create flag.
### Example
```sql
SELECT jsonb_set_lax('{"a":1}',array('a'),NULL,true,'delete_key') FORMAT csv;
```
```text
"{}"
```
## jsonb_strip_nulls
Remove JSON null object fields recursively.
### Syntax
```text
jsonb_strip_nulls(value[,strip_in_arrays])
```
### Arguments
The optional flag defaults to false. True also removes null array members. Root JSON null is retained; object keys follow native JSONB-style canonicalization.
### Returned value
Native JSON, or SQL NULL for NULL input/flag.
### Example
```sql
SELECT jsonb_strip_nulls('{"a":null,"b":1}') FORMAT csv;
```
```text
"{""b"":1}"
```
## jsonb_to_record
Expand JSON objects into one typed row.
### Syntax
```text
jsonb_to_record(document) AS alias(column native_type[, ...])
```
### Arguments
FROM only; one to 2000 explicitly typed columns. Field keys are case-sensitive; final duplicate keys win. Missing and JSON null fields give SQL NULL. Types follow native declarations, with strict INTEGER/REAL/TEXT conversions. JSONB-style keys normalize recursively. JSON declarations retain strings; other types decode string contents before native coercion. Variant/Dynamic receive decoded scalars before native coercion.
### Returned value
Typed rows. SQL NULL produces one all-NULL row.
### Example
```sql
SELECT * FROM jsonb_to_record('{"a":1,"b":"x"}') AS r(a INTEGER,b TEXT) FORMAT csv;
```
```text
1,"x"
```
## jsonb_to_recordset
Expand JSON object arrays into typed rows.
### Syntax
```text
jsonb_to_recordset(document) AS alias(column native_type[, ...])
```
### Arguments
FROM only; one to 2000 explicitly typed columns. Field keys are case-sensitive; final duplicate keys win. Missing and JSON null fields give SQL NULL. Types follow native declarations, with strict INTEGER/REAL/TEXT conversions. JSONB-style keys normalize recursively. JSON declarations retain strings; other types decode string contents before native coercion. Variant/Dynamic receive decoded scalars before native coercion.
### Returned value
Typed rows. SQL NULL produces zero rows.
### Example
```sql
SELECT * FROM jsonb_to_recordset('[{"a":1},{"a":2}]') AS r(a INTEGER) FORMAT csv;
```
```text
1
2
```
## jsonb_to_tsvector
Build a search vector from selected JSONB components.
### Syntax
```text
jsonb_to_tsvector([configuration,]document,filter)
```
### Arguments
Configurations simple/english/russian, default english. Filter is a JSON string or string array: string,numeric,boolean,key,all. Canonical JSONB key order and one gap between selected components. Native search limits apply; NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(jsonb_to_tsvector('simple','{"title":"fat cats"}','"string"') AS TEXT) FORMAT csv;
```
```text
"'cats':2 'fat':1"
```
## jsonb_typeof
Return the top-level JSONB type label.
### Syntax
```text
jsonb_typeof(json)
```
### Arguments
Existing JSON input contract; JSON null is the text label null, distinct from SQL NULL.
### Returned value
TEXT: object, array, string, number, boolean, or null; SQL NULL propagates.
### Example
```sql
SELECT jsonb_typeof('null') FORMAT csv;
```
```text
"null"
```
## row_to_json
Convert a native Tuple to a JSON object.
### Syntax
```text
row_to_json(tuple[,pretty])
```
### Arguments
Requires a native Tuple; named fields keep names, positional fields use f1/f2. Nested Tuples become objects; infinities become strings, while native SQL NaN becomes NULL before calls. Pretty Bool defaults false and inserts top-level line breaks.
### Returned value
Native JSON; plain object member order remains; SQL NULL propagates.
### Example
```sql
SELECT row_to_json(tuple(1,'x')) FORMAT csv;
```
```text
"{""f1"":1,""f2"":""x""}"
```
## to_json
Convert a SQL value into native JSON.
### Syntax
```text
to_json(value)
```
### Arguments
Text becomes a JSON string; exact numbers retain digits. Arrays/unnamed tuples become arrays; named tuples/maps become objects. BLOB becomes a hex byte string.
### Returned value
Native JSON; SQL NULL remains SQL NULL.
### Example
```sql
SELECT to_json(array(1,2)) FORMAT csv;
```
```text
"[1,2]"
```
## to_jsonb
Convert native values recursively to canonical JSONB-style native JSON.
### Syntax
```text
to_jsonb(value)
```
### Arguments
Tuples become objects with named or fN fields, including nested Tuples. Arrays and Maps retain structure; BLOB becomes a hex byte string; infinities become Infinity/-Infinity strings; native SQL NaN becomes NULL before calls; directly consumed legacy JSON subtypes stay structural.
### Returned value
Native JSON with final-key-wins canonical objects; SQL NULL propagates.
### Example
```sql
SELECT to_jsonb(tuple(1,'x')) FORMAT csv;
```
```text
"{""f1"":1,""f2"":""x""}"
```
## Core JSON functions and operators
json validates and normalizes a document. json_valid tests validity; json_extract reads a path; json_type reports its kind; json_array and json_object construct documents. json_set, json_insert, json_replace and json_remove edit paths; json_patch applies a merge patch. json_array_length counts array elements. json_quote encodes an SQL value. json_group_array and json_group_object aggregate values. json_each expands immediate children; json_tree also visits descendants and exposes key, value, type, atom, id, parent, fullkey and path columns. The -> operator returns JSON text; ->> returns an SQL scalar. Paths and documents retain a 1,000-container nesting limit.
```sql
SELECT json_extract('{"a":[10,20]}','$.a[1]'),json_set('{"a":1}','$.a',2) FORMAT csv;
```
```text
20,"{""a"":2}"
```
## json_pretty and json_error_position
json_pretty(document\[,indent]) returns indented JSON text. Indentation defaults to four spaces when omitted or NULL. A NULL document returns NULL; invalid JSON raises an error. The optional indent is converted to text.
json_error_position(document) returns zero for accepted standard JSON or supported JSON5 text, numbers and SQL NULL. Invalid text returns a one-based character position, rather than raising its syntax error.
```sql
SELECT json_pretty('{"a":1}',' ') AS document FORMAT json_each_row;
```
```text
{"document":"{\n \"a\": 1\n}"}
```
```sql
SELECT json_error_position('{"a":1}'),json_error_position('{'),json_error_position(NULL) FORMAT csv;
```
```text
0,2,0
```
## JSON aggregates
See the [aggregate function reference](https://coordinatordb.com/docs/reference/functions/aggregate-functions/reference-index#json-aggregates) for JSON array and object aggregates, including NULL handling and empty-input behavior.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/logical-functions
Language: en
# Logical expressions
Logical expressions combine conditions. SQL uses three truth values: true, false and unknown, represented by NULL.
## Syntax
```text
condition AND condition
condition OR condition
NOT condition
```
Operands are converted using SQL truth rules. A false operand makes AND false even when the other operand is NULL. A true operand makes OR true even when the other operand is NULL. NOT NULL remains NULL.
## Truth table
| A | B | A AND B | A OR B |
| ----- | ----- | ------- | ------ |
| true | true | true | true |
| true | false | false | true |
| true | NULL | NULL | true |
| false | false | false | false |
| false | NULL | false | NULL |
| NULL | NULL | NULL | NULL |
## Examples
### Combining missing and known conditions
```sql
SELECT 1 AND NULL, 0 AND NULL, 1 OR NULL, NOT 0
FORMAT csv;
```
```text
\N,0,1,1
```
### Selecting matching rows
```sql
CREATE TABLE orders (id INTEGER, paid Bool, amount INTEGER);
INSERT INTO orders VALUES (1, true, 100), (2, false, 200), (3, true, 40);
```
```sql
SELECT id
FROM orders
WHERE paid AND amount >= 50
ORDER BY id
FORMAT csv;
```
```text
1
```
A WHERE condition admits only true, so both false and NULL remove a row. Use `IS NULL` to test for a missing value, and [conditional functions](https://coordinatordb.com/docs/reference/functions/regular-functions/conditional-functions) or [coalesce](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls#coalesce) to choose a fallback.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/math-functions
Language: en
# Mathematical functions
Mathematical functions cover roots, trigonometry, exact integer operations, numeric scales and bucket assignment. Exact Decimal results and approximate REAL results are stated per function.
Check a function's domain before using it with negative, zero or nonfinite values. A mathematical domain error is distinct from SQL NULL input and numeric overflow.
## Example: Exact integer calculations
```sql
SELECT gcd(24, 36), lcm(4, 6), factorial(5)
FORMAT csv;
```
```text
12,12,120
```
## cbrt
Compute a real cube root, including negative operands.
### Syntax
```text
cbrt(value)
```
### Arguments
Numeric input; native REAL result; NaN maps to SQL NULL.
### Returned value
REAL; SQL NULL propagates.
### Example
```sql
SELECT cbrt(-64) FORMAT csv;
```
```text
-4.0
```
## cot
Compute cotangent for a finite angle in radians.
### Syntax
```text
cot(angle)
```
### Arguments
Numeric value or whole numeric text. Nonfinite input raises INVALID_ARGUMENT; Zero and floating poles return signed infinity; NaN becomes SQL NULL. SQL NULL propagates.
### Returned value
Approximate REAL cotangent, including signed infinity at poles.
### Example
```sql
SELECT round(cot(0.5),6) FORMAT csv;
```
```text
1.830488
```
## div
Compute an exact quotient truncated towards zero.
### Syntax
```text
div(numerator,denominator)
```
### Arguments
Whole numeric inputs, including native exact integers/decimals; zero divisor errors.
### Returned value
Exact native Decimal128/Decimal256 with scale 0, up to 76 digits; SQL NULL propagates.
### Example
```sql
SELECT CAST(div(-9,4) AS TEXT) FORMAT csv;
```
```text
"-2"
```
## factorial
Compute a nonnegative integer factorial exactly within native decimal precision.
### Syntax
```text
factorial(integer)
```
### Arguments
Signed integer from zero through 56; negative values raise INVALID_ARGUMENT and larger values raise NUMERIC_OVERFLOW. SQL NULL propagates.
### Returned value
Native exact Decimal128/Decimal256; 0! and 1! are one.
### Example
```sql
SELECT factorial(5) FORMAT csv;
```
```text
120
```
## gcd
Compute an exact nonnegative greatest common divisor.
### Syntax
```text
gcd(a,b)
```
### Arguments
Aligns finite decimal coefficients before Euclid; supports fractional operands and negative values. Both zero gives zero. Numeric inputs use existing 1024-digit/exponent limits; nonfinite/nonnumeric inputs error.
### Returned value
Native exact Decimal retaining maximum input fractional scale; SQL NULL propagates.
### Example
```sql
SELECT CAST(gcd(1071,462) AS TEXT) FORMAT csv;
```
```text
"21"
```
## lcm
Compute an exact nonnegative least common multiple.
### Syntax
```text
lcm(a,b)
```
### Arguments
Aligns finite decimal coefficients; divides before multiplication; either zero gives zero. Native precision/scale overflow errors. Numeric inputs use existing 1024-digit/exponent limits; nonfinite/nonnumeric inputs error.
### Returned value
Native exact Decimal retaining maximum input fractional scale; SQL NULL propagates.
### Example
```sql
SELECT CAST(lcm(1071,462) AS TEXT) FORMAT csv;
```
```text
"23562"
```
## min_scale
Report the minimum fractional scale needed for an exact number.
### Syntax
```text
min_scale(value)
```
### Arguments
Ignores trailing fractional zeroes; zero and integer-valued numbers give zero. Numeric inputs use existing 1024-digit/exponent limits; nonfinite/nonnumeric inputs error.
### Returned value
INTEGER minimum scale, or SQL NULL.
### Example
```sql
SELECT min_scale('8.4100') FORMAT csv;
```
```text
2
```
## pg_size_bytes
Parse a human-readable byte size.
### Syntax
```text
pg_size_bytes(text)
```
### Arguments
At most 512 bytes. Decimal/scientific number plus optional case-insensitive bytes/B/kB/MB/GB/TB/PB. Units use powers of 1024. Round half away from zero; signed 64-bit overflow errors. SQL NULL propagates.
### Returned value
INTEGER bytes.
### Example
```sql
SELECT pg_size_bytes('1.5 MB') FORMAT csv;
```
```text
1572864
```
## pg_size_pretty
Format an exact byte count with binary size units.
### Syntax
```text
pg_size_pretty(bytes)
```
### Arguments
Exact bounded numeric input. Uses PostgreSQL 10 KiB/half-unit thresholds and truncation before half rounding; native precision/scale limits apply. SQL NULL propagates.
### Returned value
TEXT size with bytes/kB/MB/GB/TB/PB.
### Example
```sql
SELECT pg_size_pretty(1048576) FORMAT csv;
```
```text
"1024 kB"
```
## random_normal
Draw an approximate normally distributed random value.
### Syntax
```text
random_normal([mean[,stddev]])
```
### Arguments
Defaults: mean zero and stddev one. Calls use connection-local random state and are nondeterministic. IEEE nonfinite arithmetic applies and native NaN becomes SQL NULL. SQL NULL arguments propagate.
### Returned value
Approximate REAL normal sample; no cryptographic or seeded PostgreSQL sequence compatibility.
### Example
```sql
SELECT random_normal(0,1) IS NOT NULL FORMAT csv;
```
```text
1
```
## scale
Report the retained fractional decimal scale.
### Syntax
```text
scale(value)
```
### Arguments
Includes trailing zeroes; native Decimal declarations and textual numeric inputs retain their scale. Numeric inputs use existing 1024-digit/exponent limits; nonfinite/nonnumeric inputs error.
### Returned value
INTEGER scale, or SQL NULL.
### Example
```sql
SELECT scale('8.4100') FORMAT csv;
```
```text
4
```
## to_bin
Format an integer in binary.
### Syntax
```text
to_bin(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement binary representation.
### Example
```sql
SELECT to_bin(10) FORMAT csv;
```
```text
"1010"
```
## to_oct
Format an integer in octal.
### Syntax
```text
to_oct(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement octal representation.
### Example
```sql
SELECT to_oct(10) FORMAT csv;
```
```text
"12"
```
## trim_scale
Remove trailing fractional decimal zeroes.
### Syntax
```text
trim_scale(value)
```
### Arguments
Returns native exact Decimal128/Decimal256; precision/scale remain bounded to 76 digits. Numeric inputs use existing 1024-digit/exponent limits; nonfinite/nonnumeric inputs error.
### Returned value
Native exact Decimal, or SQL NULL.
### Example
```sql
SELECT CAST(trim_scale('8.4100') AS TEXT) FORMAT csv;
```
```text
"8.41"
```
## width_bucket
Locate a histogram bucket with exact numeric boundaries or ordered native thresholds.
### Syntax
```text
width_bucket(value,low,high,count) or width_bucket(value,thresholds)
```
### Arguments
Positive Int64 count and distinct finite numeric endpoints; descending ranges supported. Threshold array must be sorted ascending and contain no NULLs; native comparison/collation apply.
### Returned value
Int64 bucket: 0 below the range, count+1 at/beyond high; threshold form returns matched lower-bound count; SQL NULL propagates.
### Example
```sql
SELECT width_bucket(5.35,0.024,10.06,5) FORMAT csv;
```
```text
3
```
## Core mathematical functions
Unary functions include abs, sign, ceil/ceiling, floor, trunc, exp, ln, log10, log2, sqrt, degrees, radians, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, asinh, acosh and atanh. pow/power and atan2 take two arguments; pi takes none. log(value) uses base 10; log(base,value) accepts a positive fractional base other than 1. Domain errors that produce NaN return NULL.
```sql
SELECT sqrt(9),pow(2,3),log(2,8),sign(-4) FORMAT csv;
```
```text
3.0,8.0,3.0,-1
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/other-functions
Language: en
# Utility functions
Utility functions inspect SQL values, format sizes and expose connection information. Some names on this page are table functions: use them in FROM when they produce several rows.
Connection counters refer to the observing SQL connection. Functions that inspect types distinguish the native type descriptor from the legacy runtime value class.
## Example: Inspecting a row
```sql
SELECT num_nonnulls(1, NULL, ''), num_nulls(1, NULL, ''), pg_typeof('hello')
FORMAT csv;
```
```text
2,1,"String"
```
## num_nonnulls
Count non-NULL arguments.
### Syntax
```text
num_nonnulls(value,...)
```
### Arguments
One or more arguments. Only the outer SQL NULL value is counted as missing.
### Returned value
INTEGER number of non-NULL arguments.
### Example
```sql
SELECT num_nonnulls(1,NULL,2) FORMAT csv;
```
```text
2
```
## num_nulls
Count SQL NULL arguments.
### Syntax
```text
num_nulls(value,...)
```
### Arguments
One or more arguments. Native JSON null and collection members are ordinary non-NULL argument values.
### Returned value
INTEGER number of NULL arguments.
### Example
```sql
SELECT num_nulls(1,NULL,2) FORMAT csv;
```
```text
1
```
## pg_size_bytes
Parse a human-readable byte size.
### Syntax
```text
pg_size_bytes(text)
```
### Arguments
At most 512 bytes. Decimal/scientific number plus optional case-insensitive bytes/B/kB/MB/GB/TB/PB. Units use powers of 1024. Round half away from zero; signed 64-bit overflow errors. SQL NULL propagates.
### Returned value
INTEGER bytes.
### Example
```sql
SELECT pg_size_bytes('1.5 MB') FORMAT csv;
```
```text
1572864
```
## pg_size_pretty
Format an exact byte count with binary size units.
### Syntax
```text
pg_size_pretty(bytes)
```
### Arguments
Exact bounded numeric input. Uses PostgreSQL 10 KiB/half-unit thresholds and truncation before half rounding; native precision/scale limits apply. SQL NULL propagates.
### Returned value
TEXT size with bytes/kB/MB/GB/TB/PB.
### Example
```sql
SELECT pg_size_pretty(1048576) FORMAT csv;
```
```text
"1024 kB"
```
## pg_typeof
Describe the bound native type, including typed NULL expressions.
### Syntax
```text
pg_typeof(value)
```
### Arguments
One argument. Bound column/CAST declarations take priority; otherwise infer the present native value. Returns CoordinatorDB type names as text, not PostgreSQL regtype OIDs.
### Returned value
Canonical native declaration, or unknown for an untyped NULL.
### Example
```sql
SELECT pg_typeof(CAST(NULL AS UInt8)) FORMAT csv;
```
```text
"UInt8"
```
## generate_series
Generate inclusive numeric or calendar values as a FROM table with one column.
### Syntax
```text
FROM generate_series(start, stop[, step[, timezone]])
```
### Arguments
Numeric step defaults to 1. Timestamp bounds require a native interval or quantity-unit step. Zero step errors; NULL input and unreachable direction produce no rows. FROM-only; joins use table-function rules.
### Returned value
One generated value per row in column generate_series, in series order.
### Example
```sql
SELECT * FROM generate_series(1,3) FORMAT csv;
```
```text
1
2
3
```
## generate_subscripts
Return one-based indexes of a rectangular native array dimension.
### Syntax
```text
FROM generate_subscripts(array,dimension[,reverse])
```
### Arguments
Positive requested dimension; absent/nonpositive dimension gives no rows; reverse Bool defaults false; ragged arrays error; NULL gives no rows.
### Returned value
One generate_subscripts INTEGER column.
### Example
```sql
SELECT * FROM generate_subscripts(array(10,20),1) FORMAT csv;
```
```text
1
2
```
## to_number
Parse a bounded numeric input mask without rounding through floating point.
### Syntax
```text
to_number(text,template)
```
### Arguments
One to 76 digit positions; 9/0, D/., G/,, S/MI/PL/SG/PR, L/$, V, FM/B, TH and quoted literals. Locale-independent punctuation; templates may contain at most 4096 bytes.
### Returned value
Exact native Decimal128/Decimal256 up to 76 digits; SQL NULL propagates.
### Example
```sql
SELECT CAST(to_number('12,454.8-','99G999D9S') AS TEXT) FORMAT csv;
```
```text
"-12454.8"
```
## unnest
Expand nested native arrays into scalar rows in depth-first order.
### Syntax
```text
FROM unnest(array)
```
### Arguments
One native Array; nested arrays flatten; NULL members emit NULL rows; NULL input and empty arrays emit no rows.
### Returned value
One value per row in column unnest; FROM-only; multiple-array and SELECT-list forms are unsupported.
### Example
```sql
SELECT * FROM unnest(array(1,NULL,2)) FORMAT csv;
```
```text
1
\N
2
```
## Version and connection counters
version() returns the CoordinatorDB server build version and is available before USE. sqlite_version() reports a compatibility version, not the CoordinatorDB build. changes() reports the most recent statement's change count, total_changes() the connection total, and last_insert_rowid() the latest inserted row identifier. Internal catalog and log maintenance preserves these counters.
```sql
SELECT version() FORMAT csv;
```
```text
"0.1.0"
```
## likelihood, likely and unlikely
These functions return their first argument unchanged. likelihood(value,probability) requires a floating-point SQL literal in the range 0 through 1; expressions, integer literals and unary signs are rejected. Parentheses around the literal are accepted. likely(value) and unlikely(value) take one argument.
```sql
SELECT likelihood(7,0.5),likely(7),unlikely(NULL) FORMAT csv;
```
```text
7,7,\N
```
## sqlite_source_id
sqlite_source_id() returns a fixed compatibility source identifier. It does not identify the current CoordinatorDB build. Use version() for the server version.
```sql
SELECT typeof(sqlite_source_id()),length(sqlite_source_id())>0 FORMAT csv;
```
```text
"text",1
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/overview
Language: en
# Scalar functions
Scalar functions evaluate expressions and return one value per input row. They transform text, numbers, dates, structured values and other SQL data.
## Calling a function
```text
function_name(argument, ...)
```
Function names ignore ASCII case. Use the documented spelling, including underscores. Accepted argument counts, conversion rules and NULL behavior are stated for each function; similar names in another database do not imply identical overloads.
```sql
SELECT lower('HELLO'), abs(-7), coalesce(NULL, 'fallback')
FORMAT csv;
```
```text
"hello",7,"fallback"
```
Unlike scalar functions, [aggregates](https://coordinatordb.com/docs/reference/functions/aggregate-functions) combine rows, [table functions](https://coordinatordb.com/docs/reference/functions/table-functions) provide rows in FROM, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) read related rows while retaining each input row.
## Function families
* [Arithmetic functions](https://coordinatordb.com/docs/reference/functions/regular-functions/arithmetic-functions)
* [Array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions)
* [Bit functions](https://coordinatordb.com/docs/reference/functions/regular-functions/bit-functions)
* [Comparison functions](https://coordinatordb.com/docs/reference/functions/regular-functions/comparison-functions)
* [Conditional functions and CASE](https://coordinatordb.com/docs/reference/functions/regular-functions/conditional-functions)
* [Date and time functions](https://coordinatordb.com/docs/reference/functions/regular-functions/date-time-functions)
* [Vector distances](https://coordinatordb.com/docs/reference/functions/regular-functions/distance-functions)
* [Encoding and binary functions](https://coordinatordb.com/docs/reference/functions/regular-functions/encoding-functions)
* [Functions for NULL values](https://coordinatordb.com/docs/reference/functions/regular-functions/functions-for-nulls)
* [Geographic functions](https://coordinatordb.com/docs/reference/functions/regular-functions/geo)
* [Hash and digest functions](https://coordinatordb.com/docs/reference/functions/regular-functions/hash-functions)
* [IP address and network functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions)
* [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions)
* [Logical expressions](https://coordinatordb.com/docs/reference/functions/regular-functions/logical-functions)
* [Mathematical functions](https://coordinatordb.com/docs/reference/functions/regular-functions/math-functions)
* [Utility functions](https://coordinatordb.com/docs/reference/functions/regular-functions/other-functions)
* [Random functions](https://coordinatordb.com/docs/reference/functions/regular-functions/random-functions)
* [Rounding functions](https://coordinatordb.com/docs/reference/functions/regular-functions/rounding-functions)
* [Splitting and joining strings](https://coordinatordb.com/docs/reference/functions/regular-functions/splitting-merging-functions)
* [String functions](https://coordinatordb.com/docs/reference/functions/regular-functions/string-functions)
* [String replacement functions](https://coordinatordb.com/docs/reference/functions/regular-functions/string-replace-functions)
* [String search and full-text functions](https://coordinatordb.com/docs/reference/functions/regular-functions/string-search-functions)
* [Tuple functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-functions)
* [Map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions)
* [Type conversion functions](https://coordinatordb.com/docs/reference/functions/regular-functions/type-conversion-functions)
* [UUID functions](https://coordinatordb.com/docs/reference/functions/regular-functions/uuid-functions)
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/random-functions
Language: en
# Random functions
Random functions generate values, set the connection pseudorandom seed or request cryptographically strong random bytes. These are separate randomness sources.
`setseed` controls the connection pseudorandom sequence; it does not control OS-random bytes or UUID entropy. Examples below compare stable properties such as byte length rather than expecting fixed random output.
## Example: Checking size and a zero-deviation sample
```sql
SELECT length(gen_random_bytes(16)), random_normal(7, 0)
FORMAT csv;
```
```text
16,7.0
```
## gen_random_bytes
Read bounded cryptographically strong OS-random bytes.
### Syntax
```text
gen_random_bytes(count)
```
### Arguments
Integer count 1..1024. OS entropy is independent of setseed. Failures use IO_ERROR. SQL NULL propagates.
### Returned value
BLOB random bytes; nondeterministic.
### Example
```sql
SELECT length(gen_random_bytes(8)) FORMAT csv;
```
```text
8
```
## random_normal
Draw an approximate normally distributed random value.
### Syntax
```text
random_normal([mean[,stddev]])
```
### Arguments
Defaults: mean zero and stddev one. Calls use connection-local random state and are nondeterministic. IEEE nonfinite arithmetic applies and native NaN becomes SQL NULL. SQL NULL arguments propagate.
### Returned value
Approximate REAL normal sample; no cryptographic or seeded PostgreSQL sequence compatibility.
### Example
```sql
SELECT random_normal(0,1) IS NOT NULL FORMAT csv;
```
```text
1
```
## setseed
Reset the connection-local random sequence.
### Syntax
```text
setseed(seed)
```
### Arguments
Finite seed in \[-1,1]. Equal seeds repeat random/random_normal/array sampling draws. UUIDs and gen_random_bytes keep independent OS entropy. NULL does not reseed. Native draw sequences differ from PostgreSQL.
### Returned value
SQL NULL after resetting the generator.
### Example
```sql
SELECT setseed(0.25) FORMAT csv;
```
```text
\N
```
## random and randomblob
random() returns a signed INTEGER random value. randomblob(length) returns that many random bytes as a BLOB; lengths below one, including NULL after integer conversion, produce one byte. Requests above 1,000,000,000 bytes fail, and request memory limits also apply.
These functions are nondeterministic. Use gen_random_bytes when cryptographically strong random bytes are required.
```sql
SELECT typeof(random()),length(randomblob(8)),length(randomblob(0)),length(randomblob(NULL)) FORMAT csv;
```
```text
"integer",8,1,1
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/rounding-functions
Language: en
# Rounding functions
Rounding functions choose a nearby representable number. The direction matters for negative values: floor moves toward negative infinity, while truncation moves toward zero.
## Syntax
```text
round(value [, digits])
ceil(value)
ceiling(value)
floor(value)
trunc(value)
```
## Behavior
| Function | Rule |
| ------------------ | ------------------------------------------------------------------ |
| `round` | Round to a number of decimal places; the default is zero. |
| `ceil` / `ceiling` | Choose the least integer value greater than or equal to the input. |
| `floor` | Choose the greatest integer value less than or equal to the input. |
| `trunc` | Remove the fractional part toward zero. |
Ordinary floating-point round uses half-away-from-zero ties and clamps its requested decimal places to 0 through 30. Floating-point values remain approximate.
Decimal rounding preserves the declared scale. A carry into an additional integer digit can widen its precision to the next supported family. SQL NULL propagates.
## Examples
### Comparing directions
```sql
SELECT round(12.345, 2), ceil(1.2), floor(-1.2), trunc(-1.2)
FORMAT csv;
```
```text
12.35,2.0,-2.0,-1.0
```
### Exact decimal rounding
```sql
SELECT round(CAST('12.345' AS Decimal(18, 3)), 2)
FORMAT csv;
```
```text
12.350
```
See [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal) and [floating-point types](https://coordinatordb.com/docs/reference/data-types/float) for precision and conversion rules.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/splitting-merging-functions
Language: en
# Splitting and joining strings
These functions split text into arrays or rows and join array members back into text. Choose literal-delimiter functions when the separator is fixed, and regular-expression variants when the separator is a pattern.
Empty separators, NULL inputs and NULL array members have function-specific behavior. `array_to_string` can supply an explicit replacement for missing members.
## Example: Changing a list separator
```sql
SELECT array_to_string(string_to_array('Ada,Grace,Linus', ','), ' | ')
FORMAT csv;
```
```text
"Ada | Grace | Linus"
```
## array_to_string
Join native array members in depth-first order, skipping NULL unless a replacement is supplied.
### Syntax
```text
array_to_string(array, delimiter[, null_string])
```
### Arguments
Native Array, delimiter text, optional NULL-member replacement; nested arrays are flattened.
### Returned value
TEXT; empty array gives empty text; NULL array or delimiter gives NULL.
### Example
```sql
SELECT array_to_string(array(1,NULL,2),',','?') FORMAT csv;
```
```text
"1,?,2"
```
## regexp_split_to_array
Split text into native text fields using a Unicode regex delimiter.
### Syntax
```text
regexp_split_to_array(text, pattern[, flags])
```
### Arguments
Existing regex syntax/flags; ignore zero-length delimiters at endpoints and immediately after a preceding match; captures are excluded.
### Returned value
Native Array(String); empty source produces one empty field; NULL propagates.
### Example
```sql
SELECT array_to_string(regexp_split_to_array('a b c',' +'),'|') FORMAT csv;
```
```text
"a|b|c"
```
## regexp_split_to_table
Split text into rows using the documented delimiter rules.
### Syntax
```text
FROM regexp_split_to_table(text, pattern[, flags])
```
### Arguments
Same separators and flags as regexp_split_to_array; any NULL argument emits no rows.
### Returned value
One TEXT field per row in column regexp_split_to_table; FROM-only.
### Example
```sql
SELECT * FROM regexp_split_to_table('a,b',',') FORMAT csv;
```
```text
"a"
"b"
```
## split_part
Return one delimiter-separated field from text.
### Syntax
```text
split_part(value, delimiter, field)
```
### Arguments
Positive fields count from one; negative fields count from the last field; zero raises INVALID_ARGUMENT. Empty delimiter leaves one field.
### Returned value
Field TEXT, empty TEXT when missing, or NULL for any NULL argument.
### Example
```sql
SELECT split_part('a::b::c','::',2) FORMAT csv;
```
```text
"b"
```
## string_to_array
Split text into a native Array(String), replacing exact null_string fields with NULL.
### Syntax
```text
string_to_array(text, delimiter[, null_string])
```
### Arguments
NULL delimiter splits Unicode characters; empty delimiter retains one field; empty input gives an empty array.
### Returned value
Native text array; nullable members when a non-NULL null_string is supplied; NULL for NULL input.
### Example
```sql
SELECT array_to_string(string_to_array('a,b,c',','),'|') FORMAT csv;
```
```text
"a|b|c"
```
## string_to_table
Split text into rows using the documented delimiter rules.
### Syntax
```text
FROM string_to_table(text,delimiter[,null_string])
```
### Arguments
NULL delimiter splits Unicode characters; empty delimiter keeps the whole nonempty input; optional marker yields SQL NULL; empty source yields zero rows.
### Returned value
One string_to_table column containing nullable TEXT.
### Example
```sql
SELECT * FROM string_to_table('a,b',',') FORMAT csv;
```
```text
"a"
"b"
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/string-functions
Language: en
# String functions
String functions inspect, slice, normalize, compare and transform text. Character-based positions count Unicode characters; byte-oriented functions such as `octet_length` and encoding functions count the underlying bytes.
`lower` and `upper` have legacy ASCII behavior. Use `lower_utf8`, `upper_utf8`, `casefold` or other explicitly documented Unicode operations when their broader behavior is required.
## Example: Normalizing a text field
```sql
SELECT lower(trim(' ADA@EXAMPLE.ORG ')) AS normalized_email
FORMAT csv;
```
```text
"ada@example.org"
```
## ascii
Return the Unicode code point of the first character; return zero for empty text.
### Syntax
```text
ascii(text)
```
### Arguments
One text-convertible SQL value.
### Returned value
INTEGER code point, or NULL for NULL input.
### Example
```sql
SELECT ascii('A') FORMAT csv;
```
```text
65
```
## bit_length
Return UTF-8 text or exact BLOB length in bits.
### Syntax
```text
bit_length(value)
```
### Arguments
Text conversions use native scalar rules; BLOB counts raw bytes without decoding. Embedded NUL bytes are included.
### Returned value
INTEGER bit count or SQL NULL.
### Example
```sql
SELECT bit_length('é') FORMAT csv;
```
```text
16
```
## btrim
Remove supplied Unicode characters from both ends of text.
### Syntax
```text
btrim(value[,characters])
```
### Arguments
Default character set is one ASCII space. Empty set retains the input. Membership uses a fixed ASCII table and distinct Unicode characters. NULL propagates.
### Returned value
Trimmed TEXT or SQL NULL.
### Example
```sql
SELECT btrim('xyhelloyx','xy') FORMAT csv;
```
```text
"hello"
```
## casefold
Apply full default Unicode case folding for caseless comparison.
### Syntax
```text
casefold(text)
```
### Arguments
Locale-independent default folding; does not normalize Unicode; NULL propagates.
### Returned value
TEXT with full folded mappings, which may expand characters.
### Example
```sql
SELECT casefold('Straße') FORMAT csv;
```
```text
"strasse"
```
## chr
Convert a nonzero Unicode scalar code point to text.
### Syntax
```text
chr(code)
```
### Arguments
Signed integer; zero, surrogate values, negative values, and values above U+10FFFF error.
### Returned value
One Unicode character as TEXT, or NULL for NULL input.
### Example
```sql
SELECT chr(65) FORMAT csv;
```
```text
"A"
```
## convert
Convert bytes from one supported character encoding to another.
### Syntax
```text
convert(bytes,source_encoding,destination_encoding)
```
### Arguments
BLOB or UTF-8 text. Reuses UTF8/SQL_ASCII, LATIN1, WIN1250..1258, KOI8R/U mappings. Native SQL_ASCII follows strict UTF8. Undefined bytes, NUL, unsupported encodings and unrepresentable characters error. SQL NULL propagates.
### Returned value
BLOB destination bytes.
### Example
```sql
SELECT encode(convert(decode('e9','hex'),'LATIN1','UTF8'),'hex') FORMAT csv;
```
```text
"c3a9"
```
## initcap
Uppercase the first character of each alphanumeric word and lowercase remaining characters using locale-independent Unicode mappings.
### Syntax
```text
initcap(text)
```
### Arguments
One SQL value converted to text; words are Unicode alphanumeric sequences.
### Returned value
TEXT, or NULL for NULL input.
### Example
```sql
SELECT initcap('hi THOMAS') FORMAT csv;
```
```text
"Hi Thomas"
```
## left
Take text characters from the start, or omit trailing characters for a negative count.
### Syntax
```text
left(value, count)
```
### Arguments
Values use ordinary text conversion; count is an integer. Positions count Unicode characters, including embedded NUL.
### Returned value
Prefix TEXT, or NULL for NULL input.
### Example
```sql
SELECT left('abcdef',3) FORMAT csv;
```
```text
"abc"
```
## length
Measure text characters, binary bytes, or native collection elements.
### Syntax
```text
length(value)
```
### Arguments
value: text counts Unicode characters before the first NUL; BLOB and FixedString count bytes; collections count elements; QBit counts dimensions. Other values use their text representation.
### Returned value
Nonnegative INTEGER length, or NULL for a NULL argument.
### Example
```sql
SELECT length('hello'),length('é'),length(x'00FF') FORMAT csv;
```
```text
5,1,2
```
## levenshtein
Compute Unicode edit distance.
### Syntax
```text
levenshtein(source,target); optional insertion/deletion/substitution costs
```
### Arguments
At most 255 characters per input. Optional nonnegative 32-bit insertion/deletion/substitution costs. SQL NULL propagates.
### Returned value
INTEGER edit distance.
### Example
```sql
SELECT levenshtein('GUMBO','GAMBOL') FORMAT csv;
```
```text
2
```
## levenshtein_less_equal
Compute Unicode edit distance up to a threshold.
### Syntax
```text
levenshtein_less_equal(source,target,max_distance); optional insertion/deletion/substitution costs
```
### Arguments
At most 255 characters per input. Optional nonnegative 32-bit insertion/deletion/substitution costs. Threshold is last; negative threshold requests the full distance. Above threshold any larger value is valid. SQL NULL propagates.
### Returned value
INTEGER edit distance or a value greater than the threshold.
### Example
```sql
SELECT levenshtein_less_equal('GUMBO','GAMBOL',2) FORMAT csv;
```
```text
2
```
## lower
Convert a value to text and lowercase ASCII letters; preserve other characters and NULL.
### Syntax
```text
lower(value)
```
### Arguments
value: one SQL value, converted to text unless NULL.
### Returned value
TEXT with ASCII letters lowercased, or NULL for a NULL argument.
### Example
```sql
SELECT lower('HELLO') FORMAT csv;
```
```text
"hello"
```
## lower_utf8
Lowercase text with locale-independent Unicode case mapping, including Cyrillic.
### Syntax
```text
lower_utf8(value)
```
### Arguments
value: one SQL value converted to text. Invalid blob UTF-8 is replaced during text conversion; NULL propagates.
### Returned value
Lowercase TEXT; Unicode mappings may change its byte length or character count. NULL for a NULL argument.
### Example
```sql
SELECT lower_utf8('HELLO ÄBC') FORMAT csv;
```
```text
"hello äbc"
```
## lpad
Pad text on the left or truncate it on the right to a character length.
### Syntax
```text
lpad(value, length[, fill])
```
### Arguments
Fill defaults to one space; fill is repeated and its final repetition may be partial. Negative length returns empty text; empty fill adds nothing.
### Returned value
Padded or truncated TEXT; NULL propagates; excessive result bytes raise STRING_TOO_LONG.
### Example
```sql
SELECT lpad('hi',5,'xy') FORMAT csv;
```
```text
"xyxhi"
```
## md5
Compute the lowercase hexadecimal MD5 digest of text bytes.
### Syntax
```text
md5(text)
```
### Arguments
Text conversion uses UTF-8 bytes; NULL propagates.
### Returned value
32-character lowercase hexadecimal TEXT.
### Example
```sql
SELECT md5('abc') FORMAT csv;
```
```text
"900150983cd24fb0d6963f7d28e17f72"
```
## normalize
Normalize Unicode text using NFC by default or an explicitly selected normalization form.
### Syntax
```text
normalize(text[, NFC|NFD|NFKC|NFKD])
```
### Arguments
Forms may also be text/parameters; Unicode normalization is locale-independent; NULL propagates.
### Returned value
TEXT in the selected normalization form.
### Example
```sql
SELECT normalize('①',NFKC) FORMAT csv;
```
```text
"1"
```
## overlay
Replace a character-position substring.
### Syntax
```text
overlay(text,replacement,start[,length])
```
### Arguments
One-based positive start; nonnegative length defaults to replacement character count; Unicode character positions. Comma argument form.
### Returned value
TEXT; starts beyond the source append replacement; SQL NULL propagates.
### Example
```sql
SELECT overlay('Txxxxas','hom',2,4) FORMAT csv;
```
```text
"Thomas"
```
## parse_ident
Parse a dotted SQL identifier into an array of components without truncation.
### Syntax
```text
parse_ident(text[,strict])
```
### Arguments
Strict defaults to true; false ignores trailing text after the final identifier. Quoted names retain spelling and doubled double quotes; unquoted names fold ASCII case. Empty/malformed components and NUL error.
### Returned value
Native Array(String), or NULL for a NULL argument.
### Example
```sql
SELECT array_to_string(parse_ident('"SomeSchema".SomeTable'),'/') FORMAT csv;
```
```text
"SomeSchema/sometable"
```
## quote_ident
Quote an identifier for the native SQL grammar.
### Syntax
```text
quote_ident(value)
```
### Arguments
Conservative quoting always uses double quotes, doubling embedded quotes; NUL errors.
### Returned value
TEXT containing a quoted SQL identifier; SQL NULL propagates.
### Example
```sql
SELECT quote_ident('Foo bar') FORMAT csv;
```
```text
"""Foo bar"""
```
## quote_literal
Quote a literal for the native SQL string grammar.
### Syntax
```text
quote_literal(value)
```
### Arguments
Scalar text is single-quoted and embedded quotes doubled. Native backslashes remain literal; no PostgreSQL E-string prefix. NUL errors.
### Returned value
TEXT containing a SQL literal; SQL NULL propagates.
### Example
```sql
SELECT quote_literal('O''Reilly') FORMAT csv;
```
```text
"'O''Reilly'"
```
## quote_nullable
Quote a literal or produce the SQL NULL keyword.
### Syntax
```text
quote_nullable(value)
```
### Arguments
Same native quoted-string contract as quote_literal.
### Returned value
TEXT; a SQL NULL input returns the text NULL.
### Example
```sql
SELECT quote_nullable(NULL) FORMAT csv;
```
```text
"NULL"
```
## repeat
Repeat text a requested number of times, subject to result-byte limits.
### Syntax
```text
repeat(text, count)
```
### Arguments
Text and signed integer count; nonpositive count gives empty text; results above the string byte ceiling error.
### Returned value
TEXT, or NULL for any NULL argument.
### Example
```sql
SELECT repeat('Pg',3) FORMAT csv;
```
```text
"PgPgPg"
```
## replace
Replace all non-overlapping, case-sensitive occurrences of a search value.
### Syntax
```text
replace(value, search, replacement)
```
### Arguments
Three SQL values converted to byte sequences. A NULL value or search returns NULL. Empty search returns the text-converted source before checking replacement; otherwise NULL replacement returns NULL.
### Returned value
TEXT, including for an empty search. NULL arguments propagate as described; oversized output raises an error.
### Example
```sql
SELECT replace('a-b-a','a','x') FORMAT csv;
```
```text
"x-b-x"
```
## reverse
Reverse Unicode scalar characters, without reversing the bytes within a character.
### Syntax
```text
reverse(text)
```
### Arguments
One SQL value converted to text; combining sequences are not treated as one grapheme.
### Returned value
TEXT, or NULL for NULL input.
### Example
```sql
SELECT reverse('abc') FORMAT csv;
```
```text
"cba"
```
## right
Take text characters from the end, or omit leading characters for a negative count.
### Syntax
```text
right(value, count)
```
### Arguments
Values use ordinary text conversion; count is an integer. Positions count Unicode characters, including embedded NUL.
### Returned value
Suffix TEXT, or NULL for NULL input.
### Example
```sql
SELECT right('abcdef',3) FORMAT csv;
```
```text
"def"
```
## rpad
Pad text on the right or truncate it on the right to a character length.
### Syntax
```text
rpad(value, length[, fill])
```
### Arguments
Fill defaults to one space; fill is repeated and its final repetition may be partial. Negative length returns empty text; empty fill adds nothing.
### Returned value
Padded or truncated TEXT; NULL propagates; excessive result bytes raise STRING_TOO_LONG.
### Example
```sql
SELECT rpad('hi',5,'xy') FORMAT csv;
```
```text
"hixyx"
```
## show_trgm
List sorted unique compact trigrams.
### Syntax
```text
show_trgm(text)
```
### Arguments
Same Unicode word/padding/lowercase rules as similarity. Multibyte compact keys use PostgreSQL legacy CRC and little-endian byte extraction. NUL errors. SQL NULL propagates.
### Returned value
Array(String): printable ASCII keys or hexadecimal compact keys.
### Example
```sql
SELECT array_to_string(show_trgm('cat'),'|') FORMAT csv;
```
```text
" c| ca|at |cat"
```
## similarity
Compare unique trigram sets.
### Syntax
```text
similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT similarity('word','two words') FORMAT csv;
```
```text
0.36363637
```
## split_part
Return one delimiter-separated field from text.
### Syntax
```text
split_part(value, delimiter, field)
```
### Arguments
Positive fields count from one; negative fields count from the last field; zero raises INVALID_ARGUMENT. Empty delimiter leaves one field.
### Returned value
Field TEXT, empty TEXT when missing, or NULL for any NULL argument.
### Example
```sql
SELECT split_part('a::b::c','::',2) FORMAT csv;
```
```text
"b"
```
## starts_with
Check whether text begins with a case-sensitive prefix.
### Syntax
```text
starts_with(text, prefix)
```
### Arguments
Two text-convertible values; empty prefix matches every string.
### Returned value
Native Bool, or NULL for a NULL argument.
### Example
```sql
SELECT starts_with('alphabet','alph') FORMAT csv;
```
```text
true
```
## strict_word_similarity
Maximize similarity over extents aligned to whole-word boundaries.
### Syntax
```text
strict_word_similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT strict_word_similarity('word','two words') FORMAT csv;
```
```text
0.5714286
```
## strpos
Find the first exact substring and count its one-based position in Unicode characters.
### Syntax
```text
strpos(text, substring)
```
### Arguments
Text and exact substring; empty substring starts at position one.
### Returned value
INTEGER position, 0 for no match, or NULL for a NULL argument.
### Example
```sql
SELECT strpos('high','ig') FORMAT csv;
```
```text
2
```
## to_ascii
Map native Unicode text to ASCII through a PostgreSQL single-byte repertoire.
### Syntax
```text
to_ascii(text[,encoding])
```
### Arguments
Native default LATIN1. Supports LATIN1/LATIN2/LATIN9/WIN1250 and PostgreSQL numeric IDs 8/9/16/29. Encode Unicode characters in that repertoire before applying its ASCII map; unrepresentable characters and NUL error. This differs from PostgreSQL applying a mapping directly to database-encoded bytes.
### Returned value
ASCII TEXT retaining one output character per input character, or NULL for a NULL argument.
### Example
```sql
SELECT to_ascii('Karél') FORMAT csv;
```
```text
"Karel"
```
## to_bin
Format an integer in binary.
### Syntax
```text
to_bin(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement binary representation.
### Example
```sql
SELECT to_bin(10) FORMAT csv;
```
```text
"1010"
```
## to_hex
Render an exact signed Int64 or unsigned UInt64 in hexadecimal.
### Syntax
```text
to_hex(integer)
```
### Arguments
Negative signed arguments use 64-bit two's complement; oversized signed fields error; NULL propagates.
### Returned value
Lowercase hexadecimal TEXT without a prefix.
### Example
```sql
SELECT to_hex(2147483647) FORMAT csv;
```
```text
"7fffffff"
```
## to_oct
Format an integer in octal.
### Syntax
```text
to_oct(integer)
```
### Arguments
Native exact integers through 256 bits. Negative values use the declared integer width, or runtime width when no declaration is bound. Ordinary INTEGER inputs use 64 bits. SQL NULL propagates.
### Returned value
TEXT two's-complement octal representation.
### Example
```sql
SELECT to_oct(10) FORMAT csv;
```
```text
"12"
```
## translate
Map characters by their positions in source and replacement sets; missing replacements delete characters.
### Syntax
```text
translate(text, from, to)
```
### Arguments
Unicode character sets; the first occurrence of each repeated source character defines its mapping.
### Returned value
TEXT, or NULL for any NULL argument.
### Example
```sql
SELECT translate('12345','143','ax') FORMAT csv;
```
```text
"a2x5"
```
## trim
Remove selected characters from both ends of a text value; default to the space character.
### Syntax
```text
trim(value[, characters])
```
### Arguments
value: converted to text. Optional characters: a set of individual characters, not a substring. NULL in either supplied argument returns NULL.
### Returned value
Trimmed TEXT. An empty character set retains the text; a NULL argument returns NULL.
### Example
```sql
SELECT trim(' hello ') FORMAT csv;
```
```text
"hello"
```
## unaccent
Apply PostgreSQL 18 default unaccent mappings.
### Syntax
```text
unaccent([dictionary,]text)
```
### Arguments
Native UTF-8 text; default mappings include ligature expansion and combining-mark removal. Named dictionary must be unaccent/public.unaccent/pg_catalog.unaccent. NUL and unknown dictionary error. SQL NULL propagates.
### Returned value
TEXT with mapped accents removed.
### Example
```sql
SELECT unaccent('Hôtel Æther') FORMAT csv;
```
```text
"Hotel AEther"
```
## unicode_assigned
Check all scalar characters against Unicode assignment data.
### Syntax
```text
unicode_assigned(text)
```
### Arguments
UTF-8 native text. Uses Unicode 17.0 data from the existing normalization library and recognizes private-use code points as assigned. SQL NULL propagates.
### Returned value
BOOL; true for empty text.
### Example
```sql
SELECT unicode_assigned('Hello') FORMAT csv;
```
```text
true
```
## unistr
Decode escaped Unicode code points and adjacent UTF-16 surrogate pairs.
### Syntax
```text
unistr(text)
```
### Arguments
Accepts backslash plus four hex digits, u plus four, U plus eight, or + plus six; doubled backslashes are literal. Invalid escapes, unpaired surrogates, NUL, and out-of-range points error.
### Returned value
Native UTF-8 TEXT, or NULL for SQL NULL.
### Example
```sql
SELECT unistr('d\0061t\+000061') FORMAT csv;
```
```text
"data"
```
## upper
Convert a value to text and uppercase ASCII letters; preserve other characters and NULL.
### Syntax
```text
upper(value)
```
### Arguments
value: one SQL value, converted to text unless NULL.
### Returned value
TEXT with ASCII letters uppercased, or NULL for a NULL argument.
### Example
```sql
SELECT upper('hello') FORMAT csv;
```
```text
"HELLO"
```
## upper_utf8
Uppercase text with locale-independent Unicode case mapping, including Cyrillic.
### Syntax
```text
upper_utf8(value)
```
### Arguments
value: one SQL value converted to text. Invalid blob UTF-8 is replaced during text conversion; NULL propagates.
### Returned value
Uppercase TEXT; Unicode mappings may expand characters, such as sharp S to SS. NULL for a NULL argument.
### Example
```sql
SELECT upper_utf8('hello Straße') FORMAT csv;
```
```text
"HELLO STRASSE"
```
## word_similarity
Maximize similarity to a contiguous extent of text trigrams.
### Syntax
```text
word_similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT word_similarity('word','two words') FORMAT csv;
```
```text
0.8
```
## Core string functions
`substr(text,start[,length])` and substring use character positions starting at 1 and allow negative starts. Text slicing stops at the first NUL; BLOB slicing retains all bytes. `instr(text,part)` returns a one-based position or zero. `ltrim` and `rtrim` strip characters from one end. concat joins values; concat_ws requires a separator and at least one value. printf/format accept a format string and values; quote produces an SQL literal. lower/upper use ASCII mapping; lower_utf8/upper_utf8 use Unicode mapping.
```sql
SELECT substr('hello',2,3),instr('hello','ll'),concat('a','b'),concat_ws('-','a','b'),printf('%04d',7) FORMAT csv;
```
```text
"ell",3,"ab","a-b","0007"
```
## octet_length
Returns the full byte length of text or a BLOB, including bytes after an embedded NUL. Text uses UTF-8; unlike length, it counts bytes rather than Unicode characters. NULL returns NULL.
```text
octet_length(value)
```
```sql
SELECT length('é'),octet_length('é'),octet_length('a'||char(0)||'b') FORMAT csv;
```
```text
1,2,3
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/string-replace-functions
Language: en
# String replacement functions
Replacement functions change text using literal matches, character translation, positional overlays or regular expressions. Choose the operation that matches the intended replacement rule.
`replace` matches a literal substring, `translate` maps individual characters, and `overlay` uses character positions. `regexp_replace` interprets its pattern and replacement syntax as documented below.
## Example: Replacing separators
```sql
SELECT replace('2025/03/05', '/', '-'),
translate('a-b-c', '-', '_')
FORMAT csv;
```
```text
"2025-03-05","a_b_c"
```
## overlay
Replace a character-position substring.
### Syntax
```text
overlay(text,replacement,start[,length])
```
### Arguments
One-based positive start; nonnegative length defaults to replacement character count; Unicode character positions. Comma argument form.
### Returned value
TEXT; starts beyond the source append replacement; SQL NULL propagates.
### Example
```sql
SELECT overlay('Txxxxas','hom',2,4) FORMAT csv;
```
```text
"Thomas"
```
## regexp_replace
Replace a selected match or all regex matches using PostgreSQL replacement references.
### Syntax
```text
regexp_replace(value, pattern, replacement[, flags]), regexp_replace(value, pattern, replacement, start[, occurrence[, flags]])
```
### Arguments
Flags support i,c,s,n,m,p,w,x,t,q,e and g; active q and x modes are incompatible. Start is one-based; occurrence 0 replaces all. Replacement backslash-digit references groups and backslash-ampersand references the entire match. Unsupported regex constructs error.
### Returned value
Replaced TEXT, or NULL for any NULL argument. Regular-expression operations remain subject to request limits.
### Example
```sql
SELECT regexp_replace('a1b2','[0-9]','X','g') FORMAT csv;
```
```text
"aXbX"
```
## replace
Replace all non-overlapping, case-sensitive occurrences of a search value.
### Syntax
```text
replace(value, search, replacement)
```
### Arguments
Three SQL values converted to byte sequences. A NULL value or search returns NULL. Empty search returns the text-converted source before checking replacement; otherwise NULL replacement returns NULL.
### Returned value
TEXT, including for an empty search. NULL arguments propagate as described; oversized output raises an error.
### Example
```sql
SELECT replace('a-b-a','a','x') FORMAT csv;
```
```text
"x-b-x"
```
## translate
Map characters by their positions in source and replacement sets; missing replacements delete characters.
### Syntax
```text
translate(text, from, to)
```
### Arguments
Unicode character sets; the first occurrence of each repeated source character defines its mapping.
### Returned value
TEXT, or NULL for any NULL argument.
### Example
```sql
SELECT translate('12345','143','ax') FORMAT csv;
```
```text
"a2x5"
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/string-search-functions
Language: en
# String search and full-text functions
Search functions test patterns, find regular-expression matches, compare similar text and construct full-text search values. LIKE/GLOB patterns, regular expressions, trigrams and tsquery expressions are different query languages.
Use literal search when the text is literal. For full-text matching, build a tsvector and a tsquery and combine them with the SQL `@@` operator. Each family below documents its syntax, configuration and NULL behavior.
## Example: Testing an identifier pattern
```sql
SELECT like('invoice-%', 'invoice-123'),
regexp_like('invoice-123', '^invoice-[0-9]+$')
FORMAT csv;
```
```text
1,true
```
## like and glob
`like(pattern,text[,escape])` and `glob(pattern,text)` expose the pattern operators
as function calls. The pattern comes first. LIKE folds ASCII case and accepts
one optional escape character; GLOB is case-sensitive and uses shell-style
wildcards. NULL arguments propagate.
```sql
SELECT like('he%','hello'),glob('h*','hello') FORMAT csv;
```
```text
1,1
```
## array_to_tsvector
Create a vector from literal array lexemes.
### Syntax
```text
array_to_tsvector(lexemes)
```
### Arguments
One-dimensional native string Array. Reject NULL or empty members; deduplicate and sort without normalization. NULL input propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(array_to_tsvector(array('rat','cat','rat')) AS TEXT) FORMAT csv;
```
```text
"'cat' 'rat'"
```
## json_to_tsvector
Build a search vector from selected JSON components.
### Syntax
```text
json_to_tsvector([configuration,]document,filter)
```
### Arguments
Same filters/configurations as jsonb_to_tsvector; original object order and duplicate keys are retained. NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(json_to_tsvector('simple','{"title":"fat cats"}','"string"') AS TEXT) FORMAT csv;
```
```text
"'cats':2 'fat':1"
```
## jsonb_to_tsvector
Build a search vector from selected JSONB components.
### Syntax
```text
jsonb_to_tsvector([configuration,]document,filter)
```
### Arguments
Configurations simple/english/russian, default english. Filter is a JSON string or string array: string,numeric,boolean,key,all. Canonical JSONB key order and one gap between selected components. Native search limits apply; NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(jsonb_to_tsvector('simple','{"title":"fat cats"}','"string"') AS TEXT) FORMAT csv;
```
```text
"'cats':2 'fat':1"
```
## levenshtein
Compute Unicode edit distance.
### Syntax
```text
levenshtein(source,target); optional insertion/deletion/substitution costs
```
### Arguments
At most 255 characters per input. Optional nonnegative 32-bit insertion/deletion/substitution costs. SQL NULL propagates.
### Returned value
INTEGER edit distance.
### Example
```sql
SELECT levenshtein('GUMBO','GAMBOL') FORMAT csv;
```
```text
2
```
## levenshtein_less_equal
Compute Unicode edit distance up to a threshold.
### Syntax
```text
levenshtein_less_equal(source,target,max_distance); optional insertion/deletion/substitution costs
```
### Arguments
At most 255 characters per input. Optional nonnegative 32-bit insertion/deletion/substitution costs. Threshold is last; negative threshold requests the full distance. Above threshold any larger value is valid. SQL NULL propagates.
### Returned value
INTEGER edit distance or a value greater than the threshold.
### Example
```sql
SELECT levenshtein_less_equal('GUMBO','GAMBOL',2) FORMAT csv;
```
```text
2
```
## numnode
Count lexemes and operators in a query.
### Syntax
```text
numnode(query)
```
### Arguments
Native tsquery or raw query text. Empty query yields zero; NULL propagates.
### Returned value
INTEGER
### Example
```sql
SELECT numnode(to_tsquery('simple','cat & dog')) FORMAT csv;
```
```text
3
```
## phraseto_tsquery
Construct a phrase query retaining gaps from stop words.
### Syntax
```text
phraseto_tsquery([configuration,]text)
```
### Arguments
Configurations simple/english/russian; default english. Unicode word matching supports compound-word positions, language-specific word stems and stop words. Queries are bounded to 128 terms/levels; lexemes to 2046 bytes. Only the listed language configurations are supported. SQL NULL propagates.
### Returned value
Native tsquery usable in tables and subqueries.
### Example
```sql
SELECT CAST(phraseto_tsquery('english','The fat rats') AS TEXT) FORMAT csv;
```
```text
"'fat' <-> 'rat'"
```
## plainto_tsquery
Construct an AND query from ordinary text.
### Syntax
```text
plainto_tsquery([configuration,]text)
```
### Arguments
Configurations simple/english/russian; default english. Unicode word matching supports compound-word positions, language-specific word stems and stop words. Queries are bounded to 128 terms/levels; lexemes to 2046 bytes. Only the listed language configurations are supported. SQL NULL propagates.
### Returned value
Native tsquery usable in tables and subqueries.
### Example
```sql
SELECT CAST(plainto_tsquery('english','The fat rats') AS TEXT) FORMAT csv;
```
```text
"'fat' & 'rat'"
```
## querytree
Render the indexable positive part of a query.
### Syntax
```text
querytree(query)
```
### Arguments
Ignore negative restrictions. Empty query yields empty text; unrestricted alternatives yield T. This helper does not create an index. NULL propagates.
### Returned value
String
### Example
```sql
SELECT querytree(to_tsquery('simple','cat & !dog')) FORMAT csv;
```
```text
"'cat'"
```
## regexp_count
Count nonoverlapping Unicode regex matches starting at a one-based character position.
### Syntax
```text
regexp_count(text, pattern[, start[, flags]])
```
### Arguments
Start defaults to 1 and must be positive; flags follow existing regex rules; empty matches advance one UTF-8 character.
### Returned value
INTEGER count, zero without matches, or NULL for any NULL argument.
### Example
```sql
SELECT regexp_count('123456789012','[0-9]{3}',2) FORMAT csv;
```
```text
3
```
## regexp_instr
Return the one-based character boundary of a selected regex match or capture.
### Syntax
```text
regexp_instr(text,pattern[,start[,occurrence[,endoption[,flags[,subexpr]]]]])
```
### Arguments
Start/occurrence positive; endoption 0 selects the start, 1 the boundary after the end; subexpr nonnegative; existing bounded regex flags.
### Returned value
INTEGER position; 0 for no matching capture; NULL propagates.
### Example
```sql
SELECT regexp_instr('ABCDEF','c(.)(..)',1,1,0,'i') FORMAT csv;
```
```text
3
```
## regexp_like
Test whether a Unicode regex matches anywhere in the input.
### Syntax
```text
regexp_like(text, pattern[, flags])
```
### Arguments
Text, Unicode regular expression, optional supported flags; g is rejected.
### Returned value
Native Bool, or NULL for any NULL argument.
### Example
```sql
SELECT regexp_like('Hello World','world$','i') FORMAT csv;
```
```text
true
```
## regexp_match
Return the first regex match or its capturing groups.
### Syntax
```text
regexp_match(value, pattern[, flags])
```
### Arguments
Flags support i,c,s,n,m,p,w,x,t,q,e; active q and x modes are incompatible. Uses Unicode regex syntax; look-around, pattern backreferences and POSIX longest-match behavior are not supported.
### Returned value
Native array of nullable TEXT capturing groups, or the whole match when there are no groups; NULL for no match or NULL input.
### Example
```sql
SELECT array_element(regexp_match('abc123','([a-z]+)([0-9]+)'),2) FORMAT csv;
```
```text
"123"
```
## regexp_matches
Return regex match groups as native arrays in separate FROM rows.
### Syntax
```text
FROM regexp_matches(text,pattern[,flags])
```
### Arguments
Existing regex syntax and flags; g emits all matches, otherwise the first; NULL input gives no rows.
### Returned value
One regexp_matches column containing Array(Nullable(String)); no-match input gives no rows.
### Example
```sql
SELECT array_to_string(regexp_matches,',') FROM regexp_matches('a1 b2','([a-z])([0-9])','g') FORMAT csv;
```
```text
"a,1"
"b,2"
```
## regexp_substr
Return the requested regex occurrence or capture, preserving anchors against the original string.
### Syntax
```text
regexp_substr(text, pattern[, start[, occurrence[, flags[, subexpr]]]])
```
### Arguments
Positive one-based start/occurrence default to 1; nonnegative subexpr defaults to whole match 0.
### Returned value
TEXT, or NULL for no match, unmatched/missing capture, or any NULL argument.
### Example
```sql
SELECT regexp_substr('ABCDEFGHI','(c..)(...)',1,1,'i',2) FORMAT csv;
```
```text
"FGH"
```
## setweight
Assign positional weights to all or selected lexemes.
### Syntax
```text
setweight(vector,weight[,lexemes])
```
### Arguments
Weight A/B/C/D; optional native string Array selects literal lexemes. NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(setweight(to_tsvector('simple','cat dog'),'A') AS TEXT) FORMAT csv;
```
```text
"'cat':1A 'dog':2A"
```
## show_trgm
List sorted unique compact trigrams.
### Syntax
```text
show_trgm(text)
```
### Arguments
Same Unicode word/padding/lowercase rules as similarity. Multibyte compact keys use PostgreSQL legacy CRC and little-endian byte extraction. NUL errors. SQL NULL propagates.
### Returned value
Array(String): printable ASCII keys or hexadecimal compact keys.
### Example
```sql
SELECT array_to_string(show_trgm('cat'),'|') FORMAT csv;
```
```text
" c| ca|at |cat"
```
## similarity
Compare unique trigram sets.
### Syntax
```text
similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT similarity('word','two words') FORMAT csv;
```
```text
0.36363637
```
## strict_word_similarity
Maximize similarity over extents aligned to whole-word boundaries.
### Syntax
```text
strict_word_similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT strict_word_similarity('word','two words') FORMAT csv;
```
```text
0.5714286
```
## strip
Remove positions and weights from a vector.
### Syntax
```text
strip(vector)
```
### Arguments
Native tsvector or vector input text. Retain lexemes; NULL propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(strip(to_tsvector('simple','cat dog')) AS TEXT) FORMAT csv;
```
```text
"'cat' 'dog'"
```
## to_tsquery
Parse Boolean, prefix, weight and phrase query syntax.
### Syntax
```text
to_tsquery([configuration,]text)
```
### Arguments
Configurations simple/english/russian; default english. Unicode word matching supports compound-word positions, language-specific word stems and stop words. Queries are bounded to 128 terms/levels; lexemes to 2046 bytes. Only the listed language configurations are supported. SQL NULL propagates.
### Returned value
Native tsquery usable in tables and subqueries.
### Example
```sql
SELECT CAST(to_tsquery('english','fat & rats') AS TEXT) FORMAT csv;
```
```text
"'fat' & 'rat'"
```
## to_tsvector
Normalize document words and retain lexeme positions.
### Syntax
```text
to_tsvector([configuration,]text)
```
### Arguments
Configurations simple/english/russian; default english. Unicode word matching supports compound-word positions, language-specific word stems and stop words. Queries are bounded to 128 terms/levels; lexemes to 2046 bytes. Only the listed language configurations are supported. SQL NULL propagates.
### Returned value
Native tsvector usable in tables and subqueries.
### Example
```sql
SELECT CAST(to_tsvector('english','The fat rats') AS TEXT) FORMAT csv;
```
```text
"'fat':2 'rat':3"
```
## ts_delete
Remove literal lexemes from a vector.
### Syntax
```text
ts_delete(vector,lexeme_or_array)
```
### Arguments
One string or native string Array; ignore absent and NULL array members. NULL input propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(ts_delete(to_tsvector('simple','cat dog'),'dog') AS TEXT) FORMAT csv;
```
```text
"'cat':1"
```
## ts_filter
Keep selected positional weights.
### Syntax
```text
ts_filter(vector,weights)
```
### Arguments
Native string Array of A/B/C/D weights. Reject invalid or NULL members. NULL input propagates.
### Returned value
tsvector
### Example
```sql
SELECT CAST(ts_filter(setweight(to_tsvector('simple','cat'),'A'),array('A')) AS TEXT) FORMAT csv;
```
```text
"'cat':1A"
```
## ts_headline
Highlight query lexemes in bounded document fragments.
### Syntax
```text
ts_headline([configuration,]document,query[,options])
```
### Arguments
Text documents; configurations simple/english/russian. Options StartSel/StopSel/MinWords/MaxWords/MaxFragments/FragmentDelimiter/HighlightAll. Native deterministic word-window selection can differ from PostgreSQL. Default HTML-like tags are removed; HighlightAll retains source markup. Returned text is not HTML-escaped. SQL NULL propagates.
### Returned value
TEXT with selected lexemes marked.
### Example
```sql
SELECT ts_headline('english','raining cats and dogs',to_tsquery('english','cat')) FORMAT csv;
```
```text
"raining cats and dogs"
```
## ts_rank
Rank matching lexemes by frequency/proximity.
### Syntax
```text
ts_rank([weights,]vector,query[,normalization])
```
### Arguments
Native/search-text tsvector and tsquery. Optional Array of at least four non-NULL weights, ordered D/C/B/A; defaults 0.1/0.2/0.4/1. Negative weights select defaults, values above one error. Normalization mask 0..63. Stripped vector entries contribute to frequency but not cover density. SQL NULL propagates.
### Returned value
Native Float32 relevance score.
### Example
```sql
SELECT ts_rank(to_tsvector('simple','cat'),to_tsquery('simple','cat')) FORMAT csv;
```
```text
0.06079271
```
## ts_rank_cd
Rank matching lexemes by minimal cover density.
### Syntax
```text
ts_rank_cd([weights,]vector,query[,normalization])
```
### Arguments
Native/search-text tsvector and tsquery. Optional Array of at least four non-NULL weights, ordered D/C/B/A; defaults 0.1/0.2/0.4/1. Negative weights select defaults, values above one error. Normalization mask 0..63. Stripped vector entries contribute to frequency but not cover density. SQL NULL propagates.
### Returned value
Native Float32 relevance score.
### Example
```sql
SELECT ts_rank_cd(to_tsvector('simple','cat'),to_tsquery('simple','cat')) FORMAT csv;
```
```text
0.1
```
## tsquery_phrase
Join two queries at an exact positional distance.
### Syntax
```text
tsquery_phrase(left,right[,distance])
```
### Arguments
Native tsquery or raw query text; distance 0..16384, default 1. Native depth/term limits apply. NULL propagates.
### Returned value
tsquery
### Example
```sql
SELECT CAST(tsquery_phrase(to_tsquery('simple','cat'),to_tsquery('simple','dog'),2) AS TEXT) FORMAT csv;
```
```text
"'cat' <2> 'dog'"
```
## tsvector_to_array
Extract sorted unique search lexemes.
### Syntax
```text
tsvector_to_array(vector)
```
### Arguments
Native tsvector or vector input text. Positions and weights are omitted. SQL NULL propagates.
### Returned value
Array(String) lexemes.
### Example
```sql
SELECT array_to_string(tsvector_to_array(to_tsvector('simple','rat cat rat')),',') FORMAT csv;
```
```text
"cat,rat"
```
## websearch_to_tsquery
Parse quoted phrases, OR and leading-minus query terms.
### Syntax
```text
websearch_to_tsquery([configuration,]text)
```
### Arguments
Configurations simple/english/russian; default english. Unicode word matching supports compound-word positions, language-specific word stems and stop words. Queries are bounded to 128 terms/levels; lexemes to 2046 bytes. Only the listed language configurations are supported. SQL NULL propagates.
### Returned value
Native tsquery usable in tables and subqueries.
### Example
```sql
SELECT CAST(websearch_to_tsquery('english','The fat rats') AS TEXT) FORMAT csv;
```
```text
"'fat' & 'rat'"
```
## word_similarity
Maximize similarity to a contiguous extent of text trigrams.
### Syntax
```text
word_similarity(pattern,text)
```
### Arguments
Unicode alphanumeric words, locale-independent Unicode lowercase, two leading/one trailing spaces, pg_trgm compact CRC keys and Jaccard scores. SQL NULL propagates. NUL errors.
### Returned value
Native Float32 score in \[0,1]; zero for empty trigram sets.
### Example
```sql
SELECT word_similarity('word','two words') FORMAT csv;
```
```text
0.8
```
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-functions
Language: en
# Tuple functions
Tuple functions construct a record and read one of its fields. Each tuple has a fixed field count, and a typed tuple can declare a different type for every field.
## tuple
```text
tuple(value1, ...)
```
Constructs a nonempty positional tuple from its arguments. To assign field names or enforce exact field types, use a Tuple declaration or cast.
## tuple_element
```text
tuple_element(value, position)
tuple_element(value, 'field_name')
```
A position is positive and one-based, and must fit the tuple's declared field count. A name is case-sensitive and must identify a named field. The selected field retains its native type.
## Examples
### Positional access
```sql
SELECT tuple_element(tuple(7, 'Ada'), 1),
tuple_element(tuple(7, 'Ada'), 2)
FORMAT csv;
```
```text
7,"Ada"
```
### Named access
```sql
SELECT tuple_element(
CAST('{"id":7,"name":"Ada"}' AS Tuple(id UInt64, name String)),
'name'
)
FORMAT csv;
```
```text
"Ada"
```
Named tuple columns also support dotted access, such as `profile.name`. `get_subcolumn` can select a named path. See [Tuple](https://coordinatordb.com/docs/reference/data-types/tuple) for input shape and nullable field rules.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions
Language: en
# Map functions
Map functions operate on typed, ordered key/value pairs. Duplicate keys remain present; a lookup selects the first matching pair.
## Functions
| Function | Result |
| ------------------------ | ------------------------------------------------------ |
| `map(key, value, ...)` | A map constructed from alternating keys and values. |
| `map_keys(map)` | An array of keys in pair order, including duplicates. |
| `map_values(map)` | An array of values in pair order. |
| `map_element(map, key)` | The first matching value, or the value type's default. |
| `map_contains(map, key)` | A Bool indicating whether the key occurs. |
Keys cannot be NULL. Typed map declarations validate every key and value. A missing key and a stored default can return the same value; use `map_contains` to distinguish them.
## Examples
### Duplicate keys
```sql
SELECT map_keys(map('a', 1, 'a', 2)),
map_values(map('a', 1, 'a', 2)),
map_element(map('a', 1, 'a', 2), 'a')
FORMAT csv;
```
```text
"[""a"",""a""]","[1,2]",1
```
### A stored default and a missing key
```sql
SELECT map_element(map('views', 0), 'views'),
map_contains(map('views', 0), 'views'),
map_element(map('views', 0), 'likes'),
map_contains(map('views', 0), 'likes')
FORMAT csv;
```
```text
0,true,0,false
```
See the [Map type](https://coordinatordb.com/docs/reference/data-types/map) for JSON input, value defaults and nullable values.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/type-conversion-functions
Language: en
# Type conversion functions
Explicit conversion applies a declared value contract to an expression. Use it when importing text, changing numeric families or extracting a representation for another operation.
## CAST
```text
CAST(value AS Type)
```
CAST supports every declared native type. It validates ranges, text, precision and collection shape. SQL NULL propagates. Native conversions report invalid or overflowing inputs instead of silently wrapping them.
## Named conversion functions
| Function | Arguments |
| ---------------------------------------------------- | -------------------------------------------------------------- |
| `to_int128`, `to_uint128`, `to_int256`, `to_uint256` | One numeric value or accepted numeric text. |
| `to_float32`, `to_float64`, `to_bfloat16` | One value to convert to the chosen approximate type. |
| `to_decimal256` | A value and a scale through 76, within the declared precision. |
| `to_interval_` | One integral quantity; for example, `to_interval_day(2)`. |
| `to_type_name` | One value whose native type descriptor is required. |
| `typeof` | One value whose SQL runtime value class is required. |
The exact input units and defaults depend on the target type. In particular, DateTime64 integer input means ticks, while Time64 integer input means seconds.
## Examples
### Checked integer conversion
```sql
SELECT CAST('255' AS UInt8), to_uint256('12345678901234567890')
FORMAT csv;
```
```text
255,12345678901234567890
```
`CAST('256' AS UInt8)` raises `NUMERIC_OVERFLOW`.
### Inspecting a decimal type
```sql
SELECT to_type_name(CAST('1.20' AS Decimal(18, 2)))
FORMAT csv;
```
```text
"Decimal(18,2)"
```
See [data types](https://coordinatordb.com/docs/reference/data-types) for target-specific conversion rules and [Interval](https://coordinatordb.com/docs/reference/data-types/special-data-types/interval) for supported units.
---
Source: https://coordinatordb.com/docs/reference/functions/regular-functions/uuid-functions
Language: en
# UUID functions
UUID functions generate identifiers and inspect their version or embedded timestamp. Generation returns a native UUID, which can be stored in a UUID column or used as a key.
Version 4 identifiers use random bits. Version 7 identifiers include a timestamp; extraction returns NULL for UUID versions or variants that do not carry a supported timestamp. The generated identifier itself is nondeterministic.
## Example: Checking generated UUID versions
```sql
SELECT uuid_extract_version(gen_random_uuid()), uuid_extract_version(uuidv7())
FORMAT csv;
```
```text
4,7
```
## gen_random_uuid
Generate an RFC 9562 random UUID version 4 from operating-system entropy.
### Syntax
```text
gen_random_uuid()
```
### Arguments
No arguments. Nondeterministic; independent of setseed.
### Returned value
Native UUID version 4; an unavailable entropy source raises IO_ERROR.
### Example
```sql
SELECT uuid_extract_version(gen_random_uuid()) FORMAT csv;
```
```text
4
```
## uuid_extract_timestamp
Extract the UTC timestamp carried by an RFC 9562 UUID version 1 or 7.
### Syntax
```text
uuid_extract_timestamp(uuid)
```
### Arguments
Native UUID or accepted UUID text. Version 1 drops submicrosecond digits; version 7 exposes its millisecond timestamp. Other versions/variants and SQL NULL return NULL.
### Returned value
Native UTC DateTime64(6), or NULL when no supported timestamp is present.
### Example
```sql
SELECT date_part('year',uuid_extract_timestamp('019535d9-3df7-79fb-b466-fa907fa17f9e')) FORMAT csv;
```
```text
2025.0
```
## uuid_extract_version
Extract the version nibble from an RFC 9562 variant UUID.
### Syntax
```text
uuid_extract_version(uuid)
```
### Arguments
Native UUID or accepted UUID text; SQL NULL propagates. Other UUID variants return NULL.
### Returned value
INTEGER version from zero through fifteen, or NULL for a non-RFC variant.
### Example
```sql
SELECT uuid_extract_version('41db1265-8bc1-4ab3-992f-885799a4af1d') FORMAT csv;
```
```text
4
```
## uuidv7
Generate an RFC 9562 time-ordered UUID version 7 with an ascending submillisecond fraction.
### Syntax
```text
uuidv7([shift])
```
### Arguments
Optional native/text interval or make_interval span shifts UTC time with calendar semantics. SQL NULL propagates. Timestamp must fit unsigned 48-bit Unix milliseconds; random bits use OS entropy.
### Returned value
Native UUID version 7. Unshifted calls ascend within one connection; shifted calls follow the supplied interval.
### Example
```sql
SELECT uuid_extract_version(uuidv7()) FORMAT csv;
```
```text
7
```
---
Source: https://coordinatordb.com/docs/reference/functions/table-functions
Language: en
# Table functions
A table function appears in FROM and supplies rows with a documented schema. It can be filtered, joined or aggregated like another query source.
## Sources
| Source | Use |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`generate_series`](https://coordinatordb.com/docs/reference/functions/table-functions/generate-series) | Generate inclusive numeric or calendar values. |
| [`file`](https://coordinatordb.com/docs/reference/functions/table-functions/file) | Read a confined server-side file with an input format. |
| `unnest`, `generate_subscripts` | Expand arrays or enumerate their positions. |
| `string_to_table`, `regexp_split_to_table` | Split text into rows. |
| `regexp_matches` | Return regular-expression matches as rows. |
| `json_each`, `json_tree` and JSON/JSONB expanders | Read JSON members, paths or typed records as rows. |
The [array](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions), [JSON](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions), [splitting](https://coordinatordb.com/docs/reference/functions/regular-functions/splitting-merging-functions) and [search](https://coordinatordb.com/docs/reference/functions/regular-functions/string-search-functions) references specify their arguments and output columns. Typed JSON record sources can require an `AS alias(column Type, ...)` schema.
## Example
### Aggregating generated rows
```sql
SELECT count(*) AS rows, sum(generate_series) AS total
FROM generate_series(1, 5)
FORMAT csv;
```
```text
5,15
```
Use the documented FROM form. A function returning rows is not interchangeable with a scalar function returning an Array or JSON value.
---
Source: https://coordinatordb.com/docs/reference/functions/table-functions/file
Language: en
# file
Reads a regular file under the server's configured `user_files_path` and exposes its decoded rows in FROM. It is a server-side source; the native client's `FROM INFILE` instead reads files on the client machine.
## Syntax
```text
file('path', format_name, 'column Type, ...')
file('path', form)
file('path', parquet_metadata)
```
## Arguments
* `path` — A relative path below `user_files_path`.
* `format_name` — A registered input format, using its snake_case name.
* `column Type, ...` — The explicit schema used to decode the rows.
All input formats require a schema except `form`, which infers String fields, and `parquet_metadata`, which supplies a fixed footer schema. Formats used here must support input.
## Path rules
Absolute paths, parent traversal, symlinks escaping the configured root and nonregular files are rejected. A symlink that resolves to a confined regular file is permitted. Confined server file access currently requires Unix.
Compression, archives, path patterns and writing files are not supported. These rules are separate from client-side INFILE options.
## Example
### Reading a CSV file
Create `people.csv` under the configured `user_files_path` with these contents:
```text
1,Ada
2,Grace
```
The schema converts the first field to UInt64 and the second to String:
```sql
SELECT id, name
FROM file('people.csv', csv, 'id UInt64, name String')
ORDER BY id
FORMAT csv;
```
```text
1,"Ada"
2,"Grace"
```
The resulting source can be filtered, joined or used in `INSERT ... SELECT` like other table sources. See the [file loading guide](https://coordinatordb.com/docs/guides/clickhouse/data-formats/intro) and [format reference](https://coordinatordb.com/docs/reference/formats).
---
Source: https://coordinatordb.com/docs/reference/functions/table-functions/generate-series
Language: en
# generate_series
Generates an inclusive series of values. Use it in FROM to produce a one-column table named `generate_series`.
## Syntax
```text
FROM generate_series(start, stop [, step [, timezone]])
```
## Arguments
* `start` — The first numeric or calendar value.
* `stop` — The inclusive bound; it is returned when the chosen step reaches it exactly.
* `step` — The increment. Numeric series default to 1. Timestamp bounds require an explicit native interval or quantity-and-unit step. Zero raises an error.
* `timezone` — An optional timezone for supported calendar series.
A NULL input or a step pointing away from the stop produces no rows. `generate_series` is a table function and cannot be called as an ordinary scalar expression.
## Returned columns
One column, `generate_series`, containing one generated value per row in series order.
## Examples
### Inclusive ascending series
```sql
SELECT generate_series AS number
FROM generate_series(1, 3)
FORMAT csv;
```
```text
1
2
3
```
### Descending with an explicit step
```sql
SELECT generate_series AS number
FROM generate_series(5, 1, -2)
FORMAT csv;
```
```text
5
3
1
```
### A direction that cannot reach the bound
```sql
SELECT count(*)
FROM generate_series(1, 5, -1)
FORMAT csv;
```
```text
0
```
See the [date and time functions](https://coordinatordb.com/docs/reference/functions/regular-functions/date-time-functions) for calendar values and [utility functions](https://coordinatordb.com/docs/reference/functions/regular-functions/other-functions#generate_series) for the full series input contract.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions
Language: en
# Window functions
Window functions calculate a value for every selected row using related rows from the same partition. Unlike a `GROUP BY` aggregate, a window calculation retains the individual input rows.
Use window functions for running totals, moving averages, rankings and comparisons with a preceding or following observation.
## Syntax
```text
function(arguments) OVER (
[PARTITION BY expression, ...]
[ORDER BY expression [ASC | DESC], ...]
[ROWS | RANGE | GROUPS frame_bounds [EXCLUDE exclusion]]
)
```
A named `WINDOW` definition can be reused by several expressions:
```sql
CREATE TABLE sales (region TEXT, day INTEGER, amount INTEGER);
INSERT INTO sales VALUES ('East', 1, 10), ('East', 2, 20), ('West', 1, 50);
```
```sql
SELECT region, day, amount,
sum(amount) OVER daily AS running_total,
row_number() OVER daily AS position
FROM sales
WINDOW daily AS (PARTITION BY region ORDER BY day)
ORDER BY region, day
FORMAT csv;
```
```text
"East",1,10,10,1
"East",2,20,30,2
"West",1,50,50,1
```
## Partitions and ordering
`PARTITION BY` groups rows for independent calculations. Without it, all selected rows belong to one partition.
The `ORDER BY` inside `OVER` determines positions for the calculation. It does not sort the final query result; use an outer `ORDER BY` for that. Rows equal on every window ordering expression are called **peers**. Ranking functions use peer groups to handle ties.
## Window frames
A frame selects a subset of a partition around the current row. Aggregate windows and `first_value`, `last_value` and `nth_value` read the frame. Ranking functions and `lag`/`lead` use the partition regardless of frame bounds.
With an ordering clause and no explicit frame, the frame runs from the beginning of the partition through the current peer group. Without ordering, the default frame covers the whole partition.
| Unit | Meaning of an offset |
| -------- | --------------------------------------------------------------------------------------------- |
| `ROWS` | A number of physical rows before or after the current row. |
| `GROUPS` | A number of peer groups before or after the current peer group. |
| `RANGE` | A distance from the current ordering value; an offset frame requires one ordering expression. |
Bounds can use `UNBOUNDED PRECEDING`, `offset PRECEDING`, `CURRENT ROW`, `offset FOLLOWING` and `UNBOUNDED FOLLOWING`, subject to their valid start/end ordering. `ROWS` and `GROUPS` offsets must be nonnegative whole numbers; `RANGE` offsets must be nonnegative numeric values.
### Moving totals
An explicit `ROWS` frame includes the current sale and at most one preceding sale:
```sql
CREATE TABLE sales_2 (day INTEGER, amount INTEGER);
INSERT INTO sales_2 VALUES (1, 10), (2, 20), (3, 30);
```
```sql
SELECT day, amount,
sum(amount) OVER (
ORDER BY day
ROWS BETWEEN 1 PRECEDING AND CURRENT ROW
) AS moving_total
FROM sales_2
ORDER BY day
FORMAT csv;
```
```text
1,10,10
2,20,30
3,30,50
```
### Frame exclusions
`EXCLUDE NO OTHERS` keeps every selected frame row. `EXCLUDE CURRENT ROW` removes the current row. `EXCLUDE GROUP` removes its whole peer group. `EXCLUDE TIES` removes other peers while retaining the current row.
## Aggregate windows
Ordinary aggregates such as `sum`, `count` and `avg` can be followed by `OVER`. Their local input and `NULL` rules still apply. Aggregate `DISTINCT` is not supported in windows. Ordered-set percentiles explicitly exclude `OVER`; consult the [aggregate reference](https://coordinatordb.com/docs/reference/functions/aggregate-functions) for restrictions on individual functions.
## Function reference
* [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number)
* [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank)
* [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank)
* [`percent_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/percent-rank)
* [`cume_dist`](https://coordinatordb.com/docs/reference/functions/window-functions/cume-dist)
* [`ntile`](https://coordinatordb.com/docs/reference/functions/window-functions/ntile)
* [`lag`](https://coordinatordb.com/docs/reference/functions/window-functions/lag)
* [`lead`](https://coordinatordb.com/docs/reference/functions/window-functions/lead)
* [`first_value`](https://coordinatordb.com/docs/reference/functions/window-functions/first-value)
* [`last_value`](https://coordinatordb.com/docs/reference/functions/window-functions/last-value)
* [`nth_value`](https://coordinatordb.com/docs/reference/functions/window-functions/nth-value)
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/cume-dist
Language: en
# cume_dist
The result is the number of rows preceding or tied with the current row, divided by the total number of partition rows. Peers share the fraction at the end of their peer group.
**Syntax**
```text
cume_dist() OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
The function takes no arguments. `PARTITION BY` starts an independent ranking for each group; without it, all selected rows form one partition. `ORDER BY` inside `OVER` determines the ranking order. A frame clause does not restrict the rows used for ranking.
**Returned value**
A `REAL` fraction greater than 0 and no greater than 1. The window order does not determine the final output order; use an outer `ORDER BY` to sort the result.
**Example**
**Ranking employee salaries**
Ada and Grace have the same salary and therefore belong to the same peer group.
```sql
CREATE TABLE salaries (player TEXT, salary INTEGER);
INSERT INTO salaries VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT player, salary,
cume_dist() OVER (ORDER BY salary DESC) AS result
FROM salaries
ORDER BY salary DESC, player
FORMAT csv;
```
```text
"Ada",100,0.5
"Grace",100,0.5
"Linus",80,0.75
"Sam",60,1.0
```
See [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank), [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank) and [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number) to compare tie handling, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partition and frame syntax.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank
Language: en
# dense_rank
Rows with equal ordering values receive the same rank. Each next distinct ordering value increases the rank by one, regardless of how many rows share the preceding rank.
**Syntax**
```text
dense_rank() OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
The function takes no arguments. `PARTITION BY` starts an independent ranking for each group; without it, all selected rows form one partition. `ORDER BY` inside `OVER` determines the ranking order. A frame clause does not restrict the rows used for ranking.
**Returned value**
An `INTEGER` greater than or equal to 1. The window order does not determine the final output order; use an outer `ORDER BY` to sort the result.
**Example**
**Ranking employee salaries**
Ada and Grace have the same salary and therefore belong to the same peer group.
```sql
CREATE TABLE salaries (player TEXT, salary INTEGER);
INSERT INTO salaries VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT player, salary,
dense_rank() OVER (ORDER BY salary DESC) AS result
FROM salaries
ORDER BY salary DESC, player
FORMAT csv;
```
```text
"Ada",100,1
"Grace",100,1
"Linus",80,2
"Sam",60,3
```
See [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank), [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank) and [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number) to compare tie handling, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partition and frame syntax.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/first-value
Language: en
# first_value
Returns the first value in the current ordered window frame. The function selects a row position; it retains a `NULL` at that position.
Frame bounds determine which rows can be selected. Use an explicit frame when the result should cover a fixed preceding range or the whole partition.
**Syntax**
```text
first_value(value) OVER (
[PARTITION BY expression, ...]
ORDER BY expression, ...
[ROWS | RANGE | GROUPS frame_bounds]
)
```
**Arguments**
* `value` — The expression evaluated at the selected row.
**Returned value**
The selected input value, preserving its native type. An empty frame returns `NULL`. Frame exclusions apply before selecting the position.
**Examples**
**Reading from a growing frame**
The frame starts at the first sale and ends at the current row:
```sql
CREATE TABLE sales (day INTEGER, amount INTEGER);
INSERT INTO sales VALUES (1, 120), (2, 150), (3, 90);
```
```sql
SELECT day, amount,
first_value(amount) OVER (
ORDER BY day
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
) AS selected_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120,120
2,150,120
3,90,120
```
**Preserving NULL at the selected position**
```sql
CREATE TABLE readings (day INTEGER, value INTEGER);
INSERT INTO readings VALUES (1, NULL), (2, 20);
```
```sql
SELECT day, first_value(value) OVER (ORDER BY day)
FROM readings
ORDER BY day
FORMAT csv;
```
```text
1,\N
2,\N
```
See [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for supported frame units and exclusions.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/lag
Language: en
# lag
Returns the value from a row at a specified offset before the current row in its ordered partition.
`lag` uses the whole partition, regardless of a `ROWS`, `RANGE` or `GROUPS` frame. To look in the opposite direction, use [`lead`](https://coordinatordb.com/docs/reference/functions/window-functions/lead).
**Syntax**
```text
lag(value [, offset [, default]])
OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
* `value` — The expression evaluated at the target row.
* `offset` — The number of rows to move before the current row. Defaults to `1`. It is converted to an integer once for the query; a negative converted offset raises a SQL error. An offset of `0` selects the current row.
* `default` — The value returned when the target is outside the partition. Defaults to `NULL`. A supplied expression is evaluated against the current row.
**Returned value**
The target row's value, preserving its native type, or the fallback when no target row exists. A `NULL` at an existing target is returned as `NULL`; it does not select the fallback.
**Examples**
**Comparing daily sales**
```sql
CREATE TABLE sales (day INTEGER, amount INTEGER);
INSERT INTO sales VALUES (1, 120), (2, 150), (3, 90);
```
```sql
SELECT day, amount,
lag(amount) OVER (ORDER BY day) AS adjacent_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120,\N
2,150,120
3,90,150
```
**Providing a fallback**
Use the current amount when there is no adjacent row:
```sql
SELECT day,
lag(amount, 1, amount) OVER (ORDER BY day) AS adjacent_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120
2,120
3,150
```
See [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partitioning, named windows and output ordering.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/last-value
Language: en
# last_value
Returns the last value in the current ordered window frame. The function selects a row position; it retains a `NULL` at that position.
The default ordered frame ends at the current peer group. Use `ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING` to read the last value of the whole partition.
**Syntax**
```text
last_value(value) OVER (
[PARTITION BY expression, ...]
ORDER BY expression, ...
[ROWS | RANGE | GROUPS frame_bounds]
)
```
**Arguments**
* `value` — The expression evaluated at the selected row.
**Returned value**
The selected input value, preserving its native type. An empty frame returns `NULL`. Frame exclusions apply before selecting the position.
**Examples**
**Reading from a growing frame**
The frame starts at the first sale and ends at the current row:
```sql
CREATE TABLE sales (day INTEGER, amount INTEGER);
INSERT INTO sales VALUES (1, 120), (2, 150), (3, 90);
```
```sql
SELECT day, amount,
last_value(amount) OVER (
ORDER BY day
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
) AS selected_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120,120
2,150,150
3,90,90
```
**Reading the last value of the whole partition**
```sql
SELECT day,
last_value(amount) OVER (
ORDER BY day
ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
) AS final_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,90
2,90
3,90
```
See [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for supported frame units and exclusions.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/lead
Language: en
# lead
Returns the value from a row at a specified offset after the current row in its ordered partition.
`lead` uses the whole partition, regardless of a `ROWS`, `RANGE` or `GROUPS` frame. To look in the opposite direction, use [`lag`](https://coordinatordb.com/docs/reference/functions/window-functions/lag).
**Syntax**
```text
lead(value [, offset [, default]])
OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
* `value` — The expression evaluated at the target row.
* `offset` — The number of rows to move after the current row. Defaults to `1`. It is converted to an integer once for the query; a negative converted offset raises a SQL error. An offset of `0` selects the current row.
* `default` — The value returned when the target is outside the partition. Defaults to `NULL`. A supplied expression is evaluated against the current row.
**Returned value**
The target row's value, preserving its native type, or the fallback when no target row exists. A `NULL` at an existing target is returned as `NULL`; it does not select the fallback.
**Examples**
**Comparing daily sales**
```sql
CREATE TABLE sales (day INTEGER, amount INTEGER);
INSERT INTO sales VALUES (1, 120), (2, 150), (3, 90);
```
```sql
SELECT day, amount,
lead(amount) OVER (ORDER BY day) AS adjacent_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120,150
2,150,90
3,90,\N
```
**Providing a fallback**
Use the current amount when there is no adjacent row:
```sql
SELECT day,
lead(amount, 1, amount) OVER (ORDER BY day) AS adjacent_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,150
2,90
3,90
```
See [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partitioning, named windows and output ordering.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/nth-value
Language: en
# nth_value
Returns the nth value in the current ordered window frame. The function selects a row position; it retains a `NULL` at that position.
Frame bounds determine which rows can be selected. Use an explicit frame when the result should cover a fixed preceding range or the whole partition.
**Syntax**
```text
nth_value(value, n) OVER (
[PARTITION BY expression, ...]
ORDER BY expression, ...
[ROWS | RANGE | GROUPS frame_bounds]
)
```
**Arguments**
* `value` — The expression evaluated at the selected row.
* `n` — The one-based position within the frame. It is evaluated once and converted to an integer; a converted position below 1 raises a SQL error.
**Returned value**
The selected input value, preserving its native type. An empty frame or a frame with fewer than `n` rows returns `NULL`. Frame exclusions apply before selecting the position.
**Examples**
**Reading from a growing frame**
The frame starts at the first sale and ends at the current row:
```sql
CREATE TABLE sales (day INTEGER, amount INTEGER);
INSERT INTO sales VALUES (1, 120), (2, 150), (3, 90);
```
```sql
SELECT day, amount,
nth_value(amount, 2) OVER (
ORDER BY day
ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
) AS selected_amount
FROM sales
ORDER BY day
FORMAT csv;
```
```text
1,120,\N
2,150,150
3,90,150
```
See [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for supported frame units and exclusions.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/ntile
Language: en
# ntile
Divides an ordered partition into a requested number of buckets and returns the bucket containing each row. Bucket numbers start at 1.
Bucket sizes differ by at most one row. When the rows cannot be divided evenly, the first buckets receive an extra row. Tied ordering values can fall in different buckets.
**Syntax**
```text
ntile(buckets) OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
* `buckets` — The requested bucket count. It is evaluated once and converted to an integer. A converted count less than 1 raises a SQL error.
**Returned value**
An `INTEGER` bucket number. Each partition is divided independently. If the bucket count exceeds the row count, each occupied bucket contains one row and the remaining buckets are empty. A frame clause does not change the allocation.
**Example**
**Splitting accounts into two groups**
Five accounts are split into buckets of three and two rows:
```sql
CREATE TABLE accounts (name TEXT, revenue INTEGER);
INSERT INTO accounts VALUES ('Ada', 100), ('Grace', 90), ('Linus', 80), ('Sam', 70), ('Terry', 60);
```
```sql
SELECT name, revenue,
ntile(2) OVER (ORDER BY revenue DESC, name) AS bucket
FROM accounts
ORDER BY revenue DESC, name
FORMAT csv;
```
```text
"Ada",100,1
"Grace",90,1
"Linus",80,1
"Sam",70,2
"Terry",60,2
```
See [`percent_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/percent-rank) for relative ranks and [`cume_dist`](https://coordinatordb.com/docs/reference/functions/window-functions/cume-dist) for cumulative fractions that keep peers together.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/percent-rank
Language: en
# percent_rank
The relative rank is `(rank - 1) / (partition_size - 1)`. Peers share the same result. A partition containing one row returns `0.0`.
**Syntax**
```text
percent_rank() OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
The function takes no arguments. `PARTITION BY` starts an independent ranking for each group; without it, all selected rows form one partition. `ORDER BY` inside `OVER` determines the ranking order. A frame clause does not restrict the rows used for ranking.
**Returned value**
A `REAL` fraction from 0 through 1. The window order does not determine the final output order; use an outer `ORDER BY` to sort the result.
**Example**
**Ranking employee salaries**
Ada and Grace have the same salary and therefore belong to the same peer group.
```sql
CREATE TABLE salaries (player TEXT, salary INTEGER);
INSERT INTO salaries VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT player, salary,
round(percent_rank() OVER (ORDER BY salary DESC), 6) AS result
FROM salaries
ORDER BY salary DESC, player
FORMAT csv;
```
```text
"Ada",100,0.0
"Grace",100,0.0
"Linus",80,0.666667
"Sam",60,1.0
```
See [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank), [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank) and [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number) to compare tie handling, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partition and frame syntax.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/rank
Language: en
# rank
Rows with equal ordering values receive the same rank. The next distinct value receives the position it would have in the full sorted partition, so ties leave gaps.
**Syntax**
```text
rank() OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
The function takes no arguments. `PARTITION BY` starts an independent ranking for each group; without it, all selected rows form one partition. `ORDER BY` inside `OVER` determines the ranking order. A frame clause does not restrict the rows used for ranking.
**Returned value**
An `INTEGER` greater than or equal to 1. The window order does not determine the final output order; use an outer `ORDER BY` to sort the result.
**Example**
**Ranking employee salaries**
Ada and Grace have the same salary and therefore belong to the same peer group.
```sql
CREATE TABLE salaries (player TEXT, salary INTEGER);
INSERT INTO salaries VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT player, salary,
rank() OVER (ORDER BY salary DESC) AS result
FROM salaries
ORDER BY salary DESC, player
FORMAT csv;
```
```text
"Ada",100,1
"Grace",100,1
"Linus",80,3
"Sam",60,4
```
See [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank), [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank) and [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number) to compare tie handling, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partition and frame syntax.
---
Source: https://coordinatordb.com/docs/reference/functions/window-functions/row-number
Language: en
# row_number
Every row receives a different number, including rows with equal ordering values. Add a unique tie-breaking column to the window ORDER BY when the assignment must be repeatable.
**Syntax**
```text
row_number() OVER ([PARTITION BY expression, ...] ORDER BY expression, ...)
```
**Arguments**
The function takes no arguments. `PARTITION BY` starts an independent ranking for each group; without it, all selected rows form one partition. `ORDER BY` inside `OVER` determines the ranking order. A frame clause does not restrict the rows used for ranking.
**Returned value**
An `INTEGER` greater than or equal to 1. The window order does not determine the final output order; use an outer `ORDER BY` to sort the result.
**Example**
**Ranking employee salaries**
`row_number` assigns different numbers to the tied salaries because `player` breaks the tie.
```sql
CREATE TABLE salaries (player TEXT, salary INTEGER);
INSERT INTO salaries VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT player, salary,
row_number() OVER (ORDER BY salary DESC, player) AS result
FROM salaries
ORDER BY salary DESC, player
FORMAT csv;
```
```text
"Ada",100,1
"Grace",100,2
"Linus",80,3
"Sam",60,4
```
See [`rank`](https://coordinatordb.com/docs/reference/functions/window-functions/rank), [`dense_rank`](https://coordinatordb.com/docs/reference/functions/window-functions/dense-rank) and [`row_number`](https://coordinatordb.com/docs/reference/functions/window-functions/row-number) to compare tie handling, and [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) for partition and frame syntax.
---
Source: https://coordinatordb.com/docs/reference/home
Language: en
# Reference
The reference defines CoordinatorDB's implemented public contracts. Use it for exact syntax, argument and value ranges, result layouts, setting scope and permanent error identifiers.
## Find a contract
::: cards
* [SQL Reference](https://coordinatordb.com/docs/reference/syntax)
* [Data Types](https://coordinatordb.com/docs/reference/data-types)
* [Functions](https://coordinatordb.com/docs/reference/functions)
* [Formats](https://coordinatordb.com/docs/reference/formats)
* [Settings](https://coordinatordb.com/docs/reference/settings)
* [System Tables](https://coordinatordb.com/docs/reference/system-tables/overview)
:::
See also [SQL statements](https://coordinatordb.com/docs/reference/statements), [operators](https://coordinatordb.com/docs/reference/operators) and [error codes](https://coordinatordb.com/docs/reference/errors).
## Reading examples
SQL examples with FORMAT use a server interface. The embedded Connection API returns typed rows directly. Format input consumes the remaining request as data, so run the later verification query as a separate request.
Examples create their own small fixtures. Use the stated schema and source-file prerequisites, and choose fresh sample table names when running several guides in one database.
---
Source: https://coordinatordb.com/docs/reference/operators
Language: en
# Operators
Operators combine values in expressions. Use parentheses when arithmetic, comparisons and search conditions should be grouped explicitly.
## Arithmetic and bits
| Operators | Meaning |
| ----------------------- | ------------------------------------------ |
| `+`, `-`, `*`, `/`, `%` | Numeric arithmetic, including unary signs. |
| `&`, `\|`, `~` | Bitwise AND, OR and inversion. |
| `<<`, `>>` | Integer shifts. |
| `\|\|` | Text concatenation. |
Ordinary integer division truncates toward zero. Ordinary numeric division and remainder by zero return NULL; Decimal operations raise INVALID_ARGUMENT instead. Native exact numeric overflow raises an error.
```sql
SELECT 7 / 2, 7 % 2, 6 & 3, 'ab' || 'cd'
FORMAT csv;
```
```text
3,1,2,"abcd"
```
## Comparisons and missing values
Comparisons include `=`, `==`, `!=`, `<>`, `<`, `<=`, `>` and `>=`. Ordinary comparisons with NULL generally return NULL.
IS and IS NOT provide NULL-safe comparisons. IS NOT DISTINCT FROM is the NULL-safe equality form; IS DISTINCT FROM is its inverse. Postfix ISNULL, NOTNULL and NOT NULL test nullness.
```sql
SELECT NULL = NULL,
NULL IS NULL,
NULL IS NOT DISTINCT FROM NULL,
1 IS DISTINCT FROM NULL
FORMAT csv;
```
```text
\N,1,1,1
```
## Logic and membership
AND, OR and NOT use SQL three-valued logic. BETWEEN includes both endpoints. IN tests membership in a list, subquery or table; EXISTS tests whether a subquery returns a row.
An empty right-hand side makes IN false and NOT IN true, including for a NULL left operand. Nonempty membership tests follow the documented NULL rules.
See [logical expressions](https://coordinatordb.com/docs/reference/functions/regular-functions/logical-functions) and [`IN`](https://coordinatordb.com/docs/reference/statements/in).
## Text and structured search
LIKE supports SQL wildcards and an optional ESCAPE character. GLOB uses shell-style matching. The full-text `@@` operator matches a tsvector against a tsquery.
JSON `->` returns JSON text and `->>` returns an SQL scalar. Native inet/cidr values also support documented subnet operators.
```sql
SELECT 'hello' LIKE 'he%',
json('{"a":2}') ->> 'a'
FORMAT csv;
```
```text
1,2
```
See [string search](https://coordinatordb.com/docs/reference/functions/regular-functions/string-search-functions), [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) and [network functions](https://coordinatordb.com/docs/reference/functions/regular-functions/ip-address-functions) for their specific operand contracts.
---
Source: https://coordinatordb.com/docs/reference/settings
Language: en
# Settings
Settings have server, database and statement scope. Choose the scope before the option name so the change has the intended lifetime.
| Scope | Interface | Effect |
| -------- | --------------------------------------- | --------------------------------------------------------- |
| Server | XML configuration | Startup listeners, credentials, diagnostics and ceilings. |
| Database | SET or documented PRAGMA/catalog writes | Persisted defaults and effective database behavior. |
| Format | Statement SETTINGS | Input/output options for one statement. |
Read system.settings for effective database values and read-only format defaults. Server-only XML options are documented separately and do not appear there.
## Reference
* [Format settings](https://coordinatordb.com/docs/reference/settings/formats)
* [Format avro](https://coordinatordb.com/docs/reference/settings/formats/format-avro)
* [Format binary](https://coordinatordb.com/docs/reference/settings/formats/format-binary)
* [Format csv](https://coordinatordb.com/docs/reference/settings/formats/format-csv)
* [Format custom](https://coordinatordb.com/docs/reference/settings/formats/format-custom)
* [Format regexp](https://coordinatordb.com/docs/reference/settings/formats/format-regexp)
* [Format schema](https://coordinatordb.com/docs/reference/settings/formats/format-schema)
* [Format template](https://coordinatordb.com/docs/reference/settings/formats/format-template)
* [Input format](https://coordinatordb.com/docs/reference/settings/formats/input-format)
* [Output format](https://coordinatordb.com/docs/reference/settings/formats/output-format)
* [Server settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings)
* [Database settings](https://coordinatordb.com/docs/reference/settings/session-settings)
* [log_queries, log_queries_min_query_duration_ms](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries)
* [max_execution_time](https://coordinatordb.com/docs/reference/settings/session-settings/max-execution)
* [max_memory_usage](https://coordinatordb.com/docs/reference/settings/session-settings/max-memory-usage)
* [max_result_rows, max_response_bytes](https://coordinatordb.com/docs/reference/settings/session-settings/max-result)
* [max_threads](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads)
* [foreign_keys, recursive_triggers, user_version, application_id](https://coordinatordb.com/docs/reference/settings/session-settings/other)
---
Source: https://coordinatordb.com/docs/reference/settings/formats
Language: en
# Format settings
Format settings control how bytes are read or written for one statement. They are separate from persisted database resource settings and server XML options.
## Syntax and scope
Use `SETTINGS name = value, ...` on one statement. A Boolean name without a value enables it. Options use the defaults again on the next statement; SET rejects format options. Names ignore ASCII case. Unknown names and invalid values are rejected before execution.
On INSERT, put SETTINGS before FORMAT because all bytes after an input format name are data. For SELECT it can appear before or after the FORMAT clause.
```sql
SELECT 7 AS id,'Ada' AS name SETTINGS csv_separator=';' FORMAT csv;
```
```text
7;"Ada"
```
## Applicable formats
Each option affects a specific set of codecs. A valid option for another codec can be accepted without changing the selected format. Use its family page or the selected format's settings table to choose applicable options. In particular, json_each_row does not apply the numeric JSON quoting options.
## Available options
| Setting | Type | Default | Meaning |
| -------------------------------------------- | -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `arrow_compression` | `String` | `lz4_frame` | Compress record batch buffers with lz4_frame or zstd; none writes uncompressed buffers. |
| `arrow_date_as_number` | `Bool` | `0` | Write Date as UInt16 days since the epoch instead of Date32; Date32 always remains Date32. |
| `arrow_dictionary` | `Bool` | `0` | Write LowCardinality as dictionary indices and values instead of expanding its scalars. |
| `arrow_dictionary_64bit_indices` | `Bool` | `0` | Use 64-bit dictionary indices instead of the smallest width that fits the dictionary. |
| `arrow_dictionary_signed_indices` | `Bool` | `1` | Use signed dictionary indices; when off, use unsigned indices. |
| `arrow_fixed_strings` | `Bool` | `1` | Write FixedString with a fixed byte width instead of variable-length Binary. |
| `arrow_ignore_case` | `Bool` | `0` | Ignore ASCII case when matching input field names to target columns. |
| `arrow_missing_as_default` | `Bool` | `1` | Give target columns absent from the input schema their DEFAULT; when off, reject missing columns. |
| `arrow_strings_as_text` | `Bool` | `1` | Write text strings as Utf8 instead of Binary; byte strings keep their exact bytes. |
| `avro_block_bytes` | `UInt64` | `16384` | Target uncompressed bytes per output block, from 32 through 1073741824; a complete row may exceed the target. |
| `avro_compression` | `String` | `''` | Output block compression: null, deflate, snappy, or zstd; empty selects snappy. |
| `avro_confluent_connect_timeout` | `UInt64` | `1` | Connection and TLS handshake timeout in seconds; positive values are capped at 599. |
| `avro_confluent_receive_timeout` | `UInt64` | `1` | Registry response receive timeout in seconds; positive values are capped at 599. |
| `avro_confluent_registry_url` | `String` | `''` | HTTP or HTTPS schema registry base URL; URL-encoded credentials select Basic authentication. |
| `avro_confluent_retries` | `UInt64` | `5` | Retry transient registry failures this many times; zero disables retries and values above 20 are capped at 20. |
| `avro_confluent_retry_delay_ms` | `UInt64` | `100` | Initial retry delay in milliseconds, capped at 60000; subsequent delays double up to 10000 milliseconds. |
| `avro_confluent_send_timeout` | `UInt64` | `1` | Registry request send timeout in seconds; positive values are capped at 599. |
| `avro_confluent_subject` | `String` | `''` | Subject under which an output record schema is registered; required for avro_confluent output. |
| `avro_missing_as_default` | `Bool` | `0` | Give target fields absent from the input schema their SQL DEFAULT or native type default; otherwise reject them. |
| `avro_null_as_default` | `Bool` | `0` | Replace input NULL in a non-nullable native target with its SQL DEFAULT or native type default; legacy SQL columns retain NULL. |
| `avro_string_columns` | `String` | `''` | Regular expression matching output String column paths to encode as UTF-8 string instead of bytes; empty matches none. |
| `bson_strings` | `Bool` | `0` | Write text and fixed-width strings as BSON String instead of Binary. |
| `csv_check_types` | `Bool` | `1` | Compare the input types header with the bound target column types; when off, skip that header. |
| `csv_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `csv_double_quotes` | `Bool` | `1` | Read a field that starts with a double quote as quoted text; when off, the quote is an ordinary character. |
| `csv_empty_as_default` | `Bool` | `1` | Give an empty unquoted field the column's DEFAULT; when off, read it as empty text. |
| `csv_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `csv_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `csv_null_text` | `String` | `\N` | The unquoted text that stands for NULL when reading and writing; it must stay one untrimmed field under the current CSV settings. |
| `csv_separator` | `Char` | `,` | The character between fields when reading and writing: one ASCII character that is not a letter, digit, quote, backslash, or line break. Write a tab as \t. |
| `csv_single_quotes` | `Bool` | `0` | Also read a field that starts with a single quote as quoted text. |
| `csv_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `csv_trim_blanks` | `Bool` | `1` | Drop spaces and tabs around a field when reading; quotes keep the blanks inside them. |
| `csv_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
| `custom_separated_detect_header` | `Bool` | `1` | Recognize an input names header and an optional matching types header. |
| `custom_separated_escaping` | `String` | `Escaped` | Field grammar: Escaped, Quoted, CSV, JSON, XML (output only), or Raw. |
| `custom_separated_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `custom_separated_result_prefix` | `String` | `''` | Text before the entire input or output result. |
| `custom_separated_result_suffix` | `String` | `''` | Text after the entire input or output result. |
| `custom_separated_row_prefix` | `String` | `''` | Text before the first field of each input or output row. |
| `custom_separated_row_separator` | `String` | `''` | Text between input or output rows, excluding their own prefixes and suffixes. |
| `custom_separated_row_suffix` | `String` | `\n` | Text after the last field of each input or output row. |
| `custom_separated_separator` | `String` | `\t` | Text between input or output fields; may contain multiple bytes. |
| `custom_separated_skip_empty_lines` | `Bool` | `0` | Skip trailing CR and LF bytes after the result; one final LF is always accepted. |
| `custom_separated_uneven_rows` | `Bool` | `0` | Give omitted input fields their SQL or native defaults and validate then skip extra fields. |
| `geo_json_unsupported_geometry` | `String` | `throw` | Reject unsupported geometry types on input; null validates them and stores NULL when geometry is requested. |
| `geo_json_validate_geometry` | `Bool` | `1` | Validate line lengths, ring lengths and closure, and nonempty geometry containers on input and output; coordinates must always be finite. |
| `hive_text_collection_separator` | `Char` | `\x02` | The byte between outermost Array and Tuple elements or Map entries on output; input uses bracketed values. |
| `hive_text_map_separator` | `Char` | `\x03` | The byte between outermost Map keys and values, also used at the next nested level on output. |
| `hive_text_row_separator` | `Char` | `\n` | The byte ending each output row; input always reads newline-delimited CSV records. |
| `hive_text_separator` | `Char` | `\x01` | The byte between top-level fields when reading and writing, with no output quoting or escaping. |
| `hive_text_uneven_rows` | `Bool` | `1` | Give omitted trailing input columns their DEFAULT and skip extra fields; off requires the exact field count. |
| `ignore_unknown_fields` | `Bool` | `0` | Skip input keys and header names that match no target column instead of failing. |
| `json_array_of_rows` | `Bool` | `0` | Wrap all output rows in one JSON array. |
| `json_arrays_as_strings` | `Bool` | `1` | Accept JSON arrays in string input columns and retain their JSON text. |
| `json_bools_as_numbers` | `Bool` | `1` | Accept JSON Boolean input in numeric columns as zero or one. |
| `json_bools_as_strings` | `Bool` | `1` | Accept JSON Boolean input in string columns as true or false text. |
| `json_check_types` | `Bool` | `1` | Compare input metadata or header types with the bound target column types. |
| `json_columns_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted input columns; off supplies only their native type defaults. |
| `json_compact_columns_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted trailing input columns; off supplies only their native type defaults. |
| `json_compact_strings_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for missing or defaulted positional whole-text JSON fields; off supplies their native type defaults. |
| `json_compact_uneven_rows` | `Bool` | `0` | Give missing positional fields their SQL or native defaults and validate then skip extra fields. |
| `json_empty_as_default` | `Bool` | `0` | Give empty JSON string fields their SQL or native type default. |
| `json_escape_slashes` | `Bool` | `1` | Escape unescaped forward slashes in JSON output strings. |
| `json_match_names` | `Bool` | `1` | Match input header names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `json_named_tuples_as_objects` | `Bool` | `1` | Read and write named Tuple values as objects; otherwise use positional arrays. |
| `json_numbers_as_strings` | `Bool` | `1` | Accept JSON numbers in string input columns and retain their exact spelling. |
| `json_object_each_row_name_column` | `String` | `''` | Use this string column for outer row keys and omit it from row objects; empty generates row_1, row_2, and so on. |
| `json_object_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted or defaulted row fields; off supplies only their native type defaults. |
| `json_objects_as_strings` | `Bool` | `1` | Accept JSON objects in string input columns and retain their JSON text. |
| `json_quote_decimals` | `Bool` | `0` | Write fixed-point decimal output values as JSON strings. |
| `json_quote_large_floats` | `Bool` | `0` | Write finite Float64 output values as JSON strings. |
| `json_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as JSON strings; retained narrow types stay numeric. |
| `json_quote_special_floats` | `Bool` | `0` | Write non-finite floats as inf, -inf, nan, or -nan strings instead of JSON null. |
| `json_strict_escapes` | `Bool` | `1` | Reject invalid JSON escapes; otherwise preserve their literal backslash spelling. |
| `json_strings_each_row_sql_defaults` | `Bool` | `1` | Evaluate SQL DEFAULT expressions for omitted or defaulted whole-text JSON fields; off supplies their native type defaults. |
| `json_tuple_ignore_unknown_fields` | `Bool` | `0` | Validate then ignore object members outside a named Tuple declaration. |
| `json_tuple_missing_as_default` | `Bool` | `1` | Give missing named Tuple members their declared type defaults. |
| `json_validate_utf8` | `Bool` | `0` | Replace invalid UTF-8 sequences in whole-text JSON output with replacement characters; off preserves byte-string payloads. |
| `markdown_escape_special_characters` | `Bool` | `0` | Escape ASCII punctuation in text and byte-string values with a backslash; when off, escape controls, backslashes, and single quotes. |
| `msg_pack_uuid_encoding` | `String` | `EXT` | Write UUID as EXT (extension type 2), BIN (16 binary bytes), or STR (canonical text). |
| `parquet_compression` | `String` | `zstd` | Compress column pages with snappy, lz4, brotli, zstd, gzip, or none. |
| `parquet_detect_variant` | `Bool` | `1` | Recognize unannotated metadata/value binary structs as Variant values. |
| `parquet_fixed_strings` | `Bool` | `1` | Write FixedString as fixed-width bytes instead of variable-width Binary. |
| `parquet_ignore_case` | `Bool` | `0` | Ignore ASCII case when matching input fields to target column names. |
| `parquet_missing_as_default` | `Bool` | `1` | Give missing input fields their SQL DEFAULT or native type default. |
| `parquet_page_bytes` | `UInt64` | `1048576` | Target uncompressed bytes per output data page. |
| `parquet_page_index` | `Bool` | `1` | Write column and offset indexes for individual data pages. |
| `parquet_parse_json` | `Bool` | `1` | Decode JSON-annotated input fields as native JSON instead of text. |
| `parquet_read_bytes` | `UInt64` | `16744704` | Target decoded batch bytes estimated from uncompressed row-group metadata. |
| `parquet_read_geo` | `Bool` | `1` | Decode WKB or WKT columns identified by GeoParquet metadata; text and binary targets retain raw payloads. |
| `parquet_read_rows` | `UInt64` | `65409` | Maximum rows per decoded input batch. |
| `parquet_row_group_bytes` | `UInt64` | `536870912` | Target output row-group bytes before compression. |
| `parquet_row_group_rows` | `UInt64` | `1000000` | Maximum rows per output row group. |
| `parquet_strings_as_text` | `Bool` | `1` | Annotate text strings as UTF-8; BLOB keeps its exact binary representation. |
| `parquet_wide_as_decimal` | `Bool` | `0` | Write 128/256-bit integers as big-endian DECIMAL instead of little-endian fixed-width bytes. |
| `parquet_write_batch_rows` | `UInt64` | `1024` | Check output data-page size after this many rows. |
| `parquet_write_geo` | `Bool` | `1` | Encode geometry as WKB and include GeoParquet column metadata. |
| `png_height` | `UInt64` | `1024` | Height of the image in pixels, from 1 through 2147483647. |
| `png_time_denominator` | `UInt64` | `60` | Positive denominator of the duration in seconds of one integer t unit. |
| `png_time_numerator` | `UInt64` | `1` | Positive numerator of the duration in seconds of one integer t unit. |
| `png_width` | `UInt64` | `1024` | Width of the image in pixels, from 1 through 2147483647. |
| `pretty_borders` | `String` | `unicode` | The characters that draw the table: unicode for box-drawing lines, ascii for plus, minus, and bar. |
| `pretty_footer_from_rows` | `UInt64` | `0` | Repeat the column names in the bottom border when the table shows at least this many rows; 0 never repeats them. |
| `pretty_max_cell_width` | `UInt64` | `0` | Cut a value wider than this many terminal columns and mark the cut; 0 never cuts. |
| `pretty_max_padding` | `UInt64` | `0` | Align a column to at most this many terminal columns; wider values extend their own row. 0 aligns to the widest value. |
| `pretty_max_rows` | `UInt64` | `0` | Show at most this many rows and report how many were left out; 0 shows every row. |
| `pretty_row_numbers` | `Bool` | `0` | Add a first column that numbers the rows from 1. |
| `protobuf_auto_schema` | `Bool` | `1` | Derive a message schema from columns when protobuf_schema is empty. |
| `protobuf_keep_default_wrappers` | `Bool` | `0` | Write present Google wrappers for default scalar values; NULL wrappers remain absent. |
| `protobuf_message` | `String` | `''` | Fully qualified message name in protobuf_schema; empty selects Row for an automatically derived schema. |
| `protobuf_missing_as_default` | `Bool` | `1` | Apply SQL DEFAULT to target columns outside the message schema; when off use their native type defaults. |
| `protobuf_oneof_tag` | `Bool` | `0` | Read the selected oneof field number into a column named after that oneof; unmatched branches yield zero. |
| `protobuf_schema` | `String` | `''` | Literal proto2 or proto3 schema; imports are limited to bundled Google definitions. |
| `protobuf_unwrap_google` | `Bool` | `0` | Read Google scalar wrappers directly into scalar columns; absent nullable wrappers become NULL. |
| `regexp_escaping` | `String` | `Raw` | Read captured fields as Raw text, Escaped text, Quoted literals, CSV fields, or JSON values. |
| `regexp_pattern` | `String` | `''` | Match every complete input line; one capture group supplies each target column. Empty requires a statement override. |
| `regexp_skip_unmatched` | `Bool` | `0` | Skip lines that do not match the expression; otherwise report their physical line number. |
| `row_binary_check_types` | `Bool` | `1` | Compare input header types with target types; when off decode matched fields with target widths. |
| `row_binary_match_names` | `Bool` | `1` | Match input header names ignoring ASCII case; when off read in target column order. |
| `row_binary_max_string_bytes` | `UInt64` | `1073741824` | Maximum bytes in an input variable-length string, including header names and type parameters; 0 disables the limit. |
| `row_binary_read_binary_types` | `Bool` | `0` | Read type tags and their binary parameters instead of textual type names in the input header. |
| `row_binary_read_json_strings` | `Bool` | `0` | Read JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `row_binary_write_binary_types` | `Bool` | `0` | Write type tags and their binary parameters instead of textual type names in the output header. |
| `row_binary_write_json_strings` | `Bool` | `0` | Write JSON fields as length-prefixed JSON text; binary JSON paths are unsupported. |
| `snappy_mode` | `String` | `basic` | Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format). |
| `sql_insert_batch_rows` | `UInt64` | `65505` | Write at most this many rows per INSERT or REPLACE statement; 0 writes one row per statement. |
| `sql_insert_column_names` | `Bool` | `1` | Include the result column names before VALUES in each written statement. |
| `sql_insert_quote_names` | `Bool` | `1` | Surround each written column name with backticks; names and the table text are otherwise written verbatim. |
| `sql_insert_replace` | `Bool` | `0` | Write REPLACE INTO instead of INSERT INTO. |
| `sql_insert_table` | `String` | `table` | The table text written verbatim after INSERT INTO or REPLACE INTO; include any desired qualification or quoting. |
| `sqlite_read_table` | `String` | `''` | Read this table from the input database; empty selects its first user table. |
| `sqlite_write_table` | `String` | `table` | Name of the single table written to the output database. |
| `tab_separated_check_types` | `Bool` | `1` | Compare the input types header with the bound target column types; when off, skip that header. |
| `tab_separated_crlf` | `Bool` | `0` | End each written row with a carriage return and a line feed instead of a line feed. |
| `tab_separated_detect_header` | `Bool` | `1` | Recognize a raw TSV names header and optional matching types header before reading data. |
| `tab_separated_empty_as_default` | `Bool` | `0` | Give an empty field the column's DEFAULT instead of reading it as empty text. |
| `tab_separated_enum_by_number` | `Bool` | `0` | Read a whole number in an Enum column as the label's number instead of its name. |
| `tab_separated_match_names` | `Bool` | `1` | Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order. |
| `tab_separated_null_text` | `String` | `\N` | The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks. |
| `tab_separated_read_crlf` | `Bool` | `0` | Accept carriage-return/line-feed endings in raw TSV input, removing the carriage return from each record. |
| `tab_separated_skip_empty_lines` | `Bool` | `0` | Ignore empty lines at the end of raw TSV input; empty lines inside the data remain records. |
| `tab_separated_skip_lines` | `UInt64` | `0` | Ignore this many lines at the start of the input, before any header row. |
| `tab_separated_uneven_rows` | `Bool` | `0` | Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped. |
| `template_quote_large_integers` | `Bool` | `0` | Write integers of at least 64 bits as strings in JSON template fields; retained narrow types stay numeric. |
| `template_result` | `String` | `''` | Literal result template; empty means `${data}`. Output supports data and rows; input may skip prefix or suffix fields. |
| `template_row` | `String` | `''` | Literal row template with named or zero-based column placeholders and per-field escaping; empty requires an override. |
| `template_row_separator` | `String` | `\n` | Text between template rows, excluding their own literals; never written after the final row. |
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format
Language: en
# Delimited format settings
Tab-separated and Hive text delimiters, headers, defaults, and row boundaries.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## hive_text_collection_separator
Type: `Char`
Default value: `\x02`
The byte between outermost Array and Tuple elements or Map entries on output; input uses bracketed values.
Applies to: `hive_text`.
## hive_text_map_separator
Type: `Char`
Default value: `\x03`
The byte between outermost Map keys and values, also used at the next nested level on output.
Applies to: `hive_text`.
## hive_text_row_separator
Type: `Char`
Default value: `\n`
The byte ending each output row; input always reads newline-delimited CSV records.
Applies to: `hive_text`.
## hive_text_separator
Type: `Char`
Default value: `\x01`
The byte between top-level fields when reading and writing, with no output quoting or escaping.
Applies to: `hive_text`.
## hive_text_uneven_rows
Type: `Bool`
Default value: `1`
Give omitted trailing input columns their DEFAULT and skip extra fields; off requires the exact field count.
Applies to: `hive_text`.
## tab_separated_check_types
Type: `Bool`
Default value: `1`
Compare the input types header with the bound target column types; when off, skip that header.
Applies to: `tab_separated_with_names_and_types`.
## tab_separated_crlf
Type: `Bool`
Default value: `0`
End each written row with a carriage return and a line feed instead of a line feed.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_detect_header
Type: `Bool`
Default value: `1`
Recognize a raw TSV names header and optional matching types header before reading data.
Applies to: `tab_separated_raw`.
## tab_separated_empty_as_default
Type: `Bool`
Default value: `0`
Give an empty field the column's DEFAULT instead of reading it as empty text.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_enum_by_number
Type: `Bool`
Default value: `0`
Read a whole number in an Enum column as the label's number instead of its name.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_match_names
Type: `Bool`
Default value: `1`
Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order.
Applies to: `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_null_text
Type: `String`
Default value: `\N`
The field text that stands for NULL when reading and writing; it cannot contain tabs or line breaks.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_read_crlf
Type: `Bool`
Default value: `0`
Accept carriage-return/line-feed endings in raw TSV input, removing the carriage return from each record.
Applies to: `tab_separated_raw`.
## tab_separated_skip_empty_lines
Type: `Bool`
Default value: `0`
Ignore empty lines at the end of raw TSV input; empty lines inside the data remain records.
Applies to: `tab_separated_raw`.
## tab_separated_skip_lines
Type: `UInt64`
Default value: `0`
Ignore this many lines at the start of the input, before any header row.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
## tab_separated_uneven_rows
Type: `Bool`
Default value: `0`
Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped.
Applies to: `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-avro
Language: en
# Avro settings
Avro options select container compression, block sizes, field defaults and schema-registry access. Ordinary avro embeds its schema; avro_confluent resolves record schema IDs through the configured registry.
Choose the codec before choosing its settings. Confluent output requires both a registry URL and a subject; compression/block settings apply to the container variant. Input name and NULL policies affect conversion into the declared target.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## avro_block_bytes
Type: `UInt64`
Default value: `16384`
Target uncompressed bytes per output block, from 32 through 1073741824; a complete row may exceed the target.
Applies to: `avro`.
## avro_compression
Type: `String`
Default value: `''`
Output block compression: null, deflate, snappy, or zstd; empty selects snappy.
Applies to: `avro`.
## avro_confluent_connect_timeout
Type: `UInt64`
Default value: `1`
Connection and TLS handshake timeout in seconds; positive values are capped at 599.
Applies to: `avro_confluent`.
## avro_confluent_receive_timeout
Type: `UInt64`
Default value: `1`
Registry response receive timeout in seconds; positive values are capped at 599.
Applies to: `avro_confluent`.
## avro_confluent_registry_url
Type: `String`
Default value: `''`
HTTP or HTTPS schema registry base URL; URL-encoded credentials select Basic authentication.
Applies to: `avro_confluent`.
## avro_confluent_retries
Type: `UInt64`
Default value: `5`
Retry transient registry failures this many times; zero disables retries and values above 20 are capped at 20.
Applies to: `avro_confluent`.
## avro_confluent_retry_delay_ms
Type: `UInt64`
Default value: `100`
Initial retry delay in milliseconds, capped at 60000; subsequent delays double up to 10000 milliseconds.
Applies to: `avro_confluent`.
## avro_confluent_send_timeout
Type: `UInt64`
Default value: `1`
Registry request send timeout in seconds; positive values are capped at 599.
Applies to: `avro_confluent`.
## avro_confluent_subject
Type: `String`
Default value: `''`
Subject under which an output record schema is registered; required for avro_confluent output.
Applies to: `avro_confluent`.
## avro_missing_as_default
Type: `Bool`
Default value: `0`
Give target fields absent from the input schema their SQL DEFAULT or native type default; otherwise reject them.
Applies to: `avro`, `avro_confluent`.
## avro_null_as_default
Type: `Bool`
Default value: `0`
Replace input NULL in a non-nullable native target with its SQL DEFAULT or native type default; legacy SQL columns retain NULL.
Applies to: `avro`, `avro_confluent`.
## avro_string_columns
Type: `String`
Default value: `''`
Regular expression matching output String column paths to encode as UTF-8 string instead of bytes; empty matches none.
Applies to: `avro`, `avro_confluent`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-binary
Language: en
# RowBinary settings
RowBinary options control name matching, type checking, binary type tags and JSON field representation. The bare format has no header; names and types options affect only the header variants listed below.
Disabling a type check does not make mismatched widths compatible: input still needs a schema that can decode the field bytes. JSON values require the explicit JSON-string modes.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## row_binary_check_types
Type: `Bool`
Default value: `1`
Compare input header types with target types; when off decode matched fields with target widths.
Applies to: `row_binary_with_names_and_types`.
## row_binary_match_names
Type: `Bool`
Default value: `1`
Match input header names ignoring ASCII case; when off read in target column order.
Applies to: `row_binary_with_names`, `row_binary_with_names_and_types`.
## row_binary_max_string_bytes
Type: `UInt64`
Default value: `1073741824`
Maximum bytes in an input variable-length string, including header names and type parameters; 0 disables the limit.
Applies to: `row_binary`, `row_binary_with_names`, `row_binary_with_names_and_types`.
## row_binary_read_binary_types
Type: `Bool`
Default value: `0`
Read type tags and their binary parameters instead of textual type names in the input header.
Applies to: `row_binary_with_names_and_types`.
## row_binary_read_json_strings
Type: `Bool`
Default value: `0`
Read JSON fields as length-prefixed JSON text; binary JSON paths are unsupported.
Applies to: `row_binary`, `row_binary_with_names`, `row_binary_with_names_and_types`.
## row_binary_write_binary_types
Type: `Bool`
Default value: `0`
Write type tags and their binary parameters instead of textual type names in the output header.
Applies to: `row_binary_with_names_and_types`.
## row_binary_write_json_strings
Type: `Bool`
Default value: `0`
Write JSON fields as length-prefixed JSON text; binary JSON paths are unsupported.
Applies to: `row_binary`, `row_binary_with_names`, `row_binary_with_names_and_types`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-csv
Language: en
# CSV format settings
Delimited-text options control how fields are separated, quoted or escaped, how header names and types bind, and how missing or empty fields are handled.
CSV and TabSeparated have separate setting names. Set the options matching the selected family. A header variant uses its name/type controls; plain positional data still needs the correct destination field order.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## csv_check_types
Type: `Bool`
Default value: `1`
Compare the input types header with the bound target column types; when off, skip that header.
Applies to: `csv_with_names_and_types`.
## csv_crlf
Type: `Bool`
Default value: `0`
End each written row with a carriage return and a line feed instead of a line feed.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_double_quotes
Type: `Bool`
Default value: `1`
Read a field that starts with a double quote as quoted text; when off, the quote is an ordinary character.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_empty_as_default
Type: `Bool`
Default value: `1`
Give an empty unquoted field the column's DEFAULT; when off, read it as empty text.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_enum_by_number
Type: `Bool`
Default value: `0`
Read a whole number in an Enum column as the label's number instead of its name.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_match_names
Type: `Bool`
Default value: `1`
Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order.
Applies to: `csv_with_names`, `csv_with_names_and_types`.
## csv_null_text
Type: `String`
Default value: `\N`
The unquoted text that stands for NULL when reading and writing; it must stay one untrimmed field under the current CSV settings.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_separator
Type: `Char`
Default value: `,`
The character between fields when reading and writing: one ASCII character that is not a letter, digit, quote, backslash, or line break. Write a tab as \t.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_single_quotes
Type: `Bool`
Default value: `0`
Also read a field that starts with a single quote as quoted text.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_skip_lines
Type: `UInt64`
Default value: `0`
Ignore this many lines at the start of the input, before any header row.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_trim_blanks
Type: `Bool`
Default value: `1`
Drop spaces and tabs around a field when reading; quotes keep the blanks inside them.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
## csv_uneven_rows
Type: `Bool`
Default value: `0`
Accept rows with too few or too many fields: missing fields take the column's DEFAULT and extra fields are dropped.
Applies to: `csv`, `csv_with_names`, `csv_with_names_and_types`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-custom
Language: en
# CustomSeparated format settings
Custom-separated formats expose field, row and result delimiters plus an escaping grammar. Hive text uses its own field, collection and map separators.
Choose an escaping grammar that protects delimiter characters in field content. Hive output does not add escaping for embedded separators. Names headers are separate from positional values.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## custom_separated_detect_header
Type: `Bool`
Default value: `1`
Recognize an input names header and an optional matching types header.
Applies to: `custom_separated`.
## custom_separated_escaping
Type: `String`
Default value: `Escaped`
Field grammar: Escaped, Quoted, CSV, JSON, XML (output only), or Raw.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_match_names
Type: `Bool`
Default value: `1`
Match input names to target columns ignoring ASCII case; when off, skip the names header and read in target order.
Applies to: `custom_separated_with_names`.
## custom_separated_result_prefix
Type: `String`
Default value: `''`
Text before the entire input or output result.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_result_suffix
Type: `String`
Default value: `''`
Text after the entire input or output result.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_row_prefix
Type: `String`
Default value: `''`
Text before the first field of each input or output row.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_row_separator
Type: `String`
Default value: `''`
Text between input or output rows, excluding their own prefixes and suffixes.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_row_suffix
Type: `String`
Default value: `\n`
Text after the last field of each input or output row.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_separator
Type: `String`
Default value: `\t`
Text between input or output fields; may contain multiple bytes.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_skip_empty_lines
Type: `Bool`
Default value: `0`
Skip trailing CR and LF bytes after the result; one final LF is always accepted.
Applies to: `custom_separated`, `custom_separated_with_names`.
## custom_separated_uneven_rows
Type: `Bool`
Default value: `0`
Give omitted input fields their SQL or native defaults and validate then skip extra fields.
Applies to: `custom_separated`, `custom_separated_with_names`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-regexp
Language: en
# Regular-expression input settings
The regexp input format matches one complete physical line and maps capture groups to destination columns. The captured field is then decoded with the chosen escaping rule.
A pattern is required because its default is empty. regexp_skip_unmatched can skip nonmatching lines; it does not remove target-type validation from matching captures.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## regexp_escaping
Type: `String`
Default value: `Raw`
Read captured fields as Raw text, Escaped text, Quoted literals, CSV fields, or JSON values.
Applies to: `regexp`.
## regexp_pattern
Type: `String`
Default value: `''`
Match every complete input line; one capture group supplies each target column. Empty requires a statement override.
Applies to: `regexp`.
## regexp_skip_unmatched
Type: `Bool`
Default value: `0`
Skip lines that do not match the expression; otherwise report their physical line number.
Applies to: `regexp`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-schema
Language: en
# Protobuf schema settings
Protobuf options select a literal proto2/proto3 schema or a schema derived from columns. protobuf_message identifies the message within that schema.
protobuf_schema is schema text rather than a file path. Imports are limited to bundled Google definitions. Wrapper, oneof and missing-field policies must match how the destination columns represent those fields.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## protobuf_auto_schema
Type: `Bool`
Default value: `1`
Derive a message schema from columns when protobuf_schema is empty.
Applies to: `protobuf`.
## protobuf_keep_default_wrappers
Type: `Bool`
Default value: `0`
Write present Google wrappers for default scalar values; NULL wrappers remain absent.
Applies to: `protobuf`.
## protobuf_message
Type: `String`
Default value: `''`
Fully qualified message name in protobuf_schema; empty selects Row for an automatically derived schema.
Applies to: `protobuf`.
## protobuf_missing_as_default
Type: `Bool`
Default value: `1`
Apply SQL DEFAULT to target columns outside the message schema; when off use their native type defaults.
Applies to: `protobuf`.
## protobuf_oneof_tag
Type: `Bool`
Default value: `0`
Read the selected oneof field number into a column named after that oneof; unmatched branches yield zero.
Applies to: `protobuf`.
## protobuf_schema
Type: `String`
Default value: `''`
Literal proto2 or proto3 schema; imports are limited to bundled Google definitions.
Applies to: `protobuf`.
## protobuf_unwrap_google
Type: `Bool`
Default value: `0`
Read Google scalar wrappers directly into scalar columns; absent nullable wrappers become NULL.
Applies to: `protobuf`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/format-template
Language: en
# Template settings
Template settings combine literal text with named or zero-based positional field placeholders. A placeholder states the field escaping grammar.
The row separator appears between rows only. Put a required final newline in the literal row or result template. Input must match literal separators; mismatches are data errors.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## template_quote_large_integers
Type: `Bool`
Default value: `0`
Write integers of at least 64 bits as strings in JSON template fields; retained narrow types stay numeric.
Applies to: `template`.
## template_result
Type: `String`
Default value: `''`
Literal result template; empty means ${data}. Output supports data and rows; input may skip prefix or suffix fields.
Applies to: `template`.
## template_row
Type: `String`
Default value: `''`
Literal row template with named or zero-based column placeholders and per-field escaping; empty requires an override.
Applies to: `template`.
## template_row_separator
Type: `String`
Default value: `\n`
Text between template rows, excluding their own literals; never written after the final row.
Applies to: `template`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/input-format
Language: en
# Shared input settings
ignore_unknown_fields allows an input codec to skip keys or header names outside the destination schema. It applies only to the named formats listed in the table.
This option does not infer new columns or remove native type validation from known fields. Positional width and container validity are governed by each codec's own rules.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## arrow_ignore_case
Type: `Bool`
Default value: `0`
Ignore ASCII case when matching input field names to target columns.
Applies to: `arrow`, `arrow_stream`.
## arrow_missing_as_default
Type: `Bool`
Default value: `1`
Give target columns absent from the input schema their DEFAULT; when off, reject missing columns.
Applies to: `arrow`, `arrow_stream`.
## ignore_unknown_fields
Type: `Bool`
Default value: `0`
Skip input keys and header names that match no target column instead of failing.
Applies to: `arrow`, `arrow_stream`, `csv_with_names`, `csv_with_names_and_types`, `custom_separated_with_names`, `form`, `json`, `json_columns`, `json_compact_each_row_with_names_and_types`, `json_each_row`, `json_object_each_row`, `json_strings_each_row`, `parquet`, `row_binary_with_names_and_types`, `tab_separated_with_names`, `tab_separated_with_names_and_types`, `tskv`, `yaml`.
## parquet_detect_variant
Type: `Bool`
Default value: `1`
Recognize unannotated metadata/value binary structs as Variant values.
Applies to: `parquet`.
## parquet_ignore_case
Type: `Bool`
Default value: `0`
Ignore ASCII case when matching input fields to target column names.
Applies to: `parquet`.
## parquet_missing_as_default
Type: `Bool`
Default value: `1`
Give missing input fields their SQL DEFAULT or native type default.
Applies to: `parquet`.
## parquet_parse_json
Type: `Bool`
Default value: `1`
Decode JSON-annotated input fields as native JSON instead of text.
Applies to: `parquet`.
## parquet_read_bytes
Type: `UInt64`
Default value: `16744704`
Target decoded batch bytes estimated from uncompressed row-group metadata.
Applies to: `parquet`.
## parquet_read_geo
Type: `Bool`
Default value: `1`
Decode WKB or WKT columns identified by GeoParquet metadata; text and binary targets retain raw payloads.
Applies to: `parquet`.
## parquet_read_rows
Type: `UInt64`
Default value: `65409`
Maximum rows per decoded input batch.
Applies to: `parquet`.
## snappy_mode
Type: `String`
Default value: `basic`
Read Snappy client files as basic (Hadoop blocks) or framed (standard streaming format).
Applies to: `arrow`, `arrow_stream`, `avro`, `avro_confluent`, `bson_each_row`, `csv`, `csv_with_names`, `csv_with_names_and_types`, `custom_separated`, `custom_separated_with_names`, `form`, `geo_json`, `hive_text`, `json`, `json_as_object`, `json_as_string`, `json_columns`, `json_compact_columns`, `json_compact_each_row`, `json_compact_each_row_with_names_and_types`, `json_compact_strings_each_row`, `json_each_row`, `json_object_each_row`, `json_strings_each_row`, `line_as_string`, `msg_pack`, `npy`, `parquet`, `parquet_metadata`, `protobuf`, `regexp`, `row_binary`, `row_binary_with_names`, `row_binary_with_names_and_types`, `sql_values`, `sqlite`, `tab_separated`, `tab_separated_raw`, `tab_separated_with_names`, `tab_separated_with_names_and_types`, `template`, `tskv`, `yaml`.
## sqlite_read_table
Type: `String`
Default value: `''`
Read this table from the input database; empty selects its first user table.
Applies to: `sqlite`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/other
Language: en
# Other format settings
BSON strings, GeoJSON validation, and MessagePack UUID encoding.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## bson_strings
Type: `Bool`
Default value: `0`
Write text and fixed-width strings as BSON String instead of Binary.
Applies to: `bson_each_row`.
## geo_json_unsupported_geometry
Type: `String`
Default value: `throw`
Reject unsupported geometry types on input; null validates them and stores NULL when geometry is requested.
Applies to: `geo_json`.
## geo_json_validate_geometry
Type: `Bool`
Default value: `1`
Validate line lengths, ring lengths and closure, and nonempty geometry containers on input and output; coordinates must always be finite.
Applies to: `geo_json`.
## msg_pack_uuid_encoding
Type: `String`
Default value: `EXT`
Write UUID as EXT (extension type 2), BIN (16 binary bytes), or STR (canonical text).
Applies to: `msg_pack`.
---
Source: https://coordinatordb.com/docs/reference/settings/formats/output-format
Language: en
# Output settings
Output settings control binary containers, display tables, image dimensions, Markdown, and generated SQL. Each setting applies only to the formats listed in its section.
Use a statement `SETTINGS` clause. Defaults in `system.settings` are read-only;
format settings cannot be persisted with `SET`. Put input settings before
`FORMAT`, because the bytes after the format name are input data.
## arrow_compression
Type: `String`
Default value: `lz4_frame`
Compress record batch buffers with lz4_frame or zstd; none writes uncompressed buffers.
Applies to: `arrow`, `arrow_stream`.
## arrow_date_as_number
Type: `Bool`
Default value: `0`
Write Date as UInt16 days since the epoch instead of Date32; Date32 always remains Date32.
Applies to: `arrow`, `arrow_stream`.
## arrow_dictionary
Type: `Bool`
Default value: `0`
Write LowCardinality as dictionary indices and values instead of expanding its scalars.
Applies to: `arrow`, `arrow_stream`.
## arrow_dictionary_64bit_indices
Type: `Bool`
Default value: `0`
Use 64-bit dictionary indices instead of the smallest width that fits the dictionary.
Applies to: `arrow`, `arrow_stream`.
## arrow_dictionary_signed_indices
Type: `Bool`
Default value: `1`
Use signed dictionary indices; when off, use unsigned indices.
Applies to: `arrow`, `arrow_stream`.
## arrow_fixed_strings
Type: `Bool`
Default value: `1`
Write FixedString with a fixed byte width instead of variable-length Binary.
Applies to: `arrow`, `arrow_stream`.
## arrow_strings_as_text
Type: `Bool`
Default value: `1`
Write text strings as Utf8 instead of Binary; byte strings keep their exact bytes.
Applies to: `arrow`, `arrow_stream`.
## markdown_escape_special_characters
Type: `Bool`
Default value: `0`
Escape ASCII punctuation in text and byte-string values with a backslash; when off, escape controls, backslashes, and single quotes.
Applies to: `markdown`.
## parquet_compression
Type: `String`
Default value: `zstd`
Compress column pages with snappy, lz4, brotli, zstd, gzip, or none.
Applies to: `parquet`.
## parquet_fixed_strings
Type: `Bool`
Default value: `1`
Write FixedString as fixed-width bytes instead of variable-width Binary.
Applies to: `parquet`.
## parquet_page_bytes
Type: `UInt64`
Default value: `1048576`
Target uncompressed bytes per output data page.
Applies to: `parquet`.
## parquet_page_index
Type: `Bool`
Default value: `1`
Write column and offset indexes for individual data pages.
Applies to: `parquet`.
## parquet_row_group_bytes
Type: `UInt64`
Default value: `536870912`
Target output row-group bytes before compression.
Applies to: `parquet`.
## parquet_row_group_rows
Type: `UInt64`
Default value: `1000000`
Maximum rows per output row group.
Applies to: `parquet`.
## parquet_strings_as_text
Type: `Bool`
Default value: `1`
Annotate text strings as UTF-8; BLOB keeps its exact binary representation.
Applies to: `parquet`.
## parquet_wide_as_decimal
Type: `Bool`
Default value: `0`
Write 128/256-bit integers as big-endian DECIMAL instead of little-endian fixed-width bytes.
Applies to: `parquet`.
## parquet_write_batch_rows
Type: `UInt64`
Default value: `1024`
Check output data-page size after this many rows.
Applies to: `parquet`.
## parquet_write_geo
Type: `Bool`
Default value: `1`
Encode geometry as WKB and include GeoParquet column metadata.
Applies to: `parquet`.
## png_height
Type: `UInt64`
Default value: `1024`
Height of the image in pixels, from 1 through 2147483647.
Applies to: `png`.
## png_time_denominator
Type: `UInt64`
Default value: `60`
Positive denominator of the duration in seconds of one integer t unit.
Applies to: `png`.
## png_time_numerator
Type: `UInt64`
Default value: `1`
Positive numerator of the duration in seconds of one integer t unit.
Applies to: `png`.
## png_width
Type: `UInt64`
Default value: `1024`
Width of the image in pixels, from 1 through 2147483647.
Applies to: `png`.
## pretty_borders
Type: `String`
Default value: `unicode`
The characters that draw the table: unicode for box-drawing lines, ascii for plus, minus, and bar.
Applies to: `pretty_compact`.
## pretty_footer_from_rows
Type: `UInt64`
Default value: `0`
Repeat the column names in the bottom border when the table shows at least this many rows; 0 never repeats them.
Applies to: `pretty_compact`.
## pretty_max_cell_width
Type: `UInt64`
Default value: `0`
Cut a value wider than this many terminal columns and mark the cut; 0 never cuts.
Applies to: `pretty_compact`.
## pretty_max_padding
Type: `UInt64`
Default value: `0`
Align a column to at most this many terminal columns; wider values extend their own row. 0 aligns to the widest value.
Applies to: `pretty_compact`.
## pretty_max_rows
Type: `UInt64`
Default value: `0`
Show at most this many rows and report how many were left out; 0 shows every row.
Applies to: `pretty_compact`.
## pretty_row_numbers
Type: `Bool`
Default value: `0`
Add a first column that numbers the rows from 1.
Applies to: `pretty_compact`.
## sql_insert_batch_rows
Type: `UInt64`
Default value: `65505`
Write at most this many rows per INSERT or REPLACE statement; 0 writes one row per statement.
Applies to: `sql_insert`.
## sql_insert_column_names
Type: `Bool`
Default value: `1`
Include the result column names before VALUES in each written statement.
Applies to: `sql_insert`.
## sql_insert_quote_names
Type: `Bool`
Default value: `1`
Surround each written column name with backticks; names and the table text are otherwise written verbatim.
Applies to: `sql_insert`.
## sql_insert_replace
Type: `Bool`
Default value: `0`
Write REPLACE INTO instead of INSERT INTO.
Applies to: `sql_insert`.
## sql_insert_table
Type: `String`
Default value: `table`
The table text written verbatim after INSERT INTO or REPLACE INTO; include any desired qualification or quoting.
Applies to: `sql_insert`.
## sqlite_write_table
Type: `String`
Default value: `table`
Name of the single table written to the output database.
Applies to: `sqlite`.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings
Language: en
# Server settings
Server options configure listeners, users, diagnostic files, admission and resource ceilings. They are read from XML at startup and do not appear as database SET names.
## File and overrides
The configuration must already exist. Unknown or duplicate settings are rejected, and command-line listener overrides do not skip XML validation. Changes require restart.
Use --config-file to select the document and --db to choose the database file independently. Relative users, logs and server-file paths follow the configuration directory.
## Reference
* [http_port](https://coordinatordb.com/docs/reference/settings/server-settings/settings/http)
* [listen_host](https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen)
* [Request and admission limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max)
* [logger and file paths](https://coordinatordb.com/docs/reference/settings/server-settings/settings/other)
* [tcp_port](https://coordinatordb.com/docs/reference/settings/server-settings/settings/tcp-port)
* [users_config](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users)
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/http
Language: en
# http_port
http_port is an optional HTTP listener port. Omit it to disable HTTP. A value of 0 selects an available port and startup output reports the address.
## Values
The accepted range is 0 through 65535. The sample configuration uses 7401:
```xml
7401
```
The setting belongs inside the coordinator root. HTTP normally binds listen_host; `--http-addr HOST:PORT` overrides its address independently of native TCP.
The listener serves SQL and `/playground`. SQL authentication uses the configured users file.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen
Language: en
# listen_host
listen_host supplies the bind address for the configured native and HTTP listeners. The default is the IPv4 loopback address `127.0.0.1`.
## Values
Use numeric IPv4 or unbracketed numeric IPv6 text. Hostnames and bracketed IPv6 text are rejected in this XML value.
```xml
127.0.0.1
```
The command-line `--addr` overrides the native listener and `--http-addr` overrides HTTP independently. Port settings remain separate from the XML host value.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/max
Language: en
# Request and admission limits
Server XML limits set ceilings shared by the service's native and HTTP interfaces. Database values can tighten the resource ceilings, while admission controls are server-only.
## Request ceilings
| Setting | Default | Unit or values |
| ------------------ | ------- | ------------------------------------------------ |
| max_execution_time | 0 | Nonnegative finite seconds, including fractions. |
| max_memory_usage | 0 | Accounted SQL heap bytes. |
| max_result_rows | 0 | Cumulative returned rows per request. |
| max_response_bytes | 0 | Successful logical response bytes. |
| max_threads | 0 | Total query threads, from 0 through 64. |
Zero removes an added time, memory, row or byte ceiling at that scope. A database setting cannot bypass a nonzero XML ceiling.
For threads, zero chooses the available processor count capped at eight total query threads. Explicit values are also bounded by hardware and available workers. The setting does not make every query parallel.
## Admission and transport
| Setting | Default | Rule |
| -------------------------- | -------- | ----------------------------------------- |
| max_connections | 128 | Positive shared connection limit. |
| max_inflight_request_bytes | 67108864 | Positive incoming-byte admission limit. |
| request_read_timeout | 5 | Positive seconds; fractions are accepted. |
These controls are not database SET options. See [connection limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/tcp-connection-limits) for login, idle-session and upload timing.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/other
Language: en
# Logger and file paths
The required logger section declares diagnostic output files and rotation. Relative paths start at the configuration directory.
## Logger fields
| Field | Contract |
| -------- | --------------------------------------------------------------------- |
| level | debug, information, warning, error, fatal or none; default debug. |
| log | Required ordinary diagnostic log path. |
| errorlog | Required error log path. |
| size | Positive rotation byte threshold; binary K/M/G suffixes are accepted. |
| count | Number of archives, including zero. |
```xml
information
server.log
server.err.log
10M
3
```
The section belongs inside coordinator. Diagnostic logging is separate from the structured query log controlled by log_queries.
## Server file root
user_files_path defaults to user_files beside the configuration. It defines the root for confined server file() sources, whose SQL paths must be relative to that root.
Changing `--db` does not move these paths. See [`file`](https://coordinatordb.com/docs/reference/functions/table-functions/file) for allowed files and schema requirements.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/tcp-port
Language: en
# tcp_port
tcp_port selects the native TCP listener port. Its default is 7400, and its accepted range is 0 through 65535.
## Values
```xml
7400
```
Zero asks for an available port, printed at startup. It does not disable the native listener. `--addr HOST:PORT` overrides both the native host and port.
Connect with the supplied CoordinatorDB client. Third-party ClickHouse or PostgreSQL native clients are not compatible.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/server-settings/settings/users
Language: en
# users_config
users_config selects the XML file containing configured users. It defaults to users.xml. A relative path starts at the server configuration directory.
```xml
users.xml
```
The file must exist. The server does not create an implicit user or infer credentials from a missing file.
## User declaration
A users file can declare a password for a named user:
```xml
example-password
```
A user has exactly one password form: plaintext password or a 64-character password_sha256_hex digest. An optional api_key_sha256_hex associates an HTTP Bearer key with that user. Usernames are case-sensitive; duplicate users and shared API-key digests are rejected.
## Applying changes
Edit the existing server XML and restart. XML values are validated even when a command-line argument overrides them. Unknown or duplicate elements are configuration errors.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) for the complete document and path rules.
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings
Language: en
# Database settings
The server exposes effective database settings in system.settings. `SET` persists log_queries, log_queries_min_query_duration_ms, max_execution_time, max_memory_usage, max_result_rows, max_response_bytes and max_threads for the selected database. Other connected clients observe committed values before later requests.
Changes require a selected database, autocommit and no active transactions in that database. Resource values are sampled once per request; a SET in a multi-statement request changes defaults for later requests.
The foreign_keys, recursive_triggers, user_version and application_id rows use [PRAGMA or catalog writes](https://coordinatordb.com/docs/reference/settings/session-settings/other); SET does not accept these four names. A nonzero server XML request ceiling can only be tightened by database settings; 0 means no additional limit at that level.
## Defaults
| Setting | Type | Default | Meaning |
| ----------------------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `application_id` | `Int32` | `0` | Application-managed database file identifier. |
| `foreign_keys` | `Bool` | `0` | Enforce foreign-key constraints in database sessions. |
| `log_queries` | `Bool` | `1` | Record TCP and HTTP requests in the structured query journal. |
| `log_queries_min_query_duration_ms` | `UInt64` | `0` | Minimum logged request duration in milliseconds. |
| `max_execution_time` | `Float64` | `0` | Maximum SQL processing time in seconds; zero disables the limit. |
| `max_memory_usage` | `UInt64` | `0` | Maximum live SQL heap bytes; zero disables the limit. |
| `max_response_bytes` | `UInt64` | `0` | Maximum formatted native response bytes; zero disables this setting. |
| `max_result_rows` | `UInt64` | `0` | Maximum cumulative returned rows per request; zero disables the limit. |
| `max_threads` | `UInt64` | `0` | Maximum threads per query, from 0 through 64. Zero selects automatically; one keeps execution serial. |
| `recursive_triggers` | `Bool` | `0` | Allow triggers to invoke themselves recursively. |
| `user_version` | `Int32` | `0` | Application-managed database schema version. |
## Inspect effective values
```sql
SELECT name,value,type,"default" FROM system.settings WHERE readonly=0 ORDER BY name FORMAT csv;
```
```text
"application_id","0","Int32","0"
"foreign_keys","0","Bool","0"
"log_queries","1","Bool","1"
"log_queries_min_query_duration_ms","0","UInt64","0"
"max_execution_time","0","Float64","0"
"max_memory_usage","0","UInt64","0"
"max_response_bytes","0","UInt64","0"
"max_result_rows","0","UInt64","0"
"max_threads","0","UInt64","0"
"recursive_triggers","0","Bool","0"
"user_version","0","Int32","0"
```
The changed column compares an effective value with its built-in default. Server ceilings can make the effective value differ from the saved value in main.settings. Format options appear separately as read-only defaults; server-only XML options are not listed.
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/log-queries
Language: en
# Query logging settings
Query logging records structured native TCP and HTTP request events. Diagnostic file logging is configured independently.
## Settings
| Setting | Type | Default | Meaning |
| --------------------------------- | ------ | ------- | -------------------------------------------------- |
| log_queries | Bool | 1 | Enable structured request history. |
| log_queries_min_query_duration_ms | UInt64 | 0 | Minimum recorded request duration in milliseconds. |
With a zero threshold, enabled logging records a start and a terminal event. A nonzero threshold omits fast requests and records only a terminal event for qualifying requests, including failures.
Disabling log_queries overrides the threshold. Earlier history remains readable.
## Example
```sql
SET log_queries = 1;
SET log_queries_min_query_duration_ms = 100;
```
```sql
SELECT name, value
FROM system.settings
WHERE name IN ('log_queries', 'log_queries_min_query_duration_ms')
ORDER BY name
FORMAT csv;
```
```text
"log_queries","1"
"log_queries_min_query_duration_ms","100"
```
These are persisted database defaults. SET requires autocommit and no active transactions in that database. Read [system.query_log](https://coordinatordb.com/docs/reference/system-tables/query-log) for event types, visibility and metrics.
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/max-execution
Language: en
# max_execution_time
Limits elapsed SQL processing time for a request. The type is Float64 and the default is `0`, meaning no additional time limit at the database scope.
Finite nonnegative fractional seconds are accepted, so `0.5` requests half a second.
## Scope and changes
Use SET after selecting a server database. The change is persisted for that database and observed by other clients before later requests. It requires autocommit and no active transactions in the database. Resource limits are sampled once per request; a SET within a batch changes defaults for later requests.
A nonzero XML ceiling can only be tightened by the saved database value. Zero removes the database's additional ceiling while retaining any server ceiling. Inspect system.settings for effective values and main.settings for stored values.
## Behavior
The deadline is shared across the request's statements and query threads. Checks are cooperative: a blocking operation can finish before a later check reports QUERY_TIME_LIMIT_EXCEEDED. This is a processing limit, separate from socket request_read_timeout.
## Example
```sql
SET max_execution_time = 0.5;
```
```sql
SELECT name, value
FROM system.settings
WHERE name = 'max_execution_time'
FORMAT csv;
```
```text
"max_execution_time","0.5"
```
See [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) and [server limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/max-memory-usage
Language: en
# max_memory_usage
Limits the request's combined live SQL heap allocations in bytes. The type is UInt64 and the default is `0`, meaning no added database memory ceiling.
## Scope and changes
Use SET after selecting a server database. The change is persisted for that database and observed by other clients before later requests. It requires autocommit and no active transactions in the database. Resource limits are sampled once per request; a SET within a batch changes defaults for later requests.
A nonzero XML ceiling can only be tightened by the saved database value. Zero removes the database's additional ceiling while retaining any server ceiling. Inspect system.settings for effective values and main.settings for stored values.
## Accounting
The budget covers SQL processing allocations across the query's threads, including parallel workers. Existing connection caches, transport/log ownership and unrelated threads are excluded.
Accounting and process metrics remain active with a zero ceiling. Checks are cooperative; an allocation can finish before the next check reports a violation. This counter describes accounted query memory rather than the server's entire resident memory.
## Example
```sql
SET max_memory_usage = 67108864;
```
```sql
SELECT name, value
FROM system.settings
WHERE name = 'max_memory_usage'
FORMAT csv;
```
```text
"max_memory_usage","67108864"
```
Terminal query-log memory_usage and peak_memory_usage both report the peak accounted value. See [query_log](https://coordinatordb.com/docs/reference/system-tables/query-log) and [processes](https://coordinatordb.com/docs/reference/system-tables/processes).
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/max-result
Language: en
# max_result_rows and max_response_bytes
These UInt64 settings limit successful request results. Both default to `0`, leaving no additional database ceiling.
## Limits
* max_result_rows counts returned rows across the request's SELECT, SHOW, PRAGMA and RETURNING results.
* max_response_bytes counts the complete successful logical response, including formatted values, borders and protocol fields such as the status byte, database name and separator.
The protocol independently caps responses at 16 MiB. Error responses retain that fixed frame limit, so a small result budget can still return a diagnostic.
## Scope and changes
Use SET after selecting a server database. The change is persisted for that database and observed by other clients before later requests. It requires autocommit and no active transactions in the database. Resource limits are sampled once per request; a SET within a batch changes defaults for later requests.
A nonzero XML ceiling can only be tightened by the saved database value. Zero removes the database's additional ceiling while retaining any server ceiling. Inspect system.settings for effective values and main.settings for stored values.
## Write results
A RETURNING result that violates a result limit rolls back that statement's writes, including inside an explicit transaction. Earlier statements in a request retain their normal commit behavior. Transaction recovery commands and management controls remain available.
## Example
```sql
SET max_result_rows = 1000;
SET max_response_bytes = 1048576;
```
```sql
SELECT name, value
FROM system.settings
WHERE name IN ('max_result_rows', 'max_response_bytes')
ORDER BY name
FORMAT csv;
```
```text
"max_response_bytes","1048576"
"max_result_rows","1000"
```
SQL LIMIT controls one query result. It does not replace the cumulative request limits described here.
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/max-threads
Language: en
# max_threads
max_threads is a UInt64 value from 0 through 64. The default is `0`; `1` requests serial execution.
## Automatic and explicit values
Zero selects the available hardware count capped at eight total query threads, including the query's main thread. Explicit counts are also bounded by hardware, the XML ceiling and available workers.
The setting is a ceiling, not a guarantee that every query uses several threads. Only eligible large scan aggregates use the parallel path; other query shapes can remain serial.
## Persistence
Server SET persists the selected database's value and requires autocommit with no active transactions in that database. A changed resource setting applies to later requests. An embedded connection uses `PRAGMA max_threads = value` instead.
## Example
```sql
SET max_threads = 1;
```
```sql
SELECT name, value
FROM system.settings
WHERE name = 'max_threads'
FORMAT csv;
```
```text
"max_threads","1"
```
Use peak_threads_usage in [process metadata](https://coordinatordb.com/docs/reference/system-tables/processes) to observe actual usage. Serial execution reports one total thread.
---
Source: https://coordinatordb.com/docs/reference/settings/session-settings/other
Language: en
# foreign_keys, recursive_triggers, user_version, application_id
These settings describe connection behavior or application-managed database identifiers. They are not accepted by the server SET command.
## Settings
| Setting | Type | Default | Meaning |
| -------------------- | ------- | ------- | ----------------------------------------------------- |
| `application_id` | `Int32` | `0` | Application-managed database file identifier. |
| `foreign_keys` | `Bool` | `0` | Enforce foreign-key constraints in database sessions. |
| `recursive_triggers` | `Bool` | `0` | Allow triggers to invoke themselves recursively. |
| `user_version` | `Int32` | `0` | Application-managed database schema version. |
## Change a value
Use `PRAGMA name = value` for the corresponding connection flag or database-header field. To save server database defaults and apply them to other clients, write validated name/value rows to system.settings. SET does not accept these four names.
For example, persist foreign-key enforcement for the selected server database with:
```sql
INSERT OR REPLACE INTO system.settings(name,value) VALUES('foreign_keys','1');
```
```sql
PRAGMA foreign_keys FORMAT csv;
```
```text
1
```
```sql
SELECT name,value FROM system.settings WHERE name IN ('foreign_keys','recursive_triggers','user_version','application_id') ORDER BY name FORMAT csv;
```
```text
"application_id","0"
"foreign_keys","1"
"recursive_triggers","0"
"user_version","0"
```
## Scope
A PRAGMA changes the observing connection's flag or database-header field according to its SQL contract. A validated system.settings write stores server database defaults for later requests by clients selecting that database. Such management writes require autocommit and no active transactions in the database.
See [database settings](https://coordinatordb.com/docs/reference/settings/session-settings) and [`SET`](https://coordinatordb.com/docs/reference/statements/set) for the separate SET-supported names.
---
Source: https://coordinatordb.com/docs/reference/statements
Language: en
# SQL statements
SQL statements read data, define schema objects and change rows. Server commands add managed database selection, settings and service introspection.
## Statement groups
* Read data with `SELECT`; combine sources with joins and set operations.
* Define tables, views, indexes and triggers with `CREATE`, `ALTER` and `DROP`.
* Change rows with `INSERT`, `UPDATE` and `DELETE`, optionally using `RETURNING`.
* Group changes with transaction and savepoint controls.
* Inspect server state with `SHOW`, system relations and `EXPLAIN`.
The [SQL syntax reference](https://coordinatordb.com/docs/reference/syntax) also covers `PRAGMA`, `ANALYZE`, `VACUUM INTO` and trigger declarations. `ATTACH` and `DETACH` operate through the embedded Connection API; server database management uses `CREATE DATABASE` and `USE`.
## Reference
* [ALTER TABLE](https://coordinatordb.com/docs/reference/statements/alter)
* [ATTACH](https://coordinatordb.com/docs/reference/statements/attach)
* [CREATE INDEX](https://coordinatordb.com/docs/reference/statements/create/create-index)
* [DELETE](https://coordinatordb.com/docs/reference/statements/delete)
* [DETACH](https://coordinatordb.com/docs/reference/statements/detach)
* [DROP](https://coordinatordb.com/docs/reference/statements/drop)
* [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain)
* [IN](https://coordinatordb.com/docs/reference/statements/in)
* [INSERT INTO](https://coordinatordb.com/docs/reference/statements/insert-into)
* [Rename a table](https://coordinatordb.com/docs/reference/statements/rename)
* [SELECT](https://coordinatordb.com/docs/reference/statements/select)
* [SET](https://coordinatordb.com/docs/reference/statements/set)
* [SHOW](https://coordinatordb.com/docs/reference/statements/show)
* [UPDATE](https://coordinatordb.com/docs/reference/statements/update)
* [USE](https://coordinatordb.com/docs/reference/statements/use)
* [CREATE TABLE](https://coordinatordb.com/docs/reference/statements/create/table)
* [CREATE DATABASE](https://coordinatordb.com/docs/reference/statements/create/database)
* [Temporary tables](https://coordinatordb.com/docs/reference/statements/create/table/temporary-table)
* [CREATE VIEW](https://coordinatordb.com/docs/reference/statements/create/view)
---
Source: https://coordinatordb.com/docs/reference/statements/alter
Language: en
# ALTER TABLE
ALTER TABLE changes the definition of an existing table. CoordinatorDB supports adding, dropping and renaming columns, and renaming the table itself.
## Supported operations
```text
ALTER TABLE table ADD COLUMN column type [constraints]
ALTER TABLE table DROP COLUMN column
ALTER TABLE table RENAME COLUMN old_name TO new_name
ALTER TABLE table RENAME TO new_name
```
A change must remain valid for existing rows and dependent schema objects. Constraints, indexes, views or triggers can prevent a change that would leave them invalid.
## Example
### Adding a defaulted column
```sql
CREATE TABLE accounts(id INTEGER PRIMARY KEY);
INSERT INTO accounts VALUES (1);
ALTER TABLE accounts ADD COLUMN status String DEFAULT 'new';
```
```sql
SELECT id, status
FROM accounts
FORMAT csv;
```
```text
1,"new"
```
See [column operations](https://coordinatordb.com/docs/reference/statements/alter/column) for the detailed syntax and [renaming a table](https://coordinatordb.com/docs/reference/statements/rename) for the rename form. Changing a column's type with `ALTER COLUMN TYPE` or ClickHouse `MODIFY COLUMN` is not supported; create a new table and copy explicitly converted values instead.
---
Source: https://coordinatordb.com/docs/reference/statements/alter/column
Language: en
# ALTER TABLE columns
Column operations change a table's schema and validate the change against existing rows and dependencies.
## Syntax
```text
ALTER TABLE table ADD COLUMN column type [constraints]
ALTER TABLE table DROP COLUMN column
ALTER TABLE table RENAME COLUMN old_name TO new_name
```
## Adding a column
An added column must have an allowed definition that also works for rows already in the table. Supply a suitable DEFAULT when existing rows need a value, particularly with `NOT NULL`.
## Dropping or renaming a column
Dependent constraints, indexes, views and triggers can prevent an incompatible change. Renaming a column changes its schema name; use the new name in later statements.
`ALTER COLUMN TYPE` and ClickHouse `MODIFY COLUMN` are not supported. To change the value type, create a replacement table and use `INSERT ... SELECT CAST(...)`.
## Examples
### Adding and renaming a field
```sql
CREATE TABLE profiles(id INTEGER PRIMARY KEY);
INSERT INTO profiles VALUES (1);
ALTER TABLE profiles ADD COLUMN label String DEFAULT 'new';
ALTER TABLE profiles RENAME COLUMN label TO status;
```
```sql
SELECT id, status
FROM profiles
FORMAT csv;
```
```text
1,"new"
```
### Dropping an unused field
```sql
ALTER TABLE profiles ADD COLUMN note String;
ALTER TABLE profiles DROP COLUMN note;
```
```sql
SELECT id, status
FROM profiles
FORMAT csv;
```
```text
1,"new"
```
See [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) for column definitions and constraints.
---
Source: https://coordinatordb.com/docs/reference/statements/attach
Language: en
# ATTACH
ATTACH makes another file-backed or in-memory database available through one embedded connection. Qualify its tables with the namespace, such as `aux.notes`.
## Syntax
```text
ATTACH [DATABASE] 'path' AS namespace
```
## Interface
A server connection rejects ATTACH on both native and HTTP interfaces. Create managed server databases with `CREATE DATABASE` and select them with `USE`.
## Example
### Using the embedded Connection API
The following application uses an in-memory attachment, so it does not require an existing database file:
```rust
use coordinator::Connection;
fn main() -> coordinator::Result<()> {
let mut db = Connection::open_in_memory()?;
db.execute("ATTACH ':memory:' AS aux; CREATE TABLE aux.notes(id INTEGER); INSERT INTO aux.notes VALUES(1);")?;
let result = db.query("SELECT id FROM aux.notes")?;
assert_eq!(result.rows[0][0].scalar_text(), "1");
Ok(())
}
```
---
Source: https://coordinatordb.com/docs/reference/statements/create/create-index
Language: en
# CREATE INDEX
CREATE INDEX defines an index over one or more columns or expressions. A UNIQUE index also rejects duplicate non-`NULL` keys. A partial index includes only rows satisfying its `WHERE` condition.
Existing rows are validated when an index is created. An invalid unique index definition therefore fails if its current rows already contain duplicate keys.
## Syntax
```text
CREATE [UNIQUE] INDEX [IF NOT EXISTS] name
ON table (expression [COLLATE collation] [ASC | DESC], ...)
[WHERE condition]
```
## Examples
### A case-insensitive unique email
Indexing `lower(email)` makes uniqueness apply to the normalized expression. The partial predicate excludes missing addresses:
```sql
CREATE TABLE contacts(id INTEGER PRIMARY KEY, email TEXT);
CREATE UNIQUE INDEX contact_email
ON contacts(lower(email))
WHERE email IS NOT NULL;
INSERT INTO contacts VALUES (1, 'Ada@example.org'), (2, NULL);
```
```sql
SELECT id
FROM contacts
WHERE lower(email) = 'ada@example.org'
FORMAT csv;
```
```text
1
```
Inserting another non-`NULL` email whose lowercase form is `ada@example.org` violates the unique index.
### A compound index
```sql
CREATE TABLE orders(id INTEGER PRIMARY KEY, account_id UInt32, day Date);
CREATE INDEX orders_by_account_day ON orders(account_id, day DESC);
```
The index can support queries constrained by `account_id` and ordered or filtered by `day`. Use [`EXPLAIN QUERY PLAN`](https://coordinatordb.com/docs/reference/statements/explain) to inspect the selected access path for a concrete query.
Remove an index with [`DROP INDEX`](https://coordinatordb.com/docs/reference/statements/drop). Each index must also be maintained when its table changes, so choose indexes for the queries the application actually runs.
---
Source: https://coordinatordb.com/docs/reference/statements/create/database
Language: en
# CREATE DATABASE
CREATE DATABASE registers a persistent server database. Use [`USE`](https://coordinatordb.com/docs/reference/statements/use) to select it for later native requests, or choose it through the HTTP database parameter.
This is a server command. An embedded application opens a database with the `Connection` API instead.
## Syntax
```text
CREATE DATABASE [IF NOT EXISTS] name
```
## Names
Names ignore ASCII case. They must begin with an ASCII letter or underscore, contain only ASCII letters, digits and underscores, and have at most 63 characters. `system` and `none` are reserved in any letter case.
`IF NOT EXISTS` allows the command to succeed when the database is already registered. Creating a database does not select it for the connection.
## Example
### Creating a reporting database
```sql
CREATE DATABASE IF NOT EXISTS reporting;
```
```sql
SELECT name
FROM system.databases
WHERE name = 'reporting'
FORMAT csv;
```
```text
"reporting"
```
Use [`SHOW DATABASES`](https://coordinatordb.com/docs/reference/statements/show) or [`system.databases`](https://coordinatordb.com/docs/reference/system-tables/databases) to inspect the inventory. `DROP DATABASE` is not an SQL command.
---
Source: https://coordinatordb.com/docs/reference/statements/create/table
Language: en
# CREATE TABLE
CREATE TABLE defines a table's columns, value contracts and constraints. A table stores rows until they are changed or deleted; it does not require a ClickHouse table engine declaration.
## Syntax
```text
CREATE [TEMP | TEMPORARY] TABLE [IF NOT EXISTS] [schema.]name
(
column type [column_constraint ...],
...
[, table_constraint ...]
)
[STRICT | WITHOUT ROWID]
CREATE TABLE name AS SELECT ...
```
`STRICT` and `WITHOUT ROWID` can be combined with a comma in either order. `CREATE VIRTUAL TABLE` and modules such as FTS5 are not supported.
## Columns and constraints
Native types validate values on writes and casts. SQL columns permit `NULL` unless declared `NOT NULL`.
Supported constraints include `PRIMARY KEY`, `UNIQUE`, `NOT NULL`, `CHECK`, `DEFAULT` and foreign keys. In an ordinary table, a column declared exactly `INTEGER PRIMARY KEY` aliases the row identifier; `AUTOINCREMENT` is supported. A native `UInt64 PRIMARY KEY` does not have that row-identifier alias contract.
Generated columns can be `VIRTUAL` or `STORED`. `CREATE TABLE AS SELECT` retains projected native declarations and copies values, but does not copy source constraints.
## Examples
### Typed columns and defaults
```sql
CREATE TABLE events
(
id INTEGER PRIMARY KEY,
kind String NOT NULL,
amount Decimal(18, 2) DEFAULT '0.00'
);
INSERT INTO events(id, kind) VALUES (1, 'view');
```
```sql
SELECT id, kind, amount
FROM events
FORMAT csv;
```
```text
1,"view",0.00
```
### A generated value
```sql
CREATE TABLE order_lines
(
id INTEGER PRIMARY KEY,
quantity INTEGER CHECK (quantity > 0),
unit_price INTEGER NOT NULL,
total INTEGER GENERATED ALWAYS AS (quantity * unit_price) STORED
);
INSERT INTO order_lines(id, quantity, unit_price) VALUES (1, 3, 10);
```
```sql
SELECT id, total
FROM order_lines
FORMAT csv;
```
```text
1,30
```
### Creating a table from a query
```sql
CREATE TABLE selected_events AS
SELECT id, kind FROM events WHERE kind = 'view';
```
```sql
SELECT * FROM selected_events
FORMAT csv;
```
```text
1,"view"
```
See [data types](https://coordinatordb.com/docs/reference/data-types), [temporary tables](https://coordinatordb.com/docs/reference/statements/create/table/temporary-table) and [ALTER TABLE](https://coordinatordb.com/docs/reference/statements/alter).
---
Source: https://coordinatordb.com/docs/reference/statements/create/table/temporary-table
Language: en
# Temporary tables
A temporary table belongs to one logical connection and lives in its `temp` namespace. It is useful for staging data or reusing intermediate rows within that connection.
## Syntax
```text
CREATE TEMP TABLE name (column type, ...)
CREATE TEMPORARY TABLE name (column type, ...)
```
A temporary table shadows a table of the same unqualified name in `main`. Qualify the source as `main.name` or `temp.name` when both exist.
A native client connection retains its temporary tables. HTTP requests use separate sessions, so create and use a temporary table in the same HTTP request.
## Example
### Main and temporary tables with the same name
```sql
CREATE TABLE staging(id UInt8);
INSERT INTO main.staging VALUES (1);
CREATE TEMP TABLE staging(id UInt8);
INSERT INTO temp.staging VALUES (7);
```
```sql
SELECT id FROM staging
FORMAT csv;
```
```text
7
```
```sql
SELECT id FROM main.staging
FORMAT csv;
```
```text
1
```
`DROP TABLE temp.staging` removes the temporary table explicitly. Its rows are not a persistent staging area across connections.
---
Source: https://coordinatordb.com/docs/reference/statements/create/view
Language: en
# CREATE VIEW
CREATE VIEW stores a SELECT definition under a table-like name. Querying an ordinary view evaluates that definition against the current source data; the view does not store or refresh result rows.
## Syntax
```text
CREATE [TEMP | TEMPORARY] VIEW [IF NOT EXISTS] name
[(column, ...)]
AS SELECT ...
```
An optional column list names the view's result columns. A view is read-only unless an `INSTEAD OF` trigger handles the requested write. Materialized views are not supported.
## Examples
### Naming a filtered query
```sql
CREATE TABLE items(id INTEGER PRIMARY KEY, active Bool);
INSERT INTO items VALUES (1, true), (2, false);
CREATE VIEW active_items AS
SELECT id FROM items WHERE active;
```
```sql
SELECT *
FROM active_items
ORDER BY id
FORMAT csv;
```
```text
1
```
### Reading changed source data
The view reflects a later update without a refresh command:
```sql
UPDATE items SET active = true WHERE id = 2;
```
```sql
SELECT *
FROM active_items
ORDER BY id
FORMAT csv;
```
```text
1
2
```
Use [`DROP VIEW`](https://coordinatordb.com/docs/reference/statements/drop) to remove the definition. See [`CREATE TABLE AS SELECT`](https://coordinatordb.com/docs/reference/statements/create/table) when a separate stored copy of a query result is required.
---
Source: https://coordinatordb.com/docs/reference/statements/delete
Language: en
# DELETE
DELETE removes rows for which the `WHERE` condition is SQL true. Without `WHERE`, it removes every row while retaining the table definition.
The deletion is applied immediately in the current transaction. Foreign-key actions apply when `foreign_keys` is enabled. Use [`DROP TABLE`](https://coordinatordb.com/docs/reference/statements/drop) to remove the table itself.
## Syntax
```text
DELETE FROM table
[WHERE condition]
[RETURNING expression, ...]
```
`RETURNING` reads the deleted row's values. It does not return the remaining rows.
## Examples
### Removing completed work
```sql
CREATE TABLE queue(id INTEGER PRIMARY KEY, done Bool);
INSERT INTO queue VALUES (1, true), (2, false), (3, true);
```
```sql
DELETE FROM queue
WHERE done
RETURNING id
FORMAT csv;
```
```text
1
3
```
```sql
SELECT id, done
FROM queue
ORDER BY id
FORMAT csv;
```
```text
2,false
```
### Clearing a table
```sql
DELETE FROM queue;
```
```sql
SELECT count(*)
FROM queue
FORMAT csv;
```
```text
0
```
Use [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) when a deletion must be committed or rolled back with other changes.
---
Source: https://coordinatordb.com/docs/reference/statements/detach
Language: en
# DETACH
DETACH removes an attached namespace from an embedded connection. It does not delete the database file. An attachment used by an active transaction cannot be detached.
## Syntax
```text
DETACH [DATABASE] namespace
```
## Interface
Native and HTTP server connections reject DETACH. This command operates on embedded connection namespaces, rather than the managed server database inventory.
## Example
### Using the embedded Connection API
The following application uses an in-memory attachment, so it does not require an existing database file:
```rust
use coordinator::Connection;
fn main() -> coordinator::Result<()> {
let mut db = Connection::open_in_memory()?;
db.execute("ATTACH ':memory:' AS aux; DETACH aux;")?;
let result = db.query("PRAGMA database_list")?;
assert!(result.rows.iter().all(|row| row[1].scalar_text() != "aux"));
Ok(())
}
```
---
Source: https://coordinatordb.com/docs/reference/statements/drop
Language: en
# DROP
DROP removes a schema object. `IF EXISTS` suppresses the error when the named object is absent; it does not suppress other failures.
## Syntax
```text
DROP TABLE [IF EXISTS] [schema.]name
DROP VIEW [IF EXISTS] [schema.]name
DROP INDEX [IF EXISTS] [schema.]name
DROP TRIGGER [IF EXISTS] [schema.]name
```
Dropping a table removes its rows and associated indexes and triggers. Dropping a view removes its query definition. Dropping an index leaves the table rows in place.
`DROP DATABASE` is not a SQL command. Managed server database inventory has a separate management interface.
## Examples
### Removing a table
```sql
CREATE TABLE obsolete(id INTEGER);
DROP TABLE obsolete;
```
```sql
SELECT count(*)
FROM sqlite_schema
WHERE name = 'obsolete'
FORMAT csv;
```
```text
0
```
### Removing an optional object
```sql
DROP TABLE IF EXISTS optional_staging;
```
The statement succeeds even when `optional_staging` does not exist.
Use [`DELETE`](https://coordinatordb.com/docs/reference/statements/delete) to remove rows while retaining a table's definition.
---
Source: https://coordinatordb.com/docs/reference/statements/explain
Language: en
# EXPLAIN
EXPLAIN describes how CoordinatorDB will execute a statement. Use `EXPLAIN QUERY PLAN` for an access-plan tree, or `EXPLAIN ANALYZE` to execute the statement and collect runtime measurements.
## Forms
* `EXPLAIN QUERY PLAN` returns the selected access plan without executing the statement.
* Plain `EXPLAIN` returns `explain_key`/`explain_value` rows describing the plan and does not run the statement.
* `EXPLAIN ANALYZE` executes a SELECT or data-changing statement once and returns an analyzed plan. It does not return the underlying query's result rows.
For analyzed writes, the changes take effect. Use ordinary transaction controls when a write should be rolled back after measurement.
CoordinatorDB does not support ClickHouse `EXPLAIN PIPELINE` or `EXPLAIN AST` syntax.
## Syntax
```text
EXPLAIN QUERY PLAN statement
EXPLAIN statement
EXPLAIN ANALYZE statement
```
## Example
### Looking up a row by primary key
```sql
CREATE TABLE lookup(id INTEGER PRIMARY KEY,v TEXT);
EXPLAIN QUERY PLAN SELECT v FROM lookup WHERE id=1;
```
```text
OK
┌─id─┬─parent─┬─notused─┬─detail────────────────────────────────────────────────────┐
│ 1 │ 0 │ 0 │ PROJECTION v │
│ 2 │ 1 │ 0 │ ROWID_SCAN Table: lookup; Lookup: Eq(Literal(Integer(1))) │
└────┴────────┴─────────┴───────────────────────────────────────────────────────────┘
(2 rows)
```
---
Source: https://coordinatordb.com/docs/reference/statements/in
Language: en
# IN
IN tests whether a value occurs in a list or query result. `NOT IN` negates the result using SQL three-valued logic.
## Syntax
```text
expression [NOT] IN (value, ...)
expression [NOT] IN (SELECT ...)
expression [NOT] IN [schema.]table
```
The left side can be a scalar or a row value. Its field count must match the right side. Table shorthand is equivalent to `IN (SELECT * FROM table)` and therefore uses every column of that table.
## NULL and empty input
A matching value makes `IN` true. If no value matches and the right side contains `NULL`, the result can be `NULL` instead of false. A `NULL` left operand also generally gives `NULL` for a nonempty right side.
An empty right side makes `IN` false and `NOT IN` true, including when the left side is `NULL`. Use `EXISTS` for a correlated presence test when the selected values themselves are irrelevant.
## Examples
### Lists and missing values
```sql
SELECT 2 IN (1, 2, 3),
4 IN (1, NULL),
4 NOT IN (1, 2, 3)
FORMAT csv;
```
```text
1,\N,1
```
### Table shorthand
```sql
CREATE TABLE allowed(value INTEGER);
INSERT INTO allowed VALUES (1), (2);
```
```sql
SELECT 2 IN allowed, 3 NOT IN main.allowed
FORMAT csv;
```
```text
1,1
```
### An empty result
```sql
SELECT NULL IN (SELECT value FROM allowed WHERE 0),
NULL NOT IN (SELECT value FROM allowed WHERE 0)
FORMAT csv;
```
```text
0,1
```
See [`WHERE`](https://coordinatordb.com/docs/reference/statements/select/where) for filtering rows with membership predicates.
---
Source: https://coordinatordb.com/docs/reference/statements/insert-into
Language: en
# INSERT INTO
INSERT adds rows to a table. Values can come from literal expressions, a SELECT, column defaults, a registered input format or files supplied by the native client.
An explicit column list maps input values to the named columns. Omitted columns receive their SQL DEFAULT expression or the applicable default behavior. Declared types and constraints validate every inserted value.
## Syntax
```text
INSERT [OR ABORT | OR FAIL | OR IGNORE | OR REPLACE | OR ROLLBACK]
INTO table [(column, ...)]
VALUES (value, ...) [, ...]
[ON CONFLICT ...]
[RETURNING expression, ...]
INSERT INTO table [(column, ...)] SELECT ...
INSERT INTO table DEFAULT VALUES
INSERT INTO table [(column, ...)] [SETTINGS ...] FORMAT name
INSERT INTO table [(column, ...)]
FROM INFILE 'path' [COMPRESSION 'type'] [SETTINGS ...] [FORMAT name]
```
## Examples
### Inserting selected columns
```sql
CREATE TABLE products
(
id INTEGER PRIMARY KEY,
name String NOT NULL,
price Decimal(18, 2) DEFAULT '0.00'
);
INSERT INTO products(id, name) VALUES (1, 'Notebook'), (2, 'Pen');
```
```sql
SELECT id, name, price
FROM products
ORDER BY id
FORMAT csv;
```
```text
1,"Notebook",0.00
2,"Pen",0.00
```
### Inserting a query result
```sql
CREATE TABLE archived_products AS SELECT * FROM products WHERE 0;
INSERT INTO archived_products
SELECT * FROM products WHERE id = 1;
```
```sql
SELECT id, name
FROM archived_products
FORMAT csv;
```
```text
1,"Notebook"
```
### Updating a conflicting row
`excluded` exposes the proposed inserted row inside `DO UPDATE`:
```sql
INSERT INTO products(id, name, price)
VALUES (1, 'Notebook', '12.50')
ON CONFLICT(id) DO UPDATE SET price = excluded.price
RETURNING id, price
FORMAT csv;
```
```text
1,12.50
```
`ON CONFLICT ... DO NOTHING` skips a conflicting row. Multiple conflict clauses and the listed `OR` conflict policies are supported.
## Formatted input
`INSERT ... FORMAT` decodes input rows with a registered format. Place `SETTINGS` before the format name: the remaining request bytes are data, including any semicolons. Send later SQL in a separate request.
```sql
CREATE TABLE imported_orders(id UInt32, amount UInt32);
```
```sql
INSERT INTO imported_orders FORMAT csv
1,100
2,60
```
```sql
SELECT id, amount
FROM imported_orders
ORDER BY id
FORMAT csv;
```
```text
1,100
2,60
```
Formatted input is the last statement in its request and does not accept `RETURNING` or `ON CONFLICT` clauses. The `OR` conflict policies still apply. Omitted format fields can use implicit type defaults according to the selected format and settings.
`FROM INFILE` reads files on the native client's machine and supplies their decoded rows to the server. See [bulk inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and the [format reference](https://coordinatordb.com/docs/reference/formats) for supported sources and options.
---
Source: https://coordinatordb.com/docs/reference/statements/rename
Language: en
# Rename a table
Rename a table with `ALTER TABLE ... RENAME TO`. Its stored rows remain available under the new name.
## Syntax
```text
ALTER TABLE old_name RENAME TO new_name
```
The ClickHouse `RENAME TABLE` command is not supported. Use [`RENAME COLUMN`](https://coordinatordb.com/docs/reference/statements/alter/column) to change a column name instead.
## Example
### Renaming an events table
```sql
CREATE TABLE old_events(id INTEGER, kind String);
INSERT INTO old_events VALUES (1, 'view');
ALTER TABLE old_events RENAME TO new_events;
```
```sql
SELECT id, kind
FROM new_events
FORMAT csv;
```
```text
1,"view"
```
Later statements must use `new_events`. A conflicting destination name or an incompatible schema dependency can prevent the rename.
---
Source: https://coordinatordb.com/docs/reference/statements/select
Language: en
# SELECT
SELECT reads rows from tables or other sources and evaluates expressions. It supports joins, subqueries, common table expressions, aggregate functions, window functions and set operations.
A SELECT without `FROM` evaluates expressions once. Without `ORDER BY`, result row order is unspecified.
## Syntax
```text
[WITH ...]
SELECT [ALL | DISTINCT] expression [AS alias] [, ...]
[FROM source]
[WHERE condition]
[GROUP BY expression, ...]
[HAVING condition]
[WINDOW name AS (...), ...]
[ORDER BY expression [ASC | DESC], ...]
[LIMIT count [OFFSET offset]]
[SETTINGS ...]
[FORMAT name]
```
## Query clauses
`FROM` chooses the input, `WHERE` filters its rows, `GROUP BY` forms groups and `HAVING` filters aggregate results. `ORDER BY` defines output order and `LIMIT` selects a bounded result. `FORMAT` controls server-side encoding.
Use aliases to name expressions and qualify column names when several sources expose the same name. The format and setting clauses are server extensions; the embedded library returns values without an encoding clause.
## Examples
### Evaluating expressions
```sql
SELECT 2 + 3 AS result, upper('hello') AS greeting
FORMAT csv;
```
```text
5,"HELLO"
```
### Grouped totals
```sql
CREATE TABLE sales (region TEXT, amount INTEGER);
INSERT INTO sales VALUES ('East', 10), ('East', 20), ('West', 5);
```
```sql
SELECT region, count(*) AS orders, sum(amount) AS total
FROM sales
GROUP BY region
HAVING sum(amount) >= 10
ORDER BY total DESC, region
FORMAT csv;
```
```text
"East",2,30
```
Use [window functions](https://coordinatordb.com/docs/reference/functions/window-functions) when a calculation must retain individual rows rather than collapse each group.
## Clause reference
* [ALL](https://coordinatordb.com/docs/reference/statements/select/all)
* [DISTINCT](https://coordinatordb.com/docs/reference/statements/select/distinct)
* [EXCEPT](https://coordinatordb.com/docs/reference/statements/select/except)
* [FORMAT](https://coordinatordb.com/docs/reference/statements/select/format)
* [FROM](https://coordinatordb.com/docs/reference/statements/select/from)
* [GROUP BY](https://coordinatordb.com/docs/reference/statements/select/group-by)
* [HAVING](https://coordinatordb.com/docs/reference/statements/select/having)
* [INTERSECT](https://coordinatordb.com/docs/reference/statements/select/intersect)
* [JOIN](https://coordinatordb.com/docs/reference/statements/select/join)
* [LIMIT](https://coordinatordb.com/docs/reference/statements/select/limit)
* [OFFSET](https://coordinatordb.com/docs/reference/statements/select/offset)
* [ORDER BY](https://coordinatordb.com/docs/reference/statements/select/order-by)
* [UNION](https://coordinatordb.com/docs/reference/statements/select/union)
* [WHERE](https://coordinatordb.com/docs/reference/statements/select/where)
* [WITH](https://coordinatordb.com/docs/reference/statements/select/with)
---
Source: https://coordinatordb.com/docs/reference/statements/select/all
Language: en
# ALL
`ALL` keeps duplicate result rows. It is the default behavior of a SELECT, so `SELECT ALL` and `SELECT` have the same meaning.
`UNION ALL` also preserves duplicates from both inputs. Use [`DISTINCT`](https://coordinatordb.com/docs/reference/statements/select/distinct) or [`UNION`](https://coordinatordb.com/docs/reference/statements/select/union) when duplicate rows should be removed.
## Syntax
```text
SELECT ALL expressions FROM source
query UNION ALL query
```
## Examples
### Retaining repeated values
```sql
CREATE TABLE visits (country TEXT);
INSERT INTO visits VALUES ('GB'), ('GB'), ('FR');
```
```sql
SELECT ALL country
FROM visits
ORDER BY country
FORMAT csv;
```
```text
"FR"
"GB"
"GB"
```
### Appending query results
```sql
SELECT 1 AS value
UNION ALL
SELECT 1
FORMAT csv;
```
```text
1
1
```
`ALL` does not define an output order. Add a final `ORDER BY` when order matters.
---
Source: https://coordinatordb.com/docs/reference/statements/select/distinct
Language: en
# DISTINCT
`DISTINCT` removes duplicate rows from the projected query result. It applies to all selected expressions together, rather than to one column independently.
For duplicate elimination, `NULL` is equal to another `NULL`. Text equality follows the expression's collation. `DISTINCT ON` is not supported.
## Syntax
```text
SELECT DISTINCT expression [, ...]
FROM source
```
## Examples
### Unique combinations
The same country can occur more than once when the complete projected rows differ:
```sql
CREATE TABLE visits (country TEXT, device TEXT);
INSERT INTO visits VALUES ('GB', 'desktop'), ('GB', 'desktop'), ('GB', 'mobile'), ('FR', 'mobile');
```
```sql
SELECT DISTINCT country, device
FROM visits
ORDER BY country, device
FORMAT csv;
```
```text
"FR","mobile"
"GB","desktop"
"GB","mobile"
```
### Duplicate NULL values
```sql
CREATE TABLE readings (value INTEGER);
INSERT INTO readings VALUES (1), (1), (NULL), (NULL);
```
```sql
SELECT DISTINCT value
FROM readings
ORDER BY value
FORMAT csv;
```
```text
\N
1
```
For a count of unique non-`NULL` values, use [`count(DISTINCT value)`](https://coordinatordb.com/docs/reference/functions/aggregate-functions/count).
---
Source: https://coordinatordb.com/docs/reference/statements/select/except
Language: en
# EXCEPT
EXCEPT keeps a row from the left input only when it does not occur in the right input. Repeated copies are removed. `EXCEPT ALL` is not supported.
## Syntax
```text
query EXCEPT query
[ORDER BY expression, ...]
[LIMIT count [OFFSET offset]]
```
Both inputs must return the same number of columns. Result column names come from the first query. Duplicate comparison applies to whole rows; `NULL` is equal to another `NULL` for this purpose.
A final `ORDER BY` or `LIMIT` applies to the combined result. Set operators at the same query level are evaluated from left to right. Put a nested query in a FROM subquery when a different grouping is needed.
## Example
### Combining two sets of identifiers
```sql
CREATE TABLE first_set (id INTEGER);
INSERT INTO first_set VALUES (1), (2), (2), (3);
CREATE TABLE second_set (id INTEGER);
INSERT INTO second_set VALUES (2), (4);
```
```sql
SELECT id FROM first_set
EXCEPT
SELECT id FROM second_set
ORDER BY id
FORMAT csv;
```
```text
1
3
```
This set operator is separate from ClickHouse column-selection syntax such as `SELECT * EXCEPT column`, which is not supported.
See [`UNION`](https://coordinatordb.com/docs/reference/statements/select/union), [`INTERSECT`](https://coordinatordb.com/docs/reference/statements/select/intersect) and [`EXCEPT`](https://coordinatordb.com/docs/reference/statements/select/except) for the other set operations.
---
Source: https://coordinatordb.com/docs/reference/statements/select/format
Language: en
# FORMAT
`FORMAT` chooses the encoding used for a query result. It is available through the native and HTTP server interfaces. The embedded `Connection` API returns typed values directly.
If no format is specified, the server uses `pretty_compact`.
## Syntax
```text
SELECT ... [SETTINGS setting = value, ...] FORMAT format_name
SELECT ... FORMAT format_name [SETTINGS setting = value, ...]
```
Format names are case-insensitive and use snake_case. For example, use `json_each_row`; `JSONEachRow` is not an alias.
`SETTINGS` in this context applies format options to one statement. It does not persist them as database settings. Each format's reference page lists its available options.
## Examples
### One JSON object per row
```sql
CREATE TABLE messages (id INTEGER, message TEXT);
INSERT INTO messages VALUES (1, 'hello'), (2, 'goodbye');
```
```sql
SELECT id, message
FROM messages
ORDER BY id
FORMAT json_each_row;
```
```text
{"id":1,"message":"hello"}
{"id":2,"message":"goodbye"}
```
### A custom CSV separator
```sql
SELECT 1 AS id, 'hello' AS message
SETTINGS csv_separator = ';'
FORMAT csv;
```
```text
1;"hello"
```
Formats can support input, output or both. An input-only format cannot encode a SELECT result. Use [`system.formats`](https://coordinatordb.com/docs/reference/system-tables/formats) to inspect directions, or browse the [format reference](https://coordinatordb.com/docs/reference/formats).
For `INSERT ... FORMAT`, place settings before the format name because the following bytes are input data. See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into).
---
Source: https://coordinatordb.com/docs/reference/statements/select/from
Language: en
# FROM
`FROM` supplies the rows read by a SELECT. A source can be a table, a view, a subquery or a table-valued function. Several sources can be combined with a [`JOIN`](https://coordinatordb.com/docs/reference/statements/select/join).
A SELECT without `FROM` evaluates expressions once and returns one row.
## Syntax
```text
FROM [schema.]table [AS alias]
FROM (query) [AS alias]
FROM table_function(arguments) [AS alias]
```
An alias gives a source a short name and disambiguates columns shared by several sources.
## Qualified names
The embedded engine resolves namespaces such as `main`, `temp` and an attached name. `main.orders` names the table in the main namespace.
A server SELECT source can use `database.schema.table` to select a managed database for that statement. This does not change the session's [`USE`](https://coordinatordb.com/docs/reference/statements/use) selection.
## Examples
### Reading a subquery
```sql
CREATE TABLE orders (id INTEGER, amount INTEGER);
INSERT INTO orders VALUES (1, 10), (2, 20), (3, 30);
```
```sql
SELECT selected.id, selected.amount
FROM (
SELECT id, amount
FROM orders
WHERE amount >= 20
) AS selected
ORDER BY selected.id
FORMAT csv;
```
```text
2,20
3,30
```
### Generating rows
```sql
SELECT generate_series AS number
FROM generate_series(1, 3)
FORMAT csv;
```
```text
1
2
3
```
Other table functions expand JSON documents or read confined server files. See [table functions](https://coordinatordb.com/docs/reference/functions/table-functions) for their syntax and restrictions.
---
Source: https://coordinatordb.com/docs/reference/statements/select/group-by
Language: en
# GROUP BY
`GROUP BY` combines rows with equal grouping values and calculates aggregates independently for each group. The result usually contains one row per distinct grouping key.
All `NULL` values in a grouping key belong to the same group. Text grouping uses the selected collation.
## Syntax
```text
SELECT key_expression, aggregate_function(value)
FROM source
[WHERE condition]
GROUP BY key_expression [, ...]
[HAVING aggregate_condition]
```
Grouping can use expressions or result-column positions. Explicit expressions are easier to maintain when the projection changes. `GROUP BY` does not sort the final result; use `ORDER BY`.
`ROLLUP`, `CUBE` and `GROUPING SETS` are not supported.
## Examples
### Totals per region
```sql
CREATE TABLE sales (region TEXT, amount INTEGER);
INSERT INTO sales VALUES ('East', 10), ('East', 20), ('West', 5);
```
```sql
SELECT region, count(*) AS orders, sum(amount) AS total
FROM sales
GROUP BY region
ORDER BY region
FORMAT csv;
```
```text
"East",2,30
"West",1,5
```
### Grouping an expression
```sql
CREATE TABLE visits (country TEXT);
INSERT INTO visits VALUES ('GB'), ('gb'), ('FR'), (NULL), (NULL);
```
```sql
SELECT lower(country) AS country, count(*) AS visits
FROM visits
GROUP BY lower(country)
ORDER BY country NULLS LAST
FORMAT csv;
```
```text
"fr",1
"gb",2
\N,2
```
Without `GROUP BY`, an aggregate query treats the whole input as one group, including empty input. A grouped query with no admitted rows returns no groups.
See [aggregate functions](https://coordinatordb.com/docs/reference/functions/aggregate-functions) and [`HAVING`](https://coordinatordb.com/docs/reference/statements/select/having).
---
Source: https://coordinatordb.com/docs/reference/statements/select/having
Language: en
# HAVING
`HAVING` filters the groups produced by an aggregate query. It can use aggregate expressions, such as `sum(amount) > 100`, because it runs after the group has been calculated.
Use [`WHERE`](https://coordinatordb.com/docs/reference/statements/select/where) to filter individual input rows before aggregation. A query can use both clauses.
## Syntax
```text
SELECT grouping_key, aggregate_function(value)
FROM source
[WHERE row_condition]
GROUP BY grouping_key
HAVING aggregate_condition
```
A group is retained only when the condition is SQL true. False and `NULL` conditions remove the group.
## Example
### Regions with enough paid revenue
`WHERE` excludes pending orders; `HAVING` then excludes regions whose paid total is too small:
```sql
CREATE TABLE orders (region TEXT, status TEXT, amount INTEGER);
INSERT INTO orders VALUES ('East', 'paid', 60),
('East', 'paid', 70),
('West', 'paid', 40),
('West', 'pending', 200);
```
```sql
SELECT region, sum(amount) AS paid_total
FROM orders
WHERE status = 'paid'
GROUP BY region
HAVING sum(amount) >= 100
ORDER BY region
FORMAT csv;
```
```text
"East",130
```
See [`GROUP BY`](https://coordinatordb.com/docs/reference/statements/select/group-by) for grouping expressions and [aggregate functions](https://coordinatordb.com/docs/reference/functions/aggregate-functions) for the calculations available in `HAVING`.
---
Source: https://coordinatordb.com/docs/reference/statements/select/intersect
Language: en
# INTERSECT
INTERSECT keeps a row only when it occurs in both inputs. Repeated copies are removed. `INTERSECT ALL` is not supported.
## Syntax
```text
query INTERSECT query
[ORDER BY expression, ...]
[LIMIT count [OFFSET offset]]
```
Both inputs must return the same number of columns. Result column names come from the first query. Duplicate comparison applies to whole rows; `NULL` is equal to another `NULL` for this purpose.
A final `ORDER BY` or `LIMIT` applies to the combined result. Set operators at the same query level are evaluated from left to right. Put a nested query in a FROM subquery when a different grouping is needed.
## Example
### Combining two sets of identifiers
```sql
CREATE TABLE first_set (id INTEGER);
INSERT INTO first_set VALUES (1), (2), (2), (3);
CREATE TABLE second_set (id INTEGER);
INSERT INTO second_set VALUES (2), (4);
```
```sql
SELECT id FROM first_set
INTERSECT
SELECT id FROM second_set
ORDER BY id
FORMAT csv;
```
```text
2
```
See [`UNION`](https://coordinatordb.com/docs/reference/statements/select/union), [`INTERSECT`](https://coordinatordb.com/docs/reference/statements/select/intersect) and [`EXCEPT`](https://coordinatordb.com/docs/reference/statements/select/except) for the other set operations.
---
Source: https://coordinatordb.com/docs/reference/statements/select/join
Language: en
# JOIN
A JOIN combines rows from two sources using a matching condition. Each matching pair produces a result row. If one key has several matches, every matching pair is included.
## Syntax
```text
left_source
[INNER | LEFT [OUTER] | RIGHT [OUTER] | FULL [OUTER] | CROSS]
JOIN right_source
[ON condition | USING (column, ...)]
```
## Join types
| Type | Result |
| ------------ | ---------------------------------------------------- |
| `INNER JOIN` | Matching row pairs only; this is the default JOIN. |
| `LEFT JOIN` | Matching pairs plus unmatched left rows. |
| `RIGHT JOIN` | Matching pairs plus unmatched right rows. |
| `FULL JOIN` | Matching pairs plus unmatched rows from either side. |
| `CROSS JOIN` | Every pair of left and right rows. |
Outer joins fill the missing side with SQL `NULL`. An equality condition does not match `NULL` keys with one another.
`ON` accepts a matching expression. `USING (id)` matches shared columns by name. A `NATURAL` join uses all shared column names, so changes to a schema can change its matching condition; explicit conditions make the intended keys visible.
ClickHouse `ANY`, `ASOF` and distributed join modifiers are not supported.
## Examples
### Retaining customers without orders
```sql
CREATE TABLE customers (id INTEGER, name TEXT);
INSERT INTO customers VALUES (1, 'Ada'), (2, 'Grace');
CREATE TABLE orders (customer_id INTEGER, amount INTEGER);
INSERT INTO orders VALUES (1, 40), (1, 60);
```
```sql
SELECT customers.id, customers.name, orders.amount
FROM customers
LEFT JOIN orders ON orders.customer_id = customers.id
ORDER BY customers.id, orders.amount
FORMAT csv;
```
```text
1,"Ada",40
1,"Ada",60
2,"Grace",\N
```
### Matching a shared column
```sql
CREATE TABLE products (id INTEGER, name TEXT);
INSERT INTO products VALUES (1, 'Book'), (2, 'Pen');
CREATE TABLE stock (id INTEGER, quantity INTEGER);
INSERT INTO stock VALUES (1, 5), (2, 20);
```
```sql
SELECT products.id, name, quantity
FROM products
JOIN stock USING (id)
ORDER BY products.id
FORMAT csv;
```
```text
1,"Book",5
2,"Pen",20
```
A condition in `WHERE` runs after the join. For example, filtering a nullable right-side column there can remove the unmatched rows of a LEFT JOIN. Put conditions that determine right-side matches in `ON` when unmatched left rows must be retained.
---
Source: https://coordinatordb.com/docs/reference/statements/select/limit
Language: en
# LIMIT
`LIMIT` returns at most the requested number of rows. If the query also has `ORDER BY`, it selects rows from that ordered result. An optional offset skips rows first.
## Syntax
```text
LIMIT count [OFFSET offset]
LIMIT offset, count
```
The comma form reverses the argument order: `LIMIT 1, 2` skips one row and returns up to two rows. `LIMIT 2 OFFSET 1` means the same thing.
A negative count removes the SQL row limit. A negative offset acts as zero. Standalone `OFFSET` and ClickHouse `LIMIT BY`/`WITH TIES` syntax are not supported.
`LIMIT` controls this query's result. It is separate from the server's request-wide `max_result_rows` setting, which can still reject a result that exceeds its ceiling.
## Examples
### Selecting the highest values
```sql
CREATE TABLE scores (name TEXT, points INTEGER);
INSERT INTO scores VALUES ('Ada', 100), ('Grace', 100), ('Linus', 80), ('Sam', 60);
```
```sql
SELECT name, points
FROM scores
ORDER BY points DESC, name
LIMIT 2
FORMAT csv;
```
```text
"Ada",100
"Grace",100
```
### Skipping the first row
```sql
SELECT generate_series
FROM generate_series(1, 5)
ORDER BY generate_series
LIMIT 2 OFFSET 1
FORMAT csv;
```
```text
2
3
```
Use ordering keys that break ties when the exact selected rows matter. See [`OFFSET`](https://coordinatordb.com/docs/reference/statements/select/offset) for page offsets.
---
Source: https://coordinatordb.com/docs/reference/statements/select/offset
Language: en
# OFFSET
`OFFSET` skips a number of rows before `LIMIT` returns the requested page. It is used together with `LIMIT`; a standalone `OFFSET` clause is not supported.
## Syntax
```text
LIMIT count OFFSET offset
```
A negative offset is treated as zero. Use `LIMIT -1 OFFSET offset` to skip rows without imposing a SQL row count limit.
Include an `ORDER BY` whose keys break ties. Without a defined order, the rows skipped by an offset are unspecified. Concurrent changes to the selected data can also shift page boundaries between separate queries.
## Examples
### Reading the second page
With two rows per page, skip the first two rows:
```sql
SELECT generate_series AS id
FROM generate_series(1, 5)
ORDER BY generate_series
LIMIT 2 OFFSET 2
FORMAT csv;
```
```text
3
4
```
### Skipping rows without a count limit
```sql
SELECT generate_series AS id
FROM generate_series(1, 5)
ORDER BY generate_series
LIMIT -1 OFFSET 3
FORMAT csv;
```
```text
4
5
```
See [`LIMIT`](https://coordinatordb.com/docs/reference/statements/select/limit) for the equivalent comma syntax.
---
Source: https://coordinatordb.com/docs/reference/statements/select/order-by
Language: en
# ORDER BY
`ORDER BY` sorts the query result by one or more expressions. The first expression is compared first; later expressions break ties.
Without `ORDER BY`, result order is unspecified. Use a unique tie breaker when `LIMIT` or `OFFSET` must return a repeatable page.
## Syntax
```text
ORDER BY expression [COLLATE collation] [ASC | DESC]
[NULLS FIRST | NULLS LAST] [, ...]
```
* `ASC` — Ascending order; the default.
* `DESC` — Descending order.
* `NULLS FIRST` or `NULLS LAST` — Explicitly places missing values. By default, `NULL` precedes other values in ascending order.
* `COLLATE` — Selects text comparison rules. `BINARY` uses the ordinary comparison; `NOCASE` folds ASCII case and `RTRIM` ignores trailing spaces.
Ordering can use a result alias or a result-column position. An `ORDER BY` inside `OVER` defines a window's calculation order and does not replace the outer ordering.
## Examples
### Sorting by total and then name
```sql
CREATE TABLE accounts (name TEXT, total INTEGER);
INSERT INTO accounts VALUES ('Grace', 100), ('Ada', 100), ('Sam', 80);
```
```sql
SELECT name, total
FROM accounts
ORDER BY total DESC, name ASC
FORMAT csv;
```
```text
"Ada",100
"Grace",100
"Sam",80
```
### Case-insensitive text and NULL placement
```sql
CREATE TABLE labels (value TEXT);
INSERT INTO labels VALUES ('b'), ('A'), (NULL);
```
```sql
SELECT value
FROM labels
ORDER BY value COLLATE NOCASE NULLS LAST
FORMAT csv;
```
```text
"A"
"b"
\N
```
See [`LIMIT`](https://coordinatordb.com/docs/reference/statements/select/limit) for selecting a bounded sorted result.
---
Source: https://coordinatordb.com/docs/reference/statements/select/union
Language: en
# UNION
UNION appends both inputs and removes duplicate complete rows. `UNION ALL` appends the inputs while retaining every duplicate.
## Syntax
```text
query UNION [ALL] query
[ORDER BY expression, ...]
[LIMIT count [OFFSET offset]]
```
Both inputs must return the same number of columns. Result column names come from the first query. Duplicate comparison applies to whole rows; `NULL` is equal to another `NULL` for this purpose.
A final `ORDER BY` or `LIMIT` applies to the combined result. Set operators at the same query level are evaluated from left to right. Put a nested query in a FROM subquery when a different grouping is needed.
## Example
### Combining two sets of identifiers
```sql
CREATE TABLE first_set (id INTEGER);
INSERT INTO first_set VALUES (1), (2);
CREATE TABLE second_set (id INTEGER);
INSERT INTO second_set VALUES (2), (3);
```
```sql
SELECT id FROM first_set
UNION
SELECT id FROM second_set
ORDER BY id
FORMAT csv;
```
```text
1
2
3
```
### Retaining duplicates
```sql
SELECT 1 AS id
UNION ALL
SELECT 1
FORMAT csv;
```
```text
1
1
```
See [`UNION`](https://coordinatordb.com/docs/reference/statements/select/union), [`INTERSECT`](https://coordinatordb.com/docs/reference/statements/select/intersect) and [`EXCEPT`](https://coordinatordb.com/docs/reference/statements/select/except) for the other set operations.
---
Source: https://coordinatordb.com/docs/reference/statements/select/where
Language: en
# WHERE
The `WHERE` clause selects the input rows used by a query. A row is retained only when its condition is SQL true. False and `NULL` results are excluded.
`WHERE` is evaluated before grouping. To filter an aggregate result, use [`HAVING`](https://coordinatordb.com/docs/reference/statements/select/having).
## Syntax
```text
SELECT expressions
FROM source
WHERE condition
```
Combine conditions with `AND`, `OR` and `NOT`. Parentheses make the intended precedence explicit. Comparisons can use columns, expressions, parameters and subqueries.
## Examples
### Selecting matching orders
```sql
CREATE TABLE orders (id INTEGER, status TEXT, amount INTEGER);
INSERT INTO orders VALUES (1, 'paid', 100), (2, 'pending', 200), (3, 'paid', 40);
```
```sql
SELECT id, amount
FROM orders
WHERE status = 'paid' AND amount >= 50
ORDER BY id
FORMAT csv;
```
```text
1,100
```
### Testing missing values
`value = NULL` does not select missing values. Use `IS NULL`:
```sql
CREATE TABLE contacts (id INTEGER, email TEXT);
INSERT INTO contacts VALUES (1, 'ada@example.org'), (2, NULL);
```
```sql
SELECT id
FROM contacts
WHERE email IS NULL
FORMAT csv;
```
```text
2
```
See [`IN`](https://coordinatordb.com/docs/reference/statements/in) for membership tests and [comparison functions](https://coordinatordb.com/docs/reference/functions/regular-functions/comparison-functions) for related predicates.
---
Source: https://coordinatordb.com/docs/reference/statements/select/with
Language: en
# WITH
`WITH` defines named subqueries, called common table expressions or CTEs, for one statement. A CTE can make a multi-stage query easier to read and can be referenced as a table source.
## Syntax
```text
WITH [RECURSIVE]
name [(column, ...)] AS [MATERIALIZED | NOT MATERIALIZED] (query)
[, ...]
query
```
The optional column list gives names to the CTE's result columns. Each definition is scoped to the statement. `WITH` can also precede supported data-changing statements.
`MATERIALIZED` and `NOT MATERIALIZED` are accepted but currently do not change execution behavior. CoordinatorDB uses subquery CTE syntax; ClickHouse-style scalar expressions in `WITH` are not supported.
## Examples
### Summarizing a grouped result
```sql
WITH orders(region, amount) AS
(
VALUES ('East', 10), ('East', 20), ('West', 5)
),
region_totals AS
(
SELECT region, sum(amount) AS total
FROM orders
GROUP BY region
)
SELECT region, total
FROM region_totals
WHERE total >= 10
ORDER BY region
FORMAT csv;
```
```text
"East",30
```
### A recursive sequence
A recursive CTE combines an initial result with a term that refers to the CTE itself:
```sql
WITH RECURSIVE sequence(number) AS
(
VALUES (1)
UNION ALL
SELECT number + 1
FROM sequence
WHERE number < 5
)
SELECT number
FROM sequence
ORDER BY number
FORMAT csv;
```
```text
1
2
3
4
5
```
The recursive term needs a termination condition. Without one, the query can continue until a request resource limit is reached. Use an outer `ORDER BY` to define the final result order.
---
Source: https://coordinatordb.com/docs/reference/statements/set
Language: en
# SET
SET saves a database setting and applies it to connected clients before later requests. A database must be selected first.
Database management changes require autocommit and no active transactions in the selected database. Resource limits are sampled once per request, so a SET within a batch changes defaults for later requests.
Values are validated before they are persisted. Configured server XML ceilings still limit the effective setting; inspect [`system.settings`](https://coordinatordb.com/docs/reference/system-tables/settings) or [`SHOW SETTINGS`](https://coordinatordb.com/docs/reference/statements/show) to see the effective values.
## Syntax
```text
SET setting_name = value
```
## Supported names
* `log_queries`
* `log_queries_min_query_duration_ms`
* `max_execution_time`
* `max_memory_usage`
* `max_result_rows`
* `max_response_bytes`
* `max_threads`
The four connection/header settings use `PRAGMA` or validated `system.settings` writes instead. Consult the [database settings reference](https://coordinatordb.com/docs/reference/settings/session-settings) for types, units and defaults.
## Example
### Enabling query logging
```sql
SET log_queries = 1;
```
```sql
SELECT name, value
FROM system.settings
WHERE name = 'log_queries'
FORMAT csv;
```
```text
"log_queries","1"
```
## SET and SETTINGS
`SET` persists a database setting. A statement `SETTINGS` clause configures data-format options for one statement and does not persist them. Format options such as `csv_separator` are not accepted as database `SET` names.
See [format settings](https://coordinatordb.com/docs/reference/settings/formats) for those statement options.
---
Source: https://coordinatordb.com/docs/reference/statements/show
Language: en
# SHOW
SHOW commands provide a short form of server introspection. Use the corresponding system tables when the result needs a filter, projection or ordering.
## Syntax
```text
SHOW DATABASES
SHOW TABLES
SHOW SETTINGS
SHOW SYSTEM TABLES
```
## Available results
| Command | Scope |
| -------------------- | ------------------------------------------------------------ |
| `SHOW DATABASES` | Registered server databases; no database selection required. |
| `SHOW TABLES` | Tables and views in the selected database. |
| `SHOW SETTINGS` | Effective settings of the selected database. |
| `SHOW SYSTEM TABLES` | Available system relations; no database selection required. |
`SHOW TABLES` and `SHOW SETTINGS` require a selected database. Server SHOW commands do not take a `FORMAT` clause. Query `system.databases`, `system.tables`, `system.settings` or `system.system_tables` for formatted SQL results.
## Example
### Listing system relations
```sql
SHOW SYSTEM TABLES;
```
```text
┌─schema_name─┬─table_name────┐
│ system │ columns │
│ system │ databases │
│ system │ formats │
│ system │ functions │
│ system │ processes │
│ system │ query_log │
│ system │ settings │
│ system │ system_tables │
│ system │ tables │
└─────────────┴───────────────┘
(9 rows)
```
---
Source: https://coordinatordb.com/docs/reference/statements/update
Language: en
# UPDATE
UPDATE assigns new values to existing rows. Its expressions can read the row's old values, so an assignment such as `quantity = quantity - 1` adjusts the current quantity.
The update is applied immediately as part of the current transaction. New values must satisfy column types and constraints. Without `WHERE`, every row is updated.
## Syntax
```text
UPDATE [OR conflict_policy] table
SET column = expression [, ...]
[FROM sources]
[WHERE condition]
[RETURNING expression, ...]
```
`FROM` supplies related rows for a joined update. `RETURNING` exposes values after the update. Use transaction controls to group the change with other statements.
## Examples
### Adjusting a quantity
```sql
CREATE TABLE stock(id INTEGER PRIMARY KEY, quantity INTEGER);
INSERT INTO stock VALUES (1, 5), (2, 3);
```
```sql
UPDATE stock
SET quantity = quantity - 1
WHERE id = 1
RETURNING id, quantity
FORMAT csv;
```
```text
1,4
```
### Updating from another source
```sql
CREATE TABLE adjustments(id INTEGER, delta INTEGER);
INSERT INTO adjustments VALUES (1, 2), (2, -1);
UPDATE stock
SET quantity = stock.quantity + adjustments.delta
FROM adjustments
WHERE stock.id = adjustments.id;
```
```sql
SELECT id, quantity
FROM stock
ORDER BY id
FORMAT csv;
```
```text
1,6
2,2
```
See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into) for upserts and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) for explicit commit and rollback.
---
Source: https://coordinatordb.com/docs/reference/statements/use
Language: en
# USE
USE selects a registered server database. On a native connection, the selection remains in effect for later requests on that connection.
## Syntax
```text
USE database_name
```
Names are case-insensitive. The database must already be registered; create it with [`CREATE DATABASE`](https://coordinatordb.com/docs/reference/statements/create/database).
## Native and HTTP sessions
Native connections retain their selection. Each HTTP request has a separate logical session: use the `database` URL parameter or run `USE` and the dependent statements inside the same request.
A SELECT source named `database.schema.table` selects a managed database for that statement without changing the connection selection.
## Example
### Creating and selecting a database
```sql
CREATE DATABASE IF NOT EXISTS analytics_example;
```
```sql
USE analytics_example;
```
```text
Database changed to analytics_example.
```
```sql
SELECT 1 AS connected
FORMAT csv;
```
```text
1
```
See [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) for per-request database selection and [`FROM`](https://coordinatordb.com/docs/reference/statements/select/from) for qualified sources.
---
Source: https://coordinatordb.com/docs/reference/syntax
Language: en
# SQL syntax
SQL statements describe queries, data changes and schema operations. Keywords and built-in function names ignore ASCII case; the accepted syntax is defined by each statement or function page.
## Identifiers and strings
Quote identifiers with double quotes or backticks. Quote strings with single quotes. Double a quote character to include it inside that quoted value.
```sql
SELECT 'It''s SQL' AS message,
hex(X'4142') AS bytes,
CAST('12.50' AS Decimal(18, 2)) AS amount
FORMAT csv;
```
```text
"It's SQL","4142",12.50
```
## Literals and expressions
Literals include integers, decimal and exponent spellings, strings, X-prefixed blobs, TRUE, FALSE and NULL. Parentheses make expression grouping explicit. CAST applies a declared type's conversions and range checks.
Use the [operators reference](https://coordinatordb.com/docs/reference/operators) for arithmetic, comparison, membership, text, JSON and full-text operators.
## Statements and comments
Semicolons separate statements in a request. Comments use `--` to the end of a line or `/* ... */` for a block.
After INSERT FORMAT, the remaining bytes are input data rather than SQL. Put input SETTINGS before FORMAT and send later verification SQL in another request.
## Parameters and interfaces
The embedded API and native parameter frames accept positional bindings. Missing bindings are errors. The ordinary HTTP SQL interface does not accept bound parameters.
Server commands USE, SHOW and SET add managed database selection and settings. The embedded engine does not provide those service commands.
## Transactions
BEGIN starts a transaction, COMMIT keeps its changes and ROLLBACK undoes them. SAVEPOINT, RELEASE and ROLLBACK TO create nested undo scopes. Native connections retain transaction state; HTTP transaction statements must share one request.
See [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) for a complete example.
## Triggers
BEFORE, AFTER and INSTEAD OF triggers can have WHEN conditions and statement bodies between BEGIN and END. Separate statements inside a trigger body with semicolons. Recursive trigger execution requires recursive_triggers.
## Introspection
PRAGMA table_info, table_xinfo, index_list, index_info, index_xinfo, foreign_key_list and database_list expose schema information. Behavior flags include foreign_keys, defer_foreign_keys and recursive_triggers.
PRAGMA max_threads accepts integers from 0 through 64 for a connection. Zero selects automatically and one keeps execution serial. integrity_check and quick_check currently return a fixed ok row without validating storage or indexes. Unknown pragmas return no result.
## Maintenance and copies
ANALYZE collects statistics for planning. VACUUM INTO writes a consistent copy of main and requires autocommit, UTF-8 source storage and no WITHOUT ROWID user tables. The destination must be absent or empty. A schema qualifier does not select another source.
Plain VACUUM and REINDEX are accepted without performing work. See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview) for the copy procedure.
---
Source: https://coordinatordb.com/docs/reference/system-tables/columns
Language: en
# system.columns
Read-only metadata for columns across registered server databases. Use it to discover a table's declared schema rather than inferring a schema from its current values.
## Columns
| Name | Meaning |
| -------------------- | ---------------------------------------------------------------- |
| database | Managed database name. |
| table | Table or view name; quote this identifier in SQL. |
| name | Column name. |
| type | Declared type text. |
| position | One-based column position. |
| default_kind | Kind of declared default or generated value. |
| default_expression | SQL expression defining that value. |
| is_in_primary_key | Whether the column is part of the primary key. |
| is_nullable | Whether the column permits a top-level NULL. |
| primary_key_position | Position in the declared key, or zero when absent. |
| schema_name | Connection namespace, such as main or temp. |
| is_temporary | Whether the object belongs to the observing temporary namespace. |
## Example
```sql
CREATE TABLE documented_columns(id UInt32, label String);
```
```sql
SELECT name, type, position
FROM system.columns
WHERE "table" = 'documented_columns' AND schema_name = 'main'
ORDER BY position
FORMAT csv;
```
```text
"id","UInt32",1
"label","String",2
```
Always use the system qualifier. This service relation is provided by the server, rather than a standalone embedded connection. See [system.tables](https://coordinatordb.com/docs/reference/system-tables/tables) for object-level metadata.
---
Source: https://coordinatordb.com/docs/reference/system-tables/databases
Language: en
# system.databases
The managed database inventory is available through the server before a database is selected. Names are case-insensitive.
## Columns
| Name | Meaning |
| ---------- | ----------------------------------- |
| id | Positive integer database identity. |
| name | Registered database name. |
| created_at | Registration timestamp. |
| file_path | Registered database file path. |
INSERT, UPDATE and DELETE support validated inventory management after database selection. Use CREATE DATABASE for ordinary creation and USE to select a database; ordinary table DDL manages the objects within it.
## Example
```sql
SELECT name
FROM system.databases
WHERE name = 'data'
FORMAT csv;
```
```text
"data"
```
Always qualify the relation with system. A standalone embedded application opens a file or in-memory database through Connection instead of using this inventory.
See [`CREATE DATABASE`](https://coordinatordb.com/docs/reference/statements/create/database), [`USE`](https://coordinatordb.com/docs/reference/statements/use) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/reference/system-tables/formats
Language: en
# system.formats
A read-only registry of the server's data formats. Its names are the canonical snake_case spellings used by FORMAT.
## Columns
| Name | Type | Meaning |
| ---------------------------- | ------ | ------------------------------------- |
| name | String | Registered format name. |
| is_input | UInt8 | 1 when an input decoder is available. |
| is_output | UInt8 | 1 when a result encoder is available. |
| supports_parallel_parsing | UInt8 | Currently 0 for every format. |
| supports_parallel_formatting | UInt8 | Currently 0 for every format. |
Selecting an unsupported direction returns a format-direction error. ASCII case is ignored when resolving a name, but CamelCase spellings are not aliases.
## Example
```sql
SELECT name, is_input, is_output
FROM system.formats
WHERE name IN ('csv', 'form', 'null_output')
ORDER BY name
FORMAT csv;
```
```text
"csv",1,1
"form",1,0
"null_output",0,1
```
Use the system qualifier through a server interface. See [formats](https://coordinatordb.com/docs/reference/formats) for layouts, type mappings and settings.
---
Source: https://coordinatordb.com/docs/reference/system-tables/functions
Language: en
# system.functions
A read-only descriptive catalog of functions. It includes syntax and behavior text for registered descriptive entries; some callable legacy functions do not have a row.
Use the function reference for the complete documented public interface. A missing catalog row is not proof that the function is unavailable.
## Columns
| Name | Meaning |
| ---------------- | ------------------------------------------------- |
| name | Function name. |
| is_aggregate | Whether this row describes an aggregate overload. |
| case_insensitive | Whether name matching ignores case. |
| alias_to | Alias target, when present. |
| create_query | Creation definition, when applicable. |
| origin | Function origin metadata. |
| description | Behavior summary. |
| syntax | Calling syntax. |
| arguments | Argument descriptions. |
| parameters | Parameter metadata. |
| returned_value | Result description. |
| examples | Example SQL text. |
| introduced_in | Available version metadata. |
| categories | Descriptive categories. |
| deterministic | Nullable determinism flag. |
| higher_order | Nullable higher-order-function flag. |
## Example
```sql
SELECT name, is_aggregate, syntax
FROM system.functions
WHERE name = 'count'
FORMAT csv;
```
```text
"count",1,"count(), count(*), count(value), count(DISTINCT value)"
```
The relation is server-provided and can be read before USE. Always qualify it with system. See [functions](https://coordinatordb.com/docs/reference/functions).
---
Source: https://coordinatordb.com/docs/reference/system-tables/overview
Language: en
# System tables
System relations expose server metadata, effective settings and request observations. Always use the system qualifier to distinguish them from user tables.
## Read and manage
Live metadata and observation relations are read-only. databases, tables and settings also support validated management writes after a database is selected. Ordinary table changes should use CREATE, ALTER and DROP; use the documented setting interface for each name.
Some catalogs, such as databases, formats and functions, can be read before USE. A standalone embedded connection does not provide these service relations.
## Inventory
system.system_tables is a read-only view with schema_name and table_name columns. SHOW SYSTEM TABLES presents the same service inventory.
## Relations
* [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns)
* [system.databases](https://coordinatordb.com/docs/reference/system-tables/databases)
* [system.formats](https://coordinatordb.com/docs/reference/system-tables/formats)
* [system.functions](https://coordinatordb.com/docs/reference/system-tables/functions)
* [system.processes](https://coordinatordb.com/docs/reference/system-tables/processes)
* [system.query_log](https://coordinatordb.com/docs/reference/system-tables/query-log)
* [system.settings](https://coordinatordb.com/docs/reference/system-tables/settings)
* [system.tables](https://coordinatordb.com/docs/reference/system-tables/tables)
---
Source: https://coordinatordb.com/docs/reference/system-tables/processes
Language: en
# system.processes
A read-only snapshot of active requests. A request remains visible until its response write completes, whether it succeeds or fails. Membership does not depend on log_queries.
## Columns
| Name | Meaning |
| ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| query_id | Current request identifier. |
| user | Authenticated user. |
| interface | TCP or HTTP interface. |
| current_database | Selected database. |
| query | Request SQL text. |
| query_kind | Current statement classification. |
| elapsed | Elapsed seconds. |
| address, port | Client network endpoint. |
| initial_user, initial_query_id, initial_address, initial_port | Initial request identity fields. |
| is_initial_query | Initial-request flag. |
| is_internal | Internal-request flag. |
| is_cancelled | Cancellation status; server-side cancellation is unavailable. |
| is_all_data_sent | Response-delivery status. |
| read_rows, read_bytes | Observed read work. |
| written_rows, written_bytes | Observed write work. |
| memory_usage, peak_memory_usage | Current and peak accounted SQL memory. |
| total_rows_approx | Available approximate total row count. |
| peak_threads_usage | Maximum total query threads observed, including the main query thread. |
| normalized_query_hash | Hash grouping structurally normalized SQL. |
## Counters
Memory counters cover accounted SQL allocations across the request's query threads, including when max_memory_usage is zero. Serial execution reports peak_threads_usage of 1.
Physical read counters can include rows later rejected by a filter. Deleted rows do not count as newly written rows. These observations describe work performed, rather than only the final returned row count.
## Example
The observing query can see its own request:
```sql
SELECT user, interface, query_kind
FROM system.processes
WHERE query LIKE '%processes%'
FORMAT csv;
```
```text
"default","TCP","SELECT"
```
Always use the system qualifier. See [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) for terminal events and [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) for accounting scope.
---
Source: https://coordinatordb.com/docs/reference/system-tables/query-log
Language: en
# system.query_log
A read-only structured request history. query_id links events from one request with its response and diagnostic records. log_queries and log_queries_min_query_duration_ms control recording.
## Columns
| Name | Meaning |
| ------------------------------- | -------------------------------------------------------------------------- |
| event_time, event_time_text | Ordered event time and its text representation. |
| type | QueryStart, QueryFinish, ExceptionBeforeStart or ExceptionWhileProcessing. |
| query_start_time | Request start time. |
| query_duration_ms | Request duration in milliseconds. |
| query_id | Request identifier linking its events. |
| current_database | Database used by the request. |
| query, query_kind | SQL text and statement classification. |
| address, port | Client endpoint. |
| user, interface | Authenticated identity and TCP/HTTP interface. |
| result_rows | Returned rows across the request statements. |
| exception_code, exception | Permanent failure code and message; zero and empty text on success. |
| normalized_query_hash | Normalized-SQL grouping hash. |
| read_rows, read_bytes | Read work observed during the request. |
| written_rows, written_bytes | Write work observed during the request. |
| memory_usage, peak_memory_usage | Peak accounted SQL memory at terminal events. |
## Visibility
Events are recorded asynchronously. A direct single-table SELECT from system.query_log waits for previously queued events before reading. Each reading statement takes a fresh history snapshot, including inside a user transaction.
The current request's terminal event appears only after its execution. A nonzero duration threshold skips fast requests and records only qualifying terminal events; disabling logging overrides it.
## Counter interpretation
At terminal events, both memory_usage and peak_memory_usage report peak accounted SQL heap usage. Work later rolled back can still contribute to read/write counters. result_rows counts returned rows across the request's statements.
## Example
```sql
SELECT type, exception_code
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 1
FORMAT csv;
```
```text
"QueryFinish",0
```
Use the system qualifier through the server. See [logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries), [active requests](https://coordinatordb.com/docs/reference/system-tables/processes) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/reference/system-tables/settings
Language: en
# system.settings
Reports effective settings for the selected database and the built-in defaults of statement format options. Server-only XML options are not listed.
## Columns
| Name | Meaning |
| ----------- | -------------------------------------------------------------- |
| name | Canonical setting name. |
| value | Effective value as text. |
| type | Setting value type. |
| default | Built-in default as text; quote this identifier in SQL. |
| changed | Whether the effective value differs from the built-in default. |
| description | Public behavior summary. |
| readonly | 1 for statement-only format defaults. |
## Effective and stored values
Resource values include stricter XML ceilings. Connection flags and database-header fields reflect the observing connection's PRAGMAs. Read main.settings when the saved database value is required.
SET and validated catalog writes manage persisted database settings. readonly=1 format rows cannot be persisted; use SETTINGS on the statement instead.
## Example
```sql
SELECT name, value, type, "default", readonly
FROM system.settings
WHERE name = 'csv_separator'
FORMAT csv;
```
```text
"csv_separator",",","Char",",",1
```
Always use the system qualifier through the server. See [settings](https://coordinatordb.com/docs/reference/settings), [database settings](https://coordinatordb.com/docs/reference/settings/session-settings) and [format settings](https://coordinatordb.com/docs/reference/settings/formats).
---
Source: https://coordinatordb.com/docs/reference/system-tables/tables
Language: en
# system.tables
Lists tables and views across registered databases and the observing connection's temporary namespace. Use database and schema_name to distinguish objects with the same name.
## Columns
| Name | Meaning |
| ------------------ | -------------------------------------------------- |
| database | Managed database containing the object. |
| schema_name | Namespace such as main or temp. |
| table_name | Object name. |
| table_type | Object classification, such as BASE TABLE or VIEW. |
| definition | SQL definition text. |
| name | Object-name field for compatible metadata queries. |
| create_table_query | Creation SQL. |
| is_temporary | Whether it is a temporary object. |
| total_rows | Available row estimate, or NULL. |
| total_bytes | Available byte estimate, or NULL. |
The estimates are not a guarantee of an exact count. Use a concrete query when an exact result is required.
## Example
```sql
CREATE TABLE documented_table(id UInt32);
CREATE VIEW documented_view AS SELECT id FROM documented_table;
```
```sql
SELECT table_name, table_type
FROM system.tables
WHERE table_name IN ('documented_table', 'documented_view')
AND schema_name = 'main'
ORDER BY table_name
FORMAT csv;
```
```text
"documented_table","BASE TABLE"
"documented_view","VIEW"
```
## Management
Validated persistent catalog writes are supported for management. CREATE, ALTER and DROP are the normal object interface; the relation's observational fields are not arbitrary writable table data.
Use the system qualifier through a server interface. See [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns) for fields and [SQL statements](https://coordinatordb.com/docs/reference/statements) for object operations.
---
Source: https://coordinatordb.com/docs/resources/about
Language: en
# About Coordinator DB
Coordinator DB is a relational SQL database for storing, querying and updating structured data. Applications can use a managed server connection or open a database directly through the public embedded API.
## Working with data
Use tables, constraints and transactions to maintain related records. SQL supports filtering, joins, grouped aggregates, window calculations and common table expressions. The type reference covers integer and decimal values, dates, text, JSON, arrays, tuples and maps.
Start with a small application dataset and check its actual queries against the reference. A familiar SQL statement or client from another database can have different behavior. Consult the documented syntax and supported interface before choosing a migration path.
## Connecting an application
The server exposes a stateful native connection and an optional HTTP interface. The supplied client supports interactive SQL, scripted queries and local input files. HTTP requests can return a selected registered output format.
The embedded connection opens a file-backed or in-memory database within an application. Applications in separate processes should connect to a server when they need to access the same managed database.
## Explore this section
* [Evaluate adoption](https://coordinatordb.com/docs/resources/about/adopters): check the workload, client contract and operating requirements for an application.
* [Prepare a support report](https://coordinatordb.com/docs/resources/about/support): collect a small reproduction and request diagnostics.
* [Support center](https://coordinatordb.com/docs/resources/support-center/home): find practical answers by topic.
* [Development and Contributing](https://coordinatordb.com/docs/resources/develop-contribute/introduction/developer-instruction): verify integrations against the public interfaces.
* [Changelog](https://coordinatordb.com/docs/resources/changelog): read published documentation updates.
For a first connection, follow [installation](https://coordinatordb.com/docs/get-started/setup/install) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes). The [SQL reference](https://coordinatordb.com/docs/reference/home) describes the available statements, functions and formats.
---
Source: https://coordinatordb.com/docs/resources/about/adopters
Language: en
# Adopting Coordinator DB
Evaluate Coordinator DB with a representative part of the application workload. Include the data types, transaction boundaries, result sizes and failure cases that the application will use after deployment.
## Define a useful trial
Choose a small dataset that contains realistic keys, missing values, duplicate input and boundary values. Create its schema explicitly, then run the application's writes and reads. Check the returned values and ordering as well as elapsed time.
Record which [deployment mode](https://coordinatordb.com/docs/get-started/about/deployment-modes) the application needs. A server connection is appropriate when several application processes share managed databases. An embedded connection is useful when the application owns the database file within its process.
## Check the integration contract
Use the supplied native client or the documented HTTP interface for a server trial. Check authentication, database selection, errors and output formats. Verify that transaction and temporary-table lifetimes match the application's request boundaries. HTTP request state ends with each request.
Test a failed write and a disconnected client. Confirm that retry logic cannot silently duplicate a mutation. Run a separate check for large result sets and inspect truncation or resource-limit errors before accepting the result.
## Record an adoption decision
Keep the schema, sample input, query commands, expected output and observations together. Include a database-copy procedure and a successful restore rehearsal. These artifacts let another person repeat the evaluation after a change.
For public case studies, use results and organization names that their owners have approved for publication. The [support report guide](https://coordinatordb.com/docs/resources/about/support) describes how to reduce a failing trial to a reproducible example. See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview) for a supported recovery starting point.
---
Source: https://coordinatordb.com/docs/resources/about/support
Language: en
# Coordinator DB support
A useful support report explains the expected result, the observed result and the smallest sequence that reproduces the difference. Start with the [Support center](https://coordinatordb.com/docs/resources/support-center/home) to check the behavior relevant to your query or connection.
## Describe the request
Include the SQL, selected database, connection interface and output format. State whether the request uses the native client, HTTP or the embedded API. A transaction that spans several native requests has a different lifetime from a transaction sent over HTTP.
Use a small synthetic dataset that preserves the failing data shape. Include `CREATE TABLE`, the required `INSERT` statements, the failing query and its actual output. Describe whether the problem occurs on every run and whether it depends on another connection.
## Collect diagnostics
For an HTTP failure, record the status and the `X-Coordinator-Query-Id` and `X-Coordinator-Exception-Code` response headers. For a completed server request, use its identifier to inspect the public request history:
```sql
SELECT type, query_duration_ms, exception_code, exception
FROM system.query_log
WHERE query_id = 'replace-with-the-request-id'
ORDER BY event_time;
```
Include effective settings relevant to the failure. A memory, processing-time or response-size limit is part of the reproduction, even when the same query succeeds with smaller input.
## Remove private information
Remove passwords, API keys, authorization headers and application data before sharing a report. Use synthetic values consistently in both the reproduction and expected output. Browser request captures can contain credentials and should be reviewed before they are attached.
See the [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) for the exact public diagnostics.
---
Source: https://coordinatordb.com/docs/resources/changelog
Language: en
# Changelog
This page documents the changes in each Coordinator DB release.
*The entries below are examples. Version numbers, dates and changes are illustrative.*
## 1.2.0 (2026-10-19)
### Features
* Add a worked example for sending SQL through the [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http), selecting a database and choosing an output format.
* Add a [SQL console guide](https://coordinatordb.com/docs/concepts/features/interfaces/sql-console) covering query execution, result inspection and exports.
Run a query against a local server with HTTP enabled and the default empty-password user:
```sh
curl --silent --user default: \
--data-binary 'SELECT 1 AS connected FORMAT csv' \
'http://127.0.0.1:7401/?database=data'
```
```text
1
```
### Polish
* Group support guides by task, including SQL queries, imports, exports and connection settings.
* Link connection examples directly to the relevant interface reference.
* Make command examples use the same database name throughout the guides.
### Bug Fixes
* Fix an HTTP example that omitted the database parameter.
* Correct links from the support overview to the query and connection guides.
## 1.1.1 (2026-10-12)
### Polish
* Clarify the difference between checking server readiness and running an authenticated SQL request.
* Show the expected output beside the first connection example.
With HTTP enabled, check whether the local server is responding:
```sh
curl --silent http://127.0.0.1:7401/ping
```
```text
Ok.
```
### Bug Fixes
* Fix a copied command that contained an incorrect HTTP port.
* Correct the output shown for the CSV query example.
## 1.1.0 (2026-10-05)
### Features
* Add a [native client quickstart](https://coordinatordb.com/docs/concepts/features/interfaces/client) with an example for scripted SQL requests.
* Add a first-query example to the SQL console guide.
Run SQL from a terminal:
```sh
./coordinator client --database data \
--query "SELECT 1 AS value FORMAT csv"
```
```text
1
```
### Polish
* Add links between the native client, HTTP interface and SQL console guides.
* Shorten the setup instructions so the first query is easier to find.
### Bug Fixes
* Fix a connection example that used a different database name from the setup guide.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute
Language: en
# Development and contributing
Developing with Coordinator DB starts with a reproducible connection and a clear account of the behavior an application needs. This section covers public interfaces, integration checks and contributions to the examples and documentation that other developers use.
## Choose a starting point
* [Introduction](https://coordinatordb.com/docs/resources/develop-contribute/introduction/developer-instruction) explains how to prepare a small, reviewable change and select an interface.
* [Building](https://coordinatordb.com/docs/resources/develop-contribute/build/build) covers verification of an executable and its accompanying configuration on the intended machine.
* [Native protocol](https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/protocol) describes the public native connection contract and the supplied client.
* [Contributing](https://coordinatordb.com/docs/resources/develop-contribute/contribute/tests) covers regression cases, reproducible checks and compatibility evidence.
* [Integration development](https://coordinatordb.com/docs/resources/develop-contribute/integrations) follows an adapter from interface selection to tests and documentation.
* [Roadmap](https://coordinatordb.com/docs/resources/develop-contribute/roadmap) explains how to distinguish documented behavior from a proposed capability.
Keep examples self-contained. Use sample data, include the selected database and output format, and state whether a check uses native TCP, HTTP or an embedded connection. Those choices affect sessions, transactions and parameter binding.
For the first connection, follow [installation](https://coordinatordb.com/docs/get-started/setup/install). For an existing application, begin with [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build
Language: en
# Verify a local build
Use the current [installation instructions](https://coordinatordb.com/docs/get-started/setup/install) to obtain a local executable. A successful build is the beginning of verification: the executable must also start with the intended configuration and complete an authenticated request on the host where it will run.
## Start in a separate directory
Keep the executable, `config.xml` and `users.xml` together for the installation example. Both configuration files must exist. From that directory, start the server:
```sh
./coordinator serve --config-file config.xml --db data.db
```
In another terminal in the same directory, verify the supplied client's connection:
```sh
./coordinator client --database data --query "SELECT 1 AS connected FORMAT csv"
```
Expect `1` followed by a newline. If the supplied configuration enables HTTP, test its [health endpoint and SQL interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) separately; a successful native request does not verify an HTTP listener.
## Keep evidence with the result
Record the host operating system and architecture, executable identity, configuration changes and exact command output. Read [configuration paths](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) when moving the executable: a working directory change and a configuration directory change have different effects on relative paths.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-cross-arm
Language: en
# Validate an ARM distribution
Identify the exact ARM target before sharing a verification result. A machine's operating system, architecture and execution environment are part of the result; a successful check on one device does not establish support for every ARM device.
Use [installation](https://coordinatordb.com/docs/get-started/setup/install) for the current procedure. If an executable is prepared elsewhere, run the checks on the machine that will actually serve the application.
## Check startup and numeric results
Start the executable with the supplied configuration in an isolated directory. Then run:
```sh
./coordinator client --database data --query "SELECT 2147483647 AS value, 12.5 AS measurement FORMAT csv"
```
Expect `2147483647,12.5`. This small result checks the connection and an application's handling of representative numeric output. Add larger integers, nullable columns and the actual data formats your adapter uses to its own test cases.
## Include file operations
Verify client-side input from a file on the target, especially when the distribution changes directory permissions or launch accounts. Keep native and HTTP results separate. Document whether any compatibility environment was involved and retain exact errors rather than silently omitting failed cases. See [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and [format verification](https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/format).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-cross-loongarch
Language: en
# Validate a LoongArch distribution
For a LoongArch-targeted executable, record both where it was produced and where it was executed. Include the target operating system and machine details. Cross-build completion and target-side behavior are distinct results; neither should be inferred from the other.
Use [installation](https://coordinatordb.com/docs/get-started/setup/install) as the current installation reference. Keep the executable and supplied configuration in a test directory with a disposable database.
## Verify configuration and SQL
```sh
./coordinator serve --config-file config.xml --db loongarch-check.db
```
In another terminal, run:
```sh
./coordinator client --database data --query "SELECT 'configuration loaded' AS result FORMAT csv"
```
Expect `"configuration loaded"`. A successful request establishes that startup, authentication and a simple result worked in that environment.
## Expand to the application's use case
Check writes, a reconnect and the input/output formats your application depends on. If the executable cannot launch, preserve that error separately from any SQL test results. When moving files between machines, verify configuration and database paths explicitly; see [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files). Submit the exact failing case with its environment rather than presenting an untested target as supported.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-cross-osx
Language: en
# Validate a macOS cross build
A build produced on another host needs runtime evidence from its intended macOS target. Producing a file alone does not establish that the executable starts, finds its configuration or completes a query there. This guide defines verification evidence; the [installation page](https://coordinatordb.com/docs/get-started/setup/install) remains the reference for the current installation procedure.
## Identify both environments
Record the build host separately from the target Mac, including the target architecture and macOS version. State whether verification used a physical Mac or another execution environment. Preserve that distinction in a report instead of describing all macOS targets as tested.
## Exercise the target executable
Copy the intended executable with the supplied `config.xml` and `users.xml` into a test directory on the target. Start it there and check the native interface:
```sh
./coordinator serve --config-file config.xml --db cross-check.db
```
```sh
./coordinator client --database data --query "SELECT 1 FORMAT csv"
```
Expect one row containing `1`. Test file input and output formats used by the application after this smoke check. If execution fails before SQL runs, capture the launch error and target details. Do not infer database behavior from a loader or permissions failure; see [local verification](https://coordinatordb.com/docs/resources/develop-contribute/build/build).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-cross-riscv
Language: en
# Validate a RISC-V distribution
A RISC-V distribution check should identify the exact target and distinguish execution on a device from execution in an emulator. Keep build completion, process startup and SQL correctness as separate observations. The current [installation procedure](https://coordinatordb.com/docs/get-started/setup/install) does not by itself establish a cross-platform support matrix.
## Use a small deterministic request
Start the target executable with a disposable database and the supplied configuration. Run the supplied client against that server:
```sh
./coordinator client --database data --query "SELECT 7 * 6 AS answer, 'riscv' AS target FORMAT csv"
```
Expect `42,"riscv"`. Follow with an application-specific case that writes rows, reads them in a fixed order and checks the values after reopening the connection.
## Separate correctness from timing
Capture startup errors and failed queries even when an emulated environment is slow. A timeout imposed by your test runner should be reported as such; it does not prove that the SQL result was incorrect. For performance comparisons, report the execution environment and use the [workload measurement guide](https://coordinatordb.com/docs/resources/develop-contribute/contribute/profile-guided-optimization). For database and session selection, follow [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-cross-s390x
Language: en
# Validate an s390x distribution
Validate the executable and its application-facing results on the intended s390x environment. Record the operating system, target machine and whether the check uses emulation. Treat this as evidence for that environment rather than a guarantee for every system with the same architecture name.
Follow the current [installation procedure](https://coordinatordb.com/docs/get-started/setup/install), then start the executable with an isolated database and the supplied configuration files.
## Check values before byte-level output
```sh
./coordinator client --database data --query "SELECT 65536 AS value, 'sample' AS label FORMAT csv"
```
Expect `65536,"sample"`. This establishes a readable baseline before testing the binary formats used by an integration.
## Verify the adapter's format contract
For binary output, decode with a reader for the selected [documented format](https://coordinatordb.com/docs/reference/formats). Compare typed values and nulls with the text baseline. Do not reinterpret bytes using the application's host memory layout or assume that native TCP framing is the same as a row format.
Keep any byte-for-byte fixture tied to an explicit format and schema. Include negative cases for truncated input in the integration's tests and record whether the server accepted or rejected the request. See [native result formats](https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/format).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-e2k
Language: en
# Validate an Elbrus distribution
An Elbrus verification report needs the specific machine and operating environment, the executable tested and the commands actually run. This page describes useful evidence for a target check; it does not prescribe an unverified build toolchain or imply that a distribution is available for every target.
Consult [installation](https://coordinatordb.com/docs/get-started/setup/install) for the current installation procedure. Prepare a separate directory with the executable, supplied configuration and a disposable database.
## Check one interface at a time
After starting the server, verify native SQL:
```sh
./coordinator client --database data --query "SELECT 2 + 3 AS total FORMAT csv"
```
Expect `5`. If the application uses HTTP, also run the health and SQL checks from the [HTTP interface guide](https://coordinatordb.com/docs/concepts/features/interfaces/http). A working native connection does not verify the HTTP listener.
## Describe the result precisely
Include launch failures, configuration errors and query errors as separate observations. For a successful check, add the application's row types, format round trips and transaction behavior to the evidence. Avoid comparing timing from unlike execution environments. The [integration test guide](https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration) provides a useful starting checklist for the application's observable contract.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/build/build-osx
Language: en
# Verify a macOS build
Verify a macOS executable on the Mac that will run it. Record whether the machine is Apple silicon or Intel and whether the process runs directly or through a compatibility environment. Keep those results separate when comparing distributions.
Follow [installation](https://coordinatordb.com/docs/get-started/setup/install) for the current installation procedure. Place the resulting executable and the supplied configuration files in a dedicated directory rather than running against an application database.
## Check the local environment
```sh
uname -m
sw_vers -productVersion
./coordinator serve --config-file config.xml --db data.db
```
Then use another terminal in that directory:
```sh
./coordinator client --database data --query "SELECT 'macOS' AS platform FORMAT csv"
```
Expect a single CSV value, `"macOS"`. Confirm that the server can create the selected database and write its configured logs under the same account used for the check.
## Check paths explicitly
Use a path containing spaces when an application or packaging change affects file selection. Quote that path in the shell and verify the configured database independently of the configuration directory. See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) and the [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client) for path and connection options.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/backports
Language: en
# Compatibility fixes and backports
A backport applies a fix to an earlier version. Before proposing one, identify the observable problem, the versions actually tested and the smallest regression case that demonstrates the difference. A successful check on the current executable does not establish behavior on an earlier one.
## Record a version-specific baseline
Keep the executable identity, interface, configuration and exact query with each result. Use disposable data for tests that write or change a schema. Separate the original failure, the intended fix and any unrelated behavior differences.
If a fix changes an adapter, verify its request and result handling with every server version the adapter claims to support. Test both successful responses and the error path that originally failed. Do not add automatic retries for a write without accounting for an uncertain outcome.
## Keep the change narrow
Include only the fix, its regression coverage and any documentation needed to explain changed behavior. A proposed backport is not evidence that an earlier release will receive it; availability must be confirmed independently.
Use [regression test guidance](https://coordinatordb.com/docs/resources/develop-contribute/contribute/tests) for deterministic cases and [integration documentation](https://coordinatordb.com/docs/resources/develop-contribute/integrations/documenting-your-integration) to state tested versions and limitations without promising an unverified compatibility range.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/building-and-benchmarking-deflate-qpl
Language: en
# Benchmark compressed input
A compressed-input benchmark should answer an application question: whether a chosen input path loads the same rows correctly and improves elapsed time or transferred size for that workload. Report the complete operation, including file preparation when it is part of the user's task.
## Establish correctness first
Use one fixed source dataset and one destination schema. Load an uncompressed baseline using the documented [client file input](https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv), then compare the compressed-file variant supported by that input path. Keep compression support tied to the documented path; do not assume every transport or format accepts the same wrappers.
Verify row count and representative values after each run. Include nulls, quoted text and numeric boundaries relevant to the dataset. Check failures with truncated or invalid input separately from successful load timing.
## Keep the comparison fair
Use fresh test data for each measured load, the same destination schema and the same success checks. Report file sizes, row count, compression choice, host details and repeated elapsed times. Distinguish client-side processing from end-to-end time when measuring both.
Avoid drawing a general performance claim from one dataset. Link the exact [format](https://coordinatordb.com/docs/reference/formats) and [batch insert behavior](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) used so another developer can reproduce the comparison.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/continuous-integration
Language: en
# Continuous integration checks
An automated integration job should establish the executable and configuration it uses, start an isolated server and wait for readiness before running assertions. A delay alone does not prove that startup succeeded.
## Check readiness and SQL separately
For a configuration with HTTP enabled, these commands check the listener and an authenticated query:
```sh
curl --fail --silent http://127.0.0.1:7401/ping
curl --fail --silent --user default: --data-binary 'SELECT 1 FORMAT csv' \
'http://127.0.0.1:7401/?database=data'
```
Expect `Ok.` from the health check and `1` from SQL. Use a bounded readiness loop in your own job and fail if the server exits. The health response alone does not verify database selection or credentials.
## Keep each job independent
Give each job its own database, configuration directory and listener ports. Capture the exact SQL, response status and non-sensitive diagnostics on failure. Stop the process the job started and remove only its own temporary data during cleanup.
Run both successful and rejected requests for an adapter that interprets [HTTP status codes](https://coordinatordb.com/docs/concepts/features/interfaces/http). For native applications, add an equivalent query with the [supplied client](https://coordinatordb.com/docs/concepts/features/interfaces/client). Preserve target-machine details when a job validates a distribution on another architecture.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/contrib
Language: en
# Third-party integration dependencies
A Coordinator DB integration may rely on an HTTP library, a data-format reader or an application connection abstraction. Review those dependencies through the public contract they must preserve: requests, authentication, typed values, errors and cleanup.
## Explain what the dependency does
State which part of the adapter needs it and why an existing application dependency does not cover that behavior. Record its version and relevant distribution terms. Keep credentials out of diagnostic logging and make connection ownership explicit.
For an HTTP client, verify that it sends the SQL body and Content-Length correctly, retains response headers and exposes non-success status codes. For a format reader, test its handling of nulls, column names, numeric limits and an incomplete input fixture.
## Check compatibility rather than names
A dependency that supports another SQL database is not automatically a Coordinator DB native client. The [native interface](https://coordinatordb.com/docs/concepts/features/interfaces/tcp) uses its own protocol. Use the supplied client or the documented [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) for the selected integration boundary.
Include a small reproducible test and explain how callers receive errors. Document configuration defaults and any format restrictions in the [integration guide](https://coordinatordb.com/docs/resources/develop-contribute/integrations/documenting-your-integration), so users can assess the dependency through actual behavior.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/integrating-rust-libraries
Language: en
# Integrate the embedded API
An embedded integration opens a database connection directly instead of sending SQL to a server. Define who owns that connection, where its database file lives and when it is closed. Use an in-memory connection for examples that do not need persistence.
## Bind values through the API
The public API provides `Connection::open(path)` and `Connection::open_in_memory()`. A prepared statement separates SQL from positional values. Use `prepare`, then the documented `execute_prepared` or `query_prepared` operation with the appropriate values. Missing bindings are errors.
The [prepared-statement example](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements) shows the complete binding and result contract. Document the adapter's conversion between database values and application values, especially nulls and integer boundaries.
## Respect the connection boundary
An embedded connection does not expose server commands such as `USE`, `SHOW` and `SET`, or the server's format encoders. Several connections in one process can share a file; simultaneous access from separate processes is outside the supported concurrency model.
Use one server when multiple application processes need shared access. Verify rollback on failure and reopen the file when testing persistence. See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) for selecting the boundary and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) for SQL transaction controls.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/profile-guided-optimization
Language: en
# Measure application workloads
Measure an integration change with a workload that represents the application's task. A useful result includes correct rows, the complete request path and repeated measurements under stated conditions.
## Define the operation
State the dataset, schema, query, output format, interface and connection lifetime. Decide whether connection setup belongs in the measurement. Reusing one native connection and making a new HTTP request exercise different session boundaries; compare them only when that distinction matches the application's question.
Run correctness checks before collecting timings. Use fixed inputs and explicit ordering for result comparisons. Separate the first run from repeated runs and report the individual observations or their spread rather than only the fastest number.
## Read public response metadata
The [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) returns `X-Coordinator-Summary` with fields including `elapsed_ms` and `result_rows`. Compare that server-reported duration with the application's own end-to-end duration. Record `X-Coordinator-Result-Truncated` when present so a capped result is not mistaken for a complete export.
Keep host details and simultaneous application activity with the report. Avoid attributing a timing difference to an unobserved implementation detail. For ingest measurements, use the separate [compressed-input benchmark guide](https://coordinatordb.com/docs/resources/develop-contribute/contribute/building-and-benchmarking-deflate-qpl) to control file preparation and row validation.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/style
Language: en
# Integration code style
Integration examples should make the connection and its ownership easy to see. Use the host application's existing conventions, descriptive names and small functions whose error paths can be read beside their successful paths.
## Keep data and SQL distinct
Use a documented parameter-binding API where one is available. The [prepared-statement guide](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements) describes positional values for embedded applications. The ordinary CLI and HTTP options do not provide that binding interface; examples must not present string interpolation as equivalent parameter binding.
Choose explicit columns and a result format appropriate for the caller. Use `ORDER BY` when the example promises an order. Describe what a function returns when a query produces no rows, a nullable field or an error.
## Make lifetime visible
Keep a transaction's related statements together. A native connection retains state, while each HTTP request owns its session. Return or close resources through the application's normal cleanup mechanism, including failure paths.
Use sample credentials only in the documented local configuration. Avoid logging authentication headers or real query values. A short example should still show how the caller detects failure; see [integration testing](https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration) for the cases its documentation should support.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/contribute/tests
Language: en
# Regression tests
A regression test preserves an observable behavior that a change could accidentally break. Start from a minimal case and give it an exact expectation: rows, an error, or a transaction's effect on later reads.
## Make output deterministic
Use an isolated database or a uniquely named test table. Include `ORDER BY` when row order matters and an explicit [output format](https://coordinatordb.com/docs/reference/formats) when comparing text. Use sample values that exercise the reported problem rather than copying production data.
```sql
CREATE TABLE regression_items(id INTEGER PRIMARY KEY, value TEXT);
INSERT INTO regression_items VALUES (2, 'second'), (1, 'first');
SELECT id, value FROM regression_items ORDER BY id FORMAT csv;
```
```text
1,"first"
2,"second"
```
## Test the relevant boundary
An HTTP session test must use separate requests when checking isolation. A native transaction test must keep the same connection when checking commit behavior, then reconnect when checking persistence. See [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
Add an invalid-input case if the change affects validation. Record whether the application receives an error and whether earlier writes remain. Clean up only the data created by the test. Include commands, expected output and interface selection with the contribution so a reviewer can reproduce it.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/integrations
Language: en
# Integration development
An integration connects an application's operations to Coordinator DB and translates results into the application's own values and errors. Begin with the interface and session behavior your application requires.
## Select the connection boundary
Use the [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) for ordinary HTTP SQL requests and documented row formats. Use the [supplied native client](https://coordinatordb.com/docs/concepts/features/interfaces/client) for interactive work, scripted exact-byte output and client-side file input. The native protocol is specific to Coordinator DB.
An embedded application can open a connection directly and use [prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements). Its API differs from the server interfaces: server database commands and format encoders are outside the embedded contract.
## Develop a complete example
Start with a connection, one read and one rejected request. Add writes only after defining transaction ownership and the response to a connection failure. A failed connection can leave a caller uncertain whether a write completed; retry policy needs to account for that outcome.
Follow [building an integration](https://coordinatordb.com/docs/resources/develop-contribute/integrations/building-integrations), then [test it](https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration) against its promised behavior. Finish with [documentation](https://coordinatordb.com/docs/resources/develop-contribute/integrations/documenting-your-integration) that states authentication, database selection, supported formats and tested versions.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/integrations/building-integrations
Language: en
# Build an integration
Define the operations the adapter exposes before adding convenience functions. Each operation should state its database selection, input values, result shape and failure behavior. Keep the application's connection configuration separate from SQL text.
## Start with a read
An HTTP-based adapter can begin with the following request against the supplied local configuration:
```sh
curl --fail --silent --user default: \
--data-binary 'SELECT 1 AS connected FORMAT json_each_row' \
'http://127.0.0.1:7401/?database=data'
```
```text
{"connected":1}
```
Preserve the response status and diagnostic headers before decoding the selected format. A health check and an authenticated SQL query serve different purposes. Follow the [HTTP reference](https://coordinatordb.com/docs/concepts/features/interfaces/http) for accepted parameters, authentication and response limits.
## Add writes deliberately
Document how the adapter sends input rows and handles an uncertain write outcome. Keep a transaction's statements in one HTTP request, or on the same native connection, as required by the [session contract](https://coordinatordb.com/docs/resources/develop-contribute/introduction/architecture).
Use a documented binding API where available; HTTP does not provide bound parameters. Handle large numeric values and nulls explicitly when decoding results. Add [integration tests](https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration) before claiming that a format or operation is supported.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/integrations/documenting-your-integration
Language: en
# Document your integration
Begin with what the integration lets an application do and the public interface it uses. State the tested Coordinator DB executable versions and the adapter version. A tested combination is evidence; an untested version range is a promise the example cannot establish.
## Make the first example runnable
Link to [installation](https://coordinatordb.com/docs/get-started/setup/install), name the database and show the configuration values a caller supplies. Identify the local example's credentials as belonging to the supplied configuration. Keep passwords, API keys and private addresses out of copied output.
Show one complete read with its expected result, then a write if supported. Specify the output format and how database nulls, numeric values and errors map into the application. Explain where the connection is closed and who commits or rolls back a transaction.
## State meaningful boundaries
Describe cancellation, retries, file input and parameter binding only to the extent the integration actually implements them. In particular, HTTP has independent request sessions and no bound-parameter interface. Refer readers to the [HTTP contract](https://coordinatordb.com/docs/concepts/features/interfaces/http) rather than implying another database driver's behavior applies.
Include troubleshooting for invalid credentials, an unavailable listener and malformed SQL. Use the same sample dataset as the [integration tests](https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration) so documentation changes can be checked against an observable result.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/integrations/testing-your-integration
Language: en
# Test your integration
Test the adapter at the public interface it uses. A mocked successful response can check decoding, but a real server check is needed to verify authentication, database selection, session behavior and rejected requests together.
## Cover the application contract
Include a successful read, an empty result, a nullable field and an invalid SQL statement. Exercise representative integer limits and text containing quotes, delimiters and newlines through the chosen [format](https://coordinatordb.com/docs/reference/formats). Check invalid credentials separately from invalid SQL so callers receive the correct failure category.
For writes, verify committed rows by reading them back. Check rollback and a connection ending before commit. HTTP transactions must complete inside one request, while a native transaction belongs to its connection; see [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
## Exercise limits and cleanup
Test the application's handling of a truncated result, a rejected request and a network failure. For HTTP, preserve relevant headers such as `X-Coordinator-Query-Id` and `X-Coordinator-Result-Truncated` in diagnostics without logging credentials.
Use isolated data and stop only the server started by the test. Record executable versions and configuration with results. Include a file-input test when the adapter promises imports. The [automated checks guide](https://coordinatordb.com/docs/resources/develop-contribute/contribute/continuous-integration) explains readiness and independent test environments.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/introduction/architecture
Language: en
# Public connection model
An application chooses between a server connection and an embedded connection. This choice defines who owns session state and how several application instances reach the database.
## Server connections
Native TCP and HTTP reach the same server-managed database inventory and configured users. A [native connection](https://coordinatordb.com/docs/concepts/features/interfaces/tcp) authenticates once and retains its selected database, temporary objects and transaction until disconnection. Closing it rolls back uncommitted work.
An [HTTP request](https://coordinatordb.com/docs/concepts/features/interfaces/http) owns a separate session. Select the database for each request. Put all statements that share a transaction or temporary table into that request; an open transaction is rolled back before the response is delivered.
## Embedded connections
An embedded connection opens a file or an in-memory database directly. It offers typed results and [prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements). Server commands such as `USE`, `SHOW` and `SET` are outside that API.
Multiple connections in one process can share a database file. Simultaneous access to the same file from separate processes is outside the supported concurrency model. Applications running in several processes should connect to one server. Choose and document this boundary before adding connection pooling or background jobs; see [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/introduction/developer-instruction
Language: en
# Developer guide
Start with the public behavior you want to exercise. A useful contribution has a concrete input, an observable result and enough connection details for another developer to reproduce it without access to your application.
## Establish a baseline
Follow [installation](https://coordinatordb.com/docs/get-started/setup/install), start a local server and run a query through the supplied client:
```sh
./coordinator client --database data --query "SELECT 1 AS connected FORMAT csv"
```
The result is one row containing `1`. Record the executable you tested, the operating system, the interface and any configuration changes. Keep credentials and private connection addresses out of shared examples.
## Make one behavior reviewable
Use a small table and deterministic data. For a reported problem, show the expected result beside the observed result. For a new integration example, explain connection ownership, error handling and how the example cleans up its own data.
Check the [public connection model](https://coordinatordb.com/docs/resources/develop-contribute/introduction/architecture) before choosing native TCP, HTTP or an embedded connection. Then add a [regression case](https://coordinatordb.com/docs/resources/develop-contribute/contribute/tests) that demonstrates the change. A documentation correction should include a runnable example when the correction affects SQL or connection behavior.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/format
Language: en
# Native result and input formats
The native connection carries requests and results; a SQL `FORMAT` clause chooses how result rows or attached input are encoded. A row format is not a specification of the native connection's wire framing.
## Choose an explicit format
```sh
./coordinator client --database data --query "SELECT 1 AS id, 'Ada' AS name FORMAT json_each_row"
```
```text
{"id":1,"name":"Ada"}
```
The client's `--query` mode writes only result bytes to stdout, including binary output. Capture diagnostics separately when an application consumes stdout as a data stream. Use the snake_case names in the [format reference](https://coordinatordb.com/docs/reference/formats); ClickHouse CamelCase format names are not aliases.
## Match input to a schema
Select a format that supports input and create the destination table before importing rows. Test nulls, quoted delimiters, empty strings and numeric boundaries with that schema. A schema-bearing container still has to satisfy the destination column declarations.
For client-side files, use the documented [batch input options](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts). Keep later SQL in another request when using inline `INSERT ... FORMAT`, because inline input occupies the remainder of its request. Avoid treating an arbitrary file extension as sufficient evidence of its encoding.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/hash
Language: en
# Native transport integrity checks
Use the supplied client to handle the native connection. The public [native TCP guide](https://coordinatordb.com/docs/concepts/features/interfaces/tcp) describes authentication, session state and request limits; it does not define a checksum algorithm or a packet layout for third-party implementations.
## Compare observable results
For a deterministic result, select a fixed row order and an explicit format:
```sh
./coordinator client --database data --query "SELECT 1 AS id, 'sample' AS value FORMAT json_each_row" > result.jsonl
```
Compare the captured bytes with a fixture only when the format and query make exact bytes part of the application's contract. For typed data, decoding the result and comparing values often gives a more useful failure than comparing a file digest alone.
## Keep integrity separate from security
A digest of a downloaded executable or exported file verifies only the comparison you performed against a trusted expected value. It does not establish server identity or encrypt a connection. Native transport has no TLS; use trusted connectivity or an external secure tunnel for credentials in transit.
When reporting a damaged transfer, include the chosen [format](https://coordinatordb.com/docs/reference/formats), input size and client error. Share a minimal non-sensitive fixture that reproduces the problem, not captured credentials or private result data.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/protocol
Language: en
# Native protocol
The native interface is a Coordinator DB connection protocol. Use the supplied `coordinator client`; clients for ClickHouse, PostgreSQL and SQLite cannot connect to it. The default native listener is `127.0.0.1:7400`.
## Connect and select a database
```sh
./coordinator client --addr 127.0.0.1:7400 --user default --database data
```
The supplied local example configures `default` with an empty password. For another configured account, the client accepts `--password` or the `COORDINATOR_PASSWORD` environment variable. Keep secrets outside shared command output.
## Own the connection lifetime
A native connection retains its selected database, temporary objects and transaction state. Closing it rolls back an uncommitted transaction. An application that returns a connection to a pool must account for that state before another operation uses it.
Native transport has no TLS. Use a trusted connection or an external secure tunnel. Ordinary SQL/control requests and responses have a 16 MiB limit; client uploads have different input limits, described in [native TCP](https://coordinatordb.com/docs/concepts/features/interfaces/tcp).
Result formats are a separate choice from the connection protocol. See [result and input formats](https://coordinatordb.com/docs/resources/develop-contribute/native-protocol/format) and the [client guide](https://coordinatordb.com/docs/concepts/features/interfaces/client) for exact-byte requests, file input and scripted execution.
---
Source: https://coordinatordb.com/docs/resources/develop-contribute/roadmap
Language: en
# Roadmap and feature proposals
Use the current public documentation to decide whether an application can depend on a capability today. A requested feature, compatibility experiment or proposed integration is not a release commitment. This page does not assign delivery dates to proposed work.
## Describe the application need
A useful proposal includes the operation a user needs, a small input and the expected observable result. State the interface involved and explain what the application does today. Link to the relevant [SQL reference](https://coordinatordb.com/docs/reference/home), [format](https://coordinatordb.com/docs/reference/formats) or [connection guide](https://coordinatordb.com/docs/get-started/about/deployment-modes).
Separate a missing capability from a reproducible failure of documented behavior. For a failure, provide a [regression case](https://coordinatordb.com/docs/resources/develop-contribute/contribute/tests) with the tested executable and actual output. For a new capability, describe the result and error behavior an integration would need to rely on.
## Assess readiness through evidence
Before an application adopts a change, verify that its target executable implements the behavior, its documentation describes the boundary and an integration test covers the application's case. Record limitations that still affect the caller. Avoid inferring availability from a page title or an example for a different database.
See [integration development](https://coordinatordb.com/docs/resources/develop-contribute/integrations) for turning a concrete application requirement into a tested adapter contract.
---
Source: https://coordinatordb.com/docs/resources/support-center/home
Language: en
# Support center
Find a Coordinator DB guide by the task you need to complete. The knowledge base covers queries, schema changes, imports and exports, connection setup, settings, diagnostics and recovery. Each article links to the relevant public reference so you can check exact syntax and limits.
If you are starting with a new database, follow [installation](https://coordinatordb.com/docs/get-started/setup/install), [create a table](https://coordinatordb.com/docs/get-started/quickstarts/creating-tables) and [run a query](https://coordinatordb.com/docs/get-started/quickstarts/writing-queries). For an existing application, choose its connection interface and the topic below that matches the observed behavior.
The Cloud category covers deploying your own server and connecting external network, broker and infrastructure services. Provider account operations and external importers remain separate from the SQL interface.
Use the sidebar to open a category or follow the article links below. General questions also group related guides by use case, integration and operating task.
## Performance & optimization
* [Tune INSERT SELECT requests](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/insert-select-settings-tuning)
* [Choose an explicit result order](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/async-vs-optimize-read-in-order)
* [Measure query processing time](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/check-query-processing-time-only)
* [Find expensive completed queries](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/find-expensive-queries)
* [Find queries with high memory usage](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/finding-expensive-queries-by-memory-usage)
* [Choose between Map fields and typed columns](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/improve-map-performance)
* [Resolve a query memory limit error](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/memory-limit-exceeded-for-query)
* [Resolve duplicate rows with explicit SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/optimize-final-vs-final)
* [Set a query execution deadline](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/query-max-execution-time)
* [Choose precise basic data types](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/tips-tricks-optimizing-basic-data-types-in-clickhouse)
* [Investigate a primary key access plan](https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/why-is-my-primary-key-not-used)
## Cloud
* [Connect ingestion clients over a private network](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-clickpipes)
* [Import from a private managed Kafka source](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-msk-clickpipes)
* [Plan a private route for a broker consumer](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-vpc-endpoint-service-for-msk-cluster)
* [Update an infrastructure billing contact](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/change-billing-email)
* [Automate Coordinator DB SQL over HTTP](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/clickhouse-cloud-api-usage)
* [Connect a private Confluent consumer to SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/confluent-cloud-private-connectivity-for-clickpipes)
* [Use a custom DNS name for SQL access](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/custom-dns-alias-for-instance)
* [Inspect service metadata with system tables](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/execute-system-queries-in-cloud)
* [Check service readiness and SQL access](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/how-to-check-my-clickhouse-cloud-sevice-state)
* [Reach SQL through an SSH tunnel](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/how-to-connect-to-ch-cloud-using-ssh-keys)
* [Diagnose ingestion failures after an upgrade](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/ingest-failures-23-9-release)
* [Move a verified database copy to another region](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/multi-region-replication)
* [Control diagnostic artifacts in your deployment](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/opt-out-core-dump-collection)
* [Restore access to a SQL endpoint](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/unable-to-access-cloud-service)
## Data import & export
* [Commit related inserts atomically](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/achieving-atomic-inserts)
* [Add data to a Parquet export safely](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/cannot-append-data-to-parquet-format)
* [Export query results to a client file](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/file-export)
* [Import GeoJSON features with nested properties](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/importing-geojason-with-nested-object-array)
* [Work with arrays of JSON objects](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/importing-and-working-with-json-array-objects)
* [Import Parquet downloaded from object storage](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/ingest-parquet-files-in-s3)
* [Choose the right JSON input format](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-import)
* [Extract values from a JSON document](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-extract-example)
* [Load and query a small JSON dataset](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-simple-example)
* [Load JSON records from an external Kafka consumer](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/kafka-clickhouse-json)
* [Set up a repeatable external Kafka import](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/kafka-to-clickhouse-setup)
* [Exchange MySQL query results through files](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/mysql-to-parquet-csv-json)
* [Convert Parquet rows to CSV or JSON](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/parquet-to-csv-json)
* [Exchange PostgreSQL results through files](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/postgresql-to-parquet-csv-json)
* [Organize exports in year and month folders](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/s3-export-data-year-month-folders)
## Configuration & settings
* [Apply request budgets without per-user quotas](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/about-quotas-and-query-complexity)
* [Replace an unsupported ALTER USER setting change](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/alter-user-settings-exception)
* [Use native client commands and connection options](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/change-the-prompt-in-clickhouse-client)
* [Configure a database request default](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/configure-a-user-setting)
* [Correct an unknown or invalid setting](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/ignoring-incorrect-settings)
* [Plan the number of tables and databases](https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/maximum-number-of-tables-and-databases)
## Integrations & client libraries
* [Run a SQL request from Node.js](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/node-js-example)
* [Connect reporting tools without assuming ODBC compatibility](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/odbc-authentication-failed-error-using-powerbi-ch-connector)
* [Import Oracle query results through a file](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/oracle-odbc)
* [Move SQL Server data into a containerized SQL service](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/how-to-set-up-ch-on-docker-odbc-connect-mssql)
* [Use Python without a product specific database driver](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/python-clickhouse-connect-example)
* [Send Python HTTP queries and parse JSON rows](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/python-http-requests)
* [Manage deployment configuration with external automation](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/terraform-example)
## Troubleshooting & errors
* [Troubleshooting overview](https://coordinatordb.com/docs/resources/support-center/troubleshooting)
* [Build a reproducible diagnostic case](https://coordinatordb.com/docs/resources/support-center/troubleshooting/troubleshooting)
* [Resolve certificate verification failures at the TLS boundary](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/certificate-verify-failed-error)
* [Review container permissions before adding capabilities](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/configure-cap-ipc-lock-and-cap-sys-nice-in-docker)
* [Diagnose remote SQL connection timeouts](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/connection-timeout-remote-remotesecure)
* [Inspect table counts and size estimates](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/count-parts-by-type)
* [Diagnose pressure from many small inserts](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/exception-too-many-parts)
* [Handle a macOS executable verification warning](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/fix-developer-verification-error-in-macos)
* [Resolve overlapping data import ranges](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/part-intersects-previous-part)
* [Recover data from a verified independent copy](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/recovering-from-corrupt-keeper-snapshot)
* [Restore an independent service after storage failure](https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/restore-replica-after-storage-failure)
## Tables & schema
* [Add a column to an existing table](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/add-column)
* [Delete rows older than a chosen boundary](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/delete-old-data)
* [Switch a table name with explicit renames](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/exchangestatementtoswitchtables)
* [Combine data from independent SQL services](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/how-to-create-table-to-query-multiple-remote-clusters)
* [Use a shared persistent table across client sessions](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/recreate-table-across-terminals)
* [Validate a JSON schema change with a small runbook](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/runbook-json)
* [Choose a schema migration workflow](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/schema-migration-tools)
* [Find tables with a name pattern](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/search-across-node-for-tables-with-a-wildcard)
## Queries & SQL
* [Calculate pi with SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/calculate-pi-using-sql)
* [Compare two query result sets](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets)
* [Compare query measurements](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/comparing-metrics-between-queries)
* [Calculate filtered aggregates](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/filtered-aggregates)
* [Filter rows by an array member](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/how-to-filter-a-clickhouse-table-by-an-array-column)
* [Insert rows from another table](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/how-to-insert-all-rows-from-another-table)
* [Pivot a known set of categories](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/pivot)
* [Useful diagnostic SQL queries](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/useful-queries-for-troubleshooting)
* [Expand JSON attributes into rows](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/using-array-join-to-extract-and-query-attributes)
## Materialized views & projections
* [Choose live views or stored query results](https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/are-materialized-views-inserted-asynchronously)
* [Inspect requests that query a view](https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/how-to-display-queries-using-mv)
* [Filter an ordinary view with query parameters](https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/how-to-use-parametrised-views)
* [Use a targeted index for repeated queries](https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/projection-example)
* [Check report data after a restart](https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/what-happens-to-refreshable-materialized-views-when-the-server-restarts)
## Monitoring & debugging
* [Investigate repeated-query performance](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/check-query-cache-in-use)
* [Build a request timeline from query history](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/collect-and-draw-traces)
* [Capture a browser request for diagnosis](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/generate-har-file)
* [Choose request metrics for external monitoring](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/mapping-of-system-metrics-to-prometheus-metrics)
* [Write diagnostic logs to a file](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/outputsendlogsleveltracestofile)
* [Profile SQL with analyzed execution plans](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/profiling-clickhouse-with-llvm-xray)
* [Choose diagnostic and query logging levels](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/send-logs-level)
* [See currently active requests](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/which-processes-are-currently-running)
* [Monitor active data-changing requests](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/view-number-of-active-mutations)
* [Reduce diagnostic log verbosity](https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/why-default-logging-verbose)
## Security & access control
* [Check configured users and active identities](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/check-users-roles)
* [Plan access without database roles](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/common-rbac-queries)
* [Remove empty-password default access](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/remove-default-user)
* [Design row and column access boundaries](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/row-column-policy)
* [Understand browser request identity and state](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/set-role-not-persisting-in-sql-console)
* [Connect application identity to database access](https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/windows-active-directory-to-ch-roles)
## Data management
* [Preserve a selected date range](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/backing-up-a-specific-partition)
* [Measure zeros and missing values](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/calculate-ratio-of-zero-sparse-serialization)
* [Keep lookup data consistent](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/dictionaries-consistent-state)
* [Use string-keyed lookup data](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/dictionary-using-strings)
* [Read related data in one transaction](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/read-consistency)
* [Distinguish tables from interchange formats](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/understanding-part-types-and-storage-formats)
* [Apply an explicit retention cutoff](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/when-is-ttl-applied)
## Setup & installation
* [Verify the executable you are running](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/difference-between-official-builds-and-3rd-party)
* [Use HTTPS in front of the HTTP interface](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/enabling-ssl-with-lets-encrypt)
* [Choose and verify a query thread limit](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/how-to-increase-thread-pool-size)
* [Plan a Windows client connection](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/install-clickhouse-windows10)
* [Check installation prerequisites](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/llvm-clang-up-to-date)
* [Prepare a persistent Coordinator DB service](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/production)
* [Use documentation safely with a SQL assistant](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/set-up-clickhouse-documentation-mcp-server)
## General & FAQs
* [Coordinator DB frequently asked questions](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/faq-index)
### General
* [General Coordinator DB questions](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs)
* [Choose SQL by the reader task](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/columnar-database)
* [Connect concurrent applications safely](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/concurrency)
* [Inspect the chosen query plan](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/cost-based)
* [Query and import a local data file](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/datalake)
* [Name databases and SQL objects](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/dbms-naming)
* [Prepare the files and credentials a service needs](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/dependencies)
* [Join related data in Coordinator DB](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/distributed-join)
* [Query available data sources deliberately](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/federated)
* [Prepare a useful Coordinator DB contribution](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/how-do-i-contribute-code-to-clickhouse)
* [Express grouped calculations in SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/mapreduce)
* [Investigate a slow query step by step](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/ne-tormozit)
* [Build analytical reports with SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/olap)
* [Use Coordinator DB SQL deliberately](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/sql)
* [Update existing rows transactionally](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/updates)
* [Evaluate Coordinator DB for your workload](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/who-is-using-clickhouse)
* [Choose a single-server application connection](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/why-recommend-clickhouse-keeper-over-zookeeper)
### Use cases
* [Coordinator DB use cases](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-cases-index)
* [Store and update keyed records](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/key-value)
* [Query dated measurements](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/time-series)
* [Analyze application event logs](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-clickhouse-for-log-analytics)
* [Compare fixed-dimensional vectors](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/vector-search)
### Integration
* [Integrate an application with Coordinator DB](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations)
* [Choose the right JSON input format](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-import)
* [Import Oracle query results through a file](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/oracle-odbc)
### Operations
* [Operate a Coordinator DB service](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/operations-index)
* [Delete rows older than a chosen boundary](https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/delete-old-data)
* [Move a verified database copy to another region](https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/multi-region-replication)
* [Prepare a persistent Coordinator DB service](https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/production)
* [Choose database paths and independent copies](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/separate-storage)
## Tips & tricks
* [Practical habits for reliable SQL work](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/community-wisdom)
* [Reduce unnecessary query and data work](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/cost-optimization)
* [Keep a focused SQL debugging record](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/debugging-insights)
* [Choose a view or a report table](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/materialized-views)
* [Optimize a measured reader task](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/performance-optimization)
* [Write a reproducible workload result](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/success-stories)
* [Improve a workload with many small writes](https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/too-many-parts)
## Prepare a reproducible support report
Record the SQL, selected database, interface, output format and relevant settings. Include a small synthetic dataset and the actual result or error. For server requests, preserve the query identifier so it can be matched with the public request history.
Remove credentials and application data before sharing a reproduction. Follow [Coordinator DB support](https://coordinatordb.com/docs/resources/about/support) for the report contents and [HTTP diagnostics](https://coordinatordb.com/docs/concepts/features/interfaces/http) for response headers and status codes.
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-clickpipes
Language: en
# Connect ingestion clients over a private network
Coordinator DB accepts ingestion through its native client or HTTP SQL interface. It does not provision a cloud private endpoint or a managed ingestion connector. A private ingestion setup therefore connects your own importer to a reachable listener using your network's routing and access controls.
## Establish the SQL path first
Choose the server address the importer can reach and confirm the listener is enabled. From the importer host, check HTTP readiness and a small authenticated request before sending data:
```sh
curl --silent http://db.internal:7401/ping
curl --silent --user "$COORDINATOR_USER:$COORDINATOR_PASSWORD" \
--data-binary 'SELECT 1 FORMAT csv' http://db.internal:7401/
```
Use these plain HTTP examples only on a trusted route. The server does not provide TLS; external TLS termination or a protected tunnel belongs to your deployment.
## Validate ingestion separately
Create an explicit destination schema and upload a small file with a supported format. Check counts and values before increasing batch size. Keep network endpoint identifiers in the infrastructure configuration rather than inventing SQL settings for them. A successful health check confirms reachability, while an authenticated query also checks credentials.
See [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http), [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and [listener settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-msk-clickpipes
Language: en
# Import from a private managed Kafka source
A private managed Kafka cluster and Coordinator DB require separate client connections. Coordinator DB does not create Kafka consumers or private broker endpoints. Run a consumer in a network location that can reach the broker and an authenticated SQL endpoint.
## Separate the two checks
First verify broker access with the consumer's own tools and credentials. Then run a small SQL request from the same host. A broker connection failure should be investigated in broker routing, certificates and consumer permissions; a SQL authentication error belongs to the destination connection.
Decode records in the consumer and turn them into rows matching an explicit table schema. `json_each_row` is convenient when each message already contains named fields. Schema-bearing formats are another option when their conversion rules match the destination types.
## Commit progress after verification
Acknowledge source progress only after the destination operation succeeds according to your application's delivery policy. If the response is lost, inspect the destination using a stable event identifier before retrying. Coordinator DB does not couple a Kafka offset commit with a SQL transaction.
Keep broker credentials and database credentials separate. Test malformed messages, temporary network failures and duplicate delivery with a small dataset before relying on continuous import.
See [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading), [INSERT INTO](https://coordinatordb.com/docs/reference/statements/insert-into) and [HTTP requests](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/aws-privatelink-vpc-endpoint-service-for-msk-cluster
Language: en
# Plan a private route for a broker consumer
A broker endpoint service is part of the infrastructure that hosts your consumer and broker. It is not configured by Coordinator DB SQL. The destination database needs only a reachable native or HTTP listener and valid credentials.
## Draw the client connections
Identify the host running the consumer, the broker addresses it must resolve and the database address it will use. Check DNS resolution and network access from that host rather than from an administrator's laptop. A test from another network can succeed while the actual importer remains unable to connect.
Keep the broker's authentication and certificate configuration with the consumer. Configure Coordinator DB credentials independently. If the route includes a proxy or tunnel, test both a readiness request and a small authenticated INSERT followed by SELECT.
## Make failures attributable
Record which connection failed, the destination hostname, the time and the available request identifier. Do not send secrets or full private records in a support example. A retry policy should distinguish a failed connection from an ambiguous write response; only the latter needs destination reconciliation.
Coordinator DB does not advertise a broker endpoint service or provide a cloud networking API. Use your infrastructure provider's documented tooling for those resources.
See [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [HTTP authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/change-billing-email
Language: en
# Update an infrastructure billing contact
Coordinator DB's documented interfaces manage SQL requests and server configuration. They do not expose a hosted-service billing account, invoice recipient or billing-email API. A billing contact for a machine, network or storage service is managed with the provider that supplies that resource.
## Identify the account owner
Find the invoice or account record for the resource in question and confirm which organization owns it. Ask that account's administrator to change the billing contact through the provider's supported account workflow. Verify whether the change applies to future invoices, payment notices, or both; those can be separate settings in an external service.
Do not change a database username or an XML password field to update an invoice address. Those values control database authentication and are unrelated to billing. Similarly, an application email stored in a user table is ordinary application data.
## Keep operational contacts usable
Maintain a current contact for database access and incident coordination in your own operations records. Share only the resource identifier necessary to locate an invoice. Passwords, API keys and database exports are not needed for a billing-contact change.
For database identity changes, use the [users configuration](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users). For endpoint checks, see the [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/clickhouse-cloud-api-usage
Language: en
# Automate Coordinator DB SQL over HTTP
Coordinator DB provides an HTTP SQL interface rather than a hosted-service management API. Use `POST /` for SQL and `GET /ping` for an unauthenticated readiness check. Infrastructure provisioning, account billing and service lifecycle operations belong to your deployment tools.
```sh
curl --fail-with-body --silent \
--user "$COORDINATOR_USER:$COORDINATOR_PASSWORD" \
--data-binary 'SELECT 1 AS value FORMAT json_each_row' \
'http://127.0.0.1:7401/?database=data'
```
## Handle the response deliberately
Check the HTTP status before treating the body as query output. Capture `X-Coordinator-Query-Id` when diagnosing a failure. SQL errors usually return 400, invalid credentials return 401 and admission failures can return 503. Never turn every failure into an unconditional retry of a write.
The accepted URL parameters are `query`, `database`, `default_format` and `result_limit`. Passwords and API keys are not accepted in URL parameters. Duplicate or unknown parameters are errors.
Each HTTP request has a separate session. Put all transaction statements into one request and commit before it ends. Responses are buffered, bound parameters and persistent HTTP sessions are unsupported, and a client must escape application values safely rather than concatenate untrusted text.
See [HTTP request contract](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/confluent-cloud-private-connectivity-for-clickpipes
Language: en
# Connect a private Confluent consumer to SQL
Use an external consumer when records come from a private Confluent deployment. Coordinator DB does not configure the broker's private connectivity or offer a managed connector for it. The consumer must independently reach the broker and the Coordinator DB SQL endpoint.
## Choose an interchange contract
Decode the record with the consumer's schema tooling. Convert each value to a documented destination type and choose an input format. Do not assume a broker's serialized envelope is already a valid row upload. The `avro_confluent` format has its own schema-registry contract; it is not a Kafka subscription.
Create a small destination table and test a record containing missing fields, explicit nulls, Unicode and boundary numbers. Record a stable source event identifier if duplicate delivery must be detected.
## Keep delivery state outside the request
Send bounded batches, check the SQL response and only then advance the external consumer's progress according to your recovery policy. When a response is lost, reconcile by event identifier before resending. There is no transaction that atomically commits both broker offsets and database writes.
Use private routing or external TLS protection for the database connection. Store the two services' secrets separately and exclude them from diagnostic output.
See [Avro Confluent](https://coordinatordb.com/docs/reference/formats/avro/avro-confluent), [formats](https://coordinatordb.com/docs/reference/formats) and [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/custom-dns-alias-for-instance
Language: en
# Use a custom DNS name for SQL access
A custom DNS name is an address used by clients. It does not change a Coordinator DB database name or create a new listener. Configure the DNS record in the service responsible for your network, then make sure its destination reaches the intended native or HTTP address.
## Test from the client network
Use the same hostname and port the application will use. Confirm name resolution first, then check `/ping` and an authenticated SQL request. If an external TLS proxy terminates HTTPS, its certificate must cover the client-facing hostname and its upstream must reach the server.
Coordinator DB does not terminate TLS itself. Do not treat a DNS alias as encryption. Native client addresses include both host and port through `--addr`.
## Browser-specific checks
Browser requests require matching Origin and Host, and the server emits no CORS headers. Empty-password users are restricted to IP hosts or localhost. A custom hostname can therefore expose an authentication or origin restriction that a localhost command did not encounter.
Keep database credentials out of the DNS record and URL. If a name change fails, compare the resolved address, proxy route and HTTP response status before changing SQL settings.
See [HTTP browser access](https://coordinatordb.com/docs/concepts/features/interfaces/http), [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [listener configuration](https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/execute-system-queries-in-cloud
Language: en
# Inspect service metadata with system tables
Use Coordinator DB's documented `system` relations to inspect active requests, query history, table definitions and effective settings. A cloud-provider role does not add SQL commands. There is no general `SYSTEM` command interface for maintenance actions.
```sql
SELECT name, value
FROM system.settings
WHERE name IN ('max_execution_time', 'max_memory_usage')
FORMAT csv;
```
## Choose the right relation
`system.processes` describes active requests. `system.query_log` describes recorded request events, including terminal failures. `system.tables` and `system.columns` describe SQL objects. Always use the `system` qualifier and inspect the reference for the available columns instead of copying a metadata query for another product.
Most observational metadata is read-only. A relation's existence does not mean its counters can be edited. Use ordinary CREATE, ALTER and DROP statements for object changes, and the documented settings interface for configuration.
## Diagnose permissions and connection context
Confirm authentication, the selected database and the exact error before assuming a hosting restriction. Server-only XML options do not appear in `system.settings`; they are applied at startup. A missing column often means the query assumes an unsupported metadata contract.
See [system tables](https://coordinatordb.com/docs/reference/system-tables/overview), [settings](https://coordinatordb.com/docs/reference/settings) and [SQL statements](https://coordinatordb.com/docs/reference/statements).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/how-to-check-my-clickhouse-cloud-sevice-state
Language: en
# Check service readiness and SQL access
Use two checks to determine whether a Coordinator DB endpoint is usable. An unauthenticated readiness request tests the HTTP listener. A small authenticated SELECT also checks credentials and database selection.
```sh
curl --fail --silent http://127.0.0.1:7401/ping
curl --fail-with-body --silent \
--user "$COORDINATOR_USER:$COORDINATOR_PASSWORD" \
--data-binary 'SELECT 1 FORMAT csv' \
'http://127.0.0.1:7401/?database=data'
```
The readiness response is `Ok.`. A successful SQL response uses status 200. If HTTP is disabled, test the configured native listener with the supplied client instead.
## Interpret the failure stage
A connection refusal points to the address, listener or route. A 401 response points to explicit credentials. A SQL error can mean the selected database or statement is invalid. A 503 can indicate connection or request admission pressure rather than a stopped process.
For an external health monitor, choose a bounded check interval and protect stored credentials. Do not use an expensive query as a readiness probe. A healthy response does not certify the correctness of application data or the availability of an unrelated broker or object store.
Coordinator DB has no hosted-service state endpoint. Inspect the process with your deployment tooling when the network endpoint cannot be reached.
See [HTTP status codes](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [admission limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/how-to-connect-to-ch-cloud-using-ssh-keys
Language: en
# Reach SQL through an SSH tunnel
SSH keys authenticate access to an SSH host. They do not replace Coordinator DB's SQL username, password or HTTP Bearer key. When an operator already has SSH access to the server host, local port forwarding can provide a protected route to a listener bound to loopback.
```sh
ssh -N -L 17401:127.0.0.1:7401 operator@database-host
```
Keep that connection open, then address the forwarded port from a separate terminal:
```sh
curl --fail-with-body --silent \
--user "$COORDINATOR_USER:$COORDINATOR_PASSWORD" \
--data-binary 'SELECT 1 FORMAT csv' http://127.0.0.1:17401/
```
## Confirm both ends
The remote `127.0.0.1:7401` must be the HTTP listener reachable from the SSH host. Choose another local port if 17401 is already occupied. For native SQL, forward the native port and pass the corresponding local address to `coordinator client --addr`.
A successful SSH login proves only host access. A 401 response still requires checking the database credentials. A forwarding error requires checking the listener and route on the remote side. Do not publish private keys or passwords in a support report.
This is an external transport workflow; Coordinator DB does not manage SSH accounts or keys.
See [native client options](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [HTTP authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/ingest-failures-23-9-release
Language: en
# Diagnose ingestion failures after an upgrade
When an importer starts failing after a deployment change, identify the failing request before attributing it to a release. Coordinator DB does not publish a compatibility promise for another product's version numbers. Diagnose against the documented formats, schema and request limits of the installed build.
## Reduce the reproduction
Save the status code, exception code, query identifier, destination schema and a redacted sample that still fails. Separate an ordinary SQL body from an attached upload: ordinary HTTP SQL requests require Content-Length and have a 16 MiB ceiling, while attached INSERT uploads have a different size contract.
Check the registered format spelling, field names, nullability and numeric ranges. Format names use snake_case. Place statement `SETTINGS` before `FORMAT`; everything after the format name is input data.
## Compare with a small valid batch
Create an isolated test table and send one known-good row. Add the failing fields gradually until the conversion or request error is clear. Do not repeatedly replay a production batch whose outcome is unknown. Reconcile committed rows with stable identifiers first.
Keep the original deployment details in your incident record and test a correction with the same reduced input before resuming normal ingestion.
See [HTTP limits](https://coordinatordb.com/docs/concepts/features/interfaces/http), [format reference](https://coordinatordb.com/docs/reference/formats) and [INSERT INTO](https://coordinatordb.com/docs/reference/statements/insert-into).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/multi-region-replication
Language: en
# Move a verified database copy to another region
Coordinator DB does not provide automatic multi-region replication. To move a dataset, create an independent database copy or export a defined set of rows, transfer it with your infrastructure tools, and validate the destination before directing clients to it.
## Choose a transfer method
A local database copy uses the documented `VACUUM INTO` procedure and its restrictions. A logical transfer exports tables with explicit schemas and a supported interchange format. Record the moment or key boundary represented by the copy so users know which writes it includes.
Do not open the same database file from separate processes. Start the destination with its own file and listener addresses. Moving a file between hosts does not turn the two copies into synchronized replicas.
## Plan the cutover
Decide how writes are paused or routed while the final copy is taken. Compare table definitions, row counts and representative values, then test the destination with the application's actual queries. Maintain a clear rollback decision before accepting new writes at the destination; later writes will not automatically return to the source.
Credentials, DNS and external transport protection need their own destination configuration. A successful file transfer alone does not prove SQL access or data completeness.
See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview), [local copy procedure](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk) and [Parquet exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/parquet).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/opt-out-core-dump-collection
Language: en
# Control diagnostic artifacts in your deployment
Coordinator DB's documented configuration includes diagnostic log files and structured query history. It does not expose a hosted core-dump collection preference. Crash-artifact creation and collection are controlled by the operating system, container runtime or external monitoring service in your deployment.
## Identify what is being collected
Ask the host administrator which crash handler receives artifacts, where they are stored and who can read them. Review that tool's own retention and upload settings. Changing query logging does not disable a host crash collector, and disabling a collector does not change ordinary SQL history.
Treat diagnostic artifacts as potentially sensitive: query text, credentials supplied by an application, or application data can appear in surrounding context. Do not attach a full memory artifact to a public issue merely to demonstrate a failed request.
## Prefer a small reproduction
For a SQL failure, record the query identifier, exception code and a minimal redacted input. Structured `system.query_log` entries can provide duration and resource counters without a whole-process artifact. For server log paths and rotation, inspect the startup XML configuration.
Apply changes to external diagnostic tooling through the administrator who owns it, then verify its actual behavior on the host.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/cloud-services/unable-to-access-cloud-service
Language: en
# Restore access to a SQL endpoint
An inaccessible endpoint can fail before SQL is received. Test from the affected client host and keep the exact address, port and error. A successful connection from localhost does not prove that a remote application can reach the same listener.
## Find the failing layer
Check that the hostname resolves to the expected destination and that the configured native or HTTP port is reachable. Confirm `listen_host` and any command-line address override on the server. HTTP is optional and is disabled when `http_port` is omitted.
For HTTP, test `/ping` before an authenticated query. A 401 response indicates credential failure. A 403 can indicate an Origin/Host restriction. A 503 can indicate admission or locking pressure. Capture the query identifier and exception code when a SQL response includes them.
## Avoid unrelated changes
Do not rotate credentials to fix a refused TCP connection or raise query memory limits to fix DNS. Check each stage independently. Configuration-file edits require a restart, so verify the file path used by the running process before applying a change.
There is no hosted account state or recovery console in the documented Coordinator DB interface. Use the deployment's process and network tools for a stopped host or blocked route.
See [HTTP status codes](https://coordinatordb.com/docs/concepts/features/interfaces/http), [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) and [connection limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/tcp-connection-limits).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/about-quotas-and-query-complexity
Language: en
# Apply request budgets without per-user quotas
Coordinator DB provides per-request processing limits and server admission controls. It does not implement per-user quotas, usage allowances or user settings profiles. Choose limits from the work you need to bound rather than treating every control as a user-specific policy.
## Separate resource budgets from admission
`max_execution_time`, `max_memory_usage`, `max_result_rows` and `max_response_bytes` bound a request. Its statements share the relevant budget. Server XML values form ceilings, and saved database settings can tighten them. A zero value removes only the added ceiling at that scope.
`max_connections`, `max_inflight_request_bytes` and `request_read_timeout` are server-only controls. They address admission and transport behavior rather than a customer's monthly usage. Do not attempt to persist them with `SET`.
## Inspect the effective policy
```sql
SELECT name, value
FROM system.settings
WHERE name IN ('max_execution_time', 'max_memory_usage', 'max_result_rows')
ORDER BY name
FORMAT csv;
```
Saved database changes affect other clients selecting that database, so coordinate administration changes. If an application needs per-account allowances, enforce and record that policy in its own request layer; the database settings do not identify those accounts.
See [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity), [server admission](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max) and [server ceilings](https://coordinatordb.com/docs/concepts/features/configuration/settings/constraints-on-settings).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/alter-user-settings-exception
Language: en
# Replace an unsupported ALTER USER setting change
Coordinator DB does not support `ALTER USER` for settings profiles or credential changes. Credentials and SQL request defaults use different interfaces. Select the one that matches the intended change instead of rewriting the same unsupported statement.
## Change credentials
Users are declared in the file selected by `users_config`. A user has exactly one password representation and can have an HTTP API-key digest. Edit the existing file and restart the server to apply credential changes. Usernames are case-sensitive; duplicate users and shared API-key digests are rejected.
## Change a database default
Select the intended database and use a supported `SET` name, for example:
```sql
SET max_execution_time = 5;
```
The value persists for the selected database and affects later requests from other clients. It is not a private preference of the authenticated user. The change requires autocommit and no active transactions in that database, and it cannot relax a stricter server ceiling.
Use `system.settings` to inspect the effective result. Format options use statement `SETTINGS` instead of persisted `SET`. Record the actual error text when a change fails; an unsupported name, invalid value and active transaction require different corrections.
See [users_config](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users), [SET](https://coordinatordb.com/docs/reference/statements/set) and [format settings](https://coordinatordb.com/docs/reference/settings/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/change-the-prompt-in-clickhouse-client
Language: en
# Use native client commands and connection options
The supplied native client provides interactive SQL, history and completion. Its documented options select the address, identity, database and query. A custom prompt-format option is not part of the public command-line contract.
```sh
./coordinator client --addr 127.0.0.1:7400 --database data
```
## Confirm the connection explicitly
Use a distinct terminal title or your terminal application's labeling when several environments are open. Keep the chosen address and database visible in your own session notes. Do not assume that changing a shell prompt changes the database selected by an already running SQL connection.
In the interactive client, `help` lists commands and `.quit` exits. Up and Down recall history, and Tab completes keywords, databases, tables and columns. A final SQL semicolon is optional for complete input. Incomplete quotes and trigger bodies continue onto another line.
## Keep automation separate
Use `--query` for a scripted request that writes only exact result bytes to stdout. Piped SQL does not read or write interactive history. For secrets, the password can come from `COORDINATOR_PASSWORD`; avoid placing real credentials in shared command examples or terminal screenshots.
See [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [command-line syntax](https://coordinatordb.com/docs/concepts/features/interfaces/cli) and [USE](https://coordinatordb.com/docs/reference/statements/use).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/configure-a-user-setting
Language: en
# Configure a database request default
Request defaults in Coordinator DB are saved for a selected database. They are not per-user profiles. Before changing one, confirm the intended database and inspect the effective current value.
```sql
SELECT name, value, type
FROM system.settings
WHERE name = 'max_result_rows'
FORMAT csv;
```
A supported persisted change uses `SET`:
```sql
SET max_result_rows = 10000;
```
## Understand the scope
The change requires autocommit with no active transactions in that database. Other connected clients observe committed settings before later requests. Resource limits are sampled at request start; a SET inside a multi-statement request changes defaults for later requests rather than the active request's budget.
A nonzero server XML ceiling remains effective when it is stricter. Read `system.settings` for the effective value and `main.settings` for a saved value when investigating the difference.
## Choose the right interface
Only documented SET names are accepted. Connection flags and database-header values use PRAGMA or validated catalog writes. Format options such as CSV delimiters use the statement's `SETTINGS` clause and do not persist. Credential changes belong to the users XML file and require a restart.
See [SET reference](https://coordinatordb.com/docs/reference/statements/set), [database settings](https://coordinatordb.com/docs/reference/settings/session-settings) and [server ceilings](https://coordinatordb.com/docs/concepts/features/configuration/settings/constraints-on-settings).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/ignoring-incorrect-settings
Language: en
# Correct an unknown or invalid setting
Coordinator DB rejects unknown configuration elements and unsupported setting names. It does not provide a switch to silently ignore arbitrary incorrect settings. Treat the error as evidence that a name, value or configuration scope needs correction.
## Identify the interface
A server XML option belongs inside the `coordinator` root and is validated at startup, even if a command-line argument overrides it. A persisted database option uses one of the documented SET names. A format option uses `SETTINGS` on a statement, before `FORMAT` on an INSERT.
For example, a CSV delimiter is a statement option rather than a database default:
```sql
SELECT 1 AS id, 'Ada' AS name
SETTINGS csv_separator = ';'
FORMAT csv;
```
## Check names and values
Inspect the relevant reference for spelling, type and accepted range. Do not assume another database's option is an alias. `system.settings` lists effective database values and read-only format defaults, but it omits server-only XML options.
Correct one setting at a time and repeat a minimal request. When a copied configuration contains many unsupported names, remove those names deliberately after reviewing their purpose rather than disabling validation. That avoids silently losing a behavior the operator expected.
See [configuration validation](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [SET](https://coordinatordb.com/docs/reference/statements/set) and [format settings](https://coordinatordb.com/docs/reference/settings/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/configuration-settings/maximum-number-of-tables-and-databases
Language: en
# Plan the number of tables and databases
Do not plan capacity from an undocumented maximum object count. Coordinator DB exposes managed database and table inventories, while practical limits depend on the workload and resources available to your deployment. A successful CREATE alone does not prove that a very large catalog meets your latency goals.
```sql
SELECT database, count(*) AS objects
FROM system.tables
WHERE schema_name = 'main'
GROUP BY database
ORDER BY database
FORMAT csv;
```
## Choose a useful object boundary
A table should represent a meaningful schema and access pattern. Avoid creating one table per event, customer or time bucket solely to imitate a partition feature. A shared table with explicit identifiers can make application queries and schema changes easier to manage, provided it matches the required data contract.
## Measure catalog growth
Test the expected number of databases and tables in a nonproduction environment. Include startup, metadata discovery, ordinary queries and the schema changes your application performs. Record resource usage and client-visible duration as the catalog grows.
Use `system.databases`, `system.tables` and `system.columns` to confirm what actually exists. Filter by database and namespace when identical table names are intentional. Do not treat a table-size estimate as an exact count of its rows.
See [database inventory](https://coordinatordb.com/docs/reference/system-tables/databases), [table inventory](https://coordinatordb.com/docs/reference/system-tables/tables) and [schema design](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/schema-design).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/achieving-atomic-inserts
Language: en
# Commit related inserts atomically
Use a transaction when several changes must become one unit of commit or rollback. Outside an explicit transaction, statements autocommit. Choose the request interface before designing the operation because HTTP and native connections retain different session state.
```sql
BEGIN;
INSERT INTO accounts(id, balance) VALUES (1, 100);
INSERT INTO audit_log(account_id, action) VALUES (1, 'created');
COMMIT;
```
## Keep the transaction together
A native connection retains an open transaction until it commits, rolls back or closes. Closing the connection rolls back uncommitted changes. Separate invocations of the command-line client are separate connections and cannot continue each other's transaction.
Each HTTP request creates its own session. Put BEGIN, every related SQL statement and COMMIT in the same request. An unfinished transaction is rolled back before the response. Inline `INSERT ... FORMAT` consumes the rest of its request as data, so do not append a COMMIT after that input. For an HTTP workflow needing several formatted loads, use staging data and a later SQL transaction for the final changes.
Test error handling as well as success. When a client loses a write response, reconcile using application identifiers before retrying; transport failure alone does not prove rollback.
See [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions), [INSERT input](https://coordinatordb.com/docs/reference/statements/insert-into) and [HTTP sessions](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/cannot-append-data-to-parquet-format
Language: en
# Add data to a Parquet export safely
A Parquet export is a complete file with a schema and footer. Appending the bytes from another `SELECT ... FORMAT parquet` does not produce a single combined file. Treat each export as an independent artifact or create a new file containing the intended combined rows.
## Rebuild a combined export
Load the existing file into a table with an explicit compatible schema. Insert the additional rows, validate the result, then export a new file using the native client's exact-byte output:
```sh
./coordinator client --database data \
--query 'SELECT id, name FROM people ORDER BY id FORMAT parquet' \
> people-new.parquet
```
Only replace the previous artifact after the command succeeds and the new file passes a read-back check. A shell redirect can create a partial file before a query reports an error; an existing filename is therefore not proof of success.
## Keep files separate when appropriate
For periodic exports, choose a unique filename per batch and maintain a manifest outside SQL. Consumers can process those files as separate datasets. Coordinator DB's server `file()` source reads one confined regular file; it does not expand path patterns or append files.
See [Parquet format](https://coordinatordb.com/docs/reference/formats/parquet/parquet), [native client output](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [file source](https://coordinatordb.com/docs/reference/functions/table-functions/file).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/file-export
Language: en
# Export query results to a client file
Use native `--query` mode to write query results to a file on the client machine. It writes only result bytes to stdout, including binary formats. The filename is interpreted by the shell, so it need not be accessible to the server.
```sh
./coordinator client --database data \
--query 'SELECT id, name FROM people ORDER BY id FORMAT csv_with_names' \
> people-export.csv
```
## Select a format deliberately
CSV with names is useful for tools that need column headers. `json_each_row` writes one named object per row. Parquet preserves a schema and native value mappings suitable for compatible consumers. Use explicit selected columns so the exported contract does not change merely because another column was added.
Check the client's exit status before publishing or replacing an artifact. Redirect to a new temporary filename first, validate its row count or read it back, then move it into the intended location. Do not mistake an error-created empty file for a successful export.
## Know the limits
Result rows and encoded response bytes still have request limits. For large exports, choose explicit ordered key ranges and verify every range. Server-side `file()` is an input source and cannot write an export file.
See [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [formats](https://coordinatordb.com/docs/reference/formats) and [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/importing-and-working-with-json-array-objects
Language: en
# Work with arrays of JSON objects
A JSON array of objects is one document, while `json_each_row` expects one object for each input row. Choose which representation the destination needs before loading the source. Keeping the whole document and expanding it later can be useful for small request payloads.
```sql
SELECT id, name
FROM json_to_recordset('[{"id":1,"name":"Ada"},{"id":2,"name":"Grace"}]')
AS item(id UInt64, name String)
ORDER BY id
FORMAT csv;
```
## Declare the row contract
The recordset declaration makes the intended column names and types explicit. Test missing fields, nulls and values outside the declared ranges. A flexible source document is not a reason to accept an ambiguous destination schema.
For larger files, convert the outer array to one object per line in the importer and send it with `INSERT ... FORMAT json_each_row`. Do not merely rename the file: the byte representation must actually match the selected format.
If the array is a property inside a retained JSON column, extract that property first and expand its elements with the documented JSON table functions. Preserve a source identifier when one parent document produces several child rows, so later validation can reconcile the expansion.
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions), [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading) and [JSON type](https://coordinatordb.com/docs/reference/data-types/json).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/importing-geojason-with-nested-object-array
Language: en
# Import GeoJSON features with nested properties
The `geo_json` format reads a GeoJSON FeatureCollection and binds its fixed `id`, `geometry` and `properties` members. Nested properties can remain a JSON document instead of being flattened into unrelated columns during ingestion.
## Establish the destination contract
Choose a compatible native geometry type for the shapes being imported and a JSON declaration for flexible properties. Validate a small source file before a full import. Supported shapes include Point, MultiPoint, LineString, MultiLineString, Polygon and MultiPolygon. GeometryCollection is unsupported; the documented null policy can validate and replace it on input.
Use JSON functions to inspect an array-valued property after import. JSON arrays use zero-based indexes, which differ from native Array indexing. For example, extracting the first tag from a JSON document uses a JSON path such as `$.tags[0]`.
## Check geometry and properties independently
Coordinates must be finite. Geometry validation also checks ring closure, minimum line or ring sizes and nonempty collections. A syntactically valid JSON document can still fail these geometry requirements. Inspect the failing feature rather than disabling validation for an entire dataset.
When exporting, select exactly one native geometry column; other columns become properties unless a single object-valued `properties` column supplies them directly.
See [geo_json](https://coordinatordb.com/docs/reference/formats/geo-json), [geometry types](https://coordinatordb.com/docs/reference/data-types/geometry-types) and [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/ingest-parquet-files-in-s3
Language: en
# Import Parquet downloaded from object storage
Coordinator DB's documented file source reads confined local files; it is not an object-storage client. Download a Parquet object with the storage service's own authenticated tools, then load its bytes through the native client or an HTTP attached upload.
## Verify the downloaded object
Check the download command's success and the expected object version or checksum before importing. Create a destination table with explicit types compatible with the Parquet schema. Test a small representative file first, especially for timestamps, decimals, nested collections and nullable fields.
```sh
./coordinator client --database data \
--query 'INSERT INTO imported_people FORMAT parquet' \
< people.parquet
```
The example assumes `imported_people` already exists. Standard input is read on the client machine. Alternatively, place the file under the server's configured `user_files_path` and use `file()` with an explicit schema.
## Make retries traceable
Record which object and version each batch loaded. If an import response is lost, inspect the destination before repeating it. Downloading an object twice does not make the corresponding inserts idempotent. Validate row counts and representative values after ingestion, then archive or remove the local download according to your own data-handling policy.
See [Parquet mappings](https://coordinatordb.com/docs/reference/formats/parquet/parquet), [file source](https://coordinatordb.com/docs/reference/functions/table-functions/file) and [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-extract-example
Language: en
# Extract values from a JSON document
Use the JSON functions that match the desired result type. A structured extraction retains a JSON value, while a text extraction returns decoded text. JSON null and SQL NULL have different meanings, so include both in tests.
```sql
SELECT json_extract_path_text('{"user":{"name":"Ada"}}', 'user', 'name') AS name,
json_extract('{"items":[10,20]}', '$.items[1]') AS second_item
FORMAT csv;
```
## Choose literal components or a path
`json_extract_path_text` accepts literal object keys and signed zero-based array indexes. `json_extract` accepts the documented JSON path syntax. Avoid building either expression by concatenating untrusted SQL text. In an application, encode input as data using a supported ingestion format or safely quote values according to the SQL contract.
For fields with a stable schema, a typed JSON path declaration can enforce a native type at write time and expose it through dotted column access. Missing typed paths receive the type default unless the declared type is Nullable.
## Validate the boundary cases
Check missing keys, explicit JSON null, empty arrays and a scalar where an object is expected. A query returning an empty string or zero can otherwise hide the distinction between a real value and a chosen default.
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) and [typed JSON paths](https://coordinatordb.com/docs/reference/data-types/json).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-import
Language: en
# Choose the right JSON input format
JSON is a family of input representations rather than a single row layout. `json_each_row` reads one object per row. Other registered formats handle arrays, columns or a whole document. Choose the format from the actual bytes and intended destination shape.
## Load named rows
```sql
CREATE TABLE customers(id UInt64, name String);
```
Send the following input as its own request:
```sql
INSERT INTO customers FORMAT json_each_row
{"id":1,"name":"Ada"}
{"id":2,"name":"Grace"}
```
The keys map to destination columns. Declared types validate values. Unknown fields are errors unless the statement enables `ignore_unknown_fields`; enabling that option deliberately discards unmatched input rather than adding columns.
## Keep input and later SQL separate
Everything after `FORMAT json_each_row` is input data, including semicolons. Run validation queries in a later request. Put any format `SETTINGS` before `FORMAT`, since settings after it would be interpreted as data.
If the source is an outer JSON array, use a matching whole-document format or convert it to row objects in the importer. For a document retained in one JSON column, preserve it as a document instead of assuming each nested field is automatically a table column.
See [JSON input formats](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/formats), [json_each_row](https://coordinatordb.com/docs/reference/formats/json/json-each-row) and [JSON type](https://coordinatordb.com/docs/reference/data-types/json).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/json-simple-example
Language: en
# Load and query a small JSON dataset
A small end-to-end example is useful for checking an importer's field names and value types before sending a large file. Create a fresh destination table with an explicit schema:
```sql
CREATE TABLE sample_events(id UInt64, event String, amount Decimal(18, 2));
```
Send the row objects in a separate request:
```sql
INSERT INTO sample_events FORMAT json_each_row
{"id":1,"event":"purchase","amount":"12.50"}
{"id":2,"event":"refund","amount":"2.00"}
```
Then verify the result in another request:
```sql
SELECT id, event, amount FROM sample_events ORDER BY id FORMAT json_each_row;
```
## Review the contract before scaling
The field names must match the intended destination columns. A declared Decimal preserves an exact amount with its scale; it should not be replaced by an approximate type solely because the source encodes numbers as text. Decide how omitted values and explicit nulls should behave in the production table.
The input consumes the rest of its request. Do not append the verification SELECT after the row data. When sending a file, native stdin or an HTTP attached upload keeps the SQL separate from its input bytes.
Retain this reduced example when reporting a failure, replacing real customer values with equivalent synthetic values.
See [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading), [Decimal](https://coordinatordb.com/docs/reference/data-types/decimal) and [HTTP uploads](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/kafka-clickhouse-json
Language: en
# Load JSON records from an external Kafka consumer
Coordinator DB does not subscribe to Kafka topics. Use an external consumer to read messages, decode their values and submit row batches through the documented SQL interfaces. Keep broker-specific envelopes separate from the fields stored in your table.
## Define the message-to-row mapping
Create destination columns for the stable event identifier and fields the application will query. Use `json_each_row` when each decoded message is a named row object. A payload that contains a nested JSON document can retain that field as JSON while other columns remain typed.
Test absent keys, explicit nulls, schema changes and invalid numbers before continuous ingestion. Choose whether malformed messages stop a batch or are handled by the consumer's own rejection workflow. Do not silently turn an invalid record into an empty row.
## Design for redelivery
Wait for a successful destination response before advancing the consumer's progress. A lost response leaves an ambiguous result, so reconcile stable identifiers before a retry. The database does not atomically commit a Kafka offset alongside a SQL write.
If replacement by identifier is required, stage formatted rows and use a later explicit SQL operation; formatted INSERT input does not accept an `ON CONFLICT` clause.
See [json_each_row](https://coordinatordb.com/docs/reference/formats/json/json-each-row), [INSERT INTO](https://coordinatordb.com/docs/reference/statements/insert-into) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/kafka-to-clickhouse-setup
Language: en
# Set up a repeatable external Kafka import
A repeatable import needs a broker consumer, a documented row contract and a recovery policy. Coordinator DB provides the SQL destination. It does not provide a Kafka table engine or manage consumer groups.
## Establish a baseline
First read a small message sample with your chosen consumer tooling. Record the topic and source position in your importer's own state. Create an explicit destination table, then upload those records as one bounded batch. Query the destination to verify identifiers, null handling, numeric ranges and nested values.
Use separate credentials for the broker and database. Check connectivity from the machine running the consumer; a successful SQL call on a developer laptop does not verify that machine's network route.
## Exercise recovery before continuous use
Test an invalid message, a duplicate message and a destination connection failure. Decide when progress is acknowledged and how an ambiguous write is reconciled. Stable source identifiers let the consumer detect previously accepted records instead of blindly repeating a batch.
Batch size should be chosen from measured duration and memory, while respecting request admission and response limits. There is no asynchronous INSERT queue: a successful response follows completion of the statement. Monitor completed requests and errors to identify a change in behavior.
See [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [HTTP ingestion](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/mysql-to-parquet-csv-json
Language: en
# Exchange MySQL query results through files
Use MySQL's own client or an export tool to produce a file, then import that file into Coordinator DB. Coordinator DB does not expose a MySQL connection table function. CSV, row-oriented JSON and Parquet are useful interchange choices when both tools agree on their encoding.
## Define a stable export
Select explicit source columns and a bounded snapshot or key range. Document how the exporter represents nulls, decimals, timestamps, binary data and embedded delimiters. A filename ending in `.csv` does not identify the quoting or null conventions by itself.
Create the destination table with intended native types and import a representative sample. For a CSV file with column names, choose `csv_with_names` rather than treating its header as a data row. Use an external converter if the source tool cannot produce the required format.
## Verify before a full transfer
Compare row counts for the same source boundary and inspect values containing commas, quotes, Unicode and nulls. Preserve exact decimals as exact values rather than routing them through a floating-point intermediate. Export the validated Coordinator DB result in another format only after these checks pass.
Track completed ranges and source versions in the importer so retries can be reconciled.
See [CSV exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv), [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading) and [Parquet exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/parquet).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/parquet-to-csv-json
Language: en
# Convert Parquet rows to CSV or JSON
Convert a Parquet file by reading it into a typed table or a server `file()` relation, then selecting the desired output format. Decide how nested values and nulls should appear before choosing CSV for a consumer.
For a file already placed under `user_files_path`, an explicit server schema is required:
```sql
SELECT id, name
FROM file('people.parquet', parquet, 'id UInt64, name String')
ORDER BY id
FORMAT csv_with_names;
```
## Write the conversion on the client
Run the SELECT through native `--query` and redirect stdout to a new file. Use `FORMAT json_each_row` instead when the consumer needs one named object per row. Keep explicit selected columns and `ORDER BY` when deterministic output matters.
Parquet's schema does not remove the destination declaration requirement for ordinary `file()` input. Read the type-mapping reference for timestamps, exact decimals, geometry and binary values. A valid conversion can still lose meaning if a downstream CSV tool interprets strings as dates or floating-point numbers.
Check the command status and read a sample with the intended consuming tool. Query result-row and response-byte limits still apply; use verified ranges for a conversion that exceeds one response.
See [file source](https://coordinatordb.com/docs/reference/functions/table-functions/file), [Parquet](https://coordinatordb.com/docs/reference/formats/parquet/parquet) and [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/postgresql-to-parquet-csv-json
Language: en
# Exchange PostgreSQL results through files
Export a PostgreSQL query with the source system's own tools, then load the resulting file into Coordinator DB. The documented Coordinator DB interface does not provide a direct PostgreSQL connector. File exchange makes the source boundary and type conversions visible.
## Choose matching conventions
Select the columns and source range explicitly. For CSV, align the header, delimiter, quoting and null representation with the selected input format and settings. For JSON, make sure the export is truly one row object per record when using `json_each_row`. For Parquet, inspect the source schema before creating the destination.
Pay particular attention to exact numeric scale, timestamps with offsets, arrays and binary values. A source-specific textual representation is not automatically a compatible native value. Convert it in the source export or external importer when necessary.
## Validate the transferred dataset
Create a fresh destination table and load a representative sample before the full transfer. Compare row counts over the same boundary and inspect edge values. Record the snapshot or key range represented by each file so a later retry cannot silently duplicate accepted data.
Once validated, Coordinator DB can export the rows to another registered format through `SELECT ... FORMAT` and native exact-byte output.
See [format reference](https://coordinatordb.com/docs/reference/formats), [data types](https://coordinatordb.com/docs/reference/data-types) and [client file input](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-import-export/s3-export-data-year-month-folders
Language: en
# Organize exports in year and month folders
Coordinator DB writes query results to the client response. An external export job chooses local folders, filenames and any object-storage destination. There is no SQL command that automatically creates year and month prefixes in a remote bucket.
## Define a bounded export
Choose the date column, timezone interpretation and inclusive/exclusive boundaries for one period. Use those same boundaries for the export and its validation query. Select explicit columns and an order when the consumer needs reproducible row ordering.
The job can create a local path such as `exports/2026/10/orders.parquet`, run native `--query` with `FORMAT parquet`, and write the response to a temporary filename. Check the command's exit status and validate the completed file before renaming or uploading it.
## Track successful periods
Use the storage provider's authenticated tooling for upload. Record the period, source boundary and resulting object name in the job's own manifest. A folder name alone does not prove that an export completed or includes all expected rows.
If a period is too large for one response, split it into ordered key ranges with separate artifacts. Do not concatenate independent Parquet files into one binary file. Decide explicitly whether reruns replace a period or create a new version.
See [client exports](https://coordinatordb.com/docs/concepts/features/interfaces/client), [Parquet exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/parquet) and [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/backing-up-a-specific-partition
Language: en
# Preserve a selected date range
For a selected date range, use an explicit predicate to copy the rows you intend to preserve. Coordinator DB does not expose table partitions as independent backup objects.
```sql
CREATE TABLE archived_events AS
SELECT id, day, kind
FROM events
WHERE day >= '2025-01-01' AND day < '2025-02-01';
```
The half-open range includes all of January while giving the next period a clear starting boundary. Adapt the columns and dates to the actual table. `CREATE TABLE ... AS SELECT` copies values but not the source table's constraints. Define a destination explicitly when keys or checks must be preserved.
A copied table inside the same database is not an independent backup. To keep a separate whole-database copy, run `VACUUM INTO` outside an open transaction and choose an absent or empty destination. Follow its UTF-8 and table restrictions before relying on the copy.
Before deleting source rows, verify the archived values, retain the schema information needed to restore them and test the intended recovery process. Exact counts help catch omissions but do not alone prove that every value was copied correctly.
See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview), [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) and [result comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/calculate-ratio-of-zero-sparse-serialization
Language: en
# Measure zeros and missing values
Measure the actual values before deciding whether a column's representation needs attention. A zero value, an SQL NULL and an absent row have different meanings and should be counted separately.
```sql
CREATE TABLE sampled_measurements(value INTEGER);
INSERT INTO sampled_measurements VALUES (0), (0), (5), (NULL);
SELECT count(*) AS total_rows,
count(*) FILTER (WHERE value = 0) AS zero_rows,
count(*) FILTER (WHERE value IS NULL) AS null_rows,
1.0 * count(*) FILTER (WHERE value = 0) / nullif(count(*), 0)
AS zero_fraction
FROM sampled_measurements
FORMAT csv;
```
The denominator includes every row. If the reader task concerns only present measurements, use `count(value)` as the denominator and explain that choice. `nullif` protects the calculation for empty input rather than turning an undefined ratio into a misleading zero.
This distribution describes the selected rows, not on-disk compression savings. Coordinator DB does not document a sparse-serialization tuning switch tied to a zero ratio. Choose a suitable declared type, preserve the meaning of missing values and measure representative query behavior before changing the schema.
See [aggregate functions](https://coordinatordb.com/docs/reference/functions/aggregate-functions), [NULL handling](https://coordinatordb.com/docs/reference/data-types/nullable) and [type selection](https://coordinatordb.com/docs/concepts/best-practices/select-data-type).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/dictionaries-consistent-state
Language: en
# Keep lookup data consistent
Use a table for lookup data that must be queried and updated through Coordinator DB. There is no separately refreshed dictionary service to synchronize across requests.
```sql
CREATE TABLE product_labels(
product_id INTEGER PRIMARY KEY,
label TEXT NOT NULL
);
INSERT INTO product_labels VALUES (1, 'Notebook'), (2, 'Pen');
SELECT product_id, label
FROM product_labels
WHERE product_id = 1;
```
The primary key prevents several labels from competing for the same product identifier. If lookup changes must agree with related table changes, put them in one transaction and commit only after all statements succeed. A failure can then be rolled back as a unit instead of leaving one table partially updated.
For a larger lookup replacement, load and validate the proposed data first. Check duplicate keys, missing required values and referential assumptions before replacing the reader-visible data. The application must choose the replacement procedure; no background refresh interval makes independently submitted statements atomic.
HTTP transaction steps belong in one request, while a native connection can retain the transaction across submissions. Multiple clients should connect to one server rather than opening the same file from separate processes.
See [constraints](https://coordinatordb.com/docs/reference/statements/create/table), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/dictionary-using-strings
Language: en
# Use string-keyed lookup data
A string lookup can live in a table when entries should be queried, constrained and updated independently. Use a primary key to make each string resolve to at most one stored row.
```sql
CREATE TABLE country_names(code TEXT PRIMARY KEY, name TEXT NOT NULL);
INSERT INTO country_names VALUES ('FR', 'France'), ('JP', 'Japan');
SELECT name FROM country_names WHERE code = 'JP';
```
Choose an explicit normalization rule when callers may supply different spellings or letter cases. For example, normalize incoming codes in the application and store that same representation consistently. Do not silently assume that all string comparisons ignore case.
For a small collection stored inside a single row or expression, a native `Map(String, String)` is another option:
```sql
SELECT map_element(map('FR', 'France', 'JP', 'Japan'), 'JP');
```
Maps retain pair order and duplicate keys. Lookup selects the first matching pair, while a missing key returns the value type's default. Use `map_contains` when a stored default and a missing key must be distinguished. A map is therefore not the same contract as a unique-key lookup table.
See [map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions), [Map](https://coordinatordb.com/docs/reference/data-types/map) and [table constraints](https://coordinatordb.com/docs/reference/statements/create/table).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/read-consistency
Language: en
# Read related data in one transaction
Begin a transaction when several SQL steps belong to one unit of work. Statements outside an explicit transaction autocommit, so independently submitted reads and writes are not automatically one operation.
```sql
BEGIN;
SELECT id, amount FROM balances WHERE id = 1;
UPDATE balances SET amount = amount - 5 WHERE id = 1;
SELECT id, amount FROM balances WHERE id = 1;
COMMIT;
```
This example assumes the application's `balances` table already exists. Handle any statement error before deciding to commit; use `ROLLBACK` when the intended operation cannot finish. Constraints remain important even when an application first checks data with a SELECT.
Connection lifetime matters. A native connection retains its transaction, and closing it rolls back uncommitted changes. Every HTTP request has a separate session, so send the complete transaction in one request. An unfinished HTTP transaction rolls back before the response is sent.
Do not infer cross-process coordination from ordinary SQL transactions. Several connections in one process can share a database file; separate processes must use independent files or connect to one server. Query-history reads take fresh history snapshots and have their own documented visibility behavior.
See [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions), [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) and [query-log visibility](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/understanding-part-types-and-storage-formats
Language: en
# Distinguish tables from interchange formats
A Coordinator DB table is defined by its columns and constraints. Import and export formats describe how rows cross an interface; choosing CSV or JSON output does not change the stored table's definition.
```sql
SELECT table_name, table_type, definition
FROM system.tables
WHERE schema_name = 'main'
ORDER BY table_name;
```
Inspect column metadata when a conversion problem depends on a declared type:
```sql
SELECT name, type, position
FROM system.columns
WHERE "table" = 'events' AND schema_name = 'main'
ORDER BY position;
```
Always identify the managed database when several databases contain similarly named objects. Available row and byte metadata can be estimates; use a concrete query when an exact count is required.
Coordinator DB does not expose MergeTree-style parts, compact-versus-wide part settings or merge queues as an administrative interface. Use `CREATE TABLE`, `ALTER TABLE` and `CREATE INDEX` for documented schema work. For moving data, select a registered input or output format that represents the values you need, and verify the receiving schema separately.
See [table metadata](https://coordinatordb.com/docs/reference/system-tables/tables), [column metadata](https://coordinatordb.com/docs/reference/system-tables/columns), [table definitions](https://coordinatordb.com/docs/reference/statements/create/table) and [formats](https://coordinatordb.com/docs/reference/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/when-is-ttl-applied
Language: en
# Apply an explicit retention cutoff
Coordinator DB does not document automatic table TTL processing. Apply retention with an explicit `DELETE` whose predicate expresses the cutoff you intend. Schedule that maintenance in the application or your own operations process if it must recur.
First preview the affected range:
```sql
SELECT count(*) AS expired_rows
FROM events
WHERE day < '2025-01-01';
```
Then use the same predicate for the change:
```sql
BEGIN;
DELETE FROM events WHERE day < '2025-01-01';
SELECT count(*) AS remaining_expired_rows
FROM events
WHERE day < '2025-01-01';
COMMIT;
```
Check the preview and ensure the intended backup or archive exists before executing the deletion. The transaction groups these steps but does not choose a safe business cutoff for you. Use `ROLLBACK` if the verification is wrong.
For timestamp columns, specify the precise timestamp and timezone convention instead of assuming a date label describes every boundary. Deletion takes effect in the current transaction; there is no background TTL queue whose completion makes it final. If using HTTP, all transaction statements must be in the same request.
See [`DELETE`](https://coordinatordb.com/docs/reference/statements/delete), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs
Language: en
# General Coordinator DB questions
Coordinator DB stores relational data, validates declared types and lets applications query and change rows with SQL. Start by choosing the reader task: a keyed lookup, a grouped report, a joined query or a transactional change. The same product can serve different tasks, but each should be checked against its documented public interface.
A first connection can verify SQL execution without creating application data:
```sql
SELECT 1 AS connected FORMAT csv;
```
Then create a small table and exercise the types, constraints and query shapes your task needs. A successful connection alone does not prove every syntax extension or external integration is available.
General questions often depend on connection scope. A native connection retains its selected database and open transaction. HTTP requests each have a separate session. An embedded connection opens a file or an in-memory database directly and does not expose server-only commands.
Use the [FAQ directory](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/faq-index) for specific questions, [use cases](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-cases-index) for examples and [operations](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/operations-index) for running a service. Keep feature claims tied to the [statement reference](https://coordinatordb.com/docs/reference/statements).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/columnar-database
Language: en
# Choose SQL by the reader task
When evaluating Coordinator DB, start with the operations your application needs rather than inferring capabilities from a database category label. The public contract covers typed tables, constraints, transactions, joins, grouped aggregates and window functions.
A reporting task can be expressed directly:
```sql
SELECT account_id, count(*) AS event_count, sum(amount) AS total_amount
FROM events
WHERE day >= '2025-01-01' AND day < '2025-02-01'
GROUP BY account_id
ORDER BY total_amount DESC
LIMIT 20;
```
This example assumes the table contains the named columns. Define representative data and verify the result before measuring it. Use `EXPLAIN QUERY PLAN` to inspect access choices and query history to inspect the actual execution's duration and read work.
For a keyed application lookup, primary keys and targeted indexes may matter more than a wide grouped report. For a multi-step change, transaction scope and constraints matter. These are separate reader tasks, so a single benchmark or a storage label cannot stand in for validating them all.
Choose declared types for the actual value range and precision, and avoid projecting columns the caller does not need.
See [SQL queries](https://coordinatordb.com/docs/reference/statements/select), [indexes](https://coordinatordb.com/docs/reference/statements/create/create-index) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/concurrency
Language: en
# Connect concurrent applications safely
Several applications can connect to one Coordinator DB server using native TCP or HTTP. The server's public connection and request limits determine how admitted work is bounded. This is different from opening the same database file independently in several processes.
Multiple connections within one process can share a file. Simultaneous access to the same file from separate processes is outside the supported concurrency model. If callers live in separate applications, connect them to one server process or give them independent database copies.
Native connections retain transactions and temporary tables. Closing a connection rolls back its uncommitted work. HTTP requests each have their own session, so an explicit transaction must start and finish in one request. Do not spread a transaction across several HTTP calls and assume they share state.
Observe active work before adjusting limits:
```sql
SELECT query_id, user, interface, elapsed
FROM system.processes
ORDER BY elapsed DESC;
```
The snapshot can include the observing request and does not guarantee that a listed request is still present later. Review admission settings and application retry behavior together when requests encounter locking or admission failures.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [server limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/cost-based
Language: en
# Inspect the chosen query plan
An optimizer label does not tell you which access path a particular Coordinator DB query will use. Inspect the documented plan output for the exact predicate, schema and representative input data.
```sql
CREATE TABLE plan_items(id INTEGER PRIMARY KEY, category TEXT, price INTEGER);
CREATE INDEX plan_items_by_category ON plan_items(category);
EXPLAIN QUERY PLAN
SELECT id, price FROM plan_items WHERE category = 'books';
```
The plan is evidence about this statement. It is not a promise that an index will be selected for every category, table size or differently written predicate. A primary-key equality lookup and a grouped scan can require very different work.
Use `EXPLAIN ANALYZE` when an executed measurement is needed. It runs the statement once and returns measured plan information instead of the original rows. For data-changing statements, those changes take effect unless rolled back in an appropriate transaction.
Compare equivalent results, keep the input data stable and record the query ID for terminal request counters. Do not describe undocumented optimizer statistics, cost formulas or tuning commands as supported APIs. A useful performance decision should be justified by the selected plan and actual reader workload.
See [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain), [index definitions](https://coordinatordb.com/docs/reference/statements/create/create-index) and [measurement comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/comparing-metrics-between-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/datalake
Language: en
# Query and import a local data file
Coordinator DB can read supported input formats from a confined server-side file source. This provides a concrete way to inspect a local dataset before importing it. It is not a documented object-storage catalog or automatic data-lake connector.
Place a regular CSV file beneath the configured `user_files_path`, then supply the decoding schema:
```sql
SELECT id, name
FROM file('people.csv', csv, 'id UInt64, name String')
WHERE id > 10
ORDER BY id
LIMIT 20;
```
The SQL path is relative to the configured root. Absolute paths, parent traversal and escaping symlinks are rejected. Confined server file access currently requires Unix, and this source does not expand path patterns or archives.
Use `INSERT ... SELECT` to persist the selected rows in a defined table once their values and types have been checked. For a file on the client machine, choose the native client's `FROM INFILE` workflow or an HTTP upload rather than assuming the server can read the client's path.
Select a format based on its documented input support and value representation. The presence of a filename alone does not establish compatibility with every possible file schema.
See [`file`](https://coordinatordb.com/docs/reference/functions/table-functions/file), [formats](https://coordinatordb.com/docs/reference/formats) and [bulk inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/dbms-naming
Language: en
# Name databases and SQL objects
Use Coordinator DB as the product name and choose application database names independently. A managed server database is created with `CREATE DATABASE`; creating it does not select it for the current connection.
```sql
CREATE DATABASE IF NOT EXISTS reporting;
USE reporting;
SELECT 1 AS connected FORMAT csv;
```
Managed database names ignore ASCII case. They begin with an ASCII letter or underscore, contain only ASCII letters, digits and underscores, and have at most 63 characters. `system` and `none` are reserved in any letter case.
For an HTTP query, select the database with the `database` URL parameter or put `USE` and its dependent statements in the same request. A later HTTP request has a separate session. An embedded connection instead opens a file or in-memory database and does not use these server commands.
Keep table and column names clear enough that predicates remain readable. When inspecting system metadata, include database and namespace information so identically named objects are not confused. Quote reserved identifiers in SQL rather than changing a metadata column's spelling.
See [`CREATE DATABASE`](https://coordinatordb.com/docs/reference/statements/create/database), [`USE`](https://coordinatordb.com/docs/reference/statements/use) and [qualified sources](https://coordinatordb.com/docs/reference/statements/select/from).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/dependencies
Language: en
# Prepare the files and credentials a service needs
A Coordinator DB server starts with an existing executable, server XML and a users file. Keep the supplied configuration beside the executable; the server does not generate missing configuration or infer credentials.
Before startup, confirm the selected configuration path and database path. `--config-file` chooses the server XML independently from `--db`. Relative user and log destinations start at the configuration directory, so moving only a database file does not move those other inputs.
The users file must explicitly declare the credentials clients will use. Test the native or HTTP interface required by the application rather than treating a running process as proof that the application can connect. A health check and an authenticated SQL request answer different questions.
No external coordination service, hosted account or managed connector is required by the documented local installation procedure. Add external secure transport or application authentication only where your deployment needs it, following that service's own instructions.
For installation prerequisites, use the current installation guide instead of guessing minimum versions or undocumented packages. Keep the first relevant error when setup fails.
See [installation](https://coordinatordb.com/docs/get-started/setup/install), [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [credentials](https://coordinatordb.com/docs/concepts/features/security) and [HTTP checks](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/distributed-join
Language: en
# Join related data in Coordinator DB
Use a regular SQL join when related rows are available in Coordinator DB tables or another documented local source. Distributed join modifiers and remote query execution are unavailable.
```sql
SELECT customers.id, customers.name, orders.amount
FROM customers
LEFT JOIN orders ON orders.customer_id = customers.id
ORDER BY customers.id, orders.amount;
```
The example assumes the two application tables already exist. A LEFT JOIN preserves customers without orders and fills the missing side with SQL NULL. If an order key has multiple matches, every matching pair contributes a row; check key uniqueness before interpreting totals.
For data held elsewhere, use a documented import workflow to create a suitable local table, validate its keys and then join it. Decide how fresh that imported copy must be and how the application will replace it. A join does not automatically synchronize an external source.
Keep right-side match conditions in `ON` when unmatched left rows must survive. A later `WHERE` predicate on the nullable right side can remove those rows. Inspect the actual plan and result cardinality before changing indexes or denormalizing the data.
See [JOIN behavior](https://coordinatordb.com/docs/reference/statements/select/join), [bulk input](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and [query plans](https://coordinatordb.com/docs/reference/statements/explain).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/faq-index
Language: en
# Coordinator DB frequently asked questions
Use these questions to choose the public documentation for the task at hand. Coordinator DB supports relational SQL, typed values, transactions and server or embedded connections. Feature names from another database should be checked against the reference before their syntax is used.
For the general query model, start with [SQL](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/sql), [analytical queries](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/olap) and [data changes](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/updates). For application connections, read [concurrency](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/concurrency) and [integration choices](https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations).
For a concrete reader task, the use-case guides show [key lookups](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/key-value), [time series](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/time-series), [log analysis](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-clickhouse-for-log-analytics) and [vector distances](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/vector-search). These describe supported SQL workflows rather than a managed service or an automatic ingestion promise.
When an answer depends on the interface, state whether the query runs through native TCP, HTTP or an embedded connection. Session lifetime, parameter binding and server commands differ. Include the selected database and exact error when asking for help; remove credentials and private input values.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) and the [statement reference](https://coordinatordb.com/docs/reference/statements).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/federated
Language: en
# Query available data sources deliberately
A SELECT can read tables, views, subqueries and documented table functions. On the server, a source named `database.schema.table` selects a registered managed database for that statement without changing the connection's selected database.
```sql
SELECT id, name
FROM reporting.main.products
WHERE id = 1;
```
This example requires a registered `reporting` database and its `products` table. It is a qualified server source, not a remote network address. The public interface does not promise federated execution against arbitrary external databases.
For an external dataset, import rows through a supported format or inspect a confined local file with `file()`. Define types explicitly and verify the imported data before joining it with application tables. The application owns any refresh procedure; a local copy does not stay synchronized by itself.
An embedded connection has its own documented namespace operations through `ATTACH` and `DETACH`. Keep those separate from the server's managed-database commands. In either mode, respect the rule against simultaneous access to one database file from separate processes.
See [FROM sources](https://coordinatordb.com/docs/reference/statements/select/from), [database selection](https://coordinatordb.com/docs/reference/statements/use), [file input](https://coordinatordb.com/docs/reference/functions/table-functions/file) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/how-do-i-contribute-code-to-clickhouse
Language: en
# Prepare a useful Coordinator DB contribution
Start a Coordinator DB contribution with a concrete public behavior: the SQL or connection task, what currently happens and what should happen instead. For a bug, include a small schema and synthetic rows that reproduce it. For a documentation fix, name the page and the statement that needs correction.
A useful SQL report keeps setup and observation together:
```sql
CREATE TABLE contribution_example(id INTEGER PRIMARY KEY, value INTEGER);
INSERT INTO contribution_example VALUES (1, 10);
SELECT id, value FROM contribution_example WHERE id = 1;
```
Replace this example with the smallest case that demonstrates your issue. Include the exact error and expected result, and state whether the request used native TCP, HTTP or an embedded connection. Interface differences can be part of the behavior being reported.
Before proposing a fix, check the public reference so a missing feature is not mistaken for a regression. Keep changes focused on the stated behavior and include meaningful verification. Do not publish private data, credentials or unrelated operational output in a contribution.
Use the project's current contribution instructions for its submission procedure rather than assuming a particular review policy or release schedule.
See [SQL statements](https://coordinatordb.com/docs/reference/statements), [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) and [installation](https://coordinatordb.com/docs/get-started/setup/install).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/key-value
Language: en
# Store and update keyed records
A simple key-value task fits a table with a primary key and a value column. The key contract prevents several rows from representing the same identifier, while ordinary SQL supports lookup, replacement and deletion.
```sql
CREATE TABLE app_values(key TEXT PRIMARY KEY, value TEXT NOT NULL);
INSERT INTO app_values VALUES ('theme', 'light');
INSERT INTO app_values(key, value) VALUES ('theme', 'dark')
ON CONFLICT(key) DO UPDATE SET value = excluded.value;
SELECT value FROM app_values WHERE key = 'theme' FORMAT csv;
```
The final value is `dark`. An absolute-value upsert can be repeated without appending another row for the same key. It does not automatically make a multi-key application operation atomic; use an explicit transaction when several records must change together.
Choose types according to the stored value. Use JSON when the value is a document that will be queried structurally, or separate columns when fields need their own constraints and predicates. A native Map inside one row has different duplicate-key and missing-value rules from this table.
For multiple application processes, connect to one server rather than opening one shared database file independently.
See [table constraints](https://coordinatordb.com/docs/reference/statements/create/table), [upserts](https://coordinatordb.com/docs/reference/statements/insert-into), [JSON](https://coordinatordb.com/docs/reference/data-types/json) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/mapreduce
Language: en
# Express grouped calculations in SQL
Many tasks described as mapping and reducing rows can be written as a SELECT followed by `GROUP BY`. Expressions calculate the values of interest, while aggregate functions combine rows sharing the grouping key.
```sql
CREATE TABLE usage_samples(account_id INTEGER, quantity INTEGER, unit_price INTEGER);
INSERT INTO usage_samples VALUES (1, 2, 5), (1, 3, 5), (2, 1, 9);
SELECT account_id, sum(quantity * unit_price) AS total
FROM usage_samples
WHERE quantity > 0
GROUP BY account_id
ORDER BY account_id
FORMAT csv;
```
This example produces one total per account. The filter selects participating rows before aggregation. Use `HAVING` when a predicate depends on the completed group total, and choose types appropriate for the numeric range and exactness required by the calculation.
This is ordinary SQL over the selected data sources, not a distributed MapReduce execution service. If input lives elsewhere, import or read it through a documented source first. Check join cardinality before grouping because duplicated matches can multiply a total even when the aggregate itself is correct.
See [`GROUP BY`](https://coordinatordb.com/docs/reference/statements/select/group-by), [`HAVING`](https://coordinatordb.com/docs/reference/statements/select/having), [aggregates](https://coordinatordb.com/docs/reference/functions/aggregate-functions) and [input sources](https://coordinatordb.com/docs/reference/statements/select/from).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/ne-tormozit
Language: en
# Investigate a slow query step by step
Begin with the exact query, representative data and the result the reader actually needs. A slow request can be expensive SQL, a large result or delayed response delivery. Do not change several limits before identifying which observation supports the diagnosis.
First inspect the access plan without executing a write:
```sql
EXPLAIN QUERY PLAN
SELECT id, amount FROM orders WHERE id = 42;
```
Then retain the real execution's query ID and read its terminal history. Compare duration, read rows, returned rows and peak accounted memory. Active `elapsed` includes the request's lifetime through response delivery, so it answers a different question from a plan measurement.
Check whether the query projects unnecessary columns, joins duplicate keys or requests rows that the caller never uses. A targeted index can help a repeated lookup, but verify its chosen access path and write overhead with the actual workload.
Finally, inspect effective settings if a request fails at a resource limit. Raising a ceiling is a deliberate operational choice, not evidence that the query became more efficient.
See [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks), [indexes](https://coordinatordb.com/docs/reference/statements/create/create-index) and [effective settings](https://coordinatordb.com/docs/reference/system-tables/settings).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/olap
Language: en
# Build analytical reports with SQL
Coordinator DB supports analytical query tasks through ordinary SQL: filters select the input, aggregates summarize groups and window functions compare rows without collapsing them all into one total. Start with a precise report question and verify its expected rows on a small dataset.
```sql
SELECT day, count(*) AS orders, sum(amount) AS revenue
FROM orders
WHERE day >= '2025-01-01' AND day < '2025-02-01'
GROUP BY day
ORDER BY day;
```
This query reports only dates present in the source. If empty dates must appear, generate or supply a calendar relation and join the totals to it. Choose a decimal declaration for money when exact decimal arithmetic is required, rather than inferring precision from display formatting.
Add joins carefully: a one-to-many relationship can multiply rows before aggregation. For ranking or running comparisons, use the documented window functions with an explicit ordering. An ordinary view can name a reusable report query but does not store its result.
Measure representative input sizes and output needs rather than promising performance from the word analytical alone. Inspect plans and query counters when a report becomes expensive.
See [aggregates](https://coordinatordb.com/docs/reference/functions/aggregate-functions), [window functions](https://coordinatordb.com/docs/reference/functions/window-functions), [views](https://coordinatordb.com/docs/reference/statements/create/view) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/operations-index
Language: en
# Operate a Coordinator DB service
A service needs explicit configuration, working credentials and a known database path. Start from the installation procedure, then verify the interface your application will use. A successful unauthenticated health check does not establish authenticated SQL access.
Use [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) to locate listener, user and log options. XML edits require a restart. Database settings have separate persistence and transaction rules, and `system.settings` reports effective values rather than every server-only XML option.
For observation, use [active requests](https://coordinatordb.com/docs/reference/system-tables/processes) for current work and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) for recorded terminal events. Keep query IDs with error reports. Diagnostic file logging and structured request logging are separate controls.
For recovery, use [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk) and test reopening an independent copy. For retention, review a cutoff and apply an explicit DELETE; do not wait for an automatic TTL queue.
Respect the [file-sharing model](https://coordinatordb.com/docs/get-started/about/deployment-modes): multiple client applications connect to one server process, while separate instances use independent files. Document the chosen credentials, listener addresses and recovery steps without publishing secrets or private row data.
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/separate-storage
Language: en
# Choose database paths and independent copies
`--db` selects the database file independently from `--config-file`. Moving a database path does not move the users file, diagnostic destinations or the confined input-file root. Relative user and log paths start at the configuration directory.
```sh
./coordinator serve --config-file /srv/coordinator/config.xml --db /srv/data/app.db
```
This illustrates path selection, not a requirement to use those directories. Prepare existing configuration and suitable filesystem access before startup. Use the intended listener addresses for the instance.
A path does not create remote storage semantics. The public interface does not document automatic separation of query compute from an object-storage service, and several processes must not open one database file simultaneously. Multiple applications can instead connect to one server that owns the file.
For an independent copy, use `VACUUM INTO` rather than copying only the live database file. Run it outside a transaction, choose an absent or empty destination and check the documented source restrictions. Open the resulting copy only with its own owner process and distinct listeners.
See [configuration paths](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview) and [file sources](https://coordinatordb.com/docs/reference/functions/table-functions/file).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/sql
Language: en
# Use Coordinator DB SQL deliberately
Coordinator DB SQL can create typed tables, insert rows, select and join data, calculate aggregates, use window functions and apply transactional updates or deletions. Use the statement reference for the exact supported syntax rather than assuming every extension from another SQL database is accepted.
```sql
CREATE TABLE sql_example(id INTEGER PRIMARY KEY, name TEXT NOT NULL);
INSERT INTO sql_example VALUES (1, 'Ada'), (2, 'Grace');
SELECT id, name FROM sql_example ORDER BY id FORMAT csv;
```
Declared types and constraints validate writes. A query's `ORDER BY` controls presentation order; stored row order is not a substitute. NULL values also require explicit predicates such as `IS NULL` when missing data is the target.
Some commands depend on the interface. Server connections support managed-database selection and output formats. An embedded connection opens its database directly and uses its own API for prepared bindings. HTTP requests have separate sessions, unlike a stateful native connection.
For unfamiliar behavior, reduce the case to a small schema, values, query and expected output. Inspect `EXPLAIN QUERY PLAN` when the concern is an access choice, keeping execution measurements separate from correctness checks.
See [statements](https://coordinatordb.com/docs/reference/statements), [functions](https://coordinatordb.com/docs/reference/functions), [data types](https://coordinatordb.com/docs/reference/data-types) and [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/time-series
Language: en
# Query dated measurements
Store a measurement's time, identity and value in declared columns. Choose `Date` for a calendar day or a documented timestamp type when time of day matters. State the timezone convention before comparing or aggregating timestamps.
```sql
CREATE TABLE daily_measurements(day Date, sensor_id INTEGER, value Float64);
INSERT INTO daily_measurements VALUES
('2025-01-01', 1, 10.0), ('2025-01-01', 1, 14.0),
('2025-01-02', 1, 12.0);
SELECT day, sensor_id, count(*) AS samples, avg(value) AS mean_value
FROM daily_measurements
GROUP BY day, sensor_id
ORDER BY day, sensor_id;
```
This query groups available rows. A day with no measurement does not appear automatically. Use a generated calendar or another date relation when a report must distinguish missing observations from a measured zero.
Use half-open ranges for adjacent reporting periods so their shared boundary is not counted twice. A targeted index can help repeated time-and-identity lookups; inspect the actual plan before keeping it. Retention is an explicit `DELETE` task, not automatic TTL processing.
See [Date](https://coordinatordb.com/docs/reference/data-types/date), [DateTime](https://coordinatordb.com/docs/reference/data-types/datetime), [series generation](https://coordinatordb.com/docs/reference/functions/table-functions/generate-series) and [retention](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/when-is-ttl-applied).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/updates
Language: en
# Update existing rows transactionally
`UPDATE` changes matching rows immediately in the current transaction. There is no asynchronous mutation completion step. Without `WHERE`, every row is updated, so preview the intended key set before applying a broad change.
```sql
CREATE TABLE inventory_items(id INTEGER PRIMARY KEY, quantity INTEGER);
INSERT INTO inventory_items VALUES (1, 5), (2, 3);
UPDATE inventory_items
SET quantity = quantity - 1
WHERE id = 1
RETURNING id, quantity
FORMAT csv;
```
The example returns the new quantity of 4. Assignment expressions can read old row values, and the resulting values must still satisfy declared types and constraints.
For a row that may not exist, use `INSERT ... ON CONFLICT ... DO UPDATE` when a suitable unique key defines the conflict. Decide how repeated requests should behave: subtracting twice is a different contract from setting an absolute value twice.
Wrap related changes in a transaction so the application can commit or roll back the complete operation. Native sessions retain open transactions; HTTP requires every transaction statement in one request. Confirm the committed state with a targeted SELECT rather than interpreting a read-work counter as the number of changed rows.
See [`UPDATE`](https://coordinatordb.com/docs/reference/statements/update), [upserts](https://coordinatordb.com/docs/reference/statements/insert-into) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-cases-index
Language: en
# Coordinator DB use cases
Choose a use case by the result a reader needs and the changes the application must make. The examples in this section use documented SQL behavior and make their data assumptions explicit. They do not imply an automatic external connector, managed service or background refresh process.
For exact identifiers and small records, start with [key-value lookups](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/key-value). Primary keys and upserts express how repeated keys should behave. For dated measurements, use the [time-series guide](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/time-series), with explicit timestamp and retention rules.
For operational events, [log analysis](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-clickhouse-for-log-analytics) combines typed columns with optional JSON attributes. For embeddings already supplied by an application, [vector comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/vector-search) show fixed-dimensional values and distance functions.
A task can combine these patterns, such as filtering events by account before grouping their counts. Validate joins and result cardinality before interpreting a report. Pick the connection mode according to session lifetime and file ownership, then measure representative queries through that same interface.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [types](https://coordinatordb.com/docs/reference/data-types) and [SQL statements](https://coordinatordb.com/docs/reference/statements).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-clickhouse-for-log-analytics
Language: en
# Analyze application event logs
Use typed columns for fields that reports commonly filter or group, such as a day, service name and severity. Keep optional structured attributes in JSON when their shape varies. The application supplies the events through a documented insert or file-input workflow; no automatic log collector is implied.
```sql
CREATE TABLE application_events(day Date, service TEXT, severity TEXT, details JSON);
INSERT INTO application_events VALUES
('2025-01-01', 'api', 'error', '{"route":"/orders"}'),
('2025-01-01', 'api', 'info', '{"route":"/orders"}');
SELECT day, service, count(*) AS errors
FROM application_events
WHERE severity = 'error'
GROUP BY day, service
ORDER BY day, service;
```
Keep timestamps and severity values consistent at insertion time so comparisons do not depend on accidental spelling differences. Use JSON extraction for a specific attribute and `json_each` only when the task needs expanded child rows.
Event retention requires an explicit cutoff and DELETE workflow. Review sensitive values before importing them, and remove them from support examples and exported results. Application event tables are separate from `system.query_log`, which records database requests rather than arbitrary application messages.
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions), [input formats](https://coordinatordb.com/docs/reference/formats), [retention](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/when-is-ttl-applied) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/vector-search
Language: en
# Compare fixed-dimensional vectors
Use `QBit` when an application supplies fixed-dimensional numeric vectors. Each value must contain exactly the declared number of non-NULL coordinates. Coordinator DB provides distance functions for comparing those stored values with a reference array; it does not promise automatic embedding generation or a vector index.
```sql
CREATE TABLE vector_items(id INTEGER PRIMARY KEY, embedding QBit(Float32, 3));
INSERT INTO vector_items VALUES (1, '[1,2,3]'), (2, '[1,2,4]');
SELECT id,
l2_distance_transposed(embedding, array(1,2,3), 32) AS distance
FROM vector_items
ORDER BY distance, id
LIMIT 2;
```
The 32 argument selects full Float32 precision. Lower probe precision can change the distance and therefore the ranking. Keep the reference dimension and metric consistent with how the application produced its vectors. Nonfinite coordinates are invalid, and cosine distance returns NULL for a zero-norm vector.
Filter the candidate rows with ordinary predicates when the reader task is restricted to an account or category. Measure representative candidate counts and verify ranking quality before choosing a lower precision. Do not infer approximate-nearest-neighbor indexing from the presence of a distance function.
See [QBit](https://coordinatordb.com/docs/reference/data-types/qbit), [distance functions](https://coordinatordb.com/docs/reference/functions/regular-functions/distance-functions) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/who-is-using-clickhouse
Language: en
# Evaluate Coordinator DB for your workload
Evaluate Coordinator DB using the task and data shape your application actually has. Public documentation describes supported SQL and connection behavior; it does not establish a customer roster, deployment count or performance guarantee for another organization's workload.
Prepare a small evaluation that includes the declared types, key constraints and query shapes you require. Verify expected output before increasing the data size. Include the real mix of reads and changes if both matter, rather than measuring only a constant SELECT.
For a read-heavy task, inspect the selected plan and record terminal duration, read work, result rows and peak accounted memory. For an application change, verify transaction behavior, repeated-request handling and errors as well as successful execution. Test through the interface the application intends to use.
Keep the evaluation reproducible with synthetic or shareable data. Describe the observed scope precisely: one dataset, query and environment do not prove every workload will behave the same way. If publishing a report, avoid invented users, private operational figures and claims the measurement did not establish.
See [use-case guides](https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/use-cases-index), [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/general-faqs/why-recommend-clickhouse-keeper-over-zookeeper
Language: en
# Choose a single-server application connection
The documented Coordinator DB server workflow lets several clients connect to one server process using native TCP or HTTP. It does not require a separately configured coordination service for that local service.
Choose one persistent database owner process and route application requests through its public interfaces. Several connections in that process can share the file. Separate processes must not open the same database file simultaneously; pointing independent services at a shared path does not create a supported cluster.
If you need a separate instance for testing or recovery, create an independent database copy with `VACUUM INTO`, then open it with its own listener addresses. That copy is independent. It does not replicate later source writes or elect a replacement server automatically.
Applications that need failover, replicated data or multi-region behavior must first distinguish those requirements from the available single-server connection model. Do not add coordination configuration fields that are absent from the public server reference and expect them to change the file-sharing rules.
Verify connectivity and recovery using the documented procedures before exposing the service to callers.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [native connections](https://coordinatordb.com/docs/concepts/features/interfaces/client), [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [independent copies](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations
Language: en
# Integrate an application with Coordinator DB
Choose an integration by where the application runs and how long its connection state must live. The documented public options are native TCP, HTTP and an embedded connection API. Do not assume a driver or compatibility protocol exists merely because another database offers one.
Native connections are stateful. They retain the selected database, transactions and temporary tables, and the supplied client supports interactive queries, scripted output and local file input. HTTP accepts authenticated SQL requests and returns registered formats; each request has its own session.
```sh
curl --silent --user default: --data-binary 'SELECT 1 FORMAT csv' \
'http://127.0.0.1:7401/?database=data'
```
This command uses the local sample account. Use the credentials and secure connectivity intended for the actual application. An embedded application opens its database directly and can use prepared bindings; server commands and format encoders are not part of that connection's interface.
For data exchange, choose an input or output format based on the values that must be preserved. Validate NULL handling, exact numeric types and repeated-request behavior before sending real data. Several applications should connect to one server instead of opening the same file independently.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [formats](https://coordinatordb.com/docs/reference/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/how-to-set-up-ch-on-docker-odbc-connect-mssql
Language: en
# Move SQL Server data into a containerized SQL service
A container does not add an ODBC connector to Coordinator DB. Use SQL Server's own client or an export tool to read the source, then send a supported file or row upload to the Coordinator DB endpoint. Treat source access and destination routing as separate checks.
## Verify the destination route
Inside a container, `127.0.0.1` refers to that container. An importer outside it must use a published host port or an address reachable on the configured container network. Confirm the destination HTTP listener with `/ping`, then run a small authenticated SELECT from the importer host.
Do not expose an empty-password service broadly to make a connectivity test succeed. Configure credentials and the intended listener before testing the real route.
## Transfer a defined dataset
Export explicit SQL Server columns to CSV, row-oriented JSON or a compatible Parquet file. Create the destination schema and validate a small batch, paying attention to decimal scale, timestamps, Unicode and nulls. Then transfer bounded batches with recorded source ranges.
If an export or import fails, keep the error attributed to the correct side. Coordinator DB does not manage SQL Server DSNs, drivers or credentials.
See [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http), [listener settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen) and [format reference](https://coordinatordb.com/docs/reference/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/node-js-example
Language: en
# Run a SQL request from Node.js
A Node.js application can use the documented HTTP interface without a database-specific package. Send SQL with POST, check the response status and select an output format that the application can parse.
```js
const endpoint = process.env.COORDINATOR_HTTP_URL;
const user = process.env.COORDINATOR_USER;
const password = process.env.COORDINATOR_PASSWORD;
if (!endpoint || !user || password === undefined) throw new Error('Missing connection configuration');
const response = await fetch(endpoint, {
method: 'POST',
headers: {
Authorization: `Basic ${Buffer.from(`${user}:${password}`).toString('base64')}`,
},
body: 'SELECT 1 AS value FORMAT json_each_row',
});
const body = await response.text();
if (!response.ok) throw new Error(`SQL HTTP ${response.status}: ${body}`);
console.log(JSON.parse(body));
```
## Keep the request contract visible
The example sends a fixed query and parses one returned row. For several `json_each_row` rows, parse each nonempty line separately. Do not concatenate untrusted input into SQL: HTTP bound parameters are unsupported. Encode uploaded values using a supported input format and keep schema choices under application control.
Use HTTPS through external TLS termination or a trusted route; the server itself has no TLS listener. Save `X-Coordinator-Query-Id` for diagnostics, redact secrets from errors, and reconcile an ambiguous write before retrying it. Each HTTP request has a separate session.
See [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [JSON row format](https://coordinatordb.com/docs/reference/formats/json/json-each-row).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/odbc-authentication-failed-error-using-powerbi-ch-connector
Language: en
# Connect reporting tools without assuming ODBC compatibility
An ODBC authentication error can occur before a query reaches Coordinator DB. The documented Coordinator DB interfaces are native TCP and HTTP SQL; they do not promise compatibility with a reporting tool's database-specific ODBC connector.
## Verify database access separately
Run a small authenticated HTTP SELECT from the reporting host. If it succeeds, the credentials and HTTP route are usable. It does not prove that the ODBC driver speaks the same protocol. Do not change server passwords repeatedly to fix a driver or protocol mismatch.
Confirm the connector's actual destination, port, protocol and expected product. A connector labeled for another database can assume unsupported login exchanges, metadata tables or SQL settings.
## Use a supported exchange path
When the reporting tool can import CSV or Parquet, export explicit columns through native `--query` and load that artifact into the tool. Validate timestamp, decimal and null interpretation with a small sample. For an application-controlled integration, use the HTTP interface and parse a supported result format.
There is no documented Coordinator DB ODBC driver or built-in reporting connector to configure. Keep a failed integration report specific: include the driver name, redacted endpoint, error stage and result of the independent HTTP check.
See [HTTP authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http), [native exports](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [formats](https://coordinatordb.com/docs/reference/formats).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/oracle-odbc
Language: en
# Import Oracle query results through a file
Coordinator DB does not query Oracle through an ODBC table function. Use an Oracle client or export tool to produce a file, then import it through Coordinator DB's native or HTTP interface. The source tool owns its driver, connection settings and credentials.
## Review the exported values
Select explicit columns and a known source boundary. Establish how the export encodes exact numeric scale, date and timestamp values, empty strings, nulls and large text or binary fields. CSV quoting must match the destination input format; a database-specific display format is not necessarily an interchange format.
Create a destination table with intended native declarations and load a representative sample. Use `csv_with_names` when the file includes a header, or convert the export to a supported row-oriented JSON format if that makes null and nested values clearer.
## Verify the result
Compare the same source range's row count and representative values after import. Include values with delimiters, quotes, Unicode and boundary numbers. Preserve the source export and its identifier long enough to reconcile an interrupted transfer.
For repeated import jobs, record completed batches outside the SQL request and check the destination before replaying a batch with an unknown outcome.
See [CSV exchange](https://coordinatordb.com/docs/guides/clickhouse/data-formats/csv-tsv), [data types](https://coordinatordb.com/docs/reference/data-types) and [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/python-clickhouse-connect-example
Language: en
# Use Python without a product specific database driver
Coordinator DB's native protocol is specific to its supplied client. A Python driver intended for another database is not a compatible replacement merely because some SQL syntax overlaps. Use HTTP for a Python integration unless a library explicitly implements the documented Coordinator DB contract.
## Start with a fixed query
The Python standard library can send a request with Basic authentication:
```python
import base64
import os
from urllib.request import Request, urlopen
credentials = f"{os.environ['COORDINATOR_USER']}:{os.environ['COORDINATOR_PASSWORD']}"
request = Request(
os.environ['COORDINATOR_HTTP_URL'],
data=b'SELECT 1 AS value FORMAT csv',
headers={'Authorization': 'Basic ' + base64.b64encode(credentials.encode()).decode()},
method='POST',
)
with urlopen(request, timeout=10) as response:
print(response.read().decode(), end='')
```
## Handle data separately
The example uses a fixed SELECT. For imported values, encode a supported input format instead of constructing SQL with untrusted strings. Check exceptions and preserve the response query identifier when available. A client timeout does not guarantee that a write was rolled back.
Each HTTP request has a separate session; transactions must begin and commit within one request. Use external TLS termination or a trusted route because the server does not provide TLS.
See [HTTP requests](https://coordinatordb.com/docs/concepts/features/interfaces/http), [formats](https://coordinatordb.com/docs/reference/formats) and [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/python-http-requests
Language: en
# Send Python HTTP queries and parse JSON rows
For a Python application using an HTTP client library, treat SQL errors and result data as different response paths. `json_each_row` produces one object per line, so parse each nonempty line rather than assuming the whole body is a single JSON array.
```python
import json
import os
import requests
response = requests.post(
os.environ['COORDINATOR_HTTP_URL'],
params={'database': 'data'},
auth=(os.environ['COORDINATOR_USER'], os.environ['COORDINATOR_PASSWORD']),
data='SELECT 1 AS value FORMAT json_each_row',
timeout=10,
)
query_id = response.headers.get('X-Coordinator-Query-Id')
response.raise_for_status()
rows = [json.loads(line) for line in response.text.splitlines() if line]
print(rows)
```
## Keep failures diagnosable
Install the external `requests` package in the application's own environment. Store credentials outside source code and use external TLS protection for an untrusted network. Preserve a redacted error body and query identifier when raising an application error.
The timeout belongs to the HTTP client; SQL processing has a separate `max_execution_time` setting. Do not automatically replay a timed-out INSERT, since its result can be ambiguous. HTTP bound parameters and persistent sessions are unsupported. For application data, send encoded format input with SQL in the `query` URL parameter rather than concatenating values into SQL.
See [HTTP uploads and metadata](https://coordinatordb.com/docs/concepts/features/interfaces/http), [JSON rows](https://coordinatordb.com/docs/reference/formats/json/json-each-row) and [execution deadlines](https://coordinatordb.com/docs/reference/settings/session-settings/max-execution).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/integrations/terraform-example
Language: en
# Manage deployment configuration with external automation
Coordinator DB does not provide a documented Terraform provider or hosted-service provisioning API. Use your infrastructure tooling to manage the host, network, service startup and configuration files. Use the SQL interfaces for database objects and data.
## Define the external resources
Choose the database file location, native and optional HTTP listener addresses, existing XML configuration path and credentials file. Relative configuration paths have documented rules: user and log paths start at the configuration directory, while an explicit relative `--config-file` starts at the working directory.
The server does not generate missing configuration files. Automation should place complete validated files before startup and keep secrets out of public plans, logs and version-controlled examples. File edits require a restart to take effect.
## Verify the result
After the service starts, test `/ping` when HTTP is enabled, then run an authenticated `SELECT 1` against the intended database. Apply schema migrations as an explicit separate step so a network failure is not confused with a SQL migration failure.
A declarative infrastructure run does not prove that the database contains the required tables or that an application can use its route. Capture both deployment success and the small SQL verification result in your own workflow.
See [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [command-line options](https://coordinatordb.com/docs/concepts/features/interfaces/cli) and [HTTP readiness](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/are-materialized-views-inserted-asynchronously
Language: en
# Choose live views or stored query results
An ordinary Coordinator DB view stores a SELECT definition. Reading the view evaluates that definition against its sources; it does not queue an asynchronous insert or maintain a separate result table. Materialized views and automatic refresh schedules are unavailable.
```sql
CREATE TABLE view_orders(id INTEGER PRIMARY KEY, amount INTEGER);
INSERT INTO view_orders VALUES (1, 40), (2, 60);
CREATE VIEW order_amounts AS
SELECT id, amount FROM view_orders WHERE amount > 0;
SELECT * FROM order_amounts ORDER BY id;
```
A later committed change to `view_orders` is read by subsequent view queries according to their normal transaction context. There is no refresh command to wait for.
When a report needs stored result rows, create a separate table with `CREATE TABLE ... AS SELECT`. That table is an independent copy; later source writes do not update it. The application must explicitly replace or adjust its rows and define when that work is considered complete. Use a transaction if several statements must commit together, and verify the stored totals against the source query after maintenance.
See [`CREATE VIEW`](https://coordinatordb.com/docs/reference/statements/create/view), [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/how-to-display-queries-using-mv
Language: en
# Inspect requests that query a view
Views are named SELECT definitions, so diagnose a view query as a normal SQL request. Capture its query ID from the response or query history, then inspect that request's terminal event.
```sql
SELECT query_id, query, query_duration_ms, read_rows, peak_memory_usage
FROM system.query_log
WHERE type = 'QueryFinish'
AND query LIKE '%order_amounts%'
ORDER BY event_time DESC
LIMIT 10;
```
A text search is only a convenient starting point. It can also match a comment, another object name or the diagnostic query itself. Use the exact query ID for a final correlation. `normalized_query_hash` groups structurally related statements but is not a catalog of view dependencies.
To understand how a particular view read accesses its source data, run `EXPLAIN QUERY PLAN` on that read. The plan describes the concrete statement; it does not prove that a stored materialization was refreshed. Coordinator DB ordinary views contain no stored result rows, and materialized views are unavailable.
Keep a record of the view definition with the diagnostic report so the source filters and joins are reviewable.
See [`CREATE VIEW`](https://coordinatordb.com/docs/reference/statements/create/view), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/how-to-use-parametrised-views
Language: en
# Filter an ordinary view with query parameters
Use an ordinary view for the reusable portion of a query and place caller-specific predicates in the SELECT that reads it. A view definition does not declare invocation arguments.
```sql
CREATE TABLE customer_orders(id INTEGER PRIMARY KEY, account_id INTEGER, amount INTEGER);
CREATE VIEW positive_orders AS
SELECT id, account_id, amount
FROM customer_orders
WHERE amount > 0;
SELECT id, amount
FROM positive_orders
WHERE account_id = 42
ORDER BY id;
```
The application supplies the account value for its own request. With the embedded connection API, prepared statements provide binding for values. Do not construct SQL by concatenating untrusted input. HTTP SQL requests do not accept bound parameters, so their caller must use a correctly escaped SQL value or another suitable application interface.
This filter is query behavior, not an access policy. A user allowed to submit arbitrary SQL is not restricted to the filtered view; database roles and row-level permissions are unavailable. Enforce any account boundary in the application and deployment that controls access.
See [`CREATE VIEW`](https://coordinatordb.com/docs/reference/statements/create/view), [prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements) and [authentication](https://coordinatordb.com/docs/concepts/features/security).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/projection-example
Language: en
# Use a targeted index for repeated queries
A query that repeatedly filters the same columns may benefit from a targeted index. Coordinator DB provides column, expression, partial and unique indexes; it does not provide automatically maintained aggregate projections.
```sql
CREATE TABLE account_events(
id INTEGER PRIMARY KEY,
account_id INTEGER,
day Date,
event_type TEXT
);
CREATE INDEX account_events_by_day
ON account_events(account_id, day);
EXPLAIN QUERY PLAN
SELECT id, day, event_type
FROM account_events
WHERE account_id = 42 AND day >= '2025-01-01'
ORDER BY day;
```
Inspect the selected plan for the exact predicate and representative data. Defining an index does not guarantee it will be chosen for every query shape. Extra indexes also add work to changes in the indexed table, so measure an actual reader task before keeping them.
When the expensive operation is a grouped calculation rather than a lookup, first check filters and aggregation. A separate summary table is possible, but its update procedure belongs to the application and must be explicit. An ordinary view names a query without storing its result.
See [`CREATE INDEX`](https://coordinatordb.com/docs/reference/statements/create/create-index) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/materialized-views/what-happens-to-refreshable-materialized-views-when-the-server-restarts
Language: en
# Check report data after a restart
Coordinator DB has no refreshable materialized-view scheduler to resume after a restart. An ordinary persistent view retains a SELECT definition, while a persistent report table retains the rows that were committed to it. These objects have different freshness rules.
After restarting, connect to the intended named database and read the view with a known predicate. The result is calculated from the current source data. There is no saved refresh interval or pending view refresh to inspect.
For a manually maintained report table, compare its contents with the source calculation:
```sql
SELECT count(*) AS source_rows, sum(amount) AS source_amount
FROM report_source;
SELECT count(*) AS report_rows, sum(amount) AS report_amount
FROM saved_report;
```
Replace these example object names with the tables used by your application. Compare like-for-like filters and aggregation levels; equal row counts alone do not prove equal contents. Record a completed refresh marker in the application's own data if its readers need an explicit freshness signal.
Uncommitted transaction work is not a successful refresh. Keep refresh changes and their marker in the same committed transaction when they must remain consistent.
See [views](https://coordinatordb.com/docs/reference/statements/create/view) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/check-query-cache-in-use
Language: en
# Investigate repeated-query performance
A repeated query can have a different duration even when its SQL is unchanged. Use measurements to determine what work the request performed; Coordinator DB does not document a result-cache setting or cache-hit counter that an application can rely on.
```sql
SELECT query_id, query_duration_ms, read_rows, read_bytes, result_rows
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 10;
```
Match the executions by query ID and verify that they read the same database and input values. Keep `LIMIT`, output format and result-row caps identical. A client that retrieves fewer bytes can appear faster even when SQL work is similar.
Inspect `EXPLAIN QUERY PLAN` if a change in the access path could explain the result. Use `EXPLAIN ANALYZE` for a measured execution when appropriate, remembering that it returns a plan instead of the usual rows and executes writes once.
Do not base correctness or freshness on a presumed cache lifetime. An ordinary view evaluates its SELECT when queried; if a stored result is required, maintain an explicit table with an application-defined update procedure.
See [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks) and [views](https://coordinatordb.com/docs/reference/statements/create/view).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/collect-and-draw-traces
Language: en
# Build a request timeline from query history
Start a request investigation with the query ID rather than attempting to reconstruct activity from unrelated log lines. HTTP responses expose `X-Coordinator-Query-Id`; structured request history uses the same identifier.
```sql
SELECT event_time_text, type, query_duration_ms,
read_rows, written_rows, exception_code
FROM system.query_log
WHERE query_id = 'replace-with-query-id'
ORDER BY event_time;
```
Record these events in time order when explaining a request to another reader. With logging enabled and a zero duration threshold, history records a start and terminal event. A nonzero threshold records only qualifying terminal events, so a missing start is not itself evidence of lost data.
For work still running, capture `system.processes` separately. It is a current snapshot, while query history describes recorded events. The current request's terminal event becomes available after execution completes.
These tables provide request measurements, not a distributed tracing export or stack-sampling interface. Keep a chart labeled with the observed event types and timestamp source rather than drawing unsupported spans. Include the exact SQL and relevant limits, with sensitive values removed.
See [query history](https://coordinatordb.com/docs/reference/system-tables/query-log), [active requests](https://coordinatordb.com/docs/reference/system-tables/processes) and [HTTP metadata](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/generate-har-file
Language: en
# Capture a browser request for diagnosis
A browser network archive can help explain a failed Playground request by preserving its URL, status and timing. Open the browser's developer tools, select the Network panel, clear unrelated requests and reproduce the issue once. Inspect the SQL request and its response before exporting the browser's network archive.
For Coordinator DB, useful details include the selected database, response status, `X-Coordinator-Query-Id`, `X-Coordinator-Exception-Code` and the response text. An HTTP SQL error commonly uses status 400; authentication and admission failures use different statuses. The exact error is more useful than a screenshot showing only a generic failure.
Before sharing an archive, remove Authorization headers, passwords, Bearer keys, SQL literals containing private data and returned rows. Inspect the exported file itself: a browser's display of hidden header values does not guarantee they were excluded from an export.
Browser requests must satisfy the documented Origin and Host rules, and the server does not emit CORS headers. If command-line requests succeed while browser requests fail, compare those request details directly rather than changing SQL at random.
See [HTTP requests and responses](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [authentication](https://coordinatordb.com/docs/concepts/features/security).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/mapping-of-system-metrics-to-prometheus-metrics
Language: en
# Choose request metrics for external monitoring
Choose a measurement by the question it answers. `system.processes` describes requests active now; `system.query_log` describes recorded request events. Coordinator DB does not document a Prometheus metrics endpoint or a built-in mapping from every query counter to a metric name.
```sql
SELECT count(*) AS active_requests,
max(elapsed) AS oldest_elapsed_seconds
FROM system.processes;
```
The observing request may appear in this snapshot. Do not interpret that count as a perfectly independent external connection count.
For completed work, aggregate terminal history within the observation period your collector manages. Avoid counting both start and finish events as separate executed queries. Distinguish `QueryFinish` from the two exception event types, and account for any configured minimum logging duration.
Use units in any externally chosen metric names. Durations in query history are milliseconds, `elapsed` in active requests is seconds, and memory counters are bytes. Terminal peak memory is a per-request peak, so summing it does not report current server memory. A monitoring collector must also handle repeated observations without double counting events.
See [process counters](https://coordinatordb.com/docs/reference/system-tables/processes), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/outputsendlogsleveltracestofile
Language: en
# Write diagnostic logs to a file
Coordinator DB diagnostic files are configured in the server's required `logger` section. Choose a supported level, ordinary and error destinations, a rotation size and an archive count. This configuration is separate from SQL request history.
```xml
information
server.log
server.err.log
10M
3
```
Place this section inside the existing `coordinator` root, then restart the server to apply it. Relative destinations start at the configuration directory, not at the directory of a database selected with `--db`. Check that the intended account can access the destination directory before restarting.
Supported diagnostic levels are `debug`, `information`, `warning`, `error`, `fatal` and `none`. A `trace` level and a client `send_logs_level` request setting are not documented interfaces. Use `debug` only when the extra detail is useful for the current investigation, and retain the rotation limits you need.
For request IDs, SQL duration, counters and exceptions, read the structured query log instead of trying to infer those fields from free-form file output.
See [logger settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings/other) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/profiling-clickhouse-with-llvm-xray
Language: en
# Profile SQL with analyzed execution plans
Use the documented SQL measurement interfaces before requiring a special executable or an external instrumentation format. `EXPLAIN QUERY PLAN` shows the selected access path without executing the statement; `EXPLAIN ANALYZE` executes it once and includes runtime measurements.
```sql
EXPLAIN ANALYZE
SELECT sum(generate_series)
FROM generate_series(1, 10000);
```
The output is an analyzed plan, not the sum the original query would return. Run the ordinary SELECT separately when you also need to verify its result. Keep generated ranges small enough for the question you are investigating and compare representative application queries before making a performance claim.
For a server request, retain its query ID and inspect the terminal event in `system.query_log` for duration, read work and peak accounted memory. The active-request snapshot is useful only while work is still present.
Analyzing a data-changing statement applies its changes once. Use a transaction and rollback when measurement must leave no committed change. Compiler-specific tracing commands and external profiler file formats are outside the documented Coordinator DB query interface.
See [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/send-logs-level
Language: en
# Choose diagnostic and query logging levels
There are two separate choices when collecting Coordinator DB diagnostics. Server XML controls diagnostic file verbosity. Database settings control whether structured query events are recorded and which duration threshold they must meet.
For request history, inspect the current effective values first:
```sql
SELECT name, value
FROM system.settings
WHERE name IN ('log_queries', 'log_queries_min_query_duration_ms')
ORDER BY name;
```
If the investigation requires every request, enable logging with a zero threshold:
```sql
SET log_queries = 1;
SET log_queries_min_query_duration_ms = 0;
```
`SET` persists database defaults and requires autocommit with no active transactions in that database. Consider the intended duration of that change and restore the chosen operational values when the investigation ends.
For diagnostic files, edit `logger.level` in the existing configuration and restart. Accepted levels include `debug` and `information`; client commands that request a per-query trace stream are not part of the documented interface. Increasing diagnostic verbosity does not override disabled structured query logging, and enabling query history does not change file verbosity.
See [logger settings](https://coordinatordb.com/docs/reference/settings/server-settings/settings/other), [logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/view-number-of-active-mutations
Language: en
# Monitor active data-changing requests
Coordinator DB applies `UPDATE` and `DELETE` immediately within the current transaction. There is no asynchronous mutation queue to poll after those statements have completed. Observe active requests and then verify their terminal outcome.
```sql
SELECT query_id, user, query_kind, elapsed, written_rows
FROM system.processes
WHERE query_kind IN ('INSERT', 'UPDATE', 'DELETE')
ORDER BY elapsed DESC;
```
The query classification describes the current statement. A request can contain several statements, so keep its query ID when correlating it with history. Deleted rows are not counted as newly written rows; a zero `written_rows` value does not prove that a DELETE removed nothing.
After completion, inspect the exception fields and confirm the intended data state with a SELECT using the same predicate. A statement inside an explicit transaction is not committed merely because the statement itself finished. HTTP transactions must complete inside one request; an open transaction is rolled back before the response is sent.
Use small, reviewable predicates and transaction controls for maintenance work. Do not wait for an undocumented background table to report completion.
See [`UPDATE`](https://coordinatordb.com/docs/reference/statements/update), [`DELETE`](https://coordinatordb.com/docs/reference/statements/delete), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [active requests](https://coordinatordb.com/docs/reference/system-tables/processes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/which-processes-are-currently-running
Language: en
# See currently active requests
Read `system.processes` through a server connection when you need a snapshot of currently active TCP and HTTP requests. It is available independently of the query logging setting.
```sql
SELECT query_id, user, interface, elapsed,
query_kind, read_rows, memory_usage, peak_threads_usage
FROM system.processes
ORDER BY elapsed DESC
LIMIT 20
FORMAT csv;
```
A request remains present until its response write completes. Its elapsed time therefore does not describe only the SQL calculation. The observing SELECT can see itself, and another request may finish between your observations.
Use `query_id` to correlate a snapshot with a later terminal event in `system.query_log`. `memory_usage` is current accounted SQL memory in the active snapshot, while `peak_memory_usage` is the request's peak. `peak_threads_usage` includes the main query thread; a serial query reports one.
This table is read-only. The `is_cancelled` field does not provide a server-side cancellation command, and cancellation is unavailable through the documented server interface. If the concern is repeated expensive work, identify its caller and apply appropriate request limits to future work.
See [process columns](https://coordinatordb.com/docs/reference/system-tables/processes), [query history](https://coordinatordb.com/docs/reference/system-tables/query-log) and [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/monitoring-debugging/why-default-logging-verbose
Language: en
# Reduce diagnostic log verbosity
Diagnostic verbosity comes from the `logger` section in the configuration the server actually loads. The documented default level is `debug`, while the installation example explicitly uses `information`. Check the file selected by `--config-file` before editing a similarly named file elsewhere.
Choose the detail needed for normal operation:
```xml
information
server.log
server.err.log
10M
3
```
Restart to apply the change. Relative log paths are resolved from the configuration directory, so a different `--db` path does not move the logs. Keep positive rotation sizes and the archive count appropriate for your retention needs. Unknown logger fields or invalid values cause configuration errors rather than silently taking effect.
Reducing file verbosity does not disable structured request history. Its separate `log_queries` and duration settings determine what appears in `system.query_log`. Prefer those structured events when investigating a specific query ID, duration or exception; use diagnostic files for the additional context needed by that investigation.
See [logger and file paths](https://coordinatordb.com/docs/reference/settings/server-settings/settings/other) and [query logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/async-vs-optimize-read-in-order
Language: en
# Choose an explicit result order
Only `ORDER BY` promises a result order. A result that happens to arrive in key order can change after the data, predicate or access plan changes. Add a unique tie breaker when the application paginates or compares repeated results.
```sql
SELECT id, amount
FROM orders
WHERE id >= 1000
ORDER BY id
LIMIT 100;
```
## Separate ordering from concurrency
Coordinator DB does not expose asynchronous read scheduling or a read-in-order switch. Use the documented SQL order and examine `EXPLAIN QUERY PLAN` rather than porting settings from another database. Increasing `max_threads` also does not establish an order or guarantee that a particular statement runs in parallel.
If the final sort is expensive, filter earlier and return only the columns the reader needs. Test a representative key range, then compare duration and peak memory in `system.query_log`. Keep `ORDER BY` in every export that requires reproducible row order; applying a limit without an order selects an unspecified subset.
For repeated pages, a predicate such as `id > last_seen_id` with `ORDER BY id` can make the page boundary explicit. The application must decide how concurrent inserts affect the overall export.
See [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain), [max_threads](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/check-query-processing-time-only
Language: en
# Measure query processing time
A stopwatch around an HTTP or native-client call measures connection setup, authentication, SQL processing and delivery of the result. Use the request's recorded measurements when you need to investigate processing rather than the full client journey.
## Record the request
HTTP responses include `X-Coordinator-Query-Id` and `X-Coordinator-Summary`. Save these alongside the client's elapsed time. The summary includes `elapsed_ms`, result rows, read and write counters, and memory measurements. Native requests also appear in structured query history when logging is enabled.
```sql
SELECT query_id, query_duration_ms, result_rows
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 10
FORMAT csv;
```
Query history is asynchronous; a direct single-table query waits for previously queued events. The observing request's own terminal event appears only after it finishes.
## Avoid misleading comparisons
Use the same SQL, data and output format for repeated measurements. A large CSV response and a single aggregate row have different delivery costs. `EXPLAIN ANALYZE` executes the statement once and reports runtime measurements without returning its ordinary rows; analyzed writes still change data.
See [HTTP response metadata](https://coordinatordb.com/docs/concepts/features/interfaces/http), [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain) and [system.query_log](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/find-expensive-queries
Language: en
# Find expensive completed queries
Start with completed requests so a single slow query does not appear twice as both a start and finish event. Query text and resource counters help distinguish a broad scan from a request that returns a large result.
```sql
SELECT query_id, query_duration_ms, read_rows, read_bytes,
result_rows, query
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY query_duration_ms DESC
LIMIT 20
FORMAT json_each_row;
```
## Investigate a representative example
Read the SQL and selected database before changing it. Check whether the request contains several statements: request duration and returned rows can cover their combined work. Use `EXPLAIN QUERY PLAN` on the expensive SELECT to inspect access choices, then measure one deliberate change at a time.
`normalized_query_hash` can help recognize repeated query shapes, but inspect actual predicates as well. Two requests with the same shape can read very different amounts of data.
If expected events are missing, inspect `log_queries` and `log_queries_min_query_duration_ms`. A nonzero duration threshold records only qualifying terminal events. Use `system.processes` for work still running, and keep query text out of public reports when it contains private values.
See [query history](https://coordinatordb.com/docs/reference/system-tables/query-log), [active requests](https://coordinatordb.com/docs/reference/system-tables/processes) and [logging settings](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/finding-expensive-queries-by-memory-usage
Language: en
# Find queries with high memory usage
Rank terminal events by peak accounted memory to find requests that deserve inspection. This metric describes SQL memory for the request; it is not the process's full resident memory.
```sql
SELECT query_id, peak_memory_usage, query_duration_ms, query
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY peak_memory_usage DESC
LIMIT 20
FORMAT json_each_row;
```
At terminal events, `memory_usage` and `peak_memory_usage` both report the peak accounted value. For a request still running, `system.processes` exposes current and peak values. Measurements remain available when `max_memory_usage` is zero.
## Reduce the work first
Inspect wide projections, large grouped results, joins and unbounded sorts. Select only required columns, filter the input to a representative range, and consider whether the consumer actually needs every returned row. A smaller result can also reduce buffered response memory and response-byte pressure.
Repeat the same query on the same data before comparing a change. If a memory ceiling is necessary, choose it from measured workloads and remember that a saved database value cannot relax a stricter server ceiling. A higher limit alone does not explain why usage grew.
See [memory limits](https://coordinatordb.com/docs/reference/settings/session-settings/max-memory-usage), [system.processes](https://coordinatordb.com/docs/reference/system-tables/processes) and [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/improve-map-performance
Language: en
# Choose between Map fields and typed columns
A `Map` is useful for a variable collection of keys. Frequently filtered business fields often deserve dedicated typed columns so their meaning and validation are explicit. Compare both representations with your actual queries before changing a schema.
## Preserve Map semantics
Map keys can repeat and their order is retained. `map_element` returns the first matching value; a missing key returns the value type's default. Use `map_contains` when zero or an empty string could also be a real stored value.
```sql
SELECT id, map_element(counters, 'views') AS views
FROM pages
WHERE map_contains(counters, 'views')
FORMAT csv;
```
## Move a hot field carefully
Create a replacement table with an explicit column for the commonly queried value. Backfill it with `INSERT ... SELECT`, validate row counts and compare representative values. Decide how missing keys and duplicate keys should map to the new column before migrating; this is a data-contract decision.
Measure the actual query plan, elapsed time and memory after the change. Coordinator DB does not provide a Map-specific optimization switch or promise that one representation is always faster.
See [Map](https://coordinatordb.com/docs/reference/data-types/map), [map functions](https://coordinatordb.com/docs/reference/functions/regular-functions/tuple-map-functions) and [schema changes](https://coordinatordb.com/docs/reference/statements/alter/column).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/insert-select-settings-tuning
Language: en
# Tune INSERT SELECT requests
An `INSERT ... SELECT` reads rows, evaluates expressions and validates destination values in one statement. Diagnose these stages before raising a resource limit. A slow transfer can come from an expensive source query, conversion of wide values, or the amount of data being copied.
## Start with the source
Run `EXPLAIN QUERY PLAN` on the SELECT and measure a representative range. Select the destination columns explicitly so an unrelated schema change cannot shift their positions.
```sql
INSERT INTO archived_orders(id, amount)
SELECT id, amount FROM orders WHERE id >= 1000 AND id < 2000;
```
Use nonoverlapping key ranges for a large backfill and record which ranges completed. An error or interrupted response needs reconciliation before retrying; repeating a successful range can duplicate rows unless the destination key or application design prevents it.
## Compare measurements
Read terminal events in `system.query_log` for duration, read work, written work and peak memory. Compare the same data and settings before drawing conclusions. `max_threads` is a ceiling and does not make every INSERT SELECT parallel. Database `SET` changes apply to later requests and persist for other clients selecting that database.
See [INSERT INTO](https://coordinatordb.com/docs/reference/statements/insert-into), [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/memory-limit-exceeded-for-query
Language: en
# Resolve a query memory limit error
A memory-limit error means a request exceeded its accounted SQL memory budget. Inspect both the effective setting and the workload before increasing that budget. The limit is distinct from total process memory and response-size limits.
```sql
SELECT name, value, "default"
FROM system.settings
WHERE name IN ('max_memory_usage', 'max_response_bytes')
FORMAT csv;
```
## Identify the expensive operation
Find the request's terminal event in `system.query_log` using its query identifier. Review peak memory, returned rows and the SQL text. If the statement sorts or groups a large input, narrow the input and projection. If the consumer requests a large export, split it into explicitly ordered ranges and verify every range.
`max_memory_usage` covers the request across its statements. Dividing one SQL batch into separate requests can change that scope, but it also changes transaction and temporary-table behavior.
## Change a ceiling deliberately
A server XML ceiling can only be tightened by a database setting. `SET max_memory_usage` persists for the selected database, requires autocommit with no active transactions there, and affects later requests. Zero removes only the additional database ceiling.
See [max_memory_usage](https://coordinatordb.com/docs/reference/settings/session-settings/max-memory-usage), [request limits](https://coordinatordb.com/docs/concepts/features/configuration/settings/query-complexity) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/optimize-final-vs-final
Language: en
# Resolve duplicate rows with explicit SQL
Coordinator DB does not offer a `FINAL` query modifier or an `OPTIMIZE FINAL` maintenance operation. Model uniqueness with a declared key, and make the rule for replacing a row explicit in the write operation.
```sql
CREATE TABLE inventory(id INTEGER PRIMARY KEY, quantity Int64);
INSERT INTO inventory VALUES (1, 5);
INSERT INTO inventory VALUES (1, 8)
ON CONFLICT(id) DO UPDATE SET quantity = excluded.quantity;
```
This example keeps one row per identifier and replaces its quantity. It does not choose the latest event by timestamp or deduplicate arbitrary existing rows. Define that business rule separately, including how ties are handled.
## Repair an existing dataset
First query the candidate key to find duplicates and preserve a backup before changing data. Build a replacement table with the intended key and populate it using a SELECT that expresses which rows survive. Validate counts, totals and representative identifiers before changing the application's table reference.
For changes spanning several statements, use a transaction so the intended unit can commit or roll back together. Formatted input does not accept an `ON CONFLICT` clause; load into a staging table when you need a later conflict-aware SQL step.
See [INSERT conflict handling](https://coordinatordb.com/docs/reference/statements/insert-into), [table definitions](https://coordinatordb.com/docs/reference/statements/create/table) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/query-max-execution-time
Language: en
# Set a query execution deadline
`max_execution_time` limits elapsed SQL processing time for one request. Its value is a finite nonnegative number of seconds; fractional seconds are accepted. A zero database value adds no database deadline, while a nonzero server ceiling still applies.
```sql
SET max_execution_time = 2.5;
```
Send the setting as an administration request, then issue the workload in a later request. Settings are sampled at request start, so changing the value inside a batch does not retroactively change that batch's deadline.
## Check the effective value
```sql
SELECT name, value
FROM system.settings
WHERE name = 'max_execution_time'
FORMAT csv;
```
`SET` persists for the selected database and can affect other clients. It requires autocommit and no active transactions in that database. A saved value cannot relax a stricter XML ceiling.
## Interpret a timeout
The deadline is checked cooperatively. A blocking operation can complete before a later check reports the time-limit error. Socket receive timeouts and an HTTP client's timeout govern different stages. A client timeout alone does not prove whether a write completed; reconcile its result before retrying.
See [max_execution_time](https://coordinatordb.com/docs/reference/settings/session-settings/max-execution), [HTTP requests](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/tips-tricks-optimizing-basic-data-types-in-clickhouse
Language: en
# Choose precise basic data types
Select types from the values a column must represent. An identifier, an exact amount and a measurement have different contracts even when all three arrive as text. Declared types validate imported values and make an exchange format easier to interpret.
## Match the value domain
Use an integer type with enough range for identifiers and counts. Keep negative values possible only when the domain allows them. Use `Decimal` when exact decimal scale matters, such as monetary amounts, and floating-point values for approximate measurements. Use `Nullable` when missing information differs from a real zero or an empty string.
For temporal data, choose the required date or timestamp precision and verify input conversion against the type reference. A narrow declaration should express a real restriction; do not assume that choosing the smallest spelling automatically produces a proportional performance improvement.
## Validate a conversion
Create a new table with the intended declarations and copy a representative dataset using explicit casts. Include boundary values, missing values and malformed input in the review. Confirm the export type mapping when another tool will consume Parquet or Arrow.
Measure representative queries before and after the change. Schema changes should preserve meaning before they are judged by speed.
See [data types](https://coordinatordb.com/docs/reference/data-types), [type selection](https://coordinatordb.com/docs/concepts/best-practices/select-data-type) and [Parquet mappings](https://coordinatordb.com/docs/reference/formats/parquet/parquet).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/performance-optimization/why-is-my-primary-key-not-used
Language: en
# Investigate a primary key access plan
A declared primary key does not mean every query uses a key lookup. The predicate, expressions and required rows determine which access plan is useful. Start with the actual statement and a known table definition.
```sql
EXPLAIN QUERY PLAN
SELECT name FROM customers WHERE id = 42;
```
Compare this with a predicate that wraps `id` in a conversion or searches another field. A query returning most of a table may reasonably use a scan. Inspect the reported plan rather than inferring it from a fast or slow response.
## Confirm the schema
`system.columns` exposes `is_in_primary_key` and `primary_key_position`. Filter by database, table and namespace so identically named objects are not confused. Check that the application selected the intended database and bound the intended value type before rewriting the SQL.
Keep comparisons in the column's native value domain when possible. Validate a change with the same data and record duration, read rows and returned rows. Do not add an unnecessary limit merely to make a test faster if the application still needs the full result.
See [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain), [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns) and [primary key guidance](https://coordinatordb.com/docs/concepts/best-practices/choosing-a-primary-key).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/calculate-pi-using-sql
Language: en
# Calculate pi with SQL
Coordinator DB provides `pi()` when a query needs the mathematical constant. Use it directly for calculations such as the area of a circle; there is no reason to regenerate a series in a production calculation.
```sql
SELECT pi() AS pi_value, pi() * 5 * 5 AS circle_area
FORMAT csv;
```
## A series as a learning exercise
A finite Leibniz series demonstrates a generated table, conditional expressions, floating arithmetic and aggregation together:
```sql
SELECT 4.0 * sum(
CASE WHEN generate_series % 2 = 0 THEN 1.0 ELSE -1.0 END
/ (2 * generate_series + 1)
) AS approximation
FROM generate_series(0, 9999)
FORMAT csv;
```
The endpoints are inclusive, so this query evaluates 10,000 terms. The decimal literals make the intended approximate arithmetic explicit. The series converges slowly; more terms add work without turning the result into an exact decimal representation of pi. Compare the approximation with `pi()` rather than expecting identical final digits. Use a small range while learning or inspecting its execution plan.
See [mathematical functions](https://coordinatordb.com/docs/reference/functions/regular-functions/math-functions) and [`generate_series`](https://coordinatordb.com/docs/reference/functions/table-functions/generate-series).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets
Language: en
# Compare two query result sets
Compare matching columns in both directions when checking whether two SQL queries return the same set of rows. `EXCEPT` returns distinct rows from its left input that are absent on its right input.
```sql
CREATE TABLE expected_result(id INTEGER, value TEXT);
CREATE TABLE actual_result(id INTEGER, value TEXT);
INSERT INTO expected_result VALUES (1, 'a'), (2, 'b');
INSERT INTO actual_result VALUES (1, 'a'), (3, 'c');
SELECT id, value FROM expected_result
EXCEPT
SELECT id, value FROM actual_result;
SELECT id, value FROM actual_result
EXCEPT
SELECT id, value FROM expected_result;
```
An empty result in both directions proves equality as sets, including whole-row values. It does not prove equal duplicate counts: `EXCEPT` removes repeated copies. If duplicates are meaningful, group each input by the compared columns, include `count(*)`, and compare those grouped results in both directions.
Keep inputs fixed while comparing them. Different filters, column order, conversions or concurrent edits can explain a difference without a query bug. A final `ORDER BY` makes diagnostic output easier to read but is unnecessary for set membership.
See [`EXCEPT`](https://coordinatordb.com/docs/reference/statements/select/except) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/comparing-metrics-between-queries
Language: en
# Compare query measurements
A useful comparison changes one part of a query while keeping its input data, parameters and expected result constant. Check result equivalence before interpreting a shorter duration as an improvement. A query that returns fewer rows may simply be doing different work.
Use terminal events to compare completed requests:
```sql
SELECT query_id, query_duration_ms, read_rows, read_bytes,
result_rows, peak_memory_usage
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 10
FORMAT csv;
```
Record the query IDs for the two executions. Terminal `memory_usage` and `peak_memory_usage` both describe peak accounted SQL memory. `read_rows` can include rows rejected by a filter, while `result_rows` counts returned rows across the request statements. They measure different things.
Run several comparable observations when durations fluctuate, and inspect `EXPLAIN QUERY PLAN` alongside them. `EXPLAIN ANALYZE` executes the statement once and replaces its usual result with measurements; analyzed writes still change data. Do not use it on a write unless that effect is intended or enclosed in a transaction you roll back.
See [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/filtered-aggregates
Language: en
# Calculate filtered aggregates
Use `FILTER (WHERE ...)` to select the rows admitted to one aggregate without removing rows needed by the other aggregates. A top-level `WHERE` instead filters the input for the entire grouped query.
```sql
CREATE TABLE support_payments(status TEXT, amount INTEGER);
INSERT INTO support_payments VALUES
('paid', 40), ('paid', 60), ('pending', 25);
SELECT count(*) AS all_payments,
count(*) FILTER (WHERE status = 'paid') AS paid_payments,
sum(amount) FILTER (WHERE status = 'paid') AS paid_amount
FROM support_payments
FORMAT csv;
```
The example returns three payments, two paid payments and a paid amount of 100. Add `GROUP BY` when the same measures are needed per account or day. A group can contain rows while a particular aggregate receives none, so check the aggregate's empty-input contract before choosing a fallback with `coalesce`.
Coordinator DB also provides conditional functions such as `count_if`, `sum_if` and `avg_if`. Choose one consistent style for related measures and give each result a meaningful name. Always state how NULL values should affect the condition and the aggregated expression.
See [aggregate functions](https://coordinatordb.com/docs/reference/functions/aggregate-functions) and [`WHERE`](https://coordinatordb.com/docs/reference/statements/select/where).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/how-to-filter-a-clickhouse-table-by-an-array-column
Language: en
# Filter rows by an array member
Use `has(array, value)` when a row should match because its array contains a particular immediate member. This preserves one result row per matching table row; it does not expand the array into additional rows.
```sql
CREATE TABLE tagged_items(id INTEGER PRIMARY KEY, tags Array(String));
INSERT INTO tagged_items VALUES
(1, array('sql', 'guide')),
(2, array('release')),
(3, array('sql'));
SELECT id
FROM tagged_items
WHERE has(tags, 'sql')
ORDER BY id
FORMAT csv;
```
The matching IDs are 1 and 3. Array members obey the declared member type. A nested array is an immediate member of its outer array, so do not assume a membership test searches every nested level.
Use `array_position(tags, 'sql')` when the first matching position is also useful. Positions are one-based, and a missing value returns NULL. `array_positions` returns every matching position when an array contains duplicates. An empty collection and an SQL NULL array are different inputs; decide whether missing arrays should be excluded or handled explicitly in the predicate.
See [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions) and [Array](https://coordinatordb.com/docs/reference/data-types/array).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/how-to-insert-all-rows-from-another-table
Language: en
# Insert rows from another table
`INSERT INTO ... SELECT` copies a query result into an existing table. Name the destination columns so the mapping remains visible and does not accidentally depend on a later schema change.
```sql
CREATE TABLE current_items(id INTEGER PRIMARY KEY, name TEXT);
CREATE TABLE copied_items(id INTEGER PRIMARY KEY, name TEXT);
INSERT INTO current_items VALUES (1, 'Notebook'), (2, 'Pen');
INSERT INTO copied_items(id, name)
SELECT id, name FROM current_items;
SELECT id, name FROM copied_items ORDER BY id FORMAT csv;
```
The destination's declared types, primary keys, uniqueness and other constraints still apply. Running the same copy twice is not automatically safe: it can encounter existing keys or append duplicate rows, depending on the table definition. Decide whether a repeated operation should fail, skip conflicts or replace values before choosing a conflict policy.
For a new independent table, `CREATE TABLE ... AS SELECT` copies projected values and retains projected native declarations, but it does not copy source constraints. Define the destination explicitly when those constraints matter. Group the copy with related changes in a transaction when they must commit together.
See [`INSERT INTO`](https://coordinatordb.com/docs/reference/statements/insert-into) and [`CREATE TABLE`](https://coordinatordb.com/docs/reference/statements/create/table).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/pivot
Language: en
# Pivot a known set of categories
For a known set of categories, calculate one conditional aggregate per output column. This makes both the category list and the handling of missing categories explicit.
```sql
CREATE TABLE monthly_sales(account_id INTEGER, category TEXT, amount INTEGER);
INSERT INTO monthly_sales VALUES
(1, 'books', 30), (1, 'tools', 20), (2, 'books', 15);
SELECT account_id,
sum(CASE WHEN category = 'books' THEN amount ELSE 0 END) AS books,
sum(CASE WHEN category = 'tools' THEN amount ELSE 0 END) AS tools
FROM monthly_sales
GROUP BY account_id
ORDER BY account_id
FORMAT csv;
```
The `ELSE 0` supplies zero for a category absent from an existing account group. It does not create accounts absent from the source altogether. Join against a separate account table when such accounts must also appear.
Changing the output column set requires changing the SQL. For a large or changing category list, return rows grouped by account and category, then arrange them for display in the consuming application. Avoid silently turning unknown categories into an existing column. Check category spellings and NULL values before comparing pivot totals with an ungrouped total.
See [`GROUP BY`](https://coordinatordb.com/docs/reference/statements/select/group-by) and [filtered aggregates](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/filtered-aggregates).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/useful-queries-for-troubleshooting
Language: en
# Useful diagnostic SQL queries
Start with read-only observations that identify which database and requests are involved. Through the server, use the `system` qualifier for diagnostic tables; an unqualified application table with the same name is a different object.
```sql
SELECT query_id, user, elapsed, query_kind
FROM system.processes
ORDER BY elapsed DESC
LIMIT 10;
```
This snapshot shows requests still active, including response delivery. A request can finish between observations. Query history answers the separate question of what completed or failed:
```sql
SELECT event_time_text, query_id, exception_code, exception
FROM system.query_log
WHERE type IN ('ExceptionBeforeStart', 'ExceptionWhileProcessing')
ORDER BY event_time DESC
LIMIT 10;
```
Check effective database limits before assuming a request used built-in defaults:
```sql
SELECT name, value, changed
FROM system.settings
WHERE changed
ORDER BY name;
```
Save the query ID, exact error and relevant setting values with the report. Redact credentials and private SQL values before sharing output. Query logging may omit short requests when a duration threshold is configured, so absence from history alone does not prove that a request never arrived.
See [system tables](https://coordinatordb.com/docs/reference/system-tables/overview) and [query logging](https://coordinatordb.com/docs/reference/settings/session-settings/log-queries).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/using-array-join-to-extract-and-query-attributes
Language: en
# Expand JSON attributes into rows
`json_each` turns the immediate children of a JSON object or array into queryable rows. It is useful when each attribute should become an observation, rather than remaining inside one result value.
```sql
SELECT key, value, type
FROM json_each('{"region":"west","retries":2,"enabled":true}')
ORDER BY key
FORMAT csv;
```
For an object, `key` identifies a field. For an array, it identifies an element position. The `type` column helps distinguish text, numeric, boolean and nested values before interpreting them. A nested object is still one immediate child; use `json_tree` when the task requires descendants too.
Expanding children changes cardinality: one document can produce many rows. Count the expanded attributes separately from the number of original documents. Restrict the keys or types in `WHERE` before aggregating values that should be comparable. Do not sum an attribute merely because its textual representation looks numeric.
For a fixed schema, use `jsonb_to_record` or `jsonb_to_recordset` with declared output types instead of treating every field as a generic attribute. For native arrays, membership queries often need only `has`, without any expansion.
See [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) and [array functions](https://coordinatordb.com/docs/reference/functions/regular-functions/array-functions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/check-users-roles
Language: en
# Check configured users and active identities
Coordinator DB users are declared in the file selected by `users_config`. Inspect that configuration to determine which named credentials exist. The server does not create an implicit account when the file is missing, and usernames are case-sensitive.
An authenticated connection can inspect the identity recorded for active requests:
```sql
SELECT query_id, user, interface
FROM system.processes
ORDER BY user;
```
This is an observation of active requests, not a complete configured-user list. Query history records authenticated identities for earlier requests when logging admitted their events.
Each configured user has exactly one password form and can optionally have an HTTP API-key digest. Password and key changes require a server restart. Invalid explicit HTTP credentials do not fall back to the empty-password default user.
Roles, permission grants and settings profiles are unavailable. Listing several configured usernames therefore does not prove that those users have different SQL privileges. If an application requires separate access boundaries, enforce them through the application and the deployment that controls which database service can be reached.
See [authentication](https://coordinatordb.com/docs/concepts/features/security), [`users_config`](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users) and [active identities](https://coordinatordb.com/docs/reference/system-tables/processes).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/common-rbac-queries
Language: en
# Plan access without database roles
Coordinator DB authenticates named users, but roles, grants and per-table permission policies are unavailable. Commands such as `GRANT`, `CREATE ROLE` and `SET ROLE` are not a substitute for an application access design.
Start by identifying who may submit SQL directly and which operations their reader task actually requires. Use explicitly configured credentials for the service, restrict network reachability, and have the application enforce permitted operations when end users should receive a narrower interface.
For example, an application can expose a fixed report query and validate its inputs before sending SQL. A view can make that query easier to maintain:
```sql
CREATE VIEW public_product_names AS
SELECT id, name FROM products;
```
The view does not create a security boundary for a user who can query the base table directly. Do not treat omitted columns as protected merely because a report hides them.
Review HTTP and native credentials independently of any application login. Native requests authenticate before SQL is accepted; HTTP supports configured Basic credentials or Bearer keys. Credentials travel without built-in TLS, so use trusted connectivity or an external secure transport.
See [authentication and network access](https://coordinatordb.com/docs/concepts/features/security), [HTTP authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [views](https://coordinatordb.com/docs/reference/statements/create/view).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/remove-default-user
Language: en
# Remove empty-password default access
The local installation sample declares a `default` user with an empty password. It is an explicit configuration entry, not an account the server generates. To stop using it, configure the named credentials your clients will use, update those clients, and remove the old entry from `users.xml`.
```xml
replace-with-your-password
```
Use this only as a structural example; choose the actual secret outside shared documentation. A user may instead have a 64-character `password_sha256_hex` digest. Do not declare both password forms for the same user.
Restart the server to apply user changes, then test a connection with the intended username and credentials. Native client usernames default to `default`, so callers must select the replacement explicitly. HTTP requests without Authorization attempt the configured default user with an empty password; removing that account prevents this fallback from granting access.
Also test an unauthenticated SQL request. A successful unauthenticated `/ping` is expected and does not demonstrate SQL access. Preserve a working administrator-controlled configuration while making the change.
See [`users_config`](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users), [native client options](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [HTTP authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/row-column-policy
Language: en
# Design row and column access boundaries
A SQL predicate can select rows for a report, and a view can omit columns. Neither becomes an enforced access policy for a client allowed to submit arbitrary SQL. Coordinator DB does not provide row-level policies, column grants or role-based permissions.
```sql
CREATE VIEW visible_orders AS
SELECT id, account_id, amount
FROM orders
WHERE account_id = 42;
```
This view is a reusable query definition. It does not prevent a directly connected user from asking for another account's rows in the base table. Use it for readability only when that distinction is acceptable.
For restricted readers, let the application authenticate the end user, select the permitted account context and execute only reviewed queries. Avoid accepting arbitrary table names, column lists or WHERE fragments from the caller. With embedded prepared statements, bind data values rather than concatenating input into SQL.
When SQL clients themselves must be isolated, design deployment and data separation around that requirement before making the service reachable. Separately review who can read diagnostic history, because logged SQL may contain application values. Do not claim isolation based solely on distinct usernames.
See [security capabilities](https://coordinatordb.com/docs/concepts/features/security), [views](https://coordinatordb.com/docs/reference/statements/create/view) and [prepared statements](https://coordinatordb.com/docs/guides/clickhouse/data-modelling/stored-procedures-and-prepared-statements).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/set-role-not-persisting-in-sql-console
Language: en
# Understand browser request identity and state
Coordinator DB HTTP SQL requests each have a separate logical session. A later browser request does not inherit an earlier request's transaction or temporary tables. Roles and `SET ROLE` are unavailable, so there is no role selection to persist between browser tabs or requests.
Determine the identity from authentication, not from a previous SQL command. An HTTP request uses its configured Basic credentials or Bearer key. If Authorization is absent, the server attempts an explicitly configured empty-password default account. Invalid explicit credentials never fall back to it.
To check recorded identities for recent requests:
```sql
SELECT query_id, user, interface, query_kind
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 10;
```
Use the response query ID to identify the exact browser request; a recent row could belong to another caller. For transaction work, place `BEGIN`, every related statement and `COMMIT` in the same HTTP request. An unclosed transaction rolls back before its response is sent.
Choose a stateful native connection when a task requires a transaction spanning several interactive submissions.
See [HTTP request state](https://coordinatordb.com/docs/concepts/features/interfaces/http), [native sessions](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/security/windows-active-directory-to-ch-roles
Language: en
# Connect application identity to database access
External directory login and Coordinator DB authentication are separate tasks. The documented server accepts explicitly configured usernames and passwords, with optional HTTP Bearer API keys. It does not document directory authentication, group-to-role mapping or database roles.
When an application authenticates people through an external identity system, have it decide which reader tasks each person may perform. The application then connects to Coordinator DB with credentials configured for that service and executes the permitted SQL. Do not send an external access token to the database and assume it is a configured API key.
For operational visibility, the query log records the authenticated database username and interface. That username represents the database credential used by the application; it is not automatically the original person's directory identity. Keep any additional audit correlation in the application's own access records without placing sensitive tokens in SQL.
Review network reachability and secure transport separately. Coordinator DB has no built-in TLS listener. Explicit credentials, external login and encrypted connectivity answer different questions and must each be configured where needed.
See [authentication](https://coordinatordb.com/docs/concepts/features/security), [user declarations](https://coordinatordb.com/docs/reference/settings/server-settings/settings/users), [HTTP credentials](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/difference-between-official-builds-and-3rd-party
Language: en
# Verify the executable you are running
Start from the documented Coordinator DB installation procedure when establishing a reproducible environment. Record where the executable came from, which checkout or artifact you selected and which configuration files accompany it. Do not assume an independently packaged executable has the same defaults as the supplied example.
After startup, test a small public operation through the interface the application will use:
```sh
./coordinator client --database data --query "SELECT 1 AS connected FORMAT csv"
```
A successful result verifies that particular connection and query. It does not establish compatibility for every data type, file format or application workload. Run a representative import and query before replacing an existing executable.
Keep `config.xml` and `users.xml` explicit. The server requires them and does not create missing credentials. A different configuration directory can change listener addresses, user paths and log destinations independently of the database path.
For a packaging issue, report the executable source, exact startup command, selected configuration and full error. Remove credentials from the report. The public installation guide is the reference workflow; unsupported distribution channels should not be treated as a separately promised product or service.
See [installation](https://coordinatordb.com/docs/get-started/setup/install), [configuration paths](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) and [connection options](https://coordinatordb.com/docs/concepts/features/interfaces/client).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/enabling-ssl-with-lets-encrypt
Language: en
# Use HTTPS in front of the HTTP interface
Coordinator DB has no built-in TLS listener. A certificate cannot be enabled by adding undocumented SSL fields to `config.xml`. Use trusted connectivity or an external secure transport when credentials and SQL need protection in transit.
For an HTTPS browser endpoint, an externally managed TLS terminator can accept the browser connection and forward requests to the configured HTTP listener. Certificate issuance and renewal belong to that external service. Bind the database listener to the intended private address and prevent callers from bypassing the secure entry point.
Preserve the documented request semantics. Browser requests must satisfy matching Origin and Host rules; the server emits no CORS headers. Basic credentials and Bearer keys belong in Authorization, never URL parameters. Check ordinary SQL requests, attached uploads and returned error statuses through the actual endpoint before relying on it.
A `/ping` response proves only health-check reachability and does not test authentication. Verify an authenticated SELECT separately and ensure failures remain visible to the caller. Use the response query ID when diagnosing a forwarded request.
See [HTTP behavior](https://coordinatordb.com/docs/concepts/features/interfaces/http), [network access](https://coordinatordb.com/docs/concepts/features/security) and [listener configuration](https://coordinatordb.com/docs/concepts/features/security/network-ports).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/how-to-increase-thread-pool-size
Language: en
# Choose and verify a query thread limit
Use the documented `max_threads` setting when tuning the ceiling for an eligible query. It is not a command to resize an arbitrary server-wide thread pool, and it does not make every statement run in parallel.
```sql
SELECT name, value, "default"
FROM system.settings
WHERE name = 'max_threads';
```
Zero selects the available hardware count capped at eight total query threads. An explicit value is from 0 through 64 and is also bounded by hardware, the XML ceiling and available workers. One requests serial execution.
```sql
SET max_threads = 4;
```
The server persists this selected-database value for later requests. `SET` requires autocommit and no active transactions in that database. Use a representative read workload to compare performance before retaining the change.
Observe `peak_threads_usage` in `system.processes` while the request is present. It includes the main query thread, so serial execution reports one. A lower observed count than the ceiling is not necessarily a fault. Check query shape, measured duration and memory along with the count; adding allowed threads is not an automatic improvement.
See [`max_threads`](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads), [active requests](https://coordinatordb.com/docs/reference/system-tables/processes) and [server ceilings](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/install-clickhouse-windows10
Language: en
# Plan a Windows client connection
Begin with the documented Coordinator DB installation path rather than assuming a Windows installer or service package exists. The installation guide describes installing the latest release and starting it with existing XML configuration files. It does not promise a separate Windows desktop distribution.
For a Windows application that needs to query an already running server, HTTP provides a language-neutral request interface. Configure an authenticated request to `POST /`, select the managed database and send SQL in the request body. Choose a registered output format the application can decode. Validate with a small SELECT before sending real input.
Keep the server address, native TCP port and HTTP port distinct. The sample uses native port 7400 and HTTP port 7401, bound for local access. A client on another machine needs the intended network reachability and secure transport; changing its operating system does not change those requirements.
Server-side `file()` access currently requires Unix and reads beneath a configured root. For data on the client machine, use a documented upload or native-client input workflow instead of assuming the server can read a Windows path.
See [installation](https://coordinatordb.com/docs/get-started/setup/install), [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [file sources](https://coordinatordb.com/docs/reference/functions/table-functions/file).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/llvm-clang-up-to-date
Language: en
# Check installation prerequisites
Use the Coordinator DB installation guide as the source of installation prerequisites. The documented installer uses `curl` and `sh`; building from a source checkout is not required.
Follow the [installation procedure](https://coordinatordb.com/docs/get-started/setup/install) for its current prerequisites and commands. If a step fails, retain the first meaningful error, the exact command and the source you attempted to install. Later errors can be consequences of that first failure. Check that the documented prerequisites are present and that you ran the command from the expected directory before changing the environment.
After installation, follow the server startup instructions with the executable, `config.xml` and `users.xml` in the same directory. A successful installation is separate from a successful startup: missing configuration, invalid XML and unavailable listener addresses are runtime setup problems.
Report only the relevant command output and environment details, with private paths or credentials removed where necessary. Do not invent minimum tool versions or undocumented installer options when the public guide does not specify them.
See [installation](https://coordinatordb.com/docs/get-started/setup/install), [configuration validation](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files) and [server startup](https://coordinatordb.com/docs/get-started/setup/self-managed/overview).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/production
Language: en
# Prepare a persistent Coordinator DB service
Start with a persistent database file, explicit configuration and a tested client connection. Treat the supplied empty-password account as a local example; configure the credentials and network reachability required for the actual service.
The public server workflow supports several applications connecting to one server process. Separate processes must not open the same database file simultaneously. Use independent copies for separate instances rather than interpreting file sharing as replication.
Review request ceilings, connection admission and response sizes against representative work. Inspect effective values through `system.settings`, and keep server-only admission controls in XML. Changing XML requires a restart; persisted database settings have their own change rules.
Before accepting application writes, create a database copy with `VACUUM INTO` and test reopening the copy independently. The destination must be absent or empty, and the source must meet the documented copy restrictions. A backup procedure is useful only if its recovery steps are known and tested.
Finally, run authenticated reads and writes through the actual client path, verify expected error handling and confirm diagnostic rotation. Keep secrets out of shared logs and support reports.
See [deployment modes](https://coordinatordb.com/docs/get-started/about/deployment-modes), [security](https://coordinatordb.com/docs/concepts/features/security), [request limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max) and [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/setup-installation/set-up-clickhouse-documentation-mcp-server
Language: en
# Use documentation safely with a SQL assistant
Use the public Coordinator DB documentation as the reference when an assistant helps write SQL or explain an error. Start with the relevant statement, type or interface page and include the exact task. A named feature in another product is not evidence that Coordinator DB accepts its syntax.
Coordinator DB does not document a bundled documentation MCP server. An assistant can still work from the published pages you provide. Ask it to cite the relevant public contract and to distinguish proposed SQL from a command that was actually executed.
For a query task, provide a minimal schema, representative synthetic rows, expected output and the complete error message. Remove credentials, private row values and unrelated server output. Begin with a read-only SELECT or `EXPLAIN QUERY PLAN` when investigating access choices.
Review data-changing statements before execution. `EXPLAIN ANALYZE` is not a read-only substitute for a write: it executes the statement once. Transaction controls can help test changes, but their connection scope must be correct, especially over HTTP.
See [SQL statements](https://coordinatordb.com/docs/reference/statements), [types](https://coordinatordb.com/docs/reference/data-types), [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/add-column
Language: en
# Add a column to an existing table
Use `ALTER TABLE ... ADD COLUMN` with a definition that works for existing rows as well as future inserts. A required field commonly needs a suitable default so the current dataset remains valid.
```sql
ALTER TABLE profiles ADD COLUMN status String NOT NULL DEFAULT 'new';
```
## Review the application contract
Decide what the default means for old rows. A convenient placeholder can become misleading business data if it is never backfilled. If the field is unknown for old records, a nullable declaration may express the intended meaning more accurately.
Update explicit import and export column lists deliberately. Existing inserts that name their columns can continue omitting the new field according to its default behavior. Code that assumes every table column or a fixed positional layout needs review.
## Verify the result
Inspect `system.columns` for the new type, position and default expression, then query a few existing rows and insert a representative new row. Include null and boundary cases when the column has constraints.
Adding a column does not change another column's type. For a type conversion, create a replacement table and use `INSERT ... SELECT CAST(...)`, then validate before changing the application reference. Check dependencies before any later drop or rename.
See [ALTER TABLE columns](https://coordinatordb.com/docs/reference/statements/alter/column), [CREATE TABLE](https://coordinatordb.com/docs/reference/statements/create/table) and [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/delete-old-data
Language: en
# Delete rows older than a chosen boundary
Coordinator DB removes rows with ordinary `DELETE ... WHERE`. It does not require a background mutation command for this operation. Define the retention boundary in the same value domain as the stored column and preview the matching rows before deleting them.
For an application that stores a numeric sequence boundary, the shape is:
```sql
SELECT count(*) FROM events WHERE sequence_id < 1000;
```
Use the exact same predicate for the reviewed change:
```sql
BEGIN;
DELETE FROM events WHERE sequence_id < 1000;
COMMIT;
```
## Make the retention rule explicit
For dates and timestamps, agree on timezone, precision and whether the boundary is inclusive. A calendar label such as “last month” is not enough to define an unambiguous predicate. Preserve a verified copy if recovery of deleted data may be required.
A native connection retains transaction state. With HTTP, BEGIN, DELETE and COMMIT must be in one request; an unclosed transaction rolls back before the response. A client losing the response must inspect the destination before repeating the action.
Deleting all rows retains the table definition. Use DROP only when removing the object itself is the intended operation, and review foreign-key effects when enforcement is enabled.
See [DELETE](https://coordinatordb.com/docs/reference/statements/delete), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/exchangestatementtoswitchtables
Language: en
# Switch a table name with explicit renames
Coordinator DB does not provide an `EXCHANGE TABLES` statement. A replacement workflow uses ordinary tables and documented `ALTER TABLE ... RENAME TO` operations. Plan the transaction and dependency checks before changing the name used by clients.
## Prepare the replacement
Create a new table with explicit types and constraints. Populate it, then compare row counts and representative values with the intended source boundary. `CREATE TABLE AS SELECT` does not copy source constraints, so it is not a substitute for reviewing the destination definition.
After coordinating application writes, a name switch can use a transaction:
```sql
BEGIN;
ALTER TABLE current_events RENAME TO previous_events;
ALTER TABLE replacement_events RENAME TO current_events;
COMMIT;
```
The example requires the three names to be available in the expected state. Check views, triggers, indexes and other dependencies; a rename can be rejected or affect dependent definitions. Test the whole procedure on independent data first.
## Validate before cleanup
Query the new `current_events` with application statements and confirm its constraints. Keep the previous table until the rollback decision is clear. Do not immediately drop it solely because the rename succeeded. Later application writes make a rollback a data-reconciliation decision.
See [rename syntax](https://coordinatordb.com/docs/reference/statements/rename), [CREATE TABLE](https://coordinatordb.com/docs/reference/statements/create/table) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/how-to-create-table-to-query-multiple-remote-clusters
Language: en
# Combine data from independent SQL services
Coordinator DB does not provide a distributed table engine or a remote SQL table function. A query cannot transparently join several remote services. Use an external client to retrieve a defined result from each source, then load compatible local tables for analysis.
## Define a consistent boundary
Choose the source columns, types and time or key range. Record when each source was read: independent services do not automatically share one transaction snapshot. If a report needs a common cutoff, enforce that cutoff in the extraction process.
Export each source through a supported interface, create explicit destination schemas and import the artifacts. Include a source identifier when different services can use the same local key. Validate row counts and representative values before joining.
## Query the gathered data
Use ordinary SQL joins and aggregates against the imported tables. Check that key types and null behavior agree rather than converting every field to text. For repeated reports, record completed extraction batches so a retry does not add the same source rows twice.
The local result reflects the extraction boundary, not a continuously synchronized remote view. Refresh it through the same verified client workflow when newer data is required.
See [joins guidance](https://coordinatordb.com/docs/concepts/best-practices/minimize-optimize-joins), [formats](https://coordinatordb.com/docs/reference/formats) and [INSERT SELECT](https://coordinatordb.com/docs/reference/statements/insert-into).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/recreate-table-across-terminals
Language: en
# Use a shared persistent table across client sessions
Two terminals can observe the same persistent table when they connect to the same Coordinator DB server and select the same managed database. A temporary table belongs to its connection and is not a way to share data between independent clients.
## Check the session context
Start each client with an explicit database:
```sh
./coordinator client --database data
```
Create a normal table in one connection and commit its changes before expecting another connection to read them. Inspect `system.tables` with database and namespace fields if an object appears missing. An identically named temporary table can also make the observing session confusing.
## Avoid repeating creation blindly
An “already exists” error may mean the desired persistent object is already present. Read its definition before dropping or recreating it. `CREATE TABLE IF NOT EXISTS` avoids a duplicate creation error but does not verify that the existing schema matches the application's expectation.
HTTP requests have independent sessions, so temporary objects created in one request do not survive into the next. Put related temporary-table work in one request or use a deliberate persistent staging table.
Do not start separate server processes against one shared database file to connect more terminals; multiple clients should use the same server.
See [temporary tables](https://coordinatordb.com/docs/reference/statements/create/table/temporary-table), [native session state](https://coordinatordb.com/docs/concepts/features/interfaces/client) and [system.tables](https://coordinatordb.com/docs/reference/system-tables/tables).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/runbook-json
Language: en
# Validate a JSON schema change with a small runbook
A JSON schema change should be tested against documents that exercise its actual contract. Coordinator DB can retain flexible JSON while validating declared typed paths. Missing declared paths and explicit JSON null receive the type default unless the path is Nullable.
## Build representative cases
Include a valid document, a missing key, explicit null, a wrong type and a scalar where an object is expected. Add nested arrays or duplicate object keys when the source can contain them. Keep the examples synthetic so they can be shared safely.
```sql
CREATE TABLE json_contract(doc JSON(id UInt64, nickname Nullable(String)));
INSERT INTO json_contract VALUES ('{"id":1,"nickname":"Ada"}'), ('{}');
SELECT doc.id, doc.nickname FROM json_contract FORMAT csv;
```
## Check both SQL and file input
Run the same cases through the importer and selected format, not only literal SQL. Field names and statement settings can introduce a separate conversion rule. Verify extracted paths and exported values with the consuming application.
For a change to an existing column's declaration, create a replacement table and convert explicitly; changing a JSON document's shape is not automatic schema migration. Record how old documents map to the new contract and validate counts before changing application writes.
See [JSON type](https://coordinatordb.com/docs/reference/data-types/json), [JSON functions](https://coordinatordb.com/docs/reference/functions/regular-functions/json-functions) and [JSON loading](https://coordinatordb.com/docs/guides/clickhouse/data-formats/json/loading).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/schema-migration-tools
Language: en
# Choose a schema migration workflow
Coordinator DB does not document a product-specific schema migration tool. Choose a client workflow that executes the supported SQL, records which migration completed and can verify the resulting schema. A tool's generic SQL support is not proof that its generated dialect is compatible.
## Test the generated statements
Review each migration against the statement reference. Add, drop and rename columns use `ALTER TABLE`; a type change requires a replacement table and explicit conversion. Primary keys, defaults and foreign-key behavior deserve deliberate validation. `CREATE TABLE AS SELECT` copies projected declarations and rows but not the source constraints.
Use an isolated database to run the migration forward from the real starting schema. Confirm metadata and representative application queries afterward. A migration marked “applied” is weak evidence if the schema check was skipped.
## Keep the execution boundary clear
A native connection can retain transaction state. An HTTP transaction must begin and commit in one request. Separate HTTP calls cannot continue the same open transaction. Store a migration identifier only after its intended SQL unit succeeds, and reconcile ambiguous responses before rerunning.
For destructive or replacement changes, preserve an independent copy and test the rollback decision with the same data boundary. Do not assume every change can be undone after new application writes.
See [SQL statements](https://coordinatordb.com/docs/reference/statements), [ALTER columns](https://coordinatordb.com/docs/reference/statements/alter/column) and [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/tables-schema/search-across-node-for-tables-with-a-wildcard
Language: en
# Find tables with a name pattern
Use `system.tables` to search the Coordinator DB server's registered database inventory. Filter the object name with SQL LIKE and include database and namespace in the output so identical names are distinguishable.
```sql
SELECT database, schema_name, table_name, table_type
FROM system.tables
WHERE table_name LIKE 'events_%'
ORDER BY database, schema_name, table_name
FORMAT csv;
```
## Choose the pattern carefully
In LIKE, `%` matches a sequence and `_` matches one character. The example therefore searches a pattern, not a literal underscore prefix. Use the documented SQL expression rules when literal wildcard characters matter, and verify the result on known table names.
`system.tables` includes tables and views and can include the observing connection's temporary namespace. Add `schema_name = 'main'` or a table-type filter when the task concerns only persistent base tables.
## Search independent services explicitly
The metadata relation is not a cluster-wide discovery mechanism. To search several independent servers, run the same query against each through an external client and label every returned row with its source endpoint. No `remote()` function or automatic node enumeration is provided.
Do not drop or migrate every match without inspecting its definition and intended ownership. A name pattern is a discovery aid, not an authorization boundary.
See [system.tables](https://coordinatordb.com/docs/reference/system-tables/tables), [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns) and [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/certificate-verify-failed-error
Language: en
# Resolve certificate verification failures at the TLS boundary
Coordinator DB's documented server listeners do not provide TLS. An HTTPS certificate-verification failure therefore belongs to the external proxy, gateway or tunnel used by the client. Identify that endpoint before changing database credentials or SQL settings.
## Check the client-facing name
Confirm that the URL hostname matches the certificate's covered names, the certificate is within its validity dates and the client trusts the issuing chain. Check the client's system time and whether an organizational proxy substitutes its own certificate. A test using an IP address can fail even when the certificate is correct for the DNS name.
Ask the owner of the external TLS endpoint to install a complete valid chain or provide the organization's trusted CA through the client's supported trust configuration. Do not make disabled certificate validation the permanent connection policy.
## Retest SQL separately
After TLS succeeds, check `/ping` and an authenticated SELECT. A later 401 is a database authentication problem rather than a certificate problem. Verify that the proxy forwards the intended route and host information, especially for browser requests with Origin/Host checks.
Record the redacted hostname and certificate error; do not include private keys or database passwords in a report.
See [HTTP transport and authentication](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [listener configuration](https://coordinatordb.com/docs/reference/settings/server-settings/settings/listen).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/configure-cap-ipc-lock-and-cap-sys-nice-in-docker
Language: en
# Review container permissions before adding capabilities
Do not add container capabilities solely because another database's setup guide lists them. Coordinator DB's public startup contract does not require `CAP_IPC_LOCK` or `CAP_SYS_NICE`. First identify the failing action and its actual error.
## Check ordinary access requirements
Verify that the process can read its existing configuration and credentials files, write the configured log paths and access the database file location. Relative user and log paths are based on the configuration directory, which can differ from the container's working directory. Confirm listener addresses and published ports separately from filesystem access.
If a server starts but a remote client fails, test the listener and route rather than granting additional process privileges. If a file cannot be read, inspect the mounted path and ownership instead of assuming a memory-lock permission problem.
## Keep host policy explicit
Container runtime restrictions and host security policy belong to the deployment configuration. Have the host administrator evaluate a capability only when a concrete denied operation requires it. Record the exact denial and the smallest change that resolves it, then repeat startup and a simple SQL request.
A working highly privileged container does not identify which permission was necessary.
See [configuration paths](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files), [command-line startup](https://coordinatordb.com/docs/concepts/features/interfaces/cli) and [HTTP checks](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/connection-timeout-remote-remotesecure
Language: en
# Diagnose remote SQL connection timeouts
Coordinator DB does not provide `remote()` or `remoteSecure()` SQL table functions. A remote query uses a client connection to the documented native or HTTP interface. Diagnose the connection from the host that actually sends the request.
## Identify when it times out
A timeout before connection establishment points to address resolution, routing, firewall rules or the listener. A receive timeout after sending request bytes can involve transport limits or a slow client. A SQL execution-limit error is reported by the database and has a different scope.
For native access, pass the complete host and port to `coordinator client --addr`. For HTTP, test `/ping` and a small authenticated SELECT before running the workload. External TLS protection, if present, adds a separate handshake stage.
## Compare the relevant limits
Server `request_read_timeout` controls socket receive behavior. `max_execution_time` bounds SQL processing. The application's own timeout controls how long it waits; it does not cancel the server-side request. Server-side cancellation is unsupported.
If a timed-out operation writes data, reconcile the destination before repeating it. Keep the endpoint, failing stage, duration and query identifier when available. Raising all timeouts together hides which stage needed attention.
See [native client](https://coordinatordb.com/docs/concepts/features/interfaces/client), [HTTP interface](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [server limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/count-parts-by-type
Language: en
# Inspect table counts and size estimates
Coordinator DB does not expose a `system.parts` relation or part-type inventory. Use public table metadata for object counts and available size estimates. This answers which tables exist without assuming another database's physical maintenance model.
```sql
SELECT database, table_name, total_rows, total_bytes
FROM system.tables
WHERE schema_name = 'main' AND table_type = 'BASE TABLE'
ORDER BY database, table_name
FORMAT csv;
```
## Interpret the values correctly
`total_rows` and `total_bytes` are available estimates and can be NULL. They are not a guarantee of an exact count. For a specific table where accuracy matters, run `SELECT count(*)` against that table. Do not sum estimates and present them as a precise billing or capacity figure.
Filter by database and namespace when names repeat. The observing connection's temporary objects can also appear in metadata and should not be confused with persistent application tables.
## Investigate a growth problem
Compare the table's schema, known import boundaries and actual row count before changing ingestion behavior. If duplicate loads caused growth, reconcile identifiers and completed batches. If a query is slow, inspect its plan and request metrics rather than looking for a nonexistent part counter.
See [system.tables](https://coordinatordb.com/docs/reference/system-tables/tables), [system.columns](https://coordinatordb.com/docs/reference/system-tables/columns) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/exception-too-many-parts
Language: en
# Diagnose pressure from many small inserts
Coordinator DB does not report a physical-parts maintenance condition or require part merging. When an importer sends many small writes, investigate request overhead, admission failures, locks and the actual SQL error instead of applying an unrelated maintenance command.
## Group work deliberately
Use one multi-row VALUES statement or one formatted input statement for rows belonging to a batch. A successful response follows statement completion; there is no asynchronous INSERT queue. Measure a few batch sizes with the same representative data and compare duration and peak memory.
A larger batch should still fit the intended transaction and recovery boundary. Do not combine unrelated work merely to reduce request count. Keep a stable batch or event identifier so an interrupted response can be reconciled before retrying.
## Read the reported limit
HTTP 503 can signal admission or locking failures. SQL request limits separately bound time, accounted memory, returned rows and response bytes. Raising `max_connections` cannot correct malformed input or a schema constraint error.
Use `system.query_log` to inspect completed events and `system.processes` for active work. Apply an external retry policy only to failures it can safely classify, and avoid replaying an ambiguous write unconditionally.
See [batch inserts](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts), [server admission](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max) and [HTTP errors](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/fix-developer-verification-error-in-macos
Language: en
# Handle a macOS executable verification warning
A macOS warning about an unverified developer is a host security decision made before Coordinator DB processes SQL. Confirm where the executable came from and whether it is the file you intended to run before changing that decision.
## Verify the intended artifact
Use the project's documented installation path or an artifact approved by your organization. Check any available signature or checksum against the trusted source through a separate channel. A filename or an archive's appearance is not evidence of authenticity.
If the file is expected and your policy permits it, use macOS's supported privacy and security workflow to allow that specific application. Do not broadly disable host protection or remove checks from unrelated files to make one command run. A managed machine may require its administrator's approval.
## Separate later startup failures
Once the executable can run, `--help` can verify the command interface without starting the server. Server startup then requires existing valid configuration and credentials files. An XML validation error or occupied port is unrelated to the earlier developer-verification warning.
Preserve the exact warning and artifact identity when asking an administrator for help. Database credentials and application records are not needed to investigate whether an executable is trusted.
See [installation](https://coordinatordb.com/docs/get-started/setup/install), [command-line options](https://coordinatordb.com/docs/concepts/features/interfaces/cli) and [configuration files](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/part-intersects-previous-part
Language: en
# Resolve overlapping data import ranges
Coordinator DB does not expose physical-part intersection errors or a command to repair such parts. If an import produces overlapping application data, investigate the source ranges and retry history. Two successful batches can overlap even when each SQL statement is valid.
## Identify the overlap
Record the predicates used by each batch. Prefer explicit half-open ranges such as `id >= 1000 AND id < 2000`; adjoining ranges can then use the same boundary without including it twice. For time ranges, agree on timezone and precision as well as inclusivity.
Query the destination by stable identifiers and compare it with the import manifest. A unique key can reject duplicate identity, but it cannot decide which conflicting payload is correct. Define that rule before replacing data.
## Repair with a reviewed change
Preserve a verified copy before deleting or rebuilding rows. Create a replacement dataset for the affected ranges, validate counts and representative values, then apply the correction with explicit SQL and an appropriate transaction boundary. Test the same overlapping input again to confirm the import policy handles retries.
Do not delete database files or run copied maintenance commands to repair an application-level overlap.
See [INSERT conflict policies](https://coordinatordb.com/docs/reference/statements/insert-into), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/recovering-from-corrupt-keeper-snapshot
Language: en
# Recover data from a verified independent copy
Coordinator DB does not provide a Keeper snapshot service or a Keeper recovery command. For a database that cannot be opened or read reliably, use a previously verified independent database copy or a logical export. Do not apply another product's snapshot repair instructions.
## Preserve evidence first
Stop the process using the affected database before manipulating its files. Keep the damaged source intact for investigation. Do not overwrite the only available copy with a recovery attempt, and do not open one database file simultaneously from separate processes.
## Validate an independent replacement
Place the selected known-good copy at a new path and start an independent instance with separate listener addresses. Confirm the expected tables, row counts and representative queries. Record the point represented by the copy so users understand which later writes may be absent.
If only logical exports are available, recreate explicit schemas and import them into a fresh database. Validate type conversions and the export's recorded source boundary before accepting application traffic.
The documented `VACUUM INTO` operation creates a copy from a readable supported source; it is not a repair command for arbitrary damaged bytes. Keep a regular, tested copy procedure outside the incident itself.
See [database copy restrictions](https://coordinatordb.com/docs/concepts/features/backup-restore/overview), [local copy procedure](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk) and [configuration paths](https://coordinatordb.com/docs/concepts/features/configuration/server-config/configuration-files).
---
Source: https://coordinatordb.com/docs/resources/support-center/knowledge-base/troubleshooting/restore-replica-after-storage-failure
Language: en
# Restore an independent service after storage failure
Coordinator DB does not manage replicas or rebuild them automatically after storage loss. Recovery uses an independent verified database copy or a logical export, with service startup and client routing handled by your deployment.
## Prepare a new destination
Keep the failed storage isolated for investigation. Choose a new database path and restore the selected copy there. Start an independent instance with its own listener addresses and existing validated configuration files. Never open the same file from separate processes in an attempt to create redundancy.
## Check the data before routing clients
Confirm schemas, row counts and application queries against the restored service. Determine the last successful copy or export boundary and reconcile any later source events if they can be replayed safely. Stable application identifiers help distinguish missing writes from already accepted writes.
Verify authentication and the actual application network route, not only a local readiness response. Change routing only after the destination is ready and users understand the recovery point. A DNS update does not restore missing rows.
After the incident, test the copy-and-reopen procedure with independent files so the next recovery has known evidence. Scheduled backups and remote backup targets are external operational responsibilities.
See [database copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview), [local copy](https://coordinatordb.com/docs/concepts/features/backup-restore/local-disk) and [HTTP readiness](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/community-wisdom
Language: en
# Practical habits for reliable SQL work
A small reproducible query is easier to review than a large script with hidden assumptions. Keep the table definition, a few synthetic rows and the expected output together when learning a feature or diagnosing a problem. State the connection mode and selected database.
Use explicit destination columns for inserts and explicit join keys. Give result columns meaningful names, and add `ORDER BY` when output order matters. A query that happens to return a stable order today does not establish an ordering contract.
Before changing data, preview the exact predicate and decide whether several statements must commit together. Native sessions retain transactions; HTTP transaction steps must be in one request. Make repeated-request behavior deliberate through keys and appropriate conflict handling.
For performance, compare equivalent results before comparing times. Keep query IDs with observations so history, counters and errors can be correlated. Inspect the selected plan rather than guessing whether an index was used.
When sharing an example, remove credentials and private values. Prefer documented public behavior over folklore or syntax borrowed from another product.
See [SQL statements](https://coordinatordb.com/docs/reference/statements), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions), [result comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets) and [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/cost-optimization
Language: en
# Reduce unnecessary query and data work
Start with the reader's required result. Avoid returning unused columns or unlimited rows when the application only displays a small page. A smaller response can reduce transfer and client work, but it does not necessarily reduce every scan performed by SQL.
Use terminal query events to see where work is spent:
```sql
SELECT query_id, query_duration_ms, read_rows, read_bytes,
result_rows, peak_memory_usage
FROM system.query_log
WHERE type = 'QueryFinish'
ORDER BY event_time DESC
LIMIT 10;
```
Compare equivalent queries on representative data. A targeted index may help frequent lookups; unnecessary indexes also require maintenance during writes. An ordinary view can simplify a shared report definition without storing another copy of its result.
Retain data according to an explicit reader and recovery requirement. Use a reviewed date cutoff for deletion and test the archive or backup before removing source rows. Coordinator DB does not provide a documented billing meter or managed-cloud price schedule, so estimate operational cost from your own environment and observed workload rather than invented per-query prices.
See [indexes](https://coordinatordb.com/docs/reference/statements/create/create-index), [retention](https://coordinatordb.com/docs/resources/support-center/knowledge-base/data-management/when-is-ttl-applied), [copies](https://coordinatordb.com/docs/concepts/features/backup-restore/overview) and [request limits](https://coordinatordb.com/docs/reference/settings/server-settings/settings/max).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/debugging-insights
Language: en
# Keep a focused SQL debugging record
A useful debugging record answers four questions: what was submitted, through which interface, what happened and what should have happened. Include a minimal schema and synthetic input rows so another reader can reproduce the behavior without access to private data.
For a server failure, retain the response query ID and exact exception code. Look up recorded failures with a targeted query:
```sql
SELECT query_id, type, exception_code, exception
FROM system.query_log
WHERE query_id = 'replace-with-query-id'
ORDER BY event_time;
```
If there is no event, check logging settings and thresholds before concluding the request never reached the service. If it is still active, inspect `system.processes`; it is a separate snapshot with different timing semantics.
Change one factor at a time while narrowing the case: predicate, input row, type declaration or connection mode. Confirm that simplification still reproduces the original issue. For browser-only failures, retain status and Origin/Host details without exposing Authorization values.
Do not run an analyzed write as if it were a harmless explanation. Use read-only plans first or an intentional transaction and rollback.
See [query history](https://coordinatordb.com/docs/reference/system-tables/query-log), [active requests](https://coordinatordb.com/docs/reference/system-tables/processes), [HTTP](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [`EXPLAIN`](https://coordinatordb.com/docs/reference/statements/explain).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/materialized-views
Language: en
# Choose a view or a report table
Use an ordinary view when the goal is to name a reusable SELECT. Its result is evaluated from the sources when queried. Use a separate table when the goal is to retain a particular set of calculated rows. Coordinator DB does not provide automatically refreshed materialized views.
```sql
CREATE VIEW daily_order_totals AS
SELECT day, count(*) AS orders, sum(amount) AS revenue
FROM orders
GROUP BY day;
```
This view has no stored report rows and needs no refresh command. If the same calculation is copied with `CREATE TABLE ... AS SELECT`, later source changes do not update that copy. The application must define how and when it is replaced.
For an application-maintained report, specify its freshness requirement, update trigger and verification query before using it. Keep related report changes and an application-owned refresh marker in one transaction if they must agree. A completed statement inside an unfinished transaction is not yet a committed refresh.
Compare a report table with its source calculation using more than total row counts when the values themselves matter. Avoid claiming automatic recovery of refresh schedules after a restart.
See [view definitions](https://coordinatordb.com/docs/reference/statements/create/view), [table copies](https://coordinatordb.com/docs/reference/statements/create/table), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [result comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/performance-optimization
Language: en
# Optimize a measured reader task
Begin with a correct representative query and a clear result requirement. Keep the data, parameters, output format and row limits fixed when comparing a change. A query that omits required rows has not improved the original task.
Inspect its access plan:
```sql
EXPLAIN QUERY PLAN
SELECT id, amount
FROM orders
WHERE account_id = 42
ORDER BY id
LIMIT 20;
```
Check whether a targeted index matches the repeated lookup. Consider the effect on writes before adding several indexes. Restrict the projected columns and validate joins for accidental row multiplication before tuning resource ceilings.
For each measured execution, retain the query ID and terminal duration, read work, result count and peak accounted memory. Repeat only enough to understand ordinary variation; a single unusually fast run is weak evidence. `EXPLAIN ANALYZE` is useful for runtime measurements but executes the statement once, including writes.
`max_threads` is a ceiling for eligible queries, not a promise of parallel execution. Raising it or a memory limit does not by itself reduce work. Keep the change that helps the actual reader workload and document the observed scope.
See [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks), [indexes](https://coordinatordb.com/docs/reference/statements/create/create-index) and [`max_threads`](https://coordinatordb.com/docs/reference/settings/session-settings/max-threads).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/success-stories
Language: en
# Write a reproducible workload result
A useful workload report explains a concrete reader task, the query change and the evidence that its result remained correct. Use a synthetic or shareable dataset so another person can repeat the comparison. Do not invent customer names, private deployment figures or gains that were never measured.
Describe the input schema, relevant value distribution and expected output. For a lookup improvement, record the predicate and selected access plan before and after the index change. For a report rewrite, compare results in both directions and account for duplicate counts when they matter.
Keep measurement conditions consistent: same data, parameters, output format, result caps and connection mode. Report several representative observations when timing varies. Query IDs connect those observations with terminal duration, read work and memory counters in the query log.
State the practical boundary of the evidence. A faster lookup on one dataset does not establish a universal performance claim, and a smaller response can improve delivery without reducing all SQL work. Share only public SQL behavior and sanitized examples.
See [result comparisons](https://coordinatordb.com/docs/resources/support-center/knowledge-base/queries-sql/compare-resultsets), [query measurements](https://coordinatordb.com/docs/guides/clickhouse/performance-and-monitoring/isolate-query-bottlenecks) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/tips-and-tricks/too-many-parts
Language: en
# Improve a workload with many small writes
If an application sends many tiny insert requests, first measure request overhead and decide which rows can be supplied together. Coordinator DB supports multi-row VALUES, INSERT SELECT and formatted bulk input. It does not expose a part-count threshold or a background merge queue to tune.
```sql
CREATE TABLE batched_items(id INTEGER PRIMARY KEY, value TEXT);
INSERT INTO batched_items(id, value)
VALUES (1, 'a'), (2, 'b'), (3, 'c');
```
Choose batch boundaries according to the application's error and retry requirements. A repeated batch can encounter existing keys; decide whether conflicts should fail, be ignored or update values. Do not confuse batching with a promise that arbitrary repeated requests are safe.
For related statements that must commit together, use an explicit transaction. Native connections retain the transaction; HTTP requires its full lifetime inside one request. For files, use the documented native-client input or attached HTTP upload workflow and select a format that represents the values correctly.
Observe terminal duration, write counters and errors for representative batches. Retain request size and response limits when increasing batch size rather than assuming the largest possible request is best.
See [inserting rows](https://coordinatordb.com/docs/reference/statements/insert-into), [bulk input](https://coordinatordb.com/docs/concepts/features/operations/insert/bulkinserts), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [HTTP limits](https://coordinatordb.com/docs/concepts/features/interfaces/http).
---
Source: https://coordinatordb.com/docs/resources/support-center/troubleshooting
Language: en
# Troubleshooting overview
Begin with the failing action and its exact result. A connection refusal, authentication error, invalid statement and failed value conversion need different evidence. Changing several settings at once makes the cause harder to identify.
## Choose a starting point
For connection failures, confirm the hostname, port, listener and route from the affected client. Use HTTP `/ping` when available, then a small authenticated SELECT. For SQL failures, keep the exception code, query identifier, selected database and a reduced statement. For ingestion failures, add the destination schema, selected format and a small redacted input sample.
Completed request events in `system.query_log` can show duration, resource counters and an error. `system.processes` describes work still active. Metadata queries need the documented columns; copied diagnostic SQL for another product can introduce a second unrelated error.
## Preserve the outcome of writes
A lost connection does not prove that a write failed. Check the destination with stable application identifiers before retrying. For a data repair, preserve a verified copy and test the procedure on independent data first.
Share only the minimum reproduction needed to demonstrate the problem. Remove passwords, API keys, private hostnames and business records without removing the condition that triggers the failure.
See [diagnostic workflow](https://coordinatordb.com/docs/resources/support-center/troubleshooting/troubleshooting), [HTTP status codes](https://coordinatordb.com/docs/concepts/features/interfaces/http) and [query history](https://coordinatordb.com/docs/reference/system-tables/query-log).
---
Source: https://coordinatordb.com/docs/resources/support-center/troubleshooting/troubleshooting
Language: en
# Build a reproducible diagnostic case
A useful diagnostic case contains one operation, a known starting state and an observable failure. Start by recording the exact command or SQL, its selected database and the full error code. Include an HTTP or native query identifier when available.
## Reduce without changing the cause
Recreate the relevant table in an isolated database. Replace private rows with synthetic values that preserve types, nulls, lengths and nested structure. Remove unrelated columns and statements incrementally, rerunning after each change. A smaller query that no longer fails is not yet a reproduction.
For format errors, retain the input bytes around the failing row and the statement's format settings. For timing or memory issues, record row counts and settings so another run can exercise comparable work. Use `EXPLAIN QUERY PLAN` before execution and `EXPLAIN ANALYZE` only when executing the statement is intended; analyzed writes take effect.
## Verify the correction
Change one cause at a time and rerun the same reduced case. Then repeat the real workflow within its original request and transaction boundaries. HTTP requests do not share session state, while a native connection does.
Keep the final example free of secrets and private production measurements when sharing it outside your operations team.
See [EXPLAIN](https://coordinatordb.com/docs/reference/statements/explain), [transactions](https://coordinatordb.com/docs/concepts/features/operations/insert/transactions) and [HTTP request state](https://coordinatordb.com/docs/concepts/features/interfaces/http).