This is an automated email from the ASF dual-hosted git repository.
dspavlov pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ignite.git
The following commit(s) were added to refs/heads/master by this push:
new 0144ebd269e IGNITE-28725 Document CREATE TABLE on existing caches
(#13182)
0144ebd269e is described below
commit 0144ebd269ee8b0b2725d9c84bc2696bc9d2da97
Author: ignitetcbot <[email protected]>
AuthorDate: Sat Jun 6 10:06:03 2026 +0300
IGNITE-28725 Document CREATE TABLE on existing caches (#13182)
Codex co-authored-by: Dmitriy Pavlov <[email protected]>
---
docs/_docs/SQL/schemas.adoc | 4 ++--
docs/_docs/sql-reference/ddl.adoc | 30 ++++++++++++++++++++++++++----
2 files changed, 28 insertions(+), 6 deletions(-)
diff --git a/docs/_docs/SQL/schemas.adoc b/docs/_docs/SQL/schemas.adoc
index 02705deb98b..2f8abdc9ef0 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 2ebad5484ac..11b24fa5a70 100644
--- a/docs/_docs/sql-reference/ddl.adoc
+++ b/docs/_docs/sql-reference/ddl.adoc
@@ -21,8 +21,9 @@ 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. The underlying
cache stores the data in the form of
+key-value pairs while the table allows processing the data with SQL queries.
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 +58,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=<group name>` - specifies the
link:configuring-caches/cache-groups[group name] the underlying cache belongs
to.
** `AFFINITY_KEY=<affinity key column name>` - specifies an
link:data-modeling/affinity-collocation[affinity key] name which is a column of
the `PRIMARY KEY` constraint.
-** `CACHE_NAME=<custom name of the new cache>` - 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=<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=<existing data region name>` - 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=<number of SQL execution threads>` - 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=<custom name of the 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 <<Use non-SQL
API>> section below for more details.
@@ -118,6 +120,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
