From a5bac116673074322c59470094507d85599d754f Mon Sep 17 00:00:00 2001 From: Dmitriy Pavlov Date: Tue, 26 May 2026 21:09:19 +0300 Subject: [PATCH] IGNITE-28725 Document CREATE TABLE on existing caches --- docs/_docs/SQL/schemas.adoc | 4 ++-- docs/_docs/sql-reference/ddl.adoc | 29 +++++++++++++++++++++++++---- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/_docs/SQL/schemas.adoc b/docs/_docs/SQL/schemas.adoc index 02705deb98b11..2f8abdc9ef0fd 100644 --- a/docs/_docs/SQL/schemas.adoc +++ b/docs/_docs/SQL/schemas.adoc @@ -85,7 +85,7 @@ CREATE TABLE City ( ) WITH "backups=1, CACHE_NAME=City"; ---- -See the link:sql-reference/ddl#create-table[CREATE TABLE] page for more details. +See the link:sql-reference/ddl#create-table[CREATE TABLE] page for more details, including creating a table on an existing cache. If you do not use this parameter, the cache name is defined in the following format (in capital letters): @@ -140,4 +140,4 @@ cache.put(2, invalidPerson); // CacheException wrapping IgniteSQLException when With the default configuration (validation disabled for non-indexed columns), the `put` above succeeds even though the stored `BinaryObject` does not match the SQL schema. Turning on validation causes Ignite to reject the update, protecting the table from malformed records. -Enable the option when you need stronger guarantees that dynamic or user-provided data cannot break the table definition, and keep it disabled when the overhead of additional checks outweighs the risk of incorrect data. \ No newline at end of file +Enable the option when you need stronger guarantees that dynamic or user-provided data cannot break the table definition, and keep it disabled when the overhead of additional checks outweighs the risk of incorrect data. diff --git a/docs/_docs/sql-reference/ddl.adoc b/docs/_docs/sql-reference/ddl.adoc index 2ebad5484ac6f..16d867813c88b 100644 --- a/docs/_docs/sql-reference/ddl.adoc +++ b/docs/_docs/sql-reference/ddl.adoc @@ -21,8 +21,8 @@ This page encompasses all data definition language (DDL) commands supported by I == CREATE TABLE -The command creates a new Ignite cache and defines a SQL table on top of it. The underlying cache stores the data in -the form of key-value pairs while the table allows processing the data with SQL queries. +The command defines a SQL table on top of an Ignite cache. By default, Ignite creates a new cache for the table. +If `CACHE_NAME` points to an existing cache, Ignite defines the SQL table on top of that cache. The table will reside in the link:SQL/schemas[Schema] specified in the connection parameters. If no schema is specified, the `PUBLIC` will be used as a default. @@ -57,8 +57,9 @@ Parameters: sets the write synchronization mode for the underlying cache. If neither this nor the `TEMPLATE` parameter is set, then the cache is created with `FULL_SYNC` mode enabled. ** `CACHE_GROUP=` - specifies the link:configuring-caches/cache-groups[group name] the underlying cache belongs to. ** `AFFINITY_KEY=` - specifies an link:data-modeling/affinity-collocation[affinity key] name which is a column of the `PRIMARY KEY` constraint. -** `CACHE_NAME=` - the name of the underlying cache created by the command, -or the `SQL_{SCHEMA_NAME}_{TABLE}` format will be used if the parameter not specified. +** `CACHE_NAME=` - the name of the underlying cache. If the cache does not exist, it is created by the command. +If the cache already exists, Ignite tries to define the table on top of it. +If the parameter is not specified, the `SQL_{SCHEMA_NAME}_{TABLE}` format is used for the new cache name. ** `DATA_REGION=` - name of the link:memory-configuration/data-regions[data region] where table entries should be stored. By default, Ignite stores all the data in a default region. ** `PARALLELISM=` - SQL queries are executed by a single thread on each node by default, but certain scenarios can benefit from multi-threaded execution, see link:perf-and-troubleshooting/sql-tuning#query-parallelism[Query Parallelism] for details. ** `KEY_TYPE=` - sets the name of the custom key type that is used from the key-value APIs in Ignite. The name should correspond to a Java, .NET, or C++ class, or it can be a random one if link:data-modeling/data-modeling#binary-object-format[BinaryObjects] is used instead of a custom class. The number of fields and their types in the custom key type has to correspond to the `PRIMARY KEY`. Refer to the <> section below for more details. @@ -118,6 +119,26 @@ CREATE TABLE IF NOT EXISTS Person ( ) WITH "template=partitioned,backups=1,affinity_key=city_id,CACHE_NAME=Person,KEY_TYPE=PersonKey,VALUE_TYPE=PersonValue"; ---- +=== Create Table on an Existing Cache + +If `CACHE_NAME` points to an existing cache, Ignite adds only SQL metadata to that cache. This is allowed only when the +cache does not already have query entities, for example from `CacheConfiguration.setQueryEntities(...)` or +`CacheConfiguration.setIndexedTypes(...)`. + +When the existing cache has a SQL schema configured, the table must be created in the same schema. If the schema does not +match, the command fails with an `Invalid schema` error. + +[source,sql] +---- +CREATE TABLE my_schema.Person ( + id INT PRIMARY KEY, + name VARCHAR +) WITH "CACHE_NAME=PersonCache"; +---- + +Cache creation parameters such as `TEMPLATE`, `BACKUPS`, `CACHE_GROUP`, `DATA_REGION`, `ATOMICITY`, +`WRITE_SYNCHRONIZATION_MODE`, and other cache configuration options are not applied to an existing cache. + === Use non-Upper Case Columns