Meta tags:
description=Oxia: Scalable Metadata and Index storage;

Headings (most frequently used words):

and, rpcs, grpc, api, reference, source, of, truth, services, overview, shard, discovery, routing, oxiaclient, sessions, ephemerals, on, the, wire, oxiaadmin, status, codes, generating, client, stubs, partition, key, override, batched, writes, reads, compare, swap, extended, get, comparisons, go, java, python,

Text of the page (most frequently used words):
the (57), and (30), shard (21), key (21), for (14), proto (14), client (14), stream (13), oxia (12), admin (9), grpc (9), that (9), storage (8), api (8), java (7), #status (7), node (7), leader (7), session (7), delete (7), coordinator (7), sdks (7), keys (7), python (6), not (6), each (6), ephemerals (6), this (6), architecture (6), with (5), are (5), current (5), operation (5), read (5), per (5), rpcs (5), one (5), partition (5), protocol (5), reference (5), protoc (4), from (4), routing (4), getshardassignments (4), ephemeral (4), has (4), get (4), write (4), response (4), carries (4), public (4), request (4), server (4), deletes (4), notifications (4), sessions (4), field (4), requested (4), writes (4), operations (4), writerequest (4), custom (4), batched (4), sequence (4), oxiaclient (4), source (4), metrics (3), configuration (3), schema (3), codes (3), map (3), expected_version_id (3), unexpected_version_id (3), only (3), split (3), hash (3), namespaces (3), purpose (3), rpc (3), oxiaadmin (3), every (3), putrequest (3), wire (3), range (3), single (3), within (3), puts (3), ranges (3), clients (3), reads (3), open (3), new (3), any (3), port (3), namespace (3), cli (3), application (3), replication (3), page (3), documentation (3), 2026 (2), policies (2), java_out (2), src (2), main (2), paths (2), source_relative (2), generating (2), stubs (2), example (2), when (2), put (2), expired (2), been (2), closed (2), session_does_not_exist (2), match (2), versionid (2), service (2), implemented (2), optional (2), explicit (2), point (2), enumerate (2), nodes (2), their (2), internal (2), must (2), before (2), closesession (2), keepalive (2), create (2), heartbeat (2), record (2), createsessionrequest (2), exact (2), matches (2), lowest (2), strictly (2), highest (2), into (2), round (2), trip (2), extended (2), comparisons (2), expose (2), separate (2), value (2), all (2), compare (2), swap (2), order (2), types (2), its (2), without (2), official (2), buffers (2), records (2), under (2), prefix (2), values (2), kept (2), backward (2), writeresponse (2), streaming (2), discover (2), mapping (2), shardassignmentsrequest (2), local (2), override (2), change (2), route (2), assignment (2), message (2), xxhash3 (2), connect (2), common (2), discovery (2), typical (2), services (2), overview (2), live (2), truth (2), developers (2), light (2), benchmarks (2), consensus (2), maelstrom (2), tla (2), safety (2), correctness (2), physical (2), logical (2), design (2), goals (2), security (2), bare (2), metal (2), resources (2), helm (2), kubernetes (2), deployment (2), versioning (2), secondary (2), indexes (2), sorting (2), consistency (2), model (2), features (2), migrating (2), etcd (2), getting (2), started (2), what (2), blog (2), ctrl (2), copyright, 2023, series, projects, llc, website, terms, use, trademark, policy, other, project, please, see, https, lfprojects, org, last, updated, july, grpc_python_out, python_out, grpc_tools, grpc_opt, grpc_out, go_opt, go_out, vendor, files, repository, add, submodule, run, language, plugin, your, choice, standard, returned, transport, connection, level, errors, reaches, target, consume, refresh, case, failed_precondition, referenced, did, targeted, does, exist, key_not_found, succeeded, meaning, manually, splitshardresponse, splitshardrequest, splitshard, addresses, listnodesresponse, listnodesrequest, listnodes, configured, listnamespacesresponse, listnamespacesrequest, listnamespaces, messages, arrive, elapses, timeout, bound, emits, affected, key_deleted, session_timeout_ms, needs, more, than, independently, relevant, rejected, session_id, non, include, matched, getresponse, higher, lower, ceiling, floor, default, equal, behaviour, keycomparisontype, turns, lookup, getrequest, comparison_type, mismatch, returns, omitting, yields, unconditional, sentinel, maps, specific, reserved, expectedrecordnotexists, same, deleterequest, succeed, support, optimistic, concurrency, applied, positional, type, processed, bundles, independent, own, can, fail, affecting, others, option, few, milliseconds, flushing, which, chasing, throughput, should, replicate, batchlinger, close, closesessionresponse, closesessionrequest, keepaliveresponse, sessionheartbeat, createsessionresponse, createsession, cdc, modify, events, notificationbatch, notificationsrequest, getnotifications, subscribe, assignments, getsequenceupdatesresponse, getsequenceupdatesrequest, getsequenceupdates, rangescanresponse, rangescanrequest, rangescan, excluded, start, end, listresponse, listrequest, list, streams, back, chunks, readresponse, readrequest, deprecated, unary, form, above, compatibility, bidirectional, preferred, entry, writestream, track, shardassignments, corresponding, side, overrides, hashes, instead, forces, related, onto, guarantees, apply, require, partition_key, move, update, retries, delivers, string, host, send, pick, whose, covers, currently, routers, may, added, later, namespaceshardsassignment, shardkeyrouter, int32hashrange, hold, lifetime, contains, delta, full, call, job, hide, keep, correct, most, bugs, hand, rolled, topology, through, traffic, goes, operators, introspection, code, sequences, caller, package, compatible, changes, protocols, between, they, carry, implementation, details, notice, depend, these, administrative, facing, authoritative, schemas, tree, defined, served, over, writing, proxy, tool, talks, directly, using, need, wrap, everything, documented, below, scroll, top, edit, github, question, give, feedback, metadata, store, coordination, system, skip, content,

Text of the page (random words):
grpc api reference oxia skip to content oxia metadata store and coordination system documentation blog ctrl k ctrl k documentation what is oxia getting started migrating from zk etcd features consistency model ephemerals namespaces notifications key sorting partition keys secondary indexes sequence keys versioning client sdks go java node js python deployment kubernetes helm resources bare metal security admin operations reference cli configuration schema grpc api metrics architecture design goals logical architecture physical architecture correctness protocol safety tla maelstrom consensus coordinator oxia replication protocol storage benchmarks blog light what is oxia getting started migrating from zk etcd features consistency model ephemerals namespaces notifications key sorting partition keys secondary indexes sequence keys versioning client sdks go java node js python deployment kubernetes helm resources bare metal security admin operations reference cli configuration schema grpc api metrics architecture design goals logical architecture physical architecture correctness protocol safety tla maelstrom consensus coordinator oxia replication protocol storage benchmarks light on this page source of truth services overview shard discovery and routing partition key override oxiaclient rpcs batched writes and reads compare and swap extended get comparisons sessions and ephemerals on the wire oxiaadmin rpcs status codes generating client stubs question give us feedback edit this page on github scroll to top documentation reference grpc api grpc api reference oxia s wire api is defined in protocol buffers and served over grpc this page is for developers writing a custom client a proxy or a tool that talks directly to an oxia server application developers using the official go java or python sdks do not need to read this the sdks wrap everything documented below source of truth the authoritative schemas live in the oxia source tree under common proto client proto application facing api admin proto coordinator administrative api storage proto and replication proto internal protocols between coordinator and storage nodes do not depend on these from a custom client they carry implementation details and change without notice all public types live in the proto package io oxia proto v1 backward compatible changes are kept within the v1 prefix services overview service purpose implemented by typical caller oxiaclient read write notifications sessions sequences every storage node public port application code oxiaadmin namespace and node introspection shard split coordinator operators admin cli typical topology clients connect to any storage node and discover the shard leader mapping through oxiaclient getshardassignments admin traffic is separate and goes to the coordinator shard discovery and routing a custom client has one job the sdks hide keep a current map of shard leader and route each request to the correct leader this is the most common source of bugs in hand rolled clients connect to any storage node on the public grpc port call getshardassignments shardassignmentsrequest namespace the rpc is server streaming hold the stream open for the lifetime of the client each message contains the full current assignment for the namespace not a delta hash each key with xxhash3 and pick the shard whose int32hashrange covers that hash the shardkeyrouter field in namespaceshardsassignment currently has only one value xxhash3 new routers may be added later send the request to the shard s leader a host port string when the assignment stream delivers a new message leader change shard split or shard move update the local map and re route any retries partition key override putrequest partition_key and the corresponding optional field on read side rpcs overrides the routing key the server hashes the partition key instead of the record key this forces related records onto a single shard so shard local guarantees apply sequence keys require it oxiaclient rpcs rpc request response purpose getshardassignments shardassignmentsrequest stream shardassignments discover and track shard leader mapping writestream stream writerequest stream writeresponse bidirectional streaming batched writes puts deletes delete ranges preferred entry point write writerequest writeresponse deprecated unary form of the above kept for backward compatibility read readrequest stream readresponse batched reads response streams back in chunks list listrequest stream listresponse stream keys in a start end range values excluded rangescan rangescanrequest stream rangescanresponse stream keys values in a range getsequenceupdates getsequenceupdatesrequest stream getsequenceupdatesresponse subscribe to new sequence key assignments under a prefix getnotifications notificationsrequest stream notificationbatch cdc stream of create modify delete events for a shard createsession createsessionrequest createsessionresponse open a session for ephemeral records on a shard keepalive sessionheartbeat keepaliveresponse heartbeat an open session closesession closesessionrequest closesessionresponse close a session and delete its ephemerals batched writes and reads writerequest bundles independent puts deletes and delete ranges into a single round trip each operation carries its own per operation status one can fail for example with unexpected_version_id without affecting the others the official sdks expose a batchlinger option that buffers operations for a few milliseconds before flushing which custom clients chasing throughput should replicate operations within a writerequest are applied in positional order within their type and the types are processed in the order puts deletes delete ranges compare and swap all writes support optimistic concurrency putrequest expected_version_id succeed only if the current versionid matches deleterequest expected_version_id same for delete omitting the field yields an unconditional write the sdks expose a separate expectedrecordnotexists sentinel that maps to a specific reserved value a mismatch returns unexpected_version_id in the per operation status extended get comparisons getrequest comparison_type turns a get into a key range lookup in a single round trip keycomparisontype behaviour equal default exact match floor highest key requested key ceiling lowest key requested key lower highest key strictly requested key higher lowest key strictly requested key non exact matches include the matched key in getresponse key sessions and ephemerals on the wire sessions are per shard createsessionrequest carries a shard field a client that needs ephemerals on more than one shard must create one session per shard and heartbeat each independently every putrequest for an ephemeral record carries the relevant session_id if the session has been closed or expired the put is rejected with session_does_not_exist keepalive messages must arrive before session_timeout_ms elapses on timeout or an explicit closesession the server deletes every ephemeral bound to the session and emits key_deleted notifications on the affected shard oxiaadmin rpcs rpc request response purpose listnamespaces listnamespacesrequest listnamespacesresponse enumerate configured namespaces listnodes listnodesrequest listnodesresponse enumerate storage nodes with their public and internal addresses splitshard splitshardrequest splitshardresponse manually split a shard at an optional explicit hash point the admin service is implemented only by the coordinator status codes each write and read response carries a per operation status status meaning ok operation succeeded key_not_found get or delete targeted a key that does not exist unexpected_version_id expected_version_id did not match the current versionid session_does_not_exist put referenced an ephemeral session that has expired or been closed standard grpc status codes are returned by the transport for connection level errors for example failed_precondition when a client reaches a node that is not the current leader for the target shard re consume getshardassignments to refresh the routing map in that case generating client stubs vendor the proto files from the oxia repository or add it as a submodule and run protoc with the language plugin of your choice go java python go protoc go_out go_opt paths source_relative go grpc_out go grpc_opt paths source_relative client proto admin proto java protoc java_out src main java grpc java_out src main java client proto admin proto python python m grpc_tools protoc i python_out grpc_python_out client proto admin proto last updated on july 13 2026 configuration schema metrics copyright 2023 2026 oxia a series of lf projects llc for website terms of use trademark policy and other project policies please see https lfprojects org policies