Skip to content
Development documentation for unreleased code on main. Behavior can change before a release. Latest release docs

gRPC APIdev

HTTP is the fastest way to explore Luxir; gRPC is the typed, binary surface for applications that want long-lived bidirectional streams and columnar search results. Both reach the same request and execution model. The Protobuf API reference documents each message, field, enum, and service from the source definitions:

Both files use the luxir package, so services and their request and response types share one namespace (for example, luxir.SearchRequest).

For how SearchRequest, SearchOp, and Query fit together, see Queries and search operations.

The default gRPC port is one greater than the HTTP port: 9401 when HTTP uses 9400. Override it with --server.grpc.port.

Service and method Shape Purpose
luxir.Indexer/Update unary One bounded update request and response.
luxir.Indexer/UpdateStream bidirectional stream A stream of independently acknowledged update requests.
luxir.Searcher/Search bidirectional stream Several search requests per call, with one or more response batches per request.
luxir.Admin/SetSchema unary Set named definitions or replace a collection schema.
luxir.Admin/GetSchema unary Read a collection schema.
luxir.Admin/CreateCollection unary Create a collection, optionally with a schema.
luxir.Admin/DeleteCollection unary Delete a collection and its stored data.
luxir.Admin/Stats unary Read node, tenant or collection statistics (the structured form of HTTP _stats).

The server also registers the standard gRPC health service and descriptor reflection. Luxir implements the application services through gRPC’s generic byte transport, so the stock reflection plugin can resolve known symbols but does not currently enumerate those services in ListServices. Ask for a known symbol directly when using a reflection client.

Compile both protobuf files with the standard gRPC generator for your language. For C++ the shape is:

Terminal window
mkdir -p generated
protoc -I protos \
--cpp_out=generated \
--grpc_out=generated \
--plugin=protoc-gen-grpc="$(command -v grpc_cpp_plugin)" \
protos/luxir_types.proto protos/luxir.proto

Use the equivalent grpc_tools.protoc, Gradle, Go, Rust, or other language plugin for your client. Luxir does not yet publish packaged generated clients.

Reflection can inspect a known service without local proto files:

Terminal window
grpcurl -plaintext localhost:9401 describe luxir.Searcher

Searcher.Search is bidirectional. A client can keep one call open and send several SearchRequest messages. Each request may produce several SearchResponse messages when a document list is batched; more tells the client another response belongs to the same logical request. Set request_id when several requests share a call and use the echoed value for correlation. The final response of each request carries took_us, the server-side wall time in microseconds from receipt of the complete request message until its final response is ready to serialize. It includes parsing, any min_commit wait, execution, and earlier streamed batches, including any pause while the client reads them. It excludes serializing, queueing, and sending the final response.

One request contains:

  • collection: the target collection.
  • ops: named top_docs, fusion, facet, range-facet, or metric operations.
  • freshness_ms and time_zone: request-level view/date controls.
  • profile: include instrumented per-segment execution details on the final response; string field facets are currently instrumented.
  • max_parallel: 0 (the default) adaptively uses idle cores after earning work credit; 1 and -2 run serially on an arena worker; -1 publishes every sibling regardless of credit and load. Other values are rejected. Every gRPC search starts on an arena worker, keeping completion queues available for other calls on the same HTTP/2 connection. The adaptive grain is --search.fanout-grain-us (default 50 us); -1 pins 0 to serial execution. --search.fanout-sibling-grain-us sets the minimum share with only idle SMT siblings (default 1000 us); -1 disables publication in that tier.

Unlike HTTP, gRPC does not have the root top_docs shorthand. Populate the ops map explicitly. It also does not use HTTP’s document-line response_format=docs; gRPC messages are already framed.

Returned documents default to DocFormat.COLUMNS. DocList.row_count is the authoritative number of rows. Each dense column has that many slots and its type-specific missing sentinel identifies absent values. DocList.docs contains per-row maps for the fields placed in rows. A document row is the merge of columns[i] and docs[i]; a field name never appears in both.

