gRPC API Reference

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

Services Overview

Service	RPCs	Description
`HealthService`	`Check`	Health checking
`IndexService`	`CreateIndex`, `GetIndex`, `GetSchema`	Index lifecycle and schema
`DocumentService`	`PutDocument`, `AddDocument`, `GetDocuments`, `DeleteDocuments`, `Commit`	Document CRUD and commit
`SearchService`	`Search`, `SearchStream`	Unary and streaming search

HealthService

`Check`

Returns the current serving status of the server.

rpc Check(HealthCheckRequest) returns (HealthCheckResponse);

Response fields:

Field	Type	Description
`status`	`ServingStatus`	`SERVING_STATUS_SERVING` when the server is ready

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:

Field	Type	Required	Description
`schema`	`Schema`	Yes	Index schema definition

Schema structure:

message Schema {
  map<string, FieldOption> fields = 1;
  repeated string default_fields = 2;
}

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

Lexical Fields	Vector Fields
`TextOption` (`indexed`, `stored`, `term_vectors`)	`HnswOption` (`dimension`, `distance`, `m`, `ef_construction`, `base_weight`, `quantizer`)
`IntegerOption` (`indexed`, `stored`)	`FlatOption` (`dimension`, `distance`, `base_weight`, `quantizer`)
`FloatOption` (`indexed`, `stored`)	`IvfOption` (`dimension`, `distance`, `n_clusters`, `n_probe`, `base_weight`, `quantizer`)
`BooleanOption` (`indexed`, `stored`)
`DateTimeOption` (`indexed`, `stored`)
`GeoOption` (`indexed`, `stored`)
`BytesOption` (`stored`)

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

Quantization methods: NONE, SCALAR_8BIT, PRODUCT_QUANTIZATION

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:

Field	Type	Description
`document_count`	`uint64`	Total number of documents in the index
`vector_fields`	`map<string, VectorFieldStats>`	Per-field vector statistics

Each VectorFieldStats contains vector_count and dimension.

`GetSchema`

Retrieve the current index schema.

rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse);

Response fields:

Field	Type	Description
`schema`	`Schema`	The index schema

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:

Field	Type	Required	Description
`id`	`string`	Yes	External document ID
`document`	`Document`	Yes	Document content

Document structure:

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

Each Value is a oneof with these types:

Type	Proto Field	Description
Null	`null_value`	Null value
Boolean	`bool_value`	Boolean value
Integer	`int64_value`	64-bit integer
Float	`float64_value`	64-bit floating point
Text	`text_value`	UTF-8 string
Bytes	`bytes_value`	Raw bytes
Vector	`vector_value`	`VectorValue` (list of floats)
DateTime	`datetime_value`	Unix microseconds (UTC)
Geo	`geo_value`	`GeoPoint` (latitude, longitude)

`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.

`GetDocuments`

Retrieve all documents matching the given external ID.

rpc GetDocuments(GetDocumentsRequest) returns (GetDocumentsResponse);

Request fields:

Field	Type	Required	Description
`id`	`string`	Yes	External document ID

Response fields:

Field	Type	Description
`documents`	`repeated Document`	Matching documents

`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);

SearchService

`Search`

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

rpc Search(SearchRequest) returns (SearchResponse);

`SearchStream`

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

rpc SearchStream(SearchRequest) returns (stream SearchResult);

SearchRequest Fields

Field	Type	Required	Description
`query`	`string`	No	Lexical search query in Query DSL
`query_vectors`	`repeated QueryVector`	No	Vector search queries
`limit`	`uint32`	No	Maximum number of results (default: engine default)
`offset`	`uint32`	No	Number of results to skip
`fusion`	`FusionAlgorithm`	No	Fusion algorithm for hybrid search
`lexical_params`	`LexicalParams`	No	Lexical search parameters
`vector_params`	`VectorParams`	No	Vector search parameters
`field_boosts`	`map<string, float>`	No	Per-field score boosting

At least one of query or query_vectors must be provided.

QueryVector

Field	Type	Description
`vector`	`repeated float`	Query vector
`weight`	`float`	Weight for this vector (default: 1.0)
`fields`	`repeated string`	Target vector fields (empty = all)

FusionAlgorithm

A oneof with two options:

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

LexicalParams

Field	Type	Description
`min_score`	`float`	Minimum score threshold
`timeout_ms`	`uint64`	Search timeout in milliseconds
`parallel`	`bool`	Enable parallel search
`sort_by`	`SortSpec`	Sort by a field instead of score

VectorParams

Field	Type	Description
`fields`	`repeated string`	Target vector fields
`score_mode`	`VectorScoreMode`	`WEIGHTED_SUM`, `MAX_SIM`, or `LATE_INTERACTION`
`overfetch`	`float`	Overfetch factor (default: 2.0)
`min_score`	`float`	Minimum score threshold

SearchResult

Field	Type	Description
`id`	`string`	External document ID
`score`	`float`	Relevance score
`document`	`Document`	Document content

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:

Laurus Error	gRPC Status	When
Schema / Query / Field / JSON	`INVALID_ARGUMENT`	Malformed request or schema
No index open	`FAILED_PRECONDITION`	RPC called before `CreateIndex`
Index already exists	`ALREADY_EXISTS`	`CreateIndex` called twice
Not implemented	`UNIMPLEMENTED`	Feature not yet supported
Internal errors	`INTERNAL`	I/O, storage, or unexpected errors

Keyboard shortcuts

Laurus Documentation