diff --git a/docs/RFCS/sql_split_syntax.md b/docs/RFCS/sql_split_syntax.md index 90164a198c33..367f59580de9 100644 --- a/docs/RFCS/sql_split_syntax.md +++ b/docs/RFCS/sql_split_syntax.md @@ -94,6 +94,9 @@ order; for example, if there are many splits, it is advantageous to sort the split points, split at the middle point, then recursively process the left and right sides (in parallel). +*Interleaved tables*: the command works as expected; the split will inherently +cause a corresponding split in the parent or child tables/indexes. + ##### Return values ##### `ALTER TABLE/INDEX SPLIT AT` currently returns a row with two columns: the key @@ -140,6 +143,9 @@ ALTER INDEX t@idx SCATTER FROM (1) TO (2) The statement returns only after the relocations are complete. +*Interleaved tables*: the command works as expected (the ranges may contain rows +for parent or child tables/indexes). + ### 3. `ALTER TABLE/INDEX TESTING_RELOCATE` ### The `TESTING_RELOCATE` statements can be used to relocate specific ranges to @@ -180,7 +186,46 @@ ALTER TABLE t TESTING_RELOCATE SELECT ARRAY[1+i%2], i FROM GENERATE_SERIES(1, 10 The statement returns only after the relocations are complete. -# Drawbacks +*Interleaved tables*: the command works as expected (the ranges may contain rows +for parent or child tables/indexes). + +### 4. `crdb_internal.ranges` and `ranges_cached` system table ### + +To facilitate testing the implementation of the new commands (as well as allow a +user to verify what the commands did), we introduce a `crdb_internal.ranges` +system table that can be used to look at all the ranges on the system, or the +ranges from a table. + +The schema of the table is as follows: + +Column | Type | Description +---------------|------------|------------------------------ +`start_key` | BYTES | Range start key (raw) +`start_pretty` | STRING | Range start key (pretty-printed) +`end_key` | BYTES | Range end key (raw) +`end_pretty` | STRING | Range end key (pretty-printed) +`database` | STRING | Database name (if range is part of a table) +`table` | STRING | Table name (if range is part of a table); for interleaved tables this is always the root table. +`index` | STRING | Index name (if range is part of a non-primary index); +`replicas` | ARRAY(INT) | Replica store IDs +`lease_holder` | INT | Lease holder store ID + +The last two columns could be hidden (so they are only available if `SELECT`ed +for specifically). + +Implementation notes: + - the system table infrastructure will be improved so the row producing + function has access to filters; specifying a `table` or `index` filter that + should be optimized to only look at the ranges for that table. + - the row producing function should also have access to needed columns; that + way the more expensive lease holder determination can be omitted if the + column is not needed. + +A second table, `crdb_internal.ranges_cached` has the same schema, but it +returns data from the range and lease holder caches. Specifically: the ranges +along with `replicas` information are populated from the range cache; for each +range, if that range ID has an entry in the lease holder cache, `lease_holder` +is set according to that entry; otherwise it is NULL. # Alternatives @@ -194,4 +239,11 @@ splits to happen sequentially; we cannot implement the algorithm mentioned above that parallelizes the splits. One way around this would be to introduce `split_at` as an *aggregation* function (akin to `sum`). +Alternatives considered for `crdb_internal.ranges`: + - a `SHOW RANGES FOR TABLE/INDEX` statement; the system table was deemed more + useful. + - having multiple system tables (e.g. a separate one for lease holders) and + using joins as necessary; this requires too many changes to make sure we only + generate the parts of the table that are needed. + # Unresolved questions