CONCEPT Cited by 1 source

Keyspace ID¶

A Keyspace ID is Vitess's shard-address identifier — a binary(8) value per row that tells VTGate which physical shard the row lives on. It is the output of a Vindex lookup and the input to the query router.

Schema¶

Every sharded table in Vitess has an implicit keyspace_id per row; lookup-Vindex tables materialise it explicitly as a column:

NAME_USER_VDX:
+------+-----+--------------------------+
| name | id  | keyspace_id              |
+------+-----+--------------------------+
| Alex | 100 | 0x313030                 |
| Emma | 200 | 0x323030                 |
+------+-----+--------------------------+

(Source: sources/2026-04-21-planetscale-achieving-data-consistency-with-the-consistent-lookup-vindex)

Role in query routing¶

VTGate's query planner takes an incoming SQL statement, finds a predicate that matches a Vindex, looks up the keyspace_id, and forwards the query to the one VTTablet that owns the shard containing that keyspace_id. Without a matching Vindex, the query fans out to all shards (scatter-gather). The entire point of Vindexes is to translate a user-visible column value into a keyspace_id so the router can avoid scatter-gather.

8-byte opaque binary¶

The type is binary(8) — Vitess treats keyspace_id as opaque bytes, not an integer or hash. The concrete bytes are produced by the Primary Vindex function (hash-based Primary Vindexes produce them via a hash of the sharding column; functional Vindexes use other deterministic mappings). Range-based sharding assigns each shard a contiguous keyspace_id range.

Stability across rows¶

For a given Primary Vindex, the keyspace_id for a row is stable — the same id always hashes to the same keyspace_id. This is what lets lookup Vindex tables materialise the mapping: the keyspace_id stored in name_user_vdx stays valid for the lifetime of the row.

Seen in¶

sources/2026-04-21-planetscale-achieving-data-consistency-with-the-consistent-lookup-vindex — canonical wiki introduction of keyspace_id as an 8-byte opaque shard address + its role as the Vindex output + lookup-table schema.