zstan commented on code in PR #6553: URL: https://github.com/apache/ignite-3/pull/6553#discussion_r2329267723
########## docs/_docs/developers-guide/clients/overview.adoc: ########## @@ -105,6 +105,89 @@ 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 condition on colocation columns is required. + +Partition awareness works only if the SQL query contains an equality condition on all colocated 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. + +* DML query, which can **not** be rewritten to key-value operation, are not supported yet. +Partition awareness works only if the SQL query could be rewritten to a single key-value operation. The explain plan contains `KeyValueGet` or `KeyValueModify` nodes in that case. + +* 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. + +NOTE: As for now, Partition awareness is supported for queries over single partition of a single table. + +=== 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` node with equality conditions on all colocation columns of the table. +---- +TableScan + table: PUBLIC.T + predicate: AND(=(COLOCATION_COL_1, ?), =(COLOCATION_COL_2, ?)) +---- +* or similar `IndexScan` that search bound has a prefix of all the colocation columns. +---- +IndexScan + table: PUBLIC.T + predicate: AND(=(COLOCATION_COL_1, ?), =(COLOCATION_COL_2, ?)) + searchBounds: [ExactBounds [bound=?], ExactBounds [bound=?]] +---- +* or `KeyValueGet` node +---- +KeyValueGet + table: PUBLIC.T + key: [?0] +---- +* or `KeyValueModify` node +---- +KeyValueModify + table: PUBLIC.T + key: [?0] +---- + +NOTE: SQL engine allows both literals and dynamic parameters in equality conditions for partition awareness purposes. + + +=== Examples +Assumed a table `T` is defined as: +[source, sql] +---- +CREATE TABLE T ( + id INT NOT NULL, + region_id INT NOT NULL, + customer_id INT NOT NULL, + val VARCHAR, + PRIMARY KEY (id, region_id, customer_id) +) COLOCATE BY (region_id, customer_id); +---- +Next queries can utilize partition awareness optimization: +---- +SELECT * FROM T WHERE region_id =? AND customer_id = ? + +DELETE FROM T +WHERE id = ? AND region_id = ? AND customer_id = ?; + +INSERT INTO T (region_id, customer_id, value) Review Comment: is it possible to insert without PK ? + "value" column is absent -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: notifications-unsubscr...@ignite.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
