(ignite) branch master updated: IGNITE-29020 Document SQL query initiator ID (#13525)

[dpavlov]

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 aa3dec022f4 IGNITE-29020 Document SQL query initiator ID (#13525)
aa3dec022f4 is described below

commit aa3dec022f4408a8a51263ac6c0f1612a5fd73ae
Author: ignitetcbot <43213589+ignitetc...@users.noreply.github.com>
AuthorDate: Fri Aug 28 13:52:51 2026 +0300

    IGNITE-29020 Document SQL query initiator ID (#13525)
    
    Codex co-authored-by: Dmitriy Pavlov <dpav...@apache.org>
---
 docs/_docs/SQL/sql-api.adoc                           | 19 +++++++++++++++++++
 .../main/java/org/apache/ignite/snippets/SqlAPI.java  | 12 ++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/docs/_docs/SQL/sql-api.adoc b/docs/_docs/SQL/sql-api.adoc
index 92f132fb2bd..287bee48e77 100644
--- a/docs/_docs/SQL/sql-api.adoc
+++ b/docs/_docs/SQL/sql-api.adoc
@@ -116,6 +116,25 @@ 
include::code-snippets/cpp/src/sql.cpp[tag=sql-fields-query,indent=0]
 
 `SqlFieldsQuery` returns a cursor that iterates through the results that match 
the SQL query.
 
+=== Query Initiator ID
+
+To correlate SQL queries with server-side diagnostics, set a query initiator ID
+with `SqlFieldsQuery.setQueryInitiatorId(...)` before executing the query.
+
+[source,java]
+----
+include::{javaSourceFile}[tag=query-initiator-id,indent=0]
+----
+
+Ignite exposes this value in the `INITIATOR_ID` column of the
+link:monitoring-metrics/system-views#sql_queries[SQL_QUERIES] and
+link:monitoring-metrics/system-views#sql_queries_history[SQL_QUERIES_HISTORY]
+system views. Query history aggregates executions of the same query, so the
+`INITIATOR_ID` column in `SQL_QUERIES_HISTORY` contains the value from the 
latest
+execution and does not preserve initiator IDs from earlier executions.
+Server-side SQL diagnostics, such as long query warning messages, also include
+the `initiatorId` value.
+
 === Local Execution
 
 To force local execution of a query, use `SqlFieldsQuery.setLocal(true)`. In 
this case, the query is executed against the data stored on the node where the 
query is run. It means that the results of the query are almost always 
incomplete. Use the local mode only if you are confident you understand this 
limitation.
diff --git 
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/SqlAPI.java
 
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/SqlAPI.java
index 60308e4b392..77acfb825c6 100644
--- 
a/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/SqlAPI.java
+++ 
b/docs/_docs/code-snippets/java/src/main/java/org/apache/ignite/snippets/SqlAPI.java
@@ -100,6 +100,18 @@ public class SqlAPI {
         // end::simple-query[]
     }
 
+    void queryInitiatorId(Ignite ignite) {
+        // tag::query-initiator-id[]
+        IgniteCache<Long, Person> cache = ignite.cache("Person");
+
+        SqlFieldsQuery sql = new SqlFieldsQuery(
+                "select name from Person")
+                .setQueryInitiatorId("person-report-job");
+
+        cache.query(sql).getAll();
+        // end::query-initiator-id[]
+    }
+
     void insert(Ignite ignite) {
         // tag::insert[]
         IgniteCache<Long, Person> cache = ignite.cache("personCache");