This is an automated email from the ASF dual-hosted git repository. amashenkov pushed a commit to branch ignite-25616 in repository https://gitbox.apache.org/repos/asf/ignite-3.git
commit cae7ccaf7b8e4a286c29f88951422db516539d80 Author: amashenkov <[email protected]> AuthorDate: Thu Sep 4 15:03:50 2025 +0300 wip --- docs/_docs/developers-guide/clients/overview.adoc | 54 +++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/docs/_docs/developers-guide/clients/overview.adoc b/docs/_docs/developers-guide/clients/overview.adoc index 60fd9cfbdfe..18e637e4909 100644 --- a/docs/_docs/developers-guide/clients/overview.adoc +++ b/docs/_docs/developers-guide/clients/overview.adoc @@ -105,6 +105,60 @@ For each key that needs updating, the client will get the name of the node holdi NOTE: Partition awareness assumes that the cluster is stable. Client receives information about cluster data assignments in the background, and it may be outdated by the time an update is sent. If it is, nodes will automatically redirect requests to correct nodes until data on the client is updated. +=== Limitations + +* Equality on affinity columns required + Partition awareness works only if the SQL query contains an equality condition on all colocated (affinity) columns. This is required for the client to route SQL query to the node where the partition with the data resides. + +* Explicit transactions are not supported + Partition awareness may not be applied inside the explicit transactions. In this case, SQL queries must go through the transaction coordinator node, which avoids direct partition-based routing. + +* Partition awareness cache on client may miss required metadata + Client node do not parse or executed query by itself, it require query metadata with colocation information from the server node to utilize partition awareness optimization. The query metadata is cached on client after the first query execution and can be used in later query runs. However, it also can be evicted due to cache eviction policies. + +=== How to Check if Partition Awareness is Applicable + +You can verify whether partition awareness is used for a given SQL query by inspecting the EXPLAIN command results. + +The resulting plan should contain a TableScan or IndexScan node with conditions on all colocation (affinity) columns of the table. +TableScan(table=T, filters=[region_id = 10, customer_id = 200]) + +=== Examples +Assume there is a table defined as: +[source, sql] +---- +CREATE TABLE T ( + region_id INT NOT NULL, + customer_id INT NOT NULL, + value VARCHAR, + PRIMARY KEY (region_id, customer_id) +) WITH ( + AFFINITY_KEY = (region_id, customer_id) +); +---- +Next queries can utilize partition awareness optimization: +---- +SELECT * FROM T WHERE region_id =? AND customer_id = ? + +UPDATE T +SET value = 'updated' +WHERE region_id = ? AND customer_id = ?; + +INSERT INTO T (region_id, customer_id, value) +VALUES (?, ?, ?); +---- + +Next, queries can NOT utilize partition awareness. +---- +// Missed colocation information for `customer_id` +SELECT * FROM T WHERE region_id =? + +// Non-equality conditions +SELECT * FROM T WHERE region_id > ? AND customer_id > ? +---- + +In other more complex cases (nested queries, IN condition, JOINS), partition awareness may work or may not work that depends whether the query can be rewritten in form that contains colocation information. + == Client Features The following table outlines features supported by each client.