document_format (on TopDocs or Fusion) chooses where each returned field lands:

  • ROWS: every field in docs.
  • COLUMNS: every field as a dense column, which decodes far faster in clients than a map of oneofs per document. A field type with no typed column arm comes back as col_val, one Val per document. Explicitly named fields are present in every batch. Fields returned by an empty or wildcard fields selector (“discovered” fields) are left out of a batch in which no document has a value, so the set of discovered columns can vary between batches.
  • ADAPTIVE: per batch and field, whichever placement encodes the batch more compactly: a field present in few of the batch’s documents goes to docs, a dense one stays a column, and a field with no value in the batch is left out. The choice is a heuristic, not a contract: the column set varies per batch, and a named field may be in docs or absent. _score_ is always a column.

Treat each batch’s columns keys as authoritative and merge docs[i] into row i.

Indexer.UpdateStream accepts a series of UpdateRequest messages and returns one UpdateResponse for each. Each message has its own overwrite, atomicity, return-ID, and commit settings; all-or-none never spans messages. request_id is echoed so responses can be associated without depending on completion timing. Responses may complete out of request order. Each response’s took_us is the server-side wall time in microseconds from receipt of its complete request message until the response is ready to serialize, including parsing and any commit and replica wait. It excludes serializing, queueing, and sending the response.

Send documents through the repeated docs row maps. Row maps use the field coercion, update, and commit semantics described in Indexing.

Each received message, a unary request or one message of a stream, is limited to --server.grpc.max-receive-message-size, which defaults to --indexing.max-request-body (32 MiB). A larger message is rejected before it is decoded: the call ends with RESOURCE_EXHAUSTED and a message naming both sizes, and nothing in it is applied. Batch documents so each UpdateRequest stays below the limit, or send many messages over Indexer.UpdateStream; there is no limit on the number of messages in a stream. See Operating Luxir.

A unary method fails with a gRPC status whose code follows the error’s kind: INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, FAILED_PRECONDITION, RESOURCE_EXHAUSTED, UNAVAILABLE, or INTERNAL. The status message is the human detail, and the status details (grpc-status-details-bin) carry a google.rpc.Status whose single detail is the luxir.Error message, so a generated client reads the stable code and kind without parsing text.

Streaming methods report a failure of an accepted request in-band with the same Error message: SearchResponse.error (the response then carries no ops, declared warnings still ride along, and every earlier batch of that request is invalidated) and UpdateResponse.error for a request-level update failure, with per-document failures in UpdateResponse.errors[].error and total_errors counting them. request_id is echoed on both. A message that cannot be accepted at all ends the call with a status instead: one that does not decode, a search asking for the HTTP-only docs format, or an update whose collection cannot be resolved. Responses already accepted are still delivered before that status. The kinds, codes, and their meanings are transport-independent; see HTTP API conventions for the table.

SearchRequest and the SearchOp wrapper carry uint64 flags and uint64 flags_set. Starting from request defaults of 0, resolve each level as:

effective = (inherited & ~flags_set) | (flags & flags_set)

Subops inherit their parent’s effective word. The date mode occupies bits 0-1: 0 is native, 1 is iso, 2 is ms, and 3 is ns. To override it, set flags_set = 3 and put the mode value in flags. Explicit native uses flags = 0, flags_set = 3. Setting only one date-mode mask bit is rejected. Bit 2 is int64_str, accepted only on SearchRequest; a SearchOp cannot set or clear it in either word. It affects HTTP JSON rendering only, and binary gRPC responses retain their integer types. Bit 3 is estimate_count: lists in its scope with an unset or positive count_limit may estimate found (see counts). Clearing it on an op stops its subops inheriting it. Bit 4 is decimal_scaled: decimal literals and results use raw scaled units, at request or operation level (see Decimals). Unknown bits are rejected in either word. Bits absent from flags_set have no effect on inheritance.

RequestFlagBit names bit positions, not masks; shift uint64{1} by the position when constructing masks. JSON uses lowercase name arrays instead of the two wire words. See date literal units.

The HTTP JSON accepts shorthands that the protobuf messages do not: a Val is an untagged JSON value, match queries accept field-name sugar, a bare query string means expr, and a root object can stand for one top_docs operation. Generated gRPC clients use the protobuf messages directly, so they set the relevant oneof fields and maps rather than those JSON conveniences.

?explain=request on HTTP shows the canonical request message a shorthand becomes, which is the message a generated client should build.

The configured gRPC port listens on all interfaces with insecure server credentials. There is no built-in TLS, authentication, authorization, or request tenancy layer. Put it behind the same private network, proxy, or service-mesh security boundary as the HTTP port; see Operating Luxir.