Messages, fields, enums, and services shared by Luxir’s HTTP and gRPC APIs.
See the gRPC guide for client generation and streaming,
and HTTP JSON mappings
for the HTTP shorthands.
Field descriptions come from the protobuf source comments. optional marks
explicit field presence; oneof members share a single choice. Application
defaults and constraints are described in the comments and guides.
Source
Source
Source
| Method |
Request |
Response |
Description |
Search |
stream SearchRequest |
stream SearchResponse |
Each request produces one or more responses, ending with more=false. Use request_id to correlate responses when sending multiple requests. |
One analysis-chain component - a tokenizer or a token filter - named by its registry name, plus its parameters. params values are typed JSON values (string, number, bool, string list), e.g. {“possessive”: false} for kstem. A component that takes no parameters rejects any. The JSON dialect accepts a bare string for a parameterless component: “lowercase” == {“name”: “lowercase”}.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
e.g., “unicode_word”, “nfkc_cf” |
params |
2 |
map<string, Val> |
map |
|
Source
Constant-score exact value-set membership using the field’s value binding. TEXT values are analyzed: zero tokens contribute nothing, one token is accepted, and multiple tokens are an error. STRING values use the field’s normalizer; ID values remain verbatim before applying long_terms. Numeric and DATE values use the same scalar coercion as ingest.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
values |
2 |
Val |
singular |
Required scalar or array of scalars. Null and nested arrays are errors. An empty array matches nothing; duplicate values are ignored. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
ArrDouble |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
ArrFloat |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
ArrInt |
repeated |
|
One array per document, used in columns for multi-valued string fields.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
ArrStr |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
bytes |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
double |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
float |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
sint64 |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
string |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
Val |
repeated |
Repeated field of dynamically typed values. |
A list of vectors, used as a per-doc cell for multi-valued vector fields.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
Vector |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
kind |
1 |
string |
singular |
|
field |
2 |
string |
singular |
|
name |
3 |
string |
singular |
|
gen |
4 |
string |
singular |
sortable-string spelling as embedded in the files’ names (see SegmentStats) |
commit_time |
5 |
uint64 |
singular |
microseconds since the Unix epoch |
built_core_gen |
6 |
uint64 |
singular |
|
files |
7 |
string |
repeated |
|
bytes |
8 |
uint64 |
singular |
bytes of this entry’s files; informational, already counted under its segment |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
filter |
1 |
Query |
repeated |
required clauses that do not add to the score |
required |
2 |
Query |
repeated |
required clauses that do add to the score |
optional |
3 |
Query |
repeated |
optional clauses that add to the score |
prohibited |
4 |
Query |
repeated |
prohibited clauses that must not match |
min_match |
5 |
int32 |
singular |
Minimum number of optional clauses that must match. Unset (0): with any required or filter clause present, optional clauses only rank coincident matches; with only optional clauses, at least one must match. Setting min_match >= 1 makes the optional group a real constraint alongside required/filter clauses; values above the clause count mean all of them. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
|
boost |
2 |
float |
optional |
Score multiplier. Unset = 1.0; 0 preserves matches with zero scores. Must be finite and >= 0. |
Admin control over the per-collection query cache. Actions compose and apply in this order: flush, reset_admission, reset_counters, then dump. flush drops resident values and entry metadata; sighting history survives, so a known query can be readmitted and rebuilt immediately. flush + reset_admission also forgets sightings, restarting admission tracking. reset_counters zeroes the cumulative stats. An empty collection targets every collection.
Source
Source
One resident cache entry. key_text is the printable-byte extraction from the serialized key (field names and terms survive; structure bytes do not); key_hash is a diagnostic fingerprint. bytes counts resident value payloads; segments_resident counts slots currently holding a value; reader_value marks a whole-reader live-exact value.
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
n |
1 |
int32 |
singular |
number of civil units per bucket; must be positive |
unit |
2 |
CalendarGap.Unit |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
missing_val |
1 |
double |
singular |
See ColFloat.missing_val. |
v |
2 |
double |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
missing_val |
1 |
float |
singular |
Chosen per batch like ColInt.missing_val (the check is exact). Never NaN (it compares unequal to itself); +0.0/-0.0 are treated as one value when choosing. |
v |
2 |
float |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
missing_val |
1 |
sint64 |
singular |
Sentinel for documents without a value. Chosen per column per batch so it never equals a present value: v[i] == missing_val means missing. HTTP JSON represents missing values as null. |
v |
2 |
sint64 |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
missing_val |
1 |
string |
singular |
“” unless a real empty string occurs in the batch, in which case a string greater than every batch value is used (see the ColInt.missing_val sentinel note; the check is exact). |
v |
2 |
string |
repeated |
|
Single-valued vector column. Each Vector slot is independently nullable via its empty oneof - no separate missing_val needed.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
Vector |
repeated |
|
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
totals |
2 |
StatsTotals |
singular |
|
schema_gen |
3 |
string |
singular |
sortable-string spelling (see SegmentStats); empty = no schema |
shards |
4 |
ShardStats |
repeated |
|
error |
5 |
Error |
singular |
Set for a collection that is not serving (failed to load, or a delete failed partway); kind is UNAVAILABLE and the message is the recorded reason. |
One slot per document, including missing values, aligned with DocList rows. Scalar columns use missing_val; multi-valued columns use empty arrays. Vector columns use the missing-value rules described on their fields.
Source
oneof kind: at most one member can be set.
Parameters governing how a commit is performed. Presence of this message in an UpdateRequest indicates the request should commit; absence means no commit.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit_within_ms |
1 |
uint64 |
singular |
Commit deadline in milliseconds. 0 (default) commits before responding; a positive value schedules a deferred commit and responds without waiting. Deferred requests coalesce at the earliest outstanding deadline. An explicit commit also satisfies outstanding deadlines. max_segments, build_aux_indexes, or wait_for_merges force an immediate commit instead. Search visibility also depends on SearchRequest.freshness_ms. |
build_aux_indexes |
2 |
string |
repeated |
Build missing aux overlays as part of this commit. An overlay already present on a segment is retained rather than rebuilt. [] - request no aux builds [“*”] - build every eligible missing vector overlay [“vec.title_v”] - build the missing vector overlay for title_v Only “*” and exact overlay names are supported; no partial-name patterns. |
wait_for_merges |
3 |
bool |
singular |
If true, this commit will wait for any in-flight merges to finish before publishing. |
max_segments |
4 |
uint32 |
singular |
Merge down so the data visible at this commit resides in at most this many segments. 0 (default) = no forced merging. The response is not sent until the merged index is durably published: at return, everything this commit made visible lives in <= max_segments segments (concurrent ingestion after this commit may add new segments; they are not covered by the promise). The response waits for the merged layout even when commit_within_ms is positive. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
|
score |
2 |
float |
optional |
Score assigned to every match. Unset = 1.0; an explicit 0.0 is preserved. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
schema |
2 |
SchemaDef |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
A batch of returned documents. Document i is the merge of columns row i and docs[i]; all-columns (docs absent) and all-docs (columns empty) are just the degenerate cases. Which fields land where is a function of the request (see DocFormat), never of the data.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
found |
1 |
sint64 |
optional |
Exact match count when get_number was requested. For Fusion, counts distinct documents in the union of source ranked lists, before paging. |
columns |
3 |
map<string, Column> |
map |
Dense columns; each has exactly row_count slots. |
docs |
5 |
Map |
repeated |
Per-document field maps. When present: exactly row_count entries; docs[i] holds the fields of document i not represented as a dense column. A field name never appears in both columns and docs[i]. |
row_count |
6 |
int32 |
singular |
Number of documents in this batch, including rows with no returned fields. A count-only response has row_count=0. |
offset |
4 |
int64 |
singular |
|
ops |
14 |
map<string, Val> |
map |
sub-operation results performed on the TopDocs query. |
more |
15 |
bool |
singular |
true if this document list has more batches; see SearchResponse.more |
Overrides the incoming document set for an operation directly in SearchRequest.ops or TopDocs.ops. Not supported directly in Fusion.ops or beneath facet buckets.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
2 |
Query |
singular |
If present, replaces the incoming domain with this query’s matches across the collection. If absent, inherits the incoming domain. |
apply_parent_filters |
3 |
bool |
optional |
With query set, reapply the immediate parent’s filters, including facet selections, while respecting except_ops. Default false discards them. Requires query; does not restore the parent’s query or ancestor domain. |
filter |
5 |
Query |
repeated |
Additional non-scoring constraints, ANDed with the inherited or reset domain. Entries and query must each specify a query kind. |
A failure. The same shape everywhere an error appears: SearchResponse.error, UpdateResponse.error and its per-document errors, the HTTP error body, and gRPC status details. kind is the coarse class: it selects the HTTP status and gRPC status code, and tells a client whether to fix the request, the target, or retry, without knowing the code. code is the stable machine key (snake_case, like Warning.code); new codes appear under existing kinds without changing this shape. message is human detail, not a contract.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
kind |
1 |
Error.Kind |
singular |
|
code |
2 |
string |
singular |
|
message |
3 |
string |
singular |
|
Execution details for instrumented operations. STRING/ID field facets provide profiles; other operations may be absent from this list.
Source
Source
Execution details for one segment of an operation.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
kind |
1 |
string |
singular |
“segment” |
segment |
2 |
int32 |
singular |
|
max_doc |
3 |
int32 |
singular |
|
strategy |
4 |
string |
singular |
|
cardinality |
5 |
sint64 |
optional |
|
domain_size |
6 |
sint64 |
optional |
|
thread_id |
7 |
int64 |
singular |
|
elapsed_us |
8 |
uint64 |
singular |
|
details |
9 |
string |
repeated |
Human-readable execution notes. Contents and formatting may change; do not parse these entries. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
An expression aggregate over the operation’s incoming document domain. The operation name is the key in the enclosing ops map.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
expr |
1 |
string |
singular |
|
vars |
2 |
map<string, Val> |
map |
|
An expression in the Luxir query language, with strict syntax and precise parse errors. Raw search-box input can use SimpleQuery. Expressions have structured Query equivalents and use the same field analysis rules.
Syntax summary: field:value, field:“a phrase” (or ‘…’), field:(grouped boolean scope), AND / OR / NOT with real precedence (NOT > AND > OR), +required / -prohibited prefixes (may not mix with AND/OR at one level), ranges field:[a TO b] / {a TO b} and comparisons field:>=v, trailing * for prefix, term~N for fuzzy (bare ~ = auto), *:* matches everything, and the function form name(main value, arg=value, …) reaching the callable query types by their JSON names (kNN and geo queries require structured messages). $name references a value bound in `vars`. Unfielded bare words are a parse error.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
q |
1 |
string |
singular |
the expression |
vars |
2 |
map<string, Val> |
map |
Values referenced from the expression as $name. Bound as VALUES (never re-parsed as syntax), so end-user input is safe to pass through: {“q”: “simple_query($input, fields=[title])”, “vars”: {“input”: …}}. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
bucket_ids |
2 |
Column |
singular |
|
counts |
3 |
int64 |
repeated |
|
missing |
4 |
int64 |
optional |
the number of documents that do not have this field |
ops |
22 |
map<string, Val> |
map |
sub-operation results performed per bucket, like a sub-facet or statistics. |
offset |
6 |
int64 |
singular |
|
A field, template, or variant definition, named by its enclosing map key. Unset properties inherit from parent, then use type defaults, except as documented on individual properties. HTTP JSON enum values are lowercase.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
parent |
1 |
string |
singular |
inherit properties from this field or template |
type |
2 |
FieldDef.FieldClass |
optional |
required unless inherited from parent |
index |
3 |
FieldDef.IndexMode |
optional |
Unset inherits, falling back to MATCH for STRING/TEXT/ID and NONE for other types. Other type/mode combinations are rejected. |
column |
4 |
bool |
optional |
store values in a per-field column |
multi |
5 |
bool |
optional |
multi-valued |
analyzer |
6 |
AnalyzerDef |
singular |
TEXT only. Unset or empty inherits; a nonempty definition replaces the entire analyzer. Without an inherited analyzer, defaults to whitespace. |
stored |
7 |
bool |
optional |
Keep canonical source text before analysis/normalization for TEXT/STRING/ID retrieval. Defaults to true for TEXT, false otherwise; unused on other types. |
stored_resource |
8 |
string |
optional |
Stored-field group for stored TEXT/STRING/ID values, e.g. “_stored_body_”. Empty or unset inherits the parent’s group, falling back to “_stored_”. |
dims |
9 |
int32 |
optional |
Vector dimensionality. Unset inherits, falling back to 0 (infer from the first indexed value). A positive value enforces dimensions at ingest. |
metric |
10 |
VectorMetric |
optional |
Vector similarity metric. Absent means inherit, else NONE (storage-only). |
normalized |
11 |
bool |
optional |
Caller asserts that all values for this field are already L2-normalized (unit length). For COSINE, this disables write-time and aux-build normalization. No effect on non-COSINE metrics. Trust-only: not validated at index time. |
normalize_on_write |
12 |
bool |
optional |
For COSINE fields, normalize vectors before storing them in the column. If unset, COSINE defaults to true unless normalized is true; other metrics default to false. A cosine field skips and logs zero / near-zero vectors when normalized is false. |
variants |
13 |
FieldVariants |
singular |
alternate representations of this logical field |
defaults |
14 |
FieldDefaults |
singular |
default search and value representations |
normalizer |
15 |
NormalizerDef |
singular |
whole-value STRING normalization |
long_terms |
16 |
FieldDef.LongTerms |
optional |
absent: inherit from parent, else hash128 |
Default representations for bare field names. Each binding names “self” or a local variant label. Absent inherits the parent’s defaults; present replaces both bindings. An omitted value binding on a TEXT primary selects its sole STRING variant; an omitted search binding on a STRING primary selects its sole TEXT variant. Multiple candidates require an explicit binding. With no candidate, or for other type combinations, use self. Inference uses resolved types; operations still check index/column support. Explicit <field>__<label> and <field>__self selectors bypass these defaults.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
search |
1 |
string |
optional |
Match, phrase, simple query, expression terms, prefix, fuzzy, wildcard, and regex queries, including their use in filters. |
value |
2 |
string |
optional |
AnyOfQuery, ranges, field/range facets, sorts, and column expressions. Bare field names in retrieval, exists, kNN, and geo use the primary. |
Buckets of distinct field values, using the field’s value binding. STRING/ID support sub-operations and custom sorts. INT/DATE/TEXT support counts, limits, mincount, missing, and selections.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
limit |
2 |
sint64 |
optional |
Maximum ordinary buckets. Unset = 5; 0 = none; -1 = all. Selected buckets outside the ordinary page are appended after it. |
mincount |
3 |
int64 |
optional |
Minimum bucket count. Unset includes only buckets with matches. STRING/ID/TEXT also accept 0 to include indexed terms absent from the domain. INT/DATE require a positive value when set. |
missing |
4 |
bool |
singular |
return the count of documents without a value |
sort |
5 |
SortSpec |
repeated |
One metric sub-operation name. Unset sorts by count descending, then bucket value ascending. |
ops |
6 |
map<string, SearchOp> |
map |
sub-facets or search operations performed per bucket |
selected |
7 |
Val |
singular |
Scalar or array of selected values, coerced as AnyOfQuery values. Selected buckets missing from the ordinary page append in input order with exact counts, even below mincount or absent from the index. Null is an error. |
selection_mode |
8 |
SelectionMode |
singular |
ALL requires a nonempty selection |
Alternate representations of the same input value, keyed by local label. Absent inherits the parent’s variants; present replaces the whole map; empty clears it. HTTP JSON represents this directly as an object.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
entries |
1 |
map<string, FieldDef> |
map |
Each representation is addressed as <field>__<label>. Variant definitions may inherit physical settings through parent, but cannot set multi, stored, stored_resource, variants, or defaults. All representations share the logical field’s scalar, vector, or geographic shape. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
required; restricts matches without contributing to scores |
except_ops |
2 |
string |
repeated |
Keys in the enclosing TopDocs.ops map that should not receive this filter. The filter still applies to the TopDocs results and other sub-operations. Names must be nonempty, distinct, and present in that ops map. Empty applies the filter to all sub-operations. Not supported on Fusion filters or Fusion source filters. |
Hybrid-search fusion: run several source queries (each a full TopDocs spec) and merge their results into a single ranked list.
Per-source response-shape fields (`fields`, `batch_size`, `offset`, `get_scores`, `get_number`, `document_format`) are ignored - Fusion controls response shape at the top level. Per-source `ops` are rejected; put facets and metrics in Fusion.ops. Each source’s `query`, `sort`, `limit`, and any per-source `filter` are used to produce that source’s ranked list.
The fusion-level `filter` is ANDed with each source’s own filters.
Source
oneof method: at most one member can be set.
Required fusion method.
| Field |
Number |
Type |
Cardinality / group |
Description |
sources |
1 |
map<string, TopDocs> |
map |
Named source queries. At least one source is required. |
filter |
2 |
Filter |
repeated |
Filters applied to every source. except_ops is not supported here or in source filters. |
limit |
3 |
sint64 |
optional |
Maximum fused documents to return. Unset = 10; 0 = none; -1 = all remaining. |
rrf |
10 |
RrfFusion |
oneof method |
|
offset |
4 |
int64 |
singular |
Response shape (mirrors TopDocs). Zero-based rank of the first returned fused document; must be >= 0. Return up to limit after skipping. Source limits remain candidate-pool sizes: paging cannot reach beyond the union of their ranked windows. Each response DocList.offset is the absolute rank of that batch’s first row, or the requested offset for an empty page. |
get_number |
5 |
bool |
singular |
return the number of distinct documents in the source union |
get_scores |
6 |
bool |
singular |
|
fields |
7 |
string |
repeated |
as TopDocs.fields: empty returns every retrievable field, ‘*’ patterns expand |
batch_size |
8 |
int32 |
singular |
same batching rules as TopDocs.batch_size |
document_format |
9 |
DocFormat |
singular |
rows vs columns placement of returned fields (see DocFormat) |
ops |
15 |
map<string, SearchOp> |
map |
Runs over the union of filtered source ranked lists, as counted by found. Fusion limit and offset do not affect this candidate domain. |
Matches indexed terms within byte-wise Levenshtein distance of `term`. TEXT fields apply multi-term normalization without tokenization; STRING fields apply their normalizer and ID fields use it verbatim. Scoring queries use blended BM25 statistics; filter queries use constant scores.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
term |
2 |
string |
singular |
|
max_edits |
3 |
int32 |
optional |
Maximum edit distance, 0..2. Unset = AUTO by term length: 0 for <=2 bytes, 1 for <=5, else 2. |
prefix_length |
4 |
int32 |
optional |
Leading bytes that must match exactly. Unset = 1; 0 = no required prefix. |
max_expansions |
5 |
int32 |
singular |
Max term expansions, closest terms first. Unset/0 = default 50. A positive value requests that cap; the operator/clause budget may lower it with a warning. Negative values are rejected. |
Inclusive geographic bounding box in degrees. Bounds are quantized to the storage grid exactly like ingest. min_lon > max_lon crosses the dateline; min_lat > max_lat is an error. Boxes degenerate at +90 latitude or +180 longitude match nothing.
Named scalar bounds deliberately avoid positional ambiguity: the VALUE array contract [x, y] = [lon, lat] does not apply to this message.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
min_lat |
2 |
double |
singular |
south edge, degrees in [-90, 90] |
max_lat |
3 |
double |
singular |
north edge |
min_lon |
4 |
double |
singular |
west edge, degrees in [-180, 180] |
max_lon |
5 |
double |
singular |
east edge; min_lon > max_lon crosses the dateline |
Geographic distance query with a center in degrees and radius in meters. Matches when at least one GEO_POINT value is within the inclusive radius.
Named center scalars deliberately avoid positional ambiguity: the VALUE array contract [x, y] = [lon, lat] does not apply to this message.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
lat |
2 |
double |
singular |
center latitude, degrees in [-90, 90] |
lon |
3 |
double |
singular |
center longitude, degrees in [-180, 180] |
radius_meters |
4 |
double |
singular |
inclusive radius, finite and non-negative |
Source
Source
Nearest-neighbor query against a searchable vector field. Search is exact when no ANN index is available; an ANN index may produce approximate results. The query vector must be non-empty and match the field’s dimensions. Deleted documents and documents outside the enclosing domain are excluded. Multi-valued fields return one hit per document using its highest similarity.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
vector field name (e.g. “embedding_v”) |
query |
2 |
Vector |
singular |
query vector - must match the field’s dims |
k |
3 |
int32 |
singular |
number of nearest-neighbor documents to return; must be positive |
exact |
4 |
bool |
singular |
Require exact top-k results by scanning stored vectors. Cost is linear in the number of stored vectors; refine_candidates and ivf are ignored. |
refine_candidates |
5 |
int32 |
singular |
Candidate-pool size for full-precision rescoring of ANN results, before collapsing multiple vectors to one hit per document. Clamped up to k; 0 selects an adaptive default. Larger pools can improve recall at a cost in memory and latency. Fewer candidates may be available. |
ivf |
6 |
KnnQuery.Ivf |
singular |
ignored for exact search and segments without an IVF index |
Search effort for IVF indexes.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
nprobe |
1 |
int32 |
singular |
Merge-stable IVF effort: lists to probe if this field were one IVF index with nlist=sqrt(live vectors). 0 = adaptive default; positive values cap search effort. |
min_scan_fraction |
2 |
float |
singular |
Minimum fraction of live vectors to scan, in [0,1]. 0 = no floor. |
Names of every collection on the node, sorted. HTTP-only: GET or POST /collections/_list, also available as GET /collections.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
collections |
1 |
string |
repeated |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
fields |
1 |
map<string, Val> |
map |
Unordered map of dynamically typed values. |
Matches one field. TEXT, STRING, and ID accept string, bytes, numeric, or boolean scalar values; numeric and DATE fields accept string or numeric scalars. Null matches nothing. Arrays and structured values are rejected, and GEO_POINT is unsupported. TEXT values are analyzed and scored; use AnyOfQuery for constant-score value sets and SimpleQuery or ExprQuery for multi-field text.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
val |
2 |
Val |
singular |
|
operator |
3 |
Match.Operator |
singular |
How to combine the multiple terms an analyzed text field can produce. Unset = OR. |
min_match |
4 |
int32 |
singular |
Minimum number of the analyzed terms that must match (the OR..AND middle ground). When set it overrides `operator`; clamped to the term count. Mirrors BooleanQuery.min_match. |
Multi-valued vector column. Empty ArrVector means “doc does not have the field”; absence is indistinguishable from an empty list, which matches the indexing behavior (an empty list of vectors is not stored).
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
ArrVector |
repeated |
|
Whole-value STRING normalization using a keyword input and only normalizing filters. Absent inherits; present replaces; empty clears. HTTP JSON uses an array of components, e.g. [“nfkc_cf”, “fold”]. Applied at ingest and to query literals and facet selections.
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
text |
2 |
string |
singular |
Set exactly one of these.
un-analyzed text that should yield multiple words when analyzed. ex: “Thomas Anderson” |
words |
3 |
string |
repeated |
un-analyzed list of words. ex: [“Yonik”,“Seeley”] |
terms |
4 |
string |
repeated |
analyzed list of terms as strings |
terms_bin |
5 |
bytes |
repeated |
analyzed list of binary (raw bytes) terms |
slop |
6 |
int32 |
singular |
Maximum spread of rebased positions: max(docPos-queryPos) minus min(docPos-queryPos). Must be nonnegative. Adjacent transposition costs 2; this is not the number of words between terms. Zero is exact. |
positions |
15 |
int32 |
repeated |
optional positions of the terms |
Matches documents where `field` has a term starting with `prefix`. TEXT fields apply multi-term normalization without tokenization; STRING fields apply their normalizer and ID fields use the bytes exactly. An empty prefix matches documents that have at least one indexed term for the field.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
prefix |
2 |
string |
singular |
|
Source
oneof kind: at most one member can be set.
An unset kind selects all documents, same as `all`.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
nonempty output label and selection key; unique within the facet |
query |
2 |
Query |
singular |
required; the bucket predicate |
Source
Named query buckets. A document may contribute to more than one bucket.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
buckets |
1 |
QueryBucket |
repeated |
required, nonempty; response order = request order |
ops |
6 |
map<string, SearchOp> |
map |
sub-ops per bucket |
selected |
7 |
Val |
singular |
bucket name or array of distinct existing names; null is an error |
selection_mode |
8 |
SelectionMode |
singular |
same filtering rules as FieldFacet; see SelectionMode |
Numeric or DATE buckets using the field’s value binding. Each bucket is inclusive at its lower bound and exclusive at its upper bound; the final bucket is clipped to end. start must be less than end. Buckets return in lower-bound order.
Source
oneof gap_kind: at most one member can be set.
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
start |
2 |
Val |
singular |
required inclusive start of the range |
end |
3 |
Val |
singular |
required exclusive end of the range |
gap |
4 |
Val |
oneof gap_kind |
positive fixed width in field units; integer milliseconds for DATE |
calendar_gap |
10 |
CalendarGap |
oneof gap_kind |
civil gap for DATE fields only |
mincount |
5 |
int64 |
optional |
minimum bucket count; unset = 0; must be >= 0 |
missing |
6 |
bool |
singular |
return the count of documents without a value |
ops |
8 |
map<string, SearchOp> |
map |
sub-facets or search operations performed per bucket |
time_zone |
9 |
string |
singular |
empty inherits SearchRequest.time_zone; DATE fields only |
selected |
11 |
Val |
singular |
Scalar or array naming generated bucket lower bounds. Selected buckets are returned even below mincount. Null, nongenerated bounds, and duplicate bounds after coercion are errors. |
selection_mode |
12 |
SelectionMode |
singular |
same filtering rules as FieldFacet; see SelectionMode |
Matches documents whose field value falls in the given range. All bounds are optional; omit a side for an open-ended range. Set at most one of gte/gt (lower) and at most one of lte/lt (upper); setting both of a pair is an error. With no bounds the query matches every document that has a value for the field. A doc with no value never matches.
Numeric fields (INT/FLOAT/DOUBLE/DATE) require a column. Bounds go through the same value-coercion contract as ingest, so querying a literal finds the documents ingested with it. DATE accepts ISO-8601 strings or epoch millis, and a partial date names its whole window: bounds include the granule they name ([2024-01 TO 2024-06] covers January through June; exclusive bounds exclude the granule whole). FLOAT/DOUBLE compare by IEEE-754 total order: -0.0 sorts below +0.0 and NaN sorts above +Inf.
Term-backed fields (TEXT/STRING/ID) range over indexed terms in byte order (no collation), constant-scoring. TEXT bounds use multi-term normalization without tokenization; STRING bounds use the field’s normalizer. Exact bounds follow the field’s long_terms policy. Uses the field’s value binding.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
gte |
2 |
Val |
singular |
lower bound, inclusive (>=) |
gt |
3 |
Val |
singular |
lower bound, exclusive (>) |
lte |
4 |
Val |
singular |
upper bound, inclusive (<=) |
lt |
5 |
Val |
singular |
upper bound, exclusive (<) |
Matches an anchored whole indexed term using `|`, concatenation, groups, repetition, `.`, and character classes. `^` and `$` are literals. On TEXT fields, literal characters fold the way the field folds text; character classes and ranges are codepoint-exact. STRING fields also normalize literal characters; ID fields use literals verbatim.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
pattern |
2 |
string |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
|
expr |
2 |
string |
singular |
|
vars |
3 |
map<string, Val> |
map |
|
Reciprocal Rank Fusion: fused_score(d) = sum over sources s of 1 / (k + rank_s(d)), where rank_s(d) is d’s 1-based rank in source s (or omitted if d does not appear in s). k=60 is the standard default.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
k |
1 |
int32 |
singular |
0 means use default (60) |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
fields |
1 |
map<string, FieldDef> |
map |
Concrete fields, keyed by field name. Exact-name lookup consults only this map. The reserved “id” and “_version_” fields are always materialized: a REPLACE_ALL that omits them gets the defaults; redefining them incompatibly, or defining a second ID-class field, is an error. |
templates |
2 |
map<string, FieldDef> |
map |
Abstract definitions, keyed by template name. Never directly usable as a doc field; suffix matching (“title_w” -> “_w”) consults only this map, and any field/template may name one as parent. A name in both maps is an error. |
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
schema |
1 |
SchemaDef |
singular |
the resulting schema after the operation |
A named search operation. The name is its key in the enclosing ops map.
Source
oneof kind: at most one member can be set.
Top-level search request that can contain multiple search operations.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
request_id |
1 |
string |
singular |
Optional opaque identifier, echoed in every response to this request. Use distinct identifiers to correlate requests and responses in a stream. |
collection |
2 |
string |
singular |
empty selects the default collection, “main” |
ops |
3 |
map<string, SearchOp> |
map |
Multiple search operations in a single request. |
freshness_ms |
4 |
uint64 |
singular |
Index view freshness tolerance in milliseconds. 0 (the default) requires the latest advertised commit: wait for an immediate commit’s response, and a freshness_ms=0 search is guaranteed to see it. A positive value lets the search reuse a reader up to this stale, avoiding reader churn under frequent commits. It is a tolerance, not a latency bound: there is no guaranteed time from ingest to visibility. |
time_zone |
5 |
string |
singular |
Time zone for date math and date literals without an offset. Empty is UTC; accepts Z, UTC, fixed offsets, or a case-sensitive IANA zone name. |
response_format |
6 |
ResponseFormat |
singular |
HTTP response framing. ENVELOPE (default): one JSON envelope per batch. DOCS: one document per line, with optional _header_ metadata records. The HTTP ?format=docs parameter also selects DOCS. gRPC rejects DOCS. See docs/guide/http-api.md for the NDJSON formats. |
profile |
7 |
bool |
singular |
Return execution details for instrumented operations; see ExecutionProfile. |
max_parallel |
8 |
int32 |
singular |
Intra-request parallelism: 0 (default) lets the engine choose; 1 runs serially on the shared executor; -1 permits unlimited parallelism. Automatic execution is serial on the receiving thread. Other values are rejected. |
Top-level response to a Search request
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
request_id |
1 |
string |
singular |
|
ops |
2 |
map<string, Val> |
map |
the results of the search operations in the request, keyed by operation name. |
error |
3 |
Error |
singular |
Present on a failed request’s final response; ops is then empty. A final error may follow earlier result batches. |
warnings |
4 |
Warning |
repeated |
final response only, on success or failure |
profile |
5 |
ExecutionProfile |
singular |
final response only, when SearchRequest.profile is true |
more |
15 |
bool |
singular |
if true, expect at least one more streaming response to the logical request. |
Ids and generations that appear in filenames are reported in their filesystem spelling so stats output correlates directly with directory listings and logs: “seg” is the segment’s data-file prefix (e.g. “s0a”), while generations are the length-prefixed base36 sortable strings embedded in filenames (e.g. live_gen “01” -> file “s0a__L01”, schema_gen “02” -> file “_schema_02”). Sortable strings order the same as the numbers they encode, so lexicographic comparison remains valid. Empty (omitted in JSON) means none. Generations that never appear on disk (index_gen, core_gen, update_version) stay numeric.
Source
Source
Source
Forgiving end-user query for raw search-box input. Malformed query text degrades to a valid query. Reported degradations appear in SearchResponse.warnings.
Syntax: bare words (searched across `fields`), + (the NEXT clause is required; needs a preceding clause to combine with, so a leading + is inert), -word (must not; under the default OR this is its own all-except-word clause - restrictive negation needs operator AND), a | b (or), “a phrase”, (grouping), trailing * (prefix), word~N (fuzzy; bare ~ = auto edits), \ escapes the next character, and field:value / field:“a phrase” fielded terms. A colon token whose field name is not queryable degrades to literal text against `fields`.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
q |
1 |
string |
singular |
the raw user input |
fields |
2 |
string |
repeated |
The fields unfielded (bare) terms search; scores sum across fields. Required and non-empty. Invalid request parameters can cause errors even though malformed q text is tolerated. |
operator |
3 |
Match.Operator |
singular |
How adjacent clauses combine. Unset = OR (any clause may match). |
min_match |
4 |
int32 |
singular |
Minimum number of top-level optional clauses that must match (mirrors BooleanQuery.min_match). Silently inapplicable when the parsed top level cannot honor it (a single clause, required clauses from + or the AND operator). |
allowed_fields |
5 |
string |
repeated |
Narrows which field names the field:value syntax may reach. Empty = every queryable schema field. It can only narrow that set - listing a name the schema cannot query does not make it work. A field: token outside the allowed set is literal text, never an error. |
Source
Operational statistics. An empty collection requests every collection on the node; per-segment records are opt-in because they are the only unbounded part of the response.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
collection |
1 |
string |
singular |
empty selects every collection |
segments |
2 |
bool |
singular |
|
Source
Rolled-up counts. Only the fields meaningful at a given level are set, so “collections” appears only on the node total and “shards” only on node and collection totals. Absent means zero (proto3 JSON omits defaults).
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
unset selects all documents (browse / filter-only search) |
filter |
2 |
Filter |
repeated |
|
offset |
3 |
int64 |
singular |
Zero-based rank of the first returned document; must be >= 0. Skip this many ranked matches, then return up to limit (-1: all remaining; 0: none). Each response DocList.offset is the absolute rank of that batch’s first row, or the requested offset for an empty page. Ignored as a Fusion source. |
limit |
4 |
sint64 |
optional |
Maximum documents to return. Unset = 10; 0 = none; -1 = all remaining. |
get_number |
5 |
bool |
singular |
return the number of matching documents |
get_scores |
6 |
bool |
singular |
return the relevancy score for each document returned |
fields |
7 |
string |
repeated |
Fields to return for each document. Empty returns every retrievable field (stored or column-backed; not vectors or engine fields such as _version_), discovered from the index and placed in per-document rows (DocList.docs). A name containing ‘*’ is a pattern expanded the same way: the matching retrievable fields, in rows; matching nothing is not an error. Explicitly named fields win on collision and may name anything, vectors and engine fields included. |
sort |
8 |
SortSpec |
repeated |
|
batch_size |
9 |
int32 |
singular |
Maximum documents per streaming batch. Nonpositive = default (100); the server caps positive values at 256. More documents produce more batches. Ignored beneath a facet bucket, where all rows return together. |
document_format |
10 |
DocFormat |
singular |
rows vs columns placement of returned fields (see DocFormat) |
ops |
15 |
map<string, SearchOp> |
map |
sub-facets or search operations performed over docs that match this query. |
Index or delete documents, with an optional commit.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
request_id |
1 |
string |
singular |
Optional opaque identifier, echoed in the response for correlation. |
collection |
3 |
string |
singular |
empty selects the default collection, “main” |
docs |
4 |
Map |
repeated |
|
delete_ids |
6 |
string |
repeated |
Document IDs to delete. Deletes never fail per-id; deleting a nonexistent id is a no-op. |
allow_dups |
7 |
bool |
singular |
Skip overwrite/dedupe for faster indexing when incoming IDs are known to be unique and do not already exist in the collection. Default (false) overwrites any existing document with the same ID. |
all_or_none |
8 |
bool |
singular |
If true, all documents in this request must be successfully indexed or none will be. Processing stops at the first failing document: documents already indexed by this request are rolled back, queued delete_ids from this request are rolled back, and later documents are not attempted (and not listed in errors). Atomicity is per-request; it does not span multiple requests in a stream. |
return_ids |
9 |
bool |
singular |
If true, return the ids of indexed documents in the response. |
commit |
10 |
CommitParams |
singular |
Commit parameters. If present, this request will commit; if absent, no commit is performed. |
field_map |
11 |
map<string, string> |
map |
Renames input document keys onto schema fields for this request’s docs, applied before schema lookup: a doc key found in the map indexes under the mapped name. An entry mapping to “” drops that input key. After mapping, a name appearing more than once in a doc keeps the last occurrence (the same last-wins rule as duplicate keys). Keys not in the map index under their own name unless drop_unmapped is set. This reshapes a foreign document stream per request, without editing the input or the schema. |
drop_unmapped |
12 |
bool |
singular |
If true, doc keys not present in field_map are dropped instead of indexed. Requires a non-empty field_map (note “id” is dropped too unless mapped). |
The response to an update request. In streaming mode the server sends exactly one response per request.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
request_id |
1 |
string |
singular |
This is the request_id from the UpdateRequest, if it was set. |
update_version |
2 |
uint64 |
singular |
The update version assigned to the update request. |
status |
3 |
UpdateResponse.Status |
singular |
|
ids |
4 |
string |
repeated |
ids of documents that were successfully indexed, if return_ids was set to true in the request. In request order; failed documents are omitted (align against docs by skipping errors[].index). A successfully indexed doc without a string/bytes id contributes an empty string. Only meaningful when status is OK or PARTIAL; on a request-level ERROR the listed documents may have been rolled back. |
errors |
5 |
UpdateResponse.DocError |
repeated |
Per-document failures. A failed document has no effect on search results; the previous version of the document, if any, is untouched. |
total_errors |
7 |
int64 |
singular |
Number of failed documents. Equals the length of errors unless the transport retained only a prefix (the NDJSON stream keeps the first 100 per group). |
error |
6 |
Error |
singular |
Request-level failure (not tied to a single document), e.g. a failure in the commit pipeline. Set exactly when status == ERROR for a non-document failure. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
id |
1 |
string |
singular |
the id of the failed document as given in the request (empty if absent or not a string/bytes value) |
index |
2 |
int32 |
singular |
position of the failed document within the request’s document list |
error |
3 |
Error |
singular |
|
Source
oneof kind: at most one member can be set.
A dense vector value. Dimensionality is the number of elements in f32.v.
Source
oneof kind: at most one member can be set.
| Field |
Number |
Type |
Cardinality / group |
Description |
f32 |
1 |
ArrFloat |
oneof kind |
|
A nonfatal degradation reported by the query parser or engine. Documented defaults, ignored parameters, and clamps need not produce warnings.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
code |
1 |
string |
singular |
stable machine key, e.g. “fuzzy_clamped”, “field_narrowed” |
message |
2 |
string |
singular |
human-readable detail |
Matches an entire indexed term. `*` matches any bytes, `?` matches one codepoint, and backslash escapes the next character. On TEXT fields, literal characters fold the way the field folds text; `*`, `?`, and escapes are syntax and never fold. STRING fields also normalize literal characters; ID fields use literals verbatim.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
pattern |
2 |
string |
singular |
|
Source
Placement preference for returned document fields: dense columns (DocList.columns) vs per-document maps (DocList.docs). DEFAULT resolves per transport: HTTP/JSON -> ROWS, gRPC -> COLUMNS. Under COLUMNS, explicitly named fields are returned as dense columns while discovered fields (empty or wildcard selectors) use docs; under ROWS everything is returned in docs.
Source
Source
| Value |
Number |
Description |
UNKNOWN |
0 |
|
INVALID_REQUEST |
1 |
the request as written cannot be served (HTTP 400) |
NOT_FOUND |
2 |
the addressed collection or route does not exist (404) |
ALREADY_EXISTS |
3 |
the request would create what already exists (409) |
FAILED_PRECONDITION |
4 |
the node’s state forbids the operation, e.g. –read-only (403) |
RESOURCE_EXHAUSTED |
5 |
a size or memory ceiling was exceeded (429; 413 for request_too_large) |
UNAVAILABLE |
6 |
the target exists but cannot serve now: shutting down, being deleted, failed to load (503) |
INTERNAL |
7 |
a server-side failure the request did not cause (500) |
Source
| Value |
Number |
Description |
STRING |
0 |
unanalyzed string |
TEXT |
1 |
analyzed text |
INT |
2 |
|
FLOAT |
3 |
|
DOUBLE |
4 |
|
ID |
6 |
document identifier used for replacement and deletion |
VECTOR |
7 |
dense float vector |
DATE |
8 |
timestamp, stored as int64 milliseconds since the Unix epoch |
GEO_POINT |
9 |
latitude/longitude point |
Index acceleration. Numeric Match/Range and geographic predicates can scan a column with NONE. Term queries on STRING/TEXT/ID require MATCH; STRING columns alone do not provide term-query support.
Source
| Value |
Number |
Description |
NONE |
0 |
no index |
MATCH |
1 |
term index for STRING/TEXT/ID, including term ranges |
RANGE |
2 |
numeric Match/Range or GEO_POINT predicates; requires column=true |
Policy for indexed terms longer than 255 bytes: STRING after normalization, TEXT after analysis, and IDs. Exact query values use the same policy. Not valid on column-only STRING or other types. Changes do not rewrite existing terms. See docs/guide/schema.md for ordering and query implications.
Source
| Value |
Number |
Description |
TRUNCATE |
0 |
keep a UTF-8-safe prefix of at most 255 bytes; values may merge |
REJECT |
1 |
reject overlong terms |
HASH128 |
2 |
prefix of at most 230 bytes plus 25 base36 hash digits |
Source
| Value |
Number |
Description |
OPERATOR_UNSPECIFIED |
0 |
treated as OR |
OR |
1 |
a doc matches if any analyzed term matches |
AND |
2 |
a doc must match every analyzed term |
Source
Source
| Value |
Number |
Description |
SET |
0 |
Each named definition is SET to exactly the request’s definition (whole-definition, never a property-level merge); definitions not named in the request are untouched. |
REPLACE_ALL |
1 |
Replace the entire schema with this definition (the reserved id and _version_ fields are materialized when omitted). |
How facet selections filter the enclosing TopDocs results and its sub-operations. Nonempty selected is supported only on facets directly in TopDocs.ops. Selections on different facets combine with AND. Domain overrides can discard these filters; see Domain.apply_parent_filters.
Source
| Value |
Number |
Description |
ANY |
0 |
match any selected value; omit this selection’s filter from its own facet |
ALL |
1 |
Require every selected value. Keep this selection’s filter on its own facet so each unselected bucket counts matches if that value is added. |
Source
Source
| Value |
Number |
Description |
UNKNOWN |
0 |
the default |
OK |
1 |
the update was successful |
PARTIAL |
2 |
part of the request took effect, part failed (see errors) |
ERROR |
3 |
The request failed. If error is unset, the failure was per-document (see errors) and the request had no visible effect on the index. If error is set, the failure was request-level (e.g. commit pipeline) and the effect of individual documents is indeterminate beyond what errors lists. |
Vector similarity metric. NONE = storage-only, not kNN-searchable; L2 / IP / COSINE select the metric for exact column search and any ANN index.
Source
`NullValue` is a singleton enumeration to represent the null value for the `Value` type union.
The JSON representation for `NullValue` is JSON `null`.
