Document replication zones for secondary indexes #3818

jseldess · 2018-10-03T19:23:51Z

Fixes #3146.

cockroach-teamcity · 2018-10-03T19:23:56Z

This change is

jseldess · 2018-10-03T19:24:16Z

@a-robinson, I'll apply these changes to the 2.0 version of the doc as well once the content is final.

cockroach-teamcity · 2018-10-03T19:26:12Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/d48e613f58b7bd8bccd11d5382e2e9ad9f2dc79b/

cockroach-teamcity · 2018-10-03T19:34:38Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/2bc7953316ddb507588db7913d604b7daf7cba27/

cockroach-teamcity · 2018-10-03T19:59:16Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ed6ca2debfc0e1558af247abb4cf379bbf25666a/

jseldess · 2018-10-04T14:54:21Z

@a-robinson, just updated the note about what happens when you create a zone for an index, and the index data is stored in a range with table data. @bdarnell mentioned that we always split on zone config boundaries, so if you give the table and index different zone configs they will get split.

cockroach-teamcity · 2018-10-04T14:54:58Z

http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/ac6b90b21c1bdfe15300f7d1eb3cb9aae2d37865/

a-robinson

I tried playing around with the command for setting an index zone config, and found that doing so requires an enterprise license. These docs need to be changed to reflect that.

Reviewed 1 of 2 files at r1, 3 of 3 files at r2.
Reviewable status: complete! 0 of 0 LGTMs obtained

v2.1/configure-replication-zones.md, line 26 at r2 (raw file):

Cluster | CockroachDB comes with a pre-configured `.default` replication zone that applies to all table data in the cluster not constrained by a database, table, or row-specific replication zone. This zone can be adjusted but not removed. See [View the Default Replication Zone](#view-the-default-replication-zone) and [Edit the Default Replication Zone](#edit-the-default-replication-zone) for more details.
Database | You can add replication zones for specific databases. See [Create a Replication Zone for a Database](#create-a-replication-zone-for-a-database) for more details.
Table / Index | You can add replication zones for specific tables and their secondary indexes. See [Create a Replication Zone for a Table](#create-a-replication-zone-for-a-table) and [Create a Replication Zone for a Secondary Index](#create-a-replication-zone-for-a-secondary-index) for more details.<br><br>Each table and its secondary indexes initially map to a single range, where each key-value pair in the range represents a single row in the table (also called the primary index because the table is sorted by the primary key) or a single row in a secondary index. As soon as a range reaches 64 MiB in size, it splits into two ranges. This process continues as the table and its indexes continue growing. Once a table is split across multiple ranges, it's likely that the table and secondary indexes will be stored in separate ranges. However, a range can still contain data for the table and a secondary index. For such a range, defining a replication zone for the index will cause the index data to split into a separate range.

I'd argue that tables and indexes are separate levels of the hierarchy (and thus should be on separate rows of this table). A table zone config will automatically apply to the table's indexes as well.

v2.1/configure-replication-zones.md, line 43 at r2 (raw file):

1. If there's a replication zone for the row, CockroachDB uses it.
2. If there's no applicable row replication zone, CockroachDB uses the table or secondary index replication zone.

If we're really trying to be precise, this would be more like:

If there's no applicable row replication zone and the row is from a secondary index, CockroachDB uses the secondary index replication zone.
If the row isn't from a secondary index index or there is no applicable secondary index replication zone, CockroachDB uses the table replication zone.
...

Your call, though.

v2.1/configure-replication-zones.md, line 135 at r2 (raw file):

# View the replication zone for a table or index:
$ cockroach zone get <database.table|index> <flags>

Is someone supposed to be able to pull the intended syntax out of this? Because the syntax for an index is database.table@index.

v2.1/configure-replication-zones.md, line 378 at r2 (raw file):

{% include copy-clipboard.html %}
~~~ shell
$ cockroach zone set db1.idx1 \

Does db1.idx1 really work? As far as I know indexes have to be specified using db.table@idx, and trying just db.idx isn't working for me locally.

v2.1/configure-replication-zones.md, line 447 at r2 (raw file):

{% include copy-clipboard.html %}
~~~ shell
$ cockroach zone set roachlearn.students_by_list_idx1.australia \

Again, I'm skeptical that this is the correct way of referring to an index partition. Did you test this?

v2.1/configure-replication-zones.md, line 795 at r2 (raw file):

    ~~~

3. Configure a replication zone for each of the table's secondary indexes as well:

This example is actively misleading -- a table's config applies to its indexes automatically as well (as long as they haven't already been customized in their own ways). No need to apply it to all of them individually.

v2.1/architecture/distribution-layer.md, line 43 at r2 (raw file):

For such a range, defining a [replication zone](../configure-replication-zones.html) for the index will cause the index data to split into a separate range.

This is still true, although the fact that defining such a replication zone requires an enterprise license makes mentioning it here less useful. Your call

jseldess

TFTR, @a-robinson. Please take another look.

Reviewable status: complete! 0 of 0 LGTMs obtained

v2.1/configure-replication-zones.md, line 26 at r2 (raw file):