From 992cb26aaa50b36257b05e3b039577dfc74a6e0a Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 16 Apr 2026 10:56:21 -0400 Subject: [PATCH] Support hash-sharded indexes that hash only a prefix of the index key columns Fixes DOC-16113 --- .../v26.2/misc/index-storage-parameters.md | 1 + src/current/v26.2/hash-sharded-indexes.md | 14 ++++++++++++++ 2 files changed, 15 insertions(+) diff --git a/src/current/_includes/v26.2/misc/index-storage-parameters.md b/src/current/_includes/v26.2/misc/index-storage-parameters.md index e2aa6d76301..bde3fcae6db 100644 --- a/src/current/_includes/v26.2/misc/index-storage-parameters.md +++ b/src/current/_includes/v26.2/misc/index-storage-parameters.md @@ -1,6 +1,7 @@ | Parameter name | Description | Data type | Default value |---------------------+----------------------|-----|------| | `bucket_count` | The number of buckets into which a [hash-sharded index]({% link {{ page.version.version }}/hash-sharded-indexes.md %}) will split. | Integer | The value of the `sql.defaults.default_hash_sharded_index_bucket_count` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}). | +| `shard_columns` | The first key column or columns to use when computing the shard column for a [hash-sharded index]({% link {{ page.version.version }}/hash-sharded-indexes.md %}). The value must match a prefix of the index key columns. If this parameter is omitted, CockroachDB hashes all index key columns. | Tuple of column identifiers or a single column identifier | All index key columns | | `geometry_max_x` | The maximum X-value of the [spatial reference system]({% link {{ page.version.version }}/architecture/glossary.md %}#spatial-reference-system) for the object(s) being covered. This only needs to be set if you are using a custom [SRID]({% link {{ page.version.version }}/architecture/glossary.md %}#srid). | | Derived from SRID bounds, else `(1 << 31) -1`. | | `geometry_max_y` | The maximum Y-value of the [spatial reference system]({% link {{ page.version.version }}/architecture/glossary.md %}#spatial-reference-system) for the object(s) being covered. This only needs to be set if you are using a custom [SRID]({% link {{ page.version.version }}/architecture/glossary.md %}#srid). | | Derived from SRID bounds, else `(1 << 31) -1`. | | `geometry_min_x` | The minimum X-value of the [spatial reference system]({% link {{ page.version.version }}/architecture/glossary.md %}#spatial-reference-system) for the object(s) being covered. This only needs to be set if the default bounds of the SRID are too large/small for the given data, or SRID = 0 and you wish to use a smaller range (unfortunately this is currently not exposed, but is viewable on ). By default, SRID = 0 assumes `[-min int32, max int32]` ranges. | | Derived from SRID bounds, else `-(1 << 31)`. | diff --git a/src/current/v26.2/hash-sharded-indexes.md b/src/current/v26.2/hash-sharded-indexes.md index 7151690e19b..6c5b6118990 100644 --- a/src/current/v26.2/hash-sharded-indexes.md +++ b/src/current/v26.2/hash-sharded-indexes.md @@ -43,6 +43,20 @@ We recommend doing thorough performance testing of your workload with different {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} +### Shard columns + +By default, CockroachDB hashes all key columns in a hash-sharded index when it computes the shard column. + +If queries usually constrain only the first key column or columns of a multi-column index, set the [`shard_columns` storage parameter]({% link {{ page.version.version }}/with-storage-parameter.md %}#storage-parameter-shard-columns) to hash only that prefix of the index key columns. The value of `shard_columns` must match a prefix of the index key columns. + +This is useful when queries filter on the leading index columns but still need to scan or sort by later index columns within each shard. For example, the following statement hashes only `region`, while keeping `city` and `population` as ordered index columns: + +{% include_cached copy-clipboard.html %} +~~~ sql +> CREATE INDEX idx_region_city ON data_test (region, city, population) + USING HASH WITH (bucket_count = 4, shard_columns = (region)); +~~~ + ### Hash-sharded indexes on partitioned tables You can create hash-sharded indexes with implicit partitioning under the following scenarios: