# Named collections (/docs/reference/sql/statements/named-collection)



Named collections [#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](/docs/reference/clickhouse-compatibility).

Syntax [#syntax]

```sql
CREATE NAMED COLLECTION [IF NOT EXISTS] <name> [ON CLUSTER 'default']
AS <key> = <literal> [OVERRIDABLE | NOT OVERRIDABLE] [, ...]
```

Clauses [#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.

<a id="rawtree-behavior" />

Query API behavior [#query-api-behavior]

* Organization administrators and admin API keys can create collections through
  `/v1/query`.
* `IF NOT EXISTS` still 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 CLUSTER` when
  `ignore_on_cluster_for_replicated_named_collections_queries = 1`.
* Distributed DDL redacts collection values in
  `system.distributed_ddl_queue`. Use Keeper-backed storage and omit
  `ON CLUSTER` for 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 COLLECTION` on the
  requested collection, `CLUSTER`, and `NAMED 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 [#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 [#examples]

Create a collection. Replace the placeholder with a provider key only in a
secure client; this example uses a placeholder value.

```sql test
CREATE NAMED COLLECTION IF NOT EXISTS docs_ai_credentials
AS provider = 'openai', api_key = '<your-provider-api-key>' NOT OVERRIDABLE
```

`CREATE ... IF NOT EXISTS` keeps this example safe to run again. The endpoint
does not support a drop statement for cleanup.

Related [#related]

* [Query API](/docs/reference/api/query#post-v1query)
* [ClickHouse compatibility](/docs/reference/clickhouse-compatibility)