This is an automated email from the ASF dual-hosted git repository.
alexpl 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 35af216b7d6 IGNITE-26712 - Documentation of
SqlConfiguration#validationEnabled (#12423)
35af216b7d6 is described below
commit 35af216b7d6e069dab4a2ea051cd65e1c9aca02a
Author: Semyon Zikunov <[email protected]>
AuthorDate: Fri Oct 24 06:12:11 2025 +1000
IGNITE-26712 - Documentation of SqlConfiguration#validationEnabled (#12423)
Thank you for submitting the pull request to the Apache Ignite.
In order to streamline the review of the contribution
we ask you to ensure the following steps have been taken:
### The Contribution Checklist
- [x] There is a single JIRA ticket related to the pull request.
- [x] The web-link to the pull request is attached to the JIRA ticket.
- [ ] The JIRA ticket has the _Patch Available_ state.
- [ ] The pull request body describes changes that have been made.
The description explains _WHAT_ and _WHY_ was made instead of _HOW_.
- [ ] The pull request title is treated as the final commit message.
The following pattern must be used: `IGNITE-XXXX Change summary` where
`XXXX` - number of JIRA issue.
- [ ] A reviewer has been mentioned through the JIRA comments
(see [the Maintainers
list](https://cwiki.apache.org/confluence/display/IGNITE/How+to+Contribute#HowtoContribute-ReviewProcessandMaintainers))
- [ ] The pull request has been checked by the Teamcity Bot and
the `green visa` attached to the JIRA ticket (see [TC.Bot: Check
PR](https://mtcga.gridgain.com/prs.html))
### Notes
- [How to
Contribute](https://cwiki.apache.org/confluence/display/IGNITE/How+to+Contribute)
- [Coding abbreviation
rules](https://cwiki.apache.org/confluence/display/IGNITE/Abbreviation+Rules)
- [Coding
Guidelines](https://cwiki.apache.org/confluence/display/IGNITE/Coding+Guidelines)
- [Apache Ignite Teamcity
Bot](https://cwiki.apache.org/confluence/display/IGNITE/Apache+Ignite+Teamcity+Bot)
If you need any help, please email [email protected] or ask anу
advice on http://asf.slack.com _#ignite_ channel.
---
docs/_docs/SQL/schemas.adoc | 49 ++++++++++++++++++++++
.../ignite/configuration/SqlConfiguration.java | 24 ++++++++---
2 files changed, 67 insertions(+), 6 deletions(-)
diff --git a/docs/_docs/SQL/schemas.adoc b/docs/_docs/SQL/schemas.adoc
index 613fc466594..02705deb98b 100644
--- a/docs/_docs/SQL/schemas.adoc
+++ b/docs/_docs/SQL/schemas.adoc
@@ -92,3 +92,52 @@ If you do not use this parameter, the cache name is defined
in the following for
....
SQL_<SCHEMA_NAME>_<TABLE_NAME>
....
+
+
+== Validating Data Against the Schema
+
+Ignite can verify that values inserted into a table match the column types and
constraints declared in its SQL schema. By default, Ignite performs these
checks only for indexed columns. To validate all columns, enable the
server-side check on every node before startup:
+
+[tabs]
+--
+tab:Java[]
+[source,java]
+----
+SqlConfiguration sqlCfg = new SqlConfiguration()
+ .setValidationEnabled(true);
+
+IgniteConfiguration cfg = new IgniteConfiguration()
+ .setSqlConfiguration(sqlCfg);
+----
+
+tab:XML[]
+[source,xml]
+----
+<property name="sqlConfiguration">
+ <bean class="org.apache.ignite.configuration.SqlConfiguration">
+ <property name="validationEnabled" value="true"/>
+ </bean>
+</property>
+----
+--
+
+When validation is enabled, Ignite runs extra checks for each SQL `INSERT`,
`MERGE`, and `UPDATE` statement as well as cache API calls that modify
SQL-managed tables and rejects data that breaks the schema. Violations raise an
`IgniteSQLException` for SQL clients (JDBC, ODBC, REST), while key-value API
callers get a `CacheException` whose root cause is that same
`IgniteSQLException`.
+In both cases the application can handle the failure and the incorrect values
are not stored. SQL DML already attempts to coerce values to the declared
column types, so type mismatches typically appear when you write data through
the cache API or binary objects.
+
+[source,java]
+----
+// CREATE TABLE Person (id INT PRIMARY KEY, age INT);
+
+IgniteCache<Integer, BinaryObject> cache =
ignite.cache("SQL_PUBLIC_PERSON").withKeepBinary();
+
+BinaryObject invalidPerson = ignite.binary().builder("Person")
+ .setField("id", 2)
+ .setField("age", "forty-two") // String instead of INT column
+ .build();
+
+cache.put(2, invalidPerson); // CacheException wrapping IgniteSQLException
when validation is enabled
+----
+
+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
diff --git
a/modules/core/src/main/java/org/apache/ignite/configuration/SqlConfiguration.java
b/modules/core/src/main/java/org/apache/ignite/configuration/SqlConfiguration.java
index 1c6ed3734b7..7bead0b04e7 100644
---
a/modules/core/src/main/java/org/apache/ignite/configuration/SqlConfiguration.java
+++
b/modules/core/src/main/java/org/apache/ignite/configuration/SqlConfiguration.java
@@ -51,7 +51,14 @@ public class SqlConfiguration {
/** SQL plan history size. */
private int sqlPlanHistSize = -1;
- /** Enable validation of key & values against sql schema. */
+ /**
+ * Enables validation of cache keys and values against the SQL schema that
describes the cache.
+ * Ignite always enforces nullability and length/precision constraints for
indexed columns and fields
+ * that declare them. When this flag is {@code true}, Ignite also
validates runtime types for every
+ * column, including non-indexed ones. A mismatch stops the operation: SQL
clients receive an
+ * IgniteSQLException and key-value API callers get a CacheException.
+ * Disabled by default.
+ */
private boolean validationEnabled;
/** SQL query engines configuration. */
@@ -188,19 +195,24 @@ public class SqlConfiguration {
}
/**
- * Is key & value validation enabled.
+ * Returns whether Ignite validates cache keys and values against the
declared SQL schema before
+ * applying DML operations such as {@code INSERT}, {@code MERGE}, {@code
UPDATE} and cache API calls that
+ * modify data. When enabled, Ignite checks that each property uses a
runtime type compatible
+ * with the column definition (including for non-indexed columns).
Violations raise an IgniteSQLException
+ * for SQL operations or a CacheException for cache API updates.
*
- * @return {@code true} When key & value shall be validated against
SQL schema.
+ * @return {@code true} if key and value validation against the SQL schema
is enabled; {@code false} otherwise.
*/
public boolean isValidationEnabled() {
return validationEnabled;
}
/**
- * Enable/disable key & value validation.
+ * Enables or disables validation of cache keys and values against the SQL
schema.
*
- * @param validationEnabled {@code true} When key & value shall be
validated against SQL schema.
- * Default value is {@code false}.
+ * @param validationEnabled {@code true} to validate key and value objects
against the SQL schema and reject
+ * data that violates declared types or constraints; {@code false} to skip
these checks. The default value
+ * is {@code false}.
* @return {@code this} for chaining.
*/
public SqlConfiguration setValidationEnabled(boolean validationEnabled) {
