Zones
In a KWDB cluster, each data range belongs to a specific replica zone. When rebalancing data ranges in a cluster, the system considers zone configurations to ensure all constraints are met.
When being initiated, KWDB automatically generates pre-configured zones and the default zone. Pre-configured zones are suitable for internal system data while the default zone applies to other data in the cluster. You can use or adjust these zones, or set zones separately for specified databases, tables, or partitions.
SHOW ZONE CONFIGURATION
The SHOW ZONE CONFIGURATION statement shows details about zones of a specified object. The SHOW ZONE CONFIGURATIONS and SHOW ALL ZONE CONFIGURATIONS statements show all system ranges of a KWDB cluster or details about replicas of the system database and system table.
Privileges
N/A
Syntax
Show details about zones of the specified range, partition, database, or table
SHOW ZONE CONFIGURATION FOR [RANGE <range_name> | DATABASE <database_name> | TABLE <table_name> | PARTITION <partition_name> OF TABLE <table_name> ];Show details about all zones
SHOW [ALL] ZONE CONFIGURATIONS;
Parameters
| Parameter | Description |
|---|---|
range_name | The name of the data range, including: - default: default replica settings - meta: location information for all data - liveness: information about which nodes are live at any given time - system: information needed to allocate new table IDs and track the status of cluster nodes - timeseries: cluster monitoring data |
database_name | The name of the database. |
table_name | The name of the table. |
partition_name | The name of the partition. |
Examples
Check details about zones for a system range.
SHOW ZONE CONFIGURATION FOR RANGE default;If you succeed, you should see an output similar to the following:
target | raw_config_sql ----------------+------------------------------------------- RANGE default | ALTER RANGE default CONFIGURE ZONE USING | range_min_bytes = 268435456, | range_max_bytes = 536870912, | gc.ttlseconds = 90000, | num_replicas = 3, | constraints = '[]', | lease_preferences = '[]' (1 row)Check details about zones for a database.
SHOW ZONE CONFIGURATION FOR DATABASE db1;If you succeed, you should see an output similar to the following:
target | config_sql ---------------+------------------------------------------ DATABASE db1 | ALTER DATABASE db1 CONFIGURE ZONE USING | range_min_bytes = 1048576, | range_max_bytes = 8388608, | gc.ttlseconds = 100000, | num_replicas = 5, | constraints = '[]', | lease_preferences = '[]' (1 row)Check details about zones for a table.
SHOW ZONE CONFIGURATION FOR TABLE t1;If you succeed, you should see an output similar to the following:
target | raw_config_sql ----------------+------------------------------------------- RANGE default | ALTER RANGE default CONFIGURE ZONE USING | range_min_bytes = 268435456, | range_max_bytes = 536870912, | gc.ttlseconds = 90000, | num_replicas = 3, | constraints = '[]', | lease_preferences = '[]' (1 row)
CONFIGURE ZONE
The ALTER ... CONFIGURE ZONE statement modifies or removes zones for a database, table, range or partition.
Privileges
Modify zones for the system database or system range: the user must be a member of the
adminrole. By default, therootuser belongs to theadminrole.Modify zones for other databases or ranges/tables in other databases: the user must be a member of the
adminrole or have been grantedCREATEorZONECONFIGprivileges on the specified object(s).
Syntax
ALTER [DATABASE <database_name> | TABLE <table_name> | RANGE <range_name> | PARTITION <partition_name> OF TABLE <table_name> ] CONFIGURE ZONE [USING <variable> = [COPY FROM PARENT | <value>], <variable> = [<value> | COPY FROM PARENT], ... | DISCARD];
Parameters
| Parameter | Description |
|---|---|
range_name | The name of the range to modify, including: - default: default replica settings - meta: location information for all data - liveness: information about which nodes are live at any given time - system: information needed to allocate new table IDs and track the status of cluster nodes - timeseries: cluster monitoring data |
database_name | The name of the database to modify. |
table_name | The name of the table to modify. |
partition_name | The name of the table partition to modify. |
variable | The name of the variable to modify. The following variables are supported: - range_min_bytes: the minimum size in bytes for a data range. When a range is smaller than this value, KWDB merges it with an adjacent range. Default: 256 MiB. The value must be greater than 1 MiB (1048576 bytes) and smaller than the maximum size of the range. - range_max_bytes: the maximum size in bytes for a data range. When a range exceeds this value, KWDB splits it into two ranges. Default: 512 MiB. The value must not be smaller than 5 MiB (5242880 bytes). - gc.ttlseconds: the number of seconds data will be retained before garbage collection. Default: 90000 (25 hours). We recommend setting a value of at least 600 seconds (10 minutes) to avoid affecting long-running queries. A smaller value saves disk space while a larger value increases the time range allowed for AS OF SYSTEM TIME queries. Additionally, since all versions of each row are stored in a single, unsplit range, avoid setting this value too large to prevent all changes to a single row from exceeding 64 MiB, which may cause memory issues or other problems. - num_replicas: the number of replicas. Default: 3. For the system database and the meta, liveness, and system ranges, the default number of replicas is 5. Note: The number of replicas cannot be reduced when unavailable nodes exist in the cluster. - constraints: required (+) and/or prohibited (-) constraints for where replicas can be placed. For example, constraints = '{"+region=NODE1": 1, "+region=NODE2": 1, "+region=NODE3": 1}' places one replica on each of nodes 1, 2, and 3. Currently only supports the region=NODEx format. - lease_preferences: an ordered list of required (+) and/or prohibited (-) constraints for where the leaseholder should be placed. For example, lease_preferences = '[[+region=NODE1]]' prefers placing the leaseholder on node 1. If this isn't possible, KWDB tries the next preference in the list. If no preferences can be satisfied, KWDB uses the default lease distribution algorithm, which balances leases across nodes based on their current lease count. Each value in the list can contain multiple constraints. - ts_merge.days: the merging time for time-series data ranges. After ranges in the same time-series table at the same hash point are split by timestamp, ranges that exceed this time are automatically merged and won't be automatically split again. Default: 10 (10 days). The value must be greater than or equal to 0. When set to 0, time-series data ranges are automatically merged immediately after being split by timestamp. If network or other failures are caused by too many system ranges, you can reduce this value to mitigate data volume issues. Tips: - lease_preferences can be defined independently from the constraints field. - When setting constraints, you must also set num_replicas, and the number of constraints must be less than or equal to the number of replicas. The order of constraints doesn't matter. - By default, KWDB only splits ranges based on hash points, so the range merging by time is disabled by default. To support merging ranges by time, set the kv.kvserver.ts_split_interval runtime parameter to 1 and the kv.kvserver.ts_split_by_timestamp.enabled runtime parameter to true to enable splitting ranges by both hash points and timestamps. |
value | The value of the variable. |
COPY FROM PARENT | Use the settings of the parent zone. |
DISCARD | Remove the zone configuration and use the default values. |
Examples
Modify zones for a database.
ALTER DATABASE vtx CONFIGURE ZONE USING num_replicas = 5, gc.ttlseconds = 100000; CONFIGURE ZONE 1 SHOW ZONE CONFIGURATION FOR DATABASE vtx; target | config_sql ----------------+------------------------------------------- DATABASE vtx | ALTER DATABASE tsdb CONFIGURE ZONE USING | range_min_bytes = 134217728, | range_max_bytes = 536870912, | gc.ttlseconds = 100000, | num_replicas = 5, | constraints = '[]', | lease_preferences = '[]' (1 row)Modify zones for a table.
ALTER TABLE vehicles CONFIGURE ZONE USING num_replicas = 3, gc.ttlseconds = 100000; CONFIGURE ZONE 1 SHOW ZONE CONFIGURATION FOR TABLE vehicles; target | config_sql ---------------+------------------------------------------ TABLE vehicles | ALTER TABLE vehicles CONFIGURE ZONE USING | range_min_bytes = 268435456, | range_max_bytes = 536870912, | gc.ttlseconds = 100000, | num_replicas = 3, | constraints = '[]', | lease_preferences = '[]' (1 row)Remove zones from a table.
ALTER TABLE vehicles CONFIGURE ZONE DISCARD; CONFIGURE ZONE 1 SHOW ZONE CONFIGURATION FOR TABLE vehicles; target | raw_config_sql ---------------+------------------------------------------- RANGE default | ALTER RANGE default CONFIGURE ZONE USING | range_min_bytes = 268435456, | range_max_bytes = 536870912, | gc.ttlseconds = 90000, | num_replicas = 3, | constraints = '[]', | lease_preferences = '[]' (1 row)