Named collections
Create named collections through the Query API.
Named collections
This page describes statements accepted by the Query API in RawTree Cloud and RawTree BYOC. Its restrictions apply to the API, not to all RawTree SQL. See ClickHouse compatibility and API scope.
Syntax
CREATE NAMED COLLECTION [IF NOT EXISTS] <name> [ON CLUSTER 'default']
AS <key> = <literal> [OVERRIDABLE | NOT OVERRIDABLE] [, ...]Clauses
| Clause | Meaning |
|---|---|
IF NOT EXISTS | Keep an existing collection unchanged. |
ON CLUSTER 'default' | Pass the default cluster clause to the database. |
OVERRIDABLE | Allow the value to be overridden. |
NOT OVERRIDABLE | Do not allow the value to be overridden. |
Values must be string, numeric, or boolean literals. Expressions and duplicate keys are not supported. Each key can omit the override clause or use one of its two values.
Query API behavior
- Organization administrators and admin API keys can create collections through
/v1/query. IF NOT EXISTSstill checks access and repairs creation permission. It does not change an existing collection, including its credentials.- Only
ON CLUSTER 'default'is accepted. The API passes it through without changing database storage settings. - Local storage creates the collection on the selected writer replica. Keeper-backed storage replicates the collection.
- Replicated storage can ignore
ON CLUSTERwhenignore_on_cluster_for_replicated_named_collections_queries = 1. - Distributed DDL redacts collection values in
system.distributed_ddl_queue. Use Keeper-backed storage and omitON CLUSTERfor credentials. - Standard reader and writer identities receive usage of current and future collections. Custom-role API keys need an administrator to grant usage.
- Permission repair does not grant secret visibility.
- The backend service account must grant
CREATE NAMED COLLECTIONon the requested collection,CLUSTER, andNAMED COLLECTION ON *. The API repairs creation permission for the organization's writer identity. ALTER NAMED COLLECTION,DROP NAMED COLLECTION, and collection permission grants are not supported through this endpoint.- Non-admin callers, workflows, and the internal organization cannot create collections.
AI feature enablement remains a cluster configuration step.
On engine version 26.7.13.5, a native grant bug can make later column-level
permission grants ineffective when a collection name partially overlaps a
database-name prefix, such as settings and system. The bug also occurs with
direct SQL. Use distinct prefixes on this engine version.
The API sanitizes database errors. It also omits named-collection query bodies from Platform logs when the request returns an HTTP error. Do not save SQL with real credentials in saved queries or share it with other users.
Errors
Unsupported syntax, expressions, duplicate keys, multiple statements, and unsupported cluster names return a client error. The response sanitizes database details.
The endpoint does not support ALTER or DROP statements for named collections.
Do not use these statements through /v1/query.
Examples
Create a collection. Replace the placeholder with a provider key only in a secure client; this example uses a placeholder value.
CREATE NAMED COLLECTION IF NOT EXISTS docs_ai_credentials
AS provider = 'openai', api_key = '<your-provider-api-key>' NOT OVERRIDABLECREATE ... IF NOT EXISTS keeps this example safe to run again. The endpoint
does not support a drop statement for cleanup.