Skip to main content
The SHOW RANGES shows information about the that comprise the data for a table, index, database, or the current catalog. This information is useful for verifying how SQL data maps to underlying , and where the for those ranges are located.
To show range information for a specific row in a table or index, use the statement.

Synopsis

show_ranges syntax diagram

Required privileges

To use the SHOW RANGES statement, a user must either be a member of the role (the root user belongs to the admin role by default) or have the ZONECONFIG defined.

Parameters

ParameterDescription
The name of the you want information about.
The name of the you want information about.
The name of the you want information about.
The options used to configure what fields appear in the response.

Options

The following are available to affect the output. Multiple options can be passed at once, separated by commas.
  • TABLES: List contained per .
  • INDEXES: List contained per .
  • DETAILS: Add size, and other details. Note that this incurs a large computational overhead because it needs to fetch data across nodes.
  • KEYS: Include binary start and end keys.

Response

The specific fields in the response vary depending on the values passed as options. The following fields may be returned:
FieldDescriptionEmitted for option(s)
start\_keyThe start key for the .Always emitted.
end\_keyThe end key for the .Always emitted.
raw\_start\_keyThe start key for the , displayed as a .KEYS
raw\_end\_keyThe end key for the , displayed as a .KEYS
range\_idThe internal ID.Always emitted.
voting\_replicasThe that contain the range’s voting replicas (that is, the replicas that participate in elections).Always emitted.
non\_voting\_replicasThe that contain the range’s .Always emitted.
replicasThe that contain the range’s .Always emitted.
replica\_localitiesThe of the range’s .Always emitted.
range\_sizeThe size of the in bytes.DETAILS
range\_size\_mbThe size of the in MiB.DETAILS
lease\_holderThe that contains the range’s .DETAILS
lease\_holder\_localityThe of the range’s .DETAILS
learner\_replicasThe learner replicas of the range. A learner replica is a replica that has just been added to a range, and is thus in an interim state. It accepts messages but doesn’t vote in elections. This means it doesn’t affect quorum and thus doesn’t affect the stability of the range, even if it’s very far behind.Always emitted.
split\_enforced\_untilThe time a is enforced until. This can be set using using the . Example: 2262-04-11 23:47:16.854776 (this is a default value which means “never”).Always emitted.
schema\_nameThe name of the this holds data for.TABLES, INDEXES
table\_nameThe name of the this holds data for.TABLES, INDEXES
table\_idThe internal ID of the this holds data for.TABLES, INDEXES
table\_start\_keyThe start key of the first that holds data for this table.TABLES
table\_end\_keyThe end key of the last that holds data for this table.TABLES
raw\_table\_start\_keyThe start key of the first that holds data for this table, expressed as .TABLES, KEYS
raw\_table\_end\_keyThe end key of the last that holds data for this table, expressed as .TABLES, KEYS
index\_nameThe name of the this holds data for.INDEXES
index\_idThe internal ID of the this holds data for.INDEXES
index\_start\_keyThe start key of the first of data.INDEXES
index\_end\_keyThe end key of the last of data.INDEXES
raw\_index\_start\_keyThe start key of the first of data, expressed as .INDEXES, KEYS
raw\_index\_end\_keyThe end key of the last of data, expressed as .INDEXES, KEYS
span\_statsA JSON object containing span statistics. For more details, see Span Statistics.DETAILS

Span Statistics

CockroachDB stores all user data in a sorted map of key-value pairs, also known as a keyspace. A span refers to an interval within this keyspace. The SHOW RANGES command emits span statistics when the DETAILS option is specified. The statistics are included in a column named span_stats, as a JSON object. The statistics are calculated for the identifier of each row. For example:
  • SHOW RANGES WITH DETAILS will compute span statistics for each .
  • SHOW RANGES WITH TABLES, DETAILS will compute span statistics for each table.
The span_stats JSON object has the following keys:
KeyDescription
approximate\_disk\_bytesAn approximation of the total on-disk size of the given object, across all (after compression).
key\_countThe number of non-system keys, including live and deleted keys, as well as new, uncommitted keys.
key\_bytesThe total key size (in bytes) of the keys tracked in key\_count.
val\_countThe number of values, or versions, of the keys tracked in key\_count, including deletion tombstones. A key will always have at least one value, but may have several historical values.
val\_bytesTotal value size (in bytes) of the values tracked in val\_count.
sys\_countThe number of system keys, which are not included in key\_count.
sys\_bytesThe total size (in bytes) of the keys in sys\_count and all of their values, or versions.
live\_countThe number of live (committed and non-deleted) non-system keys.
live\_bytesTotal size (in bytes) of the keys tracked in live\_count and their most recent value.
intent\_countThe number of (keys with new, uncommitted values).
intent\_bytesThe total size (in bytes) of the keys tracked in intent\_count and their uncommitted values.

Examples

Setup

The following examples use MovR, a fictional vehicle-sharing application, to demonstrate CockroachDB SQL statements. For more information about the MovR example application and dataset, see . To follow along, run with the --geo-partitioned-replicas flag. This command opens an interactive SQL shell to a temporary, 9-node in-memory cluster with the movr database.

Show ranges for a database

Show ranges for a database (without options)

Show ranges for a database (with tables, keys, details)

Show ranges for a database (with tables)

Show ranges for a database (with indexes)

Show ranges for a database (with details)

Show ranges for a database (with keys)

Show ranges for a table

Show ranges for a table (without options)

Show ranges for a table (with indexes, keys, details)

Show ranges for a table (with indexes)

Show ranges for a table (with details)

Show ranges for a table (with keys)

Show ranges for an index

Show ranges for an index (without options)

Show ranges for an index (with keys, details)

Show ranges for an index (with details)

Show ranges for an index (with keys)

Video Demo

For a deep dive demo on ranges and how data is stored within them, watch the following video:

See also