gRPC API Reference

All services are defined under the laurus.v1 protobuf package.

Services Overview

HealthService

Check

Returns the current serving status of the server.

rpc Check(HealthCheckRequest) returns (HealthCheckResponse);

Response fields:

IndexService

CreateIndex

Create a new index with the given schema. Fails with ALREADY_EXISTS if an index is already open.

rpc CreateIndex(CreateIndexRequest) returns (CreateIndexResponse);

Request fields:

Schema structure:

message Schema {
  map<string, FieldOption> fields = 1;
  repeated string default_fields = 2;
  map<string, AnalyzerDefinition> analyzers = 3;
  map<string, EmbedderConfig> embedders = 4;
  DynamicFieldPolicy dynamic_field_policy = 5;
}

enum DynamicFieldPolicy {
  DYNAMIC_FIELD_POLICY_UNSPECIFIED = 0;
  DYNAMIC_FIELD_POLICY_STRICT = 1;
  DYNAMIC_FIELD_POLICY_DYNAMIC = 2;
  DYNAMIC_FIELD_POLICY_IGNORE = 3;
}

• fields — Field definitions keyed by field name.
• default_fields — Field names used as default search targets when a query does not specify a field.
• analyzers — Custom analyzer pipelines keyed by name. Referenced by TextOption.analyzer.
• embedders — Embedder configurations keyed by name. Referenced by vector field options (HnswOption.embedder, etc.).
• dynamic_field_policy — How the engine treats fields that appear in an ingested document but are absent from fields. UNSPECIFIED is interpreted as DYNAMIC for forward compatibility. See Schema & Fields for the full behaviour matrix and the warning about silent truncation under DYNAMIC.

AnalyzerDefinition:

message AnalyzerDefinition {
  repeated ComponentConfig char_filters = 1;
  ComponentConfig tokenizer = 2;
  repeated ComponentConfig token_filters = 3;
}

ComponentConfig (used for char filters, tokenizer, and token filters):

EmbedderConfig:

Each FieldOption is a oneof with one of the following field types:

The embedder field in vector options specifies the name of an embedder defined in Schema.embedders. When set, the server automatically generates vectors from document text fields at index time. Leave empty to supply pre-computed vectors directly.

Distance metrics: COSINE, EUCLIDEAN, MANHATTAN, DOT_PRODUCT, ANGULAR

Quantization methods: SCALAR_8BIT (default), PRODUCT_QUANTIZATION (Issue #481 Stage 3; supported by the HNSW index — Flat / IVF reject it at write time).

NONE (no quantization) was removed in Issue #481 Stage 1. The proto enum value 0 (QUANTIZATION_METHOD_NONE) is kept as a wire-compat reservation; if the server receives it, it falls back to SCALAR_8BIT via Default::default().

Rerank storage: the optional rerank_storage field (enum RerankStorageKind: UNSPECIFIED = no sidecar, F32) enables the Stage-2 rerank sidecar (Issue #481 / #793). When set to F32 on an HNSW field, commit writes an extra full-precision .hnsw.f32 sidecar so searches that set rerank_factor rescore int8 candidates against the original vectors. Omitting the field (or UNSPECIFIED) keeps Stage-1 int8-only ranking. Since #932 the sidecar is emitted and consumed by all three vector index types (HNSW / Flat / IVF); on Flat/IVF the rescoring applies to field-routed queries.

Shared PQ codebook: the optional pq_codebook_path field on HnswOption (Issue #631) names a storage-relative shared PQ codebook file, trained once via the laurus train pq-codebook CLI command. Segments are then encoded against the pre-trained codebook instead of re-training k-means on every commit and merge. Only meaningful with a PRODUCT_QUANTIZATION quantizer; when set but not yet trained, commits fail with an error naming the training command (no silent fallback to per-segment training). Unset keeps per-segment training.

QuantizationConfig structure:

Example:

{
  "schema": {
    "fields": {
      "title": {"text": {"indexed": true, "stored": true, "term_vectors": true}},
      "embedding": {"hnsw": {"dimension": 384, "distance": "DISTANCE_METRIC_COSINE", "m": 16, "ef_construction": 200}}
    },
    "default_fields": ["title"]
  }
}

GetIndex

Get index statistics.

rpc GetIndex(GetIndexRequest) returns (GetIndexResponse);

Response fields:

Each VectorFieldStats contains vector_count and dimension.

AddField

Add a new field to the running index at runtime.

rpc AddField(AddFieldRequest) returns (AddFieldResponse);

Request fields:

Response fields:

HTTP gateway: POST /v1/schema/fields

DeleteField

Remove a field from the running index schema.

rpc DeleteField(DeleteFieldRequest) returns (DeleteFieldResponse);

Request fields:

Response fields:

Existing indexed data for the field remains in storage but becomes inaccessible. Per-field analyzers and embedders are unregistered.

HTTP gateway: DELETE /v1/schema/fields/{name}

GetSchema

Retrieve the current index schema.

rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse);

Response fields:

DocumentService

PutDocument

Insert or replace a document by ID. If a document with the same ID already exists, it is replaced.

rpc PutDocument(PutDocumentRequest) returns (PutDocumentResponse);

Request fields:

Document structure:

message Document {
  map<string, Value> fields = 1;
}

Each Value is a oneof with these types:

Geo3dPoint:

See 3D Geographic Search (ECEF) for the full coordinate system description and the wgs84_to_ecef / ecef_to_wgs84 conversion utilities.

AddDocument

Add a document. Unlike PutDocument, this does not replace existing documents with the same ID — multiple documents can share an ID (chunking pattern).

rpc AddDocument(AddDocumentRequest) returns (AddDocumentResponse);

Request fields are the same as PutDocument.

PutDocuments

Batched upsert. Entries are applied sequentially, in input order, with one WAL fsync for the whole batch — much faster than one PutDocument call per document. Duplicate IDs within one batch dedup exactly like the same puts issued one by one (the last occurrence wins).

rpc PutDocuments(PutDocumentsRequest) returns (PutDocumentsResponse);

message DocumentEntry {
  string id = 1;
  Document document = 2;
}

message PutDocumentsRequest {
  repeated DocumentEntry documents = 1;
}

message PutDocumentsResponse {
  uint32 applied = 1; // equals the request size on success
}

The call fails fast at the first entry that cannot be applied. Already-applied entries are not rolled back — they are durable at the next commit — and the error status message carries the failing position, its ID, and the applied count, so retrying the batch (or its suffix) is idempotent. A batch that fails on a caller mistake (e.g. a schema violation) returns INVALID_ARGUMENT; storage failures return INTERNAL.

AddDocuments

Batched chunk append. Like PutDocuments but never deletes existing documents, so a batch may legitimately repeat an ID to add multiple chunks of the same logical document.

rpc AddDocuments(AddDocumentsRequest) returns (AddDocumentsResponse);

Request/response fields mirror PutDocuments.

GetDocuments

Retrieve all documents matching the given external ID.

rpc GetDocuments(GetDocumentsRequest) returns (GetDocumentsResponse);

Request fields:

Response fields:

DeleteDocuments

Delete all documents matching the given external ID.

rpc DeleteDocuments(DeleteDocumentsRequest) returns (DeleteDocumentsResponse);

Commit

Commit pending changes (additions and deletions) to the index. Changes are not visible to search until committed.

rpc Commit(CommitRequest) returns (CommitResponse);

FlushWal

Force buffered WAL records durable without a full commit. Both messages are empty. This is a near no-op under the default per-record sync policy (every write is already fsync’d); under the group-commit policy it flushes the current partial batch on demand, bounding the crash-loss window. Unlike Commit, it does not materialize segments, so buffered changes remain invisible to search until a subsequent Commit.

rpc FlushWal(FlushWalRequest) returns (FlushWalResponse);

message FlushWalRequest {}

message FlushWalResponse {}

The WAL durability policy is configured server-side via the [index.wal] config section. See Configuration → [index.wal] Section and Persistence & WAL → WAL Durability Policy.

HTTP gateway: POST /v1/flush_wal

SearchService

Search

Execute a search query and return results as a single response.

rpc Search(SearchRequest) returns (SearchResponse);

Response fields:

SearchStream

Execute a search query and stream results back one at a time.

rpc SearchStream(SearchRequest) returns (stream SearchResult);

SearchRequest Fields

At least one of query or query_vectors must be provided.

3D Geographic Queries

3D ECEF geographic queries are expressed in the lexical DSL string passed via SearchRequest.query. There is no dedicated message type — the same DSL forms used by the core library work over gRPC. Three forms are available (see Query DSL → 3D Geographic Queries for full syntax):

• position:geo3d_distance(x, y, z, distance_m) — sphere centered at (x, y, z) with maximum distance in meters
• position:geo3d_bbox(min_x, min_y, min_z, max_x, max_y, max_z) — 3D axis-aligned bounding box
• position:geo3d_nearest(x, y, z, k) — k nearest neighbours to (x, y, z)

position is the field name; substitute the actual Geo3d-typed field declared in your schema. All numeric arguments are signed double values; k is an unsigned integer.

QueryVector

FusionAlgorithm

A oneof with two options:

• RRF (Reciprocal Rank Fusion): k parameter (default: 60)
• WeightedSum: lexical_weight and vector_weight

LexicalParams

SortSpec

VectorParams

SearchResult

Example

{
  "query": "body:rust",
  "query_vectors": [
    {"vector": [0.1, 0.2, 0.3], "weight": 1.0}
  ],
  "limit": 10,
  "fusion": {
    "rrf": {"k": 60}
  },
  "field_boosts": {
    "title": 2.0
  }
}

Error Handling

gRPC errors are returned as standard Status codes: