--- title: "Cluster tablet metadata" url: "https://docs.yugabyte.com/stable/explore/observability/yb-tablet-metadata/" --- # Cluster tablet metadata View cluster-wide tablet distribution and leadership information for YSQL tables. View YSQL cluster-wide tablet metadata and leadership information The `yb_tablet_metadata` view returns tablet placement, leadership, and state for the whole cluster. The examples below look up tablets, leaders, range boundaries, and the tablet that holds a row. Columns, tablet states, and which columns are masked for unprivileged users are listed in [Tablet metadata](/stable/launch-and-manage/monitor-and-alert/tablet-metadata/#yb-tablet-metadata "Tablet metadata"). ## Examples Before you start The examples will run on any YugabyteDB universe. To create and connect to a universe, see [Set up YugabyteDB universe](/stable/explore/cluster-setup-local/). Because this view is accessible via YSQL, run your examples using [ysqlsh](/stable/api/ysqlsh/#starting-ysqlsh "ysqlsh"). ### Select nodes for a particular table To find all tablets, their leaders, and replicas for a specific table: ```sql SELECT * FROM yb_tablet_metadata WHERE db_name = 'yugabyte' AND relname = 'test_table'; ``` ```output +----------------------------------+-------+----------+-------------+-----------------+---------------+------------------+--------------------------------------------------------+ | tablet_id | oid | db_name | relname | start_hash_code | end_hash_code | leader | replicas | |----------------------------------+-------+----------+-------------+-----------------+---------------+------------------+--------------------------------------------------------| | 3987b6a16bf94fbd92262744197350d7 | 16384 | yugabyte | test_table | 0 | 10922 | 127.0.0.2:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | | dd50b59c7dcb493680093ffa5b195634 | 16384 | yugabyte | test_table | 10922 | 21845 | 127.0.0.1:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | | bed5b3c3eee747e99622a4e21acf437a | 16384 | yugabyte | test_table | 21845 | 32768 | 127.0.0.3:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | | da4bad5faa9f448f890cce57c775cd94 | 16384 | yugabyte | test_table | 32768 | 43690 | 127.0.0.2:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | | 52176c704c614846bbd80f481678519e | 16384 | yugabyte | test_table | 43690 | 54613 | 127.0.0.1:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | | ea252119fe774ba9bdc585504fae9398 | 16384 | yugabyte | test_table | 54613 | 65536 | 127.0.0.3:5433 | ['127.0.0.1:5433', '127.0.0.2:5433', '127.0.0.3:5433'] | +----------------------------------+-------+----------+-------------+-----------------+---------------+------------------+--------------------------------------------------------+ ``` ### Join with yb\_servers You can join `yb_tablet_metadata` with [`yb_servers()`](/stable/api/ysql/exprs/func_yb_servers/ "yb_servers()") to find infrastructure details (cloud, region, zone) for the tablet leader. ```sql SELECT ytm.tablet_id, ytm.oid, ytm.db_name, ytm.relname, ytm.start_hash_code, ytm.end_hash_code, ys.host, ys.port, ys.cloud, ys.region, ys.zone, ys.uuid as server_uuid, ys.universe_uuid FROM yb_tablet_metadata ytm JOIN yb_servers() ys ON split_part(ytm.leader, ':', 1) = ys.host AND split_part(ytm.leader, ':', 2)::int = ys.port ORDER BY ytm.start_hash_code; ``` ```output +----------------------------------+-------+----------+------------+-----------------+---------------+-----------+------+--------+-------------+-------+----------------------------------+--------------------------------------+ | tablet_id | oid | db_name | relname | start_hash_code | end_hash_code | host | port | cloud | region | zone | server_uuid | universe_uuid | |----------------------------------+-------+----------+------------+-----------------+---------------+-----------+------+--------+-------------+-------+----------------------------------+--------------------------------------+ | 3987b6a16bf94fbd92262744197350d7 | 16384 | yugabyte | test_table | 0 | 10922 | 127.0.0.2 | 5433 | cloud1 | datacenter1 | rack1 | 0e7b350cc6db42c3a5f0fde35352700f | 68a94218-f52d-428d-b95b-f98122d19035 | | dd50b59c7dcb493680093ffa5b195634 | 16384 | yugabyte | test_table | 10922 | 21845 | 127.0.0.1 | 5433 | cloud1 | datacenter1 | rack1 | 228be93b9b164d8c99dc775e4acc805f | 68a94218-f52d-428d-b95b-f98122d19035 | | bed5b3c3eee747e99622a4e21acf437a | 16384 | yugabyte | test_table | 21845 | 32768 | 127.0.0.3 | 5433 | cloud1 | datacenter1 | rack1 | ad618d063e2f4980bb3bc74a1a296565 | 68a94218-f52d-428d-b95b-f98122d19035 | | da4bad5faa9f448f890cce57c775cd94 | 16384 | yugabyte | test_table | 32768 | 43690 | 127.0.0.2 | 5433 | cloud1 | datacenter1 | rack1 | 0e7b350cc6db42c3a5f0fde35352700f | 68a94218-f52d-428d-b95b-f98122d19035 | | 52176c704c614846bbd80f481678519e | 16384 | yugabyte | test_table | 43690 | 54613 | 127.0.0.1 | 5433 | cloud1 | datacenter1 | rack1 | 228be93b9b164d8c99dc775e4acc805f | 68a94218-f52d-428d-b95b-f98122d19035 | | ea252119fe774ba9bdc585504fae9398 | 16384 | yugabyte | test_table | 54613 | 65536 | 127.0.0.3 | 5433 | cloud1 | datacenter1 | rack1 | ad618d063e2f4980bb3bc74a1a296565 | 68a94218-f52d-428d-b95b-f98122d19035 | +----------------------------------+-------+----------+------------+-----------------+---------------+-----------+------+--------+-------------+-------+----------------------------------+--------------------------------------+ ``` ### Find a tablet for a given key in hash-sharded tables Use the [yb\_hash\_code()](/stable/api/ysql/exprs/func_yb_hash_code/ "yb_hash_code()") function to find the `tablet_id` and leader node for a given key in hash-sharded tables. 1. Check the table structure: ```sql \d test_table ``` ```output +--------+------------------+-----------+ | Column | Type | Modifiers | |--------+------------------+-----------+ | a | text | not null | | b | integer | | | c | double precision | | +--------+------------------+-----------+ Indexes: "test_table_pkey" PRIMARY KEY, lsm (a HASH) ``` Note that `a` is the only primary key. 2. Get the hash code for a specific key: ```sql SELECT *, yb_hash_code(a) FROM test_table WHERE a = 'k1'; ``` ```output +----------+------+------+--------------+ | a | b | c | yb_hash_code | |----------+------+------+--------------+ | k1 | 2016 | 10.2 | 8000 | +----------+------+------+--------------+ ``` 3. Query `yb_tablet_metadata` to find which tablet this key belongs to: ```sql SELECT yb_hash_code('k1'::text) as hash_code, t.tablet_id, t.start_hash_code, t.end_hash_code, t.leader FROM yb_tablet_metadata t WHERE t.relname = 'test_table' AND yb_hash_code('k1'::text) >= t.start_hash_code AND yb_hash_code('k1'::text) < t.end_hash_code; ``` ```output +-----------+----------------------------------+-----------------+---------------+----------------+ | hash_code | tablet_id | start_hash_code | end_hash_code | leader | |-----------+----------------------------------+-----------------+---------------+----------------| | 8000 | 6e60770b44ad49489ccb6949b8131c0e | 0 | 10922 | 127.0.0.3:5433 | +-----------+----------------------------------+-----------------+---------------+----------------+ ``` 4. To find the `tablet_id` for all rows of the table, use the following query: ```sql SELECT tt.a, tt.b, tt.c, yb_hash_code(tt.a) as hash_code, ytm.tablet_id, ytm.start_hash_code, ytm.end_hash_code, ytm.leader FROM test_table tt JOIN yb_tablet_metadata ytm ON yb_hash_code(tt.a) >= ytm.start_hash_code AND yb_hash_code(tt.a) < ytm.end_hash_code ORDER BY tt.a; ``` ```output +----------------------------------+------+-------+-----------+----------------------------------+-----------------+---------------+----------------+ | a | b | c | hash_code | tablet_id | start_hash_code | end_hash_code | leader | |----------------------------------+------+-------+-----------+----------------------------------+-----------------+---------------+----------------| | github.com/yugabyte/yugabyte-db/ | 2020 | 108.2 | 58057 | 78c89b1113cf4f3ea1cd439851804ce1 | 54613 | 65536 | 127.0.0.3:5433 | | yb | 2020 | 108.2 | 5962 | 6e60770b44ad49489ccb6949b8131c0e | 0 | 10922 | 127.0.0.1:5433 | | ybdb | 2020 | 108.2 | 44116 | 6df5e7b1746b4c2b97bada5d49e5083a | 43690 | 54613 | 127.0.0.2:5433 | | yugabyte | 2016 | 10.2 | 8000 | 6e60770b44ad49489ccb6949b8131c0e | 0 | 10922 | 127.0.0.1:5433 | | yugabytedb | 2016 | 10.2 | 30096 | 97b6f53d462b4c2381a19f6285e4779e | 21845 | 32768 | 127.0.0.2:5433 | +----------------------------------+------+-------+-----------+----------------------------------+-----------------+---------------+----------------+ ``` Get hash codes in YCQL To obtain hash codes in YCQL, you can use the `partition_hash()` function, which, similar to `yb_hash_code()`, also dumps hash codes. You can use the `partition_hash()` function in YCQL to link rows with their tablets. ### View range boundaries for range-sharded tables For range-sharded tables, the `start_range` and `end_range` columns show the range boundaries for each tablet. These columns are NULL for hash-sharded tables. ```sql SELECT tablet_id, relname, start_range, end_range, leader FROM yb_tablet_metadata WHERE relname = 'range_sharded_table' ORDER BY start_range; ``` ### Check tablet state Use `tablet_state` to monitor tablet lifecycle. For example, to confirm that tablets for a table have finished creating and are serving traffic, or to find tablets that are stuck in a non-running state. To list the state of every tablet for a table: ```sql SELECT tablet_id, relname, tablet_state, leader FROM yb_tablet_metadata WHERE relname = 'test_table' ORDER BY tablet_state, tablet_id; ``` ```output +----------------------------------+------------+--------------+----------------+ | tablet_id | relname | tablet_state | leader | |----------------------------------+------------+--------------+----------------| | 3987b6a16bf94fbd92262744197350d7 | test_table | RUNNING | 127.0.0.2:5433 | | 52176c704c614846bbd80f481678519e | test_table | RUNNING | 127.0.0.1:5433 | | bed5b3c3eee747e99622a4e21acf437a | test_table | RUNNING | 127.0.0.3:5433 | | da4bad5faa9f448f890cce57c775cd94 | test_table | RUNNING | 127.0.0.2:5433 | | dd50b59c7dcb493680093ffa5b195634 | test_table | RUNNING | 127.0.0.1:5433 | | ea252119fe774ba9bdc585504fae9398 | test_table | RUNNING | 127.0.0.3:5433 | +----------------------------------+------------+--------------+----------------+ ``` To find tablets that are not yet (or no longer) running: ```sql SELECT db_name, relname, tablet_id, tablet_state FROM yb_tablet_metadata WHERE tablet_state <> 'RUNNING'; ``` ### Join with Active Session History For TServer events tied to a tablet, join [`yb_active_session_history`](/stable/launch-and-manage/monitor-and-alert/active-session-history-monitor/#yb-active-session-history "yb_active_session_history") with `yb_tablet_metadata` on `wait_event_aux = SUBSTRING(tablet_id, 1, 15)` to get metadata for the tablet referenced in `wait_event_aux`. ```sql SELECT tablet_id, db_name, relname, start_hash_code, end_hash_code, wait_event, wait_event_component, wait_event_type, COUNT(*) FROM yb_active_session_history JOIN yb_tablet_metadata ON wait_event_aux = SUBSTRING(tablet_id, 1, 15) GROUP BY tablet_id, db_name, relname, start_hash_code, end_hash_code, wait_event, wait_event_component, wait_event_type ORDER BY relname, count DESC; ``` ```output +----------------------------------+----------+------------------+-----------------+---------------+------------------------------------+----------------------+-----------------+-------+ | tablet_id | db_name | relname | start_hash_code | end_hash_code | wait_event | wait_event_component | wait_event_type | count | |----------------------------------+----------+------------------+-----------------+---------------+------------------------------------+----------------------+-----------------+-------+ | dfc98983540e4b98b4e3b39041f65ab3 | yugabyte | idx_test_table_b | 32768 | 65536 | Raft_ApplyingEdits | TServer | Cpu | 3 | | dc151ee1a59745d69201290307862b7d | yugabyte | idx_test_table_b | 0 | 32768 | Raft_ApplyingEdits | TServer | Cpu | 2 | | dc151ee1a59745d69201290307862b7d | yugabyte | idx_test_table_b | 0 | 32768 | ConflictResolution_ResolveConficts | TServer | RPCWait | 2 | | dc151ee1a59745d69201290307862b7d | yugabyte | idx_test_table_b | 0 | 32768 | OnCpu_Active | TServer | Cpu | 2 | | dfc98983540e4b98b4e3b39041f65ab3 | yugabyte | idx_test_table_b | 32768 | 65536 | OnCpu_Active | TServer | Cpu | 2 | | dfc98983540e4b98b4e3b39041f65ab3 | yugabyte | idx_test_table_b | 32768 | 65536 | ConflictResolution_ResolveConficts | TServer | RPCWait | 2 | | 1f7aee0ceea445959129b23285756dad | yugabyte | idx_test_table_c | 0 | 32768 | Raft_ApplyingEdits | TServer | Cpu | 20 | | b6eea846ecd9433f89ea7ccaadff8cec | yugabyte | idx_test_table_c | 32768 | 65536 | Raft_ApplyingEdits | TServer | Cpu | 19 | | 1f7aee0ceea445959129b23285756dad | yugabyte | idx_test_table_c | 0 | 32768 | OnCpu_Active | TServer | Cpu | 19 | | b6eea846ecd9433f89ea7ccaadff8cec | yugabyte | idx_test_table_c | 32768 | 65536 | OnCpu_Active | TServer | Cpu | 19 | | 1f7aee0ceea445959129b23285756dad | yugabyte | idx_test_table_c | 0 | 32768 | ConflictResolution_ResolveConficts | TServer | RPCWait | 10 | | b6eea846ecd9433f89ea7ccaadff8cec | yugabyte | idx_test_table_c | 32768 | 65536 | ConflictResolution_ResolveConficts | TServer | RPCWait | 10 | | 1f7aee0ceea445959129b23285756dad | yugabyte | idx_test_table_c | 0 | 32768 | OnCpu_Passive | TServer | Cpu | 1 | | b6eea846ecd9433f89ea7ccaadff8cec | yugabyte | idx_test_table_c | 32768 | 65536 | OnCpu_Passive | TServer | Cpu | 1 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | OnCpu_Passive | TServer | Cpu | 83 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | OnCpu_Passive | TServer | Cpu | 83 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | OnCpu_Active | TServer | Cpu | 51 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | OnCpu_Active | TServer | Cpu | 49 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | Raft_ApplyingEdits | TServer | Cpu | 34 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | Raft_ApplyingEdits | TServer | Cpu | 33 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | ConflictResolution_ResolveConficts | TServer | RPCWait | 15 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | ConflictResolution_ResolveConficts | TServer | RPCWait | 14 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | WAL_Append | TServer | DiskIO | 2 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | Rpc_Done | TServer | WaitOnCondition | 1 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | Raft_WaitingForReplication | TServer | RPCWait | 1 | | c853133c0db445928ae1262c01238d2d | yugabyte | test_table | 32768 | 65536 | RocksDB_NewIterator | TServer | DiskIO | 1 | | 99ed7472ccde4af787cb0bcfd4fd90bd | yugabyte | test_table | 0 | 32768 | RocksDB_NewIterator | TServer | DiskIO | 1 | +----------------------------------+----------+------------------+-----------------+---------------+------------------------------------+----------------------+-----------------+-------+ ```