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 kind of work: currently running, completed by outcome, and the duration of completed work (failed and cancelled work included).
Source
Source
One analysis-chain component - a tokenizer, character filter, or 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 |
|
A text analysis chain: char filters, then one tokenizer, then token filters. Alternatively `name` selects a registered analyzer (a built-in preset such as “english”, or one a plugin provides); it excludes tokenizer and filters, and char_filters alongside it replace the preset’s char filters. The JSON dialect accepts a bare string for the named form: “english” == {“name”: “english”}.
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. |
One dedicated allocator arena (a huge-page arena sums its two jemalloc arenas). Resident is jemalloc’s upper bound.
Source
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: max_bytes, flush, reset_admission, reset_counters, then dump. flush drops resident values and entry metadata, including ledgers; 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 cumulative stats without forgiving debt. An empty collection targets every collection.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
collection |
1 |
string |
singular |
Empty selects every collection of `tenant`, or of every tenant when `tenant` is also empty (administration). |
tenant |
7 |
string |
singular |
Administration only. With a collection, empty is the caller’s tenant. |
flush |
2 |
bool |
singular |
|
reset_admission |
3 |
bool |
singular |
|
reset_counters |
4 |
bool |
singular |
|
dump |
5 |
bool |
singular |
|
dump_limit |
6 |
uint32 |
singular |
max dump rows per shard; 0 = 100 |
include_ghosts |
9 |
bool |
singular |
with dump, include retained ledgers without payloads |
max_bytes |
8 |
uint64 |
optional |
Administration only. Sets the selected caches’ byte budget before the other actions; 0 disables caching and drops entries. With collection and tenant both empty it is also the budget for collections created later. Lasts for the node session: kept when a collection is replaced, dropped when it is deleted, back to –query-cache-bytes on restart. |
Source
One cache key, with resident values or retained ledgers. 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
A segment slot or whole-reader entry, including optional payload-free ledgers.
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
Source
This process’s cgroup v2. Limits are local to the cgroup; ancestors may impose stricter ones. Controllers that are not enabled are omitted.
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
current |
1 |
uint64 |
singular |
including threads |
max |
2 |
int64 |
singular |
-1 is unlimited |
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 |
|
Column of a field type that has no typed arm (an object, an interval, a boolean, a geo point): v[i] holds what document i’s row entry would. An unset kind means missing. A geo point is an arr_d [lon, lat], and a multi-valued geo field an arr of such pairs, the shapes ingest reads.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
v |
1 |
Val |
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 |
|
Partition matching documents by an exact, single-valued key.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
repeated |
One field, or an exact tuple. Uses value binding. |
missing |
2 |
Collapse.MissingPolicy |
singular |
|
head_sort |
3 |
SortSpec |
repeated |
Display member order; defaults to the list sort. |
get_count |
4 |
bool |
singular |
Count members of each returned group in the finalized match set. |
ops |
5 |
map<string, SearchOp> |
map |
Per-group operations on matching members; facet count units start at docs. Explicit group units still resolve to this nearest enclosing collapse. |
sort |
6 |
SortSpec |
repeated |
Exhaustive group order by metrics in ops; missing/failed values last. Ties use the best member under the list sort, then document order. |
Engine work that reached this collection since it was opened. The node’s ServiceStats also count requests that failed before resolving a collection, and keep their counts when a collection is deleted.
Source
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit |
1 |
string |
singular |
Durable snapshot identity, retained even if the replica wait fails. |
replicas |
2 |
ReplicaResult |
singular |
|
error |
3 |
Error |
singular |
Local commit failure for this collection. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
tenant |
7 |
string |
singular |
|
totals |
2 |
StatsTotals |
singular |
|
schema_gen |
3 |
uint64 |
singular |
Schema generation |
shards |
4 |
ShardStats |
repeated |
|
error |
5 |
Error |
singular |
Set for a collection that is not serving (failed to load, being deleted, or a delete failed partway): kind is UNAVAILABLE and the message is the reason. A node-wide walk also reports here a collection whose statistics could not be read, with the failure’s kind. |
storage_ram_bytes |
6 |
uint64 |
singular |
|
activity |
8 |
CollectionActivityStats |
singular |
Set for a serving collection. |
One slot per document, including missing values, aligned with DocList rows. Scalar columns use missing_val; multi-valued columns use empty arrays. Vector and value columns use the missing-value rules described on their fields. Every returned field type has a column form: a type with no typed arm uses col_val. In FacetResult.bucket_ids, every value is present and missing_val is ignored.
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. |
wait_for_replicas |
5 |
ReplicaRequirement |
singular |
Forces an immediate commit. All captures live followers at commit completion; members that go non-live stop counting. |
wait_for_replicas_timeout_ms |
6 |
uint64 |
optional |
Visibility wait deadline. Absent defaults to 30000; timeout never undoes commit. |
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 |
cpu |
1 |
string |
singular |
|
user |
2 |
double |
singular |
seconds; includes guest time |
nice |
3 |
double |
singular |
|
system |
4 |
double |
singular |
|
idle |
5 |
double |
singular |
|
iowait |
6 |
double |
singular |
|
irq |
7 |
double |
singular |
|
softirq |
8 |
double |
singular |
|
steal |
9 |
double |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
schema |
2 |
SchemaDef |
singular |
|
tenant |
3 |
string |
singular |
Administration only: the owning tenant. Empty is the caller’s tenant (the default tenant until credentials carry one). |
wait_for_replicas |
4 |
ReplicaRequirement |
singular |
All counts live followers subscribed to the tenant that serve any collection, since none serves the new one yet. |
wait_for_replicas_timeout_ms |
5 |
uint64 |
optional |
absent = 30000 |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit |
2 |
string |
singular |
exact snapshot published by creation |
name |
1 |
string |
singular |
|
replicas |
3 |
ReplicaResult |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
tenant |
2 |
string |
singular |
as CreateCollectionRequest.tenant |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
Matches documents that match any query and combines their matching scores as best + tie * (sum - best), defaulting to the best score (tie = 0). Duplicate queries are kept as separate scoring contributions. A single query scores as itself; tie = 1 is a boolean disjunction. Filter use shares the equivalent boolean’s membership and cache key (Elasticsearch dis_max).
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
queries |
1 |
Query |
repeated |
required, non-empty |
tie |
2 |
float |
optional |
Weight of the non-best matching queries. Unset = 0. Must be finite and in [0, 1]; 1 adds every score like a boolean disjunction. |
One block device or partition (/proc/diskstats).
Source
A document cap, applied before paging in the list’s ordinary rank order.
Source
oneof kind: at most one member can be set.
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 follows the request’s DocFormat; under COLUMNS an all-missing discovered column is left out of the batch, under ADAPTIVE placement is per batch and field.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
found |
1 |
sint64 |
optional |
Match count when count_limit is nonzero or the estimate_count flag applies. Counts groups with collapse; otherwise Fusion counts source-union documents before paging. |
found_gte |
9 |
bool |
singular |
True when found is a lower bound. Neither this nor found_estimated means the count is exact. |
found_estimated |
16 |
bool |
singular |
True when found was extrapolated from a sample of the index; it may be above or below the exact count, within what index statistics allow. |
found_docs |
2 |
sint64 |
optional |
Collapse only, when count_limit is nonzero, after missing=drop. |
found_groups |
8 |
sint64 |
optional |
Diversify only, with nonzero count_limit: distinct eligible keys. |
groups |
7 |
GroupTable |
singular |
Collapse only: complete metadata aligned with this batch’s rows. |
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 an operation’s incoming document set, including beneath facet and group buckets. A reset retains the enclosing structural identities, and re-evaluates selection-query identities outer to inner in the new scope; child membership can differ from the parent’s counted window. Not supported directly in Fusion.ops.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
from_match |
7 |
string |
optional |
In row_ops, select this named clause’s matching descendant rows. |
to |
6 |
string |
optional |
Relative descendant path, .. steps to ancestors, or / for root documents. |
query |
2 |
Query |
singular |
If present, replaces the incoming domain with this query’s matches within live documents and the enclosing structural bucket identities. If absent, inherits the incoming domain. |
apply_parent_filters |
3 |
bool |
optional |
With query set, reapply the owning list’s filters, including facet selections, while respecting except_ops. Default false discards them. Requires query; does not restore matching queries above this operation. |
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 |
Always-present bucket labels; Column.missing_val sentinels do not apply. |
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 |
FieldDef.MultiMode |
optional |
unset inherits, falling back to SINGLE |
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_”, declared in SchemaDef.stored_resources. 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. With truncate_dims, this is the full input dimension. |
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 |
truncate_dims |
19 |
int32 |
optional |
VECTOR only. Keep the first truncate_dims components of every indexed and query vector, for Matryoshka (MRL) embeddings whose prefixes are usable embeddings. Requires dims (the full input dimension, which must be larger) and metric COSINE, which renormalizes the prefix; normalized=true is rejected. Inputs carry dims components, or truncate_dims for a vector already truncated. The column, ANN overlays and kNN scoring use truncate_dims. Unset inherits; 0 means no truncation. |
ann |
22 |
VectorAnnDef |
singular |
VECTOR only: ANN overlay settings. Absent inherits the parent’s whole definition (no per-property merge), else every VectorAnnDef default. |
scale |
25 |
int32 |
optional |
DECIMAL only, and required there: digits after the decimal point, 0 to 18. Excess fractional digits round half away from zero. |
unit |
24 |
FieldDef.DateUnit |
optional |
|
ignore_malformed |
28 |
bool |
optional |
GEO_POINT only. Skip a value that is not a valid point (unreadable, out of range, or a z coordinate when ignore_z_value is false) and index the rest of the document; in a multi-valued field only the bad points are skipped. Unset inherits, else false: a malformed point fails the document. |
ignore_z_value |
29 |
bool |
optional |
GEO_POINT only. Accept a third (z, altitude) coordinate and drop it. Unset inherits, else true. Set false to reject a point with a z coordinate. |
reverse_map |
30 |
bool |
optional |
NESTED only. Store child-to-owner row lookups in segments written later. Unset inherits, else true. Changing it does not rewrite existing segments. |
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, INT/DATE/FLOAT/DOUBLE, and TEXT support counts, limits, mincount, missing, selections, sub-operations, and metric sorts. Distinct counts are supported except on TEXT; metric sorts with distinct counts are unsupported.
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/FLOAT/DOUBLE require a positive value when set. |
missing |
4 |
bool |
singular |
Return the count without a value, in the chosen count unit. |
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 |
count_unit |
9 |
FieldFacet.CountUnit |
optional |
Unset inherits a parent facet’s measure, or counts groups beneath a collapsed list; entering group ops defaults to docs. Explicit GROUPS uses the nearest enclosing collapse, including inside a group. Controls count, count order, mincount, and missing; metrics still fold documents. |
count_distinct |
10 |
Collapse |
singular |
Exact distinct keys per bucket, also usable without collapse. Same key types and missing policies as Collapse. Conflicting measures are errors. |
term_filter |
11 |
TermFilter |
singular |
STRING/ID only. Restricts which terms can be ordinary buckets while counts stay exact; see TermFilter. It applies to the ordinary page and to mincount=0 padding. `missing` still counts every document in the domain without a value, and selected buckets are returned whether or not they pass the filter. |
Cached field metadata payload, excluding allocator overhead and unused hash-table capacity.
Source
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 |
path |
1 |
string |
singular |
|
size_bytes |
2 |
uint64 |
singular |
|
free_bytes |
3 |
uint64 |
singular |
including reserved blocks |
avail_bytes |
4 |
uint64 |
singular |
available to this process |
files |
5 |
uint64 |
singular |
|
files_free |
6 |
uint64 |
singular |
|
readonly |
7 |
bool |
singular |
|
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. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
follower |
1 |
string |
singular |
|
tenant |
6 |
string |
singular |
|
collection |
2 |
string |
singular |
|
commit |
3 |
string |
singular |
|
last_seen |
4 |
uint64 |
singular |
Unix milliseconds |
lag |
5 |
uint64 |
optional |
generation distance; absent without a current acknowledgment |
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`, `count_limit`, `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. A source collapse accepts only field and missing, and its limit counts groups; the head documents enter document fusion. Source collapse head_sort, sort, get_count and ops are errors.
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: exactly one.
| Field |
Number |
Type |
Cardinality / group |
Description |
decorate |
27 |
map<string, Val> |
map |
Plugin result decorators, executed only for emitted rows. |
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 rows (groups with collapse) to return. Unset = 10; 0 = none; -1 = all remaining. |
rrf |
10 |
RrfFusion |
oneof method |
|
linear |
11 |
LinearFusion |
oneof method |
|
offset |
4 |
int64 |
singular |
Response shape (mirrors TopDocs). Zero-based rank of the first returned fused row; 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. |
count_limit |
5 |
sint64 |
optional |
Match count: unset or 0 omits found; -1 requests exact; -2 permits an estimate; positive N permits a lower bound. Fusion always supplies an exact count, which is valid for -2, N and an unset count_limit under the estimate_count flag. Counts eligible groups with collapse, otherwise source-union documents. Must be >= -2. |
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 |
placement of returned fields: rows, columns, or adaptive (see DocFormat) |
collapse |
17 |
Collapse |
singular |
Collapse the fused document list before paging. Source windows never refill. found counts eligible groups; found_docs counts eligible fused documents. |
ops |
15 |
map<string, SearchOp> |
map |
Runs over the union of filtered source ranked lists, even with collapse. Fusion limit and offset do not affect this candidate domain. |
weights |
16 |
map<string, double> |
map |
Per-source weights keyed by source name, used by the fusion method. A source without an entry has weight 1. Weights must be finite, >= 0, and within float range, every key must name a source, and at least one source must have a weight > 0. A zero weight disables its source: it is not executed and its documents do not enter the fused list, found, or the ops 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 is honored as given, with no upper bound. 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 |
A polygon vertex in degrees. Named scalars, like GeoBoxQuery, so the VALUE array contract [x, y] = [lon, lat] does not apply.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
lat |
1 |
double |
singular |
degrees in [-90, 90], finite |
lon |
2 |
double |
singular |
degrees in [-180, 180], finite |
One polygon: an outer ring and optional holes. A point is inside it when it is inside the outer ring and inside none of its holes, each ring by the even-odd rule, so a self-intersecting ring still has an interior. Holes apply to this polygon only.
Source
Matches when at least one GEO_POINT value is inside any of the polygons, their union. Edges are straight lines in latitude/longitude and do not cross the dateline: split such a polygon into two polygons of the same query. A point exactly on an edge may match either way.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
polygons |
2 |
GeoPolygon |
repeated |
at least one |
A ring lists its vertices in order; the last connects back to the first, and repeating the first vertex at the end is optional. It needs at least 3 distinct vertices.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
points |
1 |
GeoLatLon |
repeated |
|
Typed collapse identity. Component types follow the resolved schema fields.
Source
oneof value: at most one member can be set.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
component |
1 |
GroupComponent |
repeated |
|
singleton |
2 |
uint64 |
optional |
Present for missing=expand: reader-local document identity, not a key value. |
Columns aligned with a collapsed list’s returned rows. Absent columns were not requested.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
keys |
1 |
GroupKey |
repeated |
|
counts |
2 |
sint64 |
repeated |
|
ranks |
3 |
ArrVal |
repeated |
Metric sort values, or list rank values when head_sort chooses another member. |
ops |
4 |
map<string, Val> |
map |
Each operation is an array aligned with keys, as in FacetResult.ops. |
Cumulative duration histogram. counts[i] is the number of observations at or below bound i of the histogram’s family (ServiceStats.request_duration_bounds or background_duration_bounds); the last entry (+Inf) equals count. counts is empty when count is zero.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
counts |
1 |
uint64 |
repeated |
|
sum |
2 |
double |
singular |
seconds |
count |
3 |
uint64 |
singular |
|
Source
Host memory from /proc/meminfo and VM events from /proc/vmstat.
Source
Host-wide statistics, as node_exporter reports them. Collectors are listed as in SystemStats.
Source
Indexing RAM budget: the configured limit and the bytes reserved against it.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
limit_bytes |
1 |
uint64 |
singular |
zero is unlimited |
reserved_bytes |
2 |
uint64 |
singular |
may temporarily exceed the soft limit |
draining_bytes |
3 |
uint64 |
singular |
reserved bytes currently draining through flushes |
pending_merge_bytes |
4 |
uint64 |
singular |
pending merge demand, capped at the limit when limited |
retained_delete_bytes |
5 |
uint64 |
singular |
Resident delete packets across all owners, including commit and merge catch-up references. Included in reserved_bytes; flushing does not free them. |
Source
jemalloc’s process-wide statistics (stats.*), read at one statistics epoch per request. allocated counts live bytes allocated through jemalloc, including objects cached by threads; active adds page-level fragmentation; resident is jemalloc’s upper bound on its resident pages, including metadata and dirty pages awaiting decay. The process RssAnon also counts memory jemalloc does not manage.
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 - dims components, or truncate_dims when set |
k |
3 |
int32 |
singular |
nearest documents (default) or groups 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-document pool size for full-precision rescoring of ANN results, in both units. Group search caps the number of candidates per group so repeated keys cannot consume the whole pool. 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 |
unit |
7 |
string |
singular |
docs (default): k counts documents. groups: k counts nearest groups under the enclosing top_docs collapse key and missing policy; requires collapse. The match set contains one best scored witness per selected group. |
similarity |
8 |
float |
optional |
Minimum vector similarity for a hit, in the metric’s own space (not the transformed score): for l2 the maximum L2 distance (not squared), for ip the minimum dot product, for cosine the minimum cosine similarity. Hits beyond it are dropped from the k nearest, so fewer than k may match. Compared before any enclosing boost. Must be finite; l2 requires >= 0. |
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. |
Weighted linear fusion of normalized scores: fused_score(d) = sum over sources s of weight_s * normalized_s(d), where weight_s comes from Fusion.weights and sources without d contribute nothing. Each source’s scores are normalized over its ranked list after merging across segments. Sources must rank by relevance score: a source with a sort other than score descending (optionally followed by _docid_ ascending) is rejected.
Source
Names of every collection of one tenant, sorted. HTTP-only: GET or POST /collections/_list (also GET /collections) for the caller’s tenant, or /tenants/{tenant}/collections/_list.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
collections |
1 |
string |
repeated |
|
Tenants that own at least one collection, sorted. HTTP-only: GET /tenants.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
tenants |
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 MultiMatchQuery, 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. |
case_insensitive |
10 |
bool |
singular |
Match TEXT tokens and STRING/ID values regardless of simple Unicode case, after query analysis/normalization. Indexed case variants score as one word, with the query’s exact case preferred slightly: frequency weight 1.0 for the analyzed/normalized query token, 0.9 for other variants. Frequencies sum before BM25 saturation, with shared statistics. Slower than a folding variant (_t, _un, _wl), recommended for frequent use. Alternates come from analyzed tokens; case-preserving stemmers can be asymmetric (KStem stems lowercase only). Numeric and DATE fields ignore it. |
Node memory: Luxir’s own budgets and usage, and the process allocator’s statistics where the allocator reports them.
Source
Searches one text across weighted fields. In COMBINED mode, TEXT fields sharing an analyzer and long-term policy form a group scored as one field with BM25F. STRING/ID/numeric/date fields form singleton match groups with multiplicative weights. PER_FIELD scores a match in each field separately. Group or field scores combine as best + tie * (sum - best), defaulting to sum (tie = 1). Values that cannot coerce to a field contribute no clause in either mode, including with phrase options; other errors fail the request. If no field contributes, matches nothing. BM25F follows Lucene’s CombinedFieldQuery.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
text |
1 |
string |
singular |
the text to analyze or coerce |
fields |
2 |
WeightedField |
repeated |
Required and non-empty. Fields resolve through their search bindings. Field order does not matter; duplicate physical targets keep the larger weight. Names containing ‘*’ select indexed TEXT/STRING/ID search targets from concrete declarations and dynamic roots present in reader metadata. Patterns containing ‘__’ select variants; other patterns select roots through their search binding. Declared fields and variants of known roots need not be present in the index. Wildcard lists may resolve to at most 64 distinct physical targets, including explicit selectors; exceeding the limit is an error. |
mode |
3 |
MultiMatchQuery.Mode |
singular |
Unset = COMBINED. |
operator |
4 |
Match.Operator |
singular |
How analyzed terms combine. Unset = OR. COMBINED applies this within each group (AND: every term in some field of one group). PER_FIELD applies it within each field (AND: every term in that field). Must be unset when phrase is present. |
min_match |
5 |
int32 |
singular |
Zero uses operator. Positive values override operator and are clamped to the analyzed term count within each group/field. Must be >= 0, and must be zero when phrase is present. |
tie |
6 |
float |
optional |
Combines matching field/group scores as best + tie * (sum - best). Unset = 1 in every mode. Must be finite and in [0, 1]. |
phrase |
7 |
PhraseOptions |
singular |
Absent = match. Present = a phrase per TEXT field (requires indexed positions); STRING/ID fields match the whole value, and numeric/date fields still use match coercion. PER_FIELD only; fields combine by tie, and each weight multiplies its field’s score. Operator must be unset and min_match must be zero. |
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 |
|
One interface in this network namespace (/proc/net/dev).
Source
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
Completed work by outcome, and its summed duration.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
ok |
1 |
uint64 |
singular |
|
error |
2 |
uint64 |
singular |
|
cancelled |
3 |
uint64 |
singular |
|
seconds |
4 |
double |
singular |
|
Phrase matching options. A present empty message requests an exact phrase.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
slop |
1 |
int32 |
singular |
Maximum spread of query-adjusted positions. Must be >= 0; unset = 0. |
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 |
An operation registered by a compiled-in plugin (see docs/dev/plugins.md). The JSON dialect also accepts a registered plugin name as the arm key: {“my_op”: {“a”: 1, “ops”: {…}}} reads as {“plugin”: {“name”: “my_op”, “params”: {“a”: 1}, “ops”: {…}}}. An unregistered name is a request error that lists the registered operations. The plugin validates params and defines the result shape; nested ops run over the domain the plugin gives them and may not override it.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
params |
2 |
map<string, Val> |
map |
|
ops |
3 |
map<string, SearchOp> |
map |
|
A query type registered by a compiled-in plugin (see docs/dev/plugins.md). The JSON dialect also accepts a registered plugin name as the arm key: {“my_query”: {“a”: 1}} reads as {“plugin”: {“name”: “my_query”, “params”: {“a”: 1}}}, and the expression language calls it as my_query(…) with the arguments the plugin declares. An unregistered name is a request error that lists the registered query types. params are typed JSON values; a nested query is a Query-shaped value the plugin parses.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
name |
1 |
string |
singular |
|
params |
2 |
map<string, Val> |
map |
|
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 |
|
case_insensitive |
3 |
bool |
singular |
After whole-prefix normalization, also match simple Unicode case alternates. TEXT fields are supported. Uses a constant-score automaton. |
max_expansions |
4 |
int32 |
singular |
Max term expansions per segment. Unset/0 = every term with the prefix. A positive value keeps only the terms with the highest document frequency in each segment (ties go to the lower term), so a short prefix over a large dictionary costs at most this many postings lists per segment. Any positive value is valid; negative values are rejected. Selection also supports case_insensitive. Operator expansion and request memory limits still apply. |
Pressure stall information for one resource (/proc/pressure).
Source
This process’s I/O accounting (/proc/self/io).
Source
Source
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
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 under EXPLICIT bounds. start must be less than end when both are supplied. Buckets return in lower-bound order. At most 100000 buckets may be generated; with sub-operations at most 1024 may be returned after mincount filtering. Fixed DATE gaps step in local time in the facet zone: both fold occurrences are fences; skipped lattice times map to the transition.
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 |
EXPLICIT: inclusive first fence, required. DATA: optional widening bound; include its cell without excluding smaller matching values. |
end |
3 |
Val |
singular |
EXPLICIT: exclusive last fence, required. DATA: optional exclusive widening bound; include intersecting cells below it without excluding larger values. |
gap |
4 |
Val |
oneof gap_kind |
positive fixed width in field units; integer field units 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 without a value, in the chosen count unit. |
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. Not supported with DATA bounds. |
selection_mode |
12 |
SelectionMode |
singular |
same filtering rules as FieldFacet; see SelectionMode |
count_unit |
13 |
FieldFacet.CountUnit |
optional |
Inherits the parent measure; GROUPS uses the nearest collapse. |
count_distinct |
14 |
Collapse |
singular |
Exact distinct keys; same specification as Collapse. |
bounds |
15 |
RangeFacet.Bounds |
singular |
|
origin |
16 |
Val |
singular |
DATA fixed gaps only; rejected with calendar_gap. Default 0. For INT, FLOAT and DOUBLE, fences are origin + k * gap from a global integer k. For DATE, origin is a wall-clock phase in the facet zone: 21600000 with gap 86400000 starts days at 06:00 local across DST. This differs from Elasticsearch’s UTC-translated offset near transitions. Must be integer field units for DATE, an integer for INT, or a number for FLOAT/DOUBLE. |
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 values in the field’s unit, 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.
Range fields (LONG_RANGE, DOUBLE_RANGE, DATE_RANGE) compare each stored [min, max] interval with the query interval by `relation`. Bounds use the element’s scalar range-query rules. Partial date bounds name their whole granule. Open long/date ends extend to int64 limits; open double ends are -Infinity and +Infinity. Explicit double infinities at those ends are equivalent; NaN is rejected. Date endpoints in results follow date output modes. Sort, facets, collapse, value expressions, and any_of are unsupported.
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 (<) |
relation |
15 |
RangeQuery.Relation |
singular |
Range fields only; rejected on other field types unless INTERSECTS. |
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 |
|
case_insensitive |
3 |
bool |
singular |
Literal characters, after field folding, and every member of character classes and ranges also match their simple Unicode case alternates. Negated classes exclude all case forms of their members. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
from |
1 |
string |
singular |
|
to |
2 |
string |
singular |
|
tenant |
3 |
string |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
from |
1 |
string |
singular |
|
to |
2 |
string |
singular |
|
Exactly one requirement is required, including an explicit count of zero.
Source
oneof kind: at most one member can be set.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
wanted |
1 |
uint32 |
optional |
For “all”, wanted excludes captured followers that are no longer live. |
serving |
2 |
uint32 |
optional |
|
outcome |
3 |
ReplicaResult.Outcome |
optional |
independent of local commit success |
Full catalog for a discovery cursor, scoped to this source boot.
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit |
1 |
string |
singular |
|
available |
2 |
bool |
singular |
|
tenant |
3 |
string |
singular |
|
collection |
4 |
string |
singular |
|
manifest_xxh3 |
5 |
string |
singular |
xxh3-64 of the exact manifest bytes of `commit`, as 16 lowercase hex digits (exact in every JSON client): a manifest of `commit` from any source must hash to it. |
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
follower |
1 |
string |
singular |
|
collection |
2 |
string |
singular |
|
commit |
3 |
string |
singular |
|
tenant |
4 |
string |
singular |
|
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
tenant |
1 |
string |
singular |
|
revision |
2 |
uint64 |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
query |
1 |
Query |
singular |
|
expr |
2 |
string |
singular |
|
vars |
3 |
map<string, Val> |
map |
|
min_score |
4 |
float |
optional |
Minimum rescored value. Documents whose expression output is below it do not match, in scored and unscored (filter) positions alike. Compared before any enclosing boost. Must be finite. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
path |
1 |
string |
singular |
|
max_doc |
2 |
int32 |
singular |
physical child rows, including rows of deleted roots |
ends_bytes |
3 |
uint64 |
singular |
payload, alignment and block directory |
owners_bytes |
4 |
uint64 |
singular |
zero when the reverse map is absent |
Reciprocal Rank Fusion: fused_score(d) = sum over sources s of weight_s / (k + rank_s(d)), where rank_s(d) is d’s 1-based rank in source s (sources without d contribute nothing) and weight_s comes from Fusion.weights.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
k |
1 |
int32 |
optional |
rank-smoothing constant, >= 0; unset selects 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. _version_ is fixed and retrieval-only: it returns the update version of the request that indexed each document, including allow_dups and documents without an ID. |
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. |
stored_resources |
4 |
map<string, StoredResourceDef> |
map |
Stored-field groups, keyed by the name fields use as stored_resource. A name is ‘_’, ASCII letters, digits, or underscores, and a closing ‘_’ (for example “_stored_body_”), so it never matches a field or suffix template. A field may name only an entry here or the default “_stored_”, which uses the defaults without one. mode=set replaces the named entries and keeps the others. |
Source
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit |
2 |
string |
singular |
exact snapshot published by a schema update |
schema |
1 |
SchemaDef |
singular |
the resulting schema after the operation |
replicas |
3 |
ReplicaResult |
singular |
|
Background checksum scrub of published snapshot files. A mismatch also makes its collection unavailable with the failing file in its error.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
passes |
1 |
uint64 |
singular |
completed passes over every collection |
files |
2 |
uint64 |
singular |
files checked |
bytes |
3 |
uint64 |
singular |
bytes read |
mismatches |
4 |
uint64 |
singular |
checksum mismatches, EIO, or unexpectedly missing files |
last_pass_end |
5 |
uint64 |
singular |
Unix milliseconds; absent before the first pass |
errors |
6 |
uint64 |
singular |
other file check errors; retried on the next pass |
What the adaptive segment fan-out (max_parallel 0) decided, process-wide. An evaluation is a fan-out point that had earned a grain of inline time and priced the children still to run; a search can evaluate several times, and can publish at one evaluation and be refused at a later one. Each evaluation that returns normally records one outcome, so published and the four refusals sum to those evaluations. Load means this process’s recent search and indexing work, not host CPU usage. Searches with max_parallel 1, -1 or -2 are not counted.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
parallel_searches |
1 |
uint64 |
singular |
Adaptive searches that published at least one share and completed their body without error. Its rate over the rate of all searches (search ok + error + cancelled, every max_parallel mode) estimates the fraction that published adaptively. |
published |
2 |
uint64 |
singular |
Evaluations that submitted shares. |
shares |
3 |
uint64 |
singular |
Shares those evaluations submitted, excluding the part the caller keeps. |
no_split |
4 |
uint64 |
singular |
Evaluations where the planner found no split of the measured remaining work: no shares that each cover search.fanout-grain-us plus their steal cost while leaving the caller a large enough share. Load was not read. |
capped |
5 |
uint64 |
singular |
The planner found a split at the grain and physical cores were idle, but it found none within the number of shares those idle cores allow. |
siblings_only |
6 |
uint64 |
singular |
The planner found a split at the grain, but only SMT siblings were idle: either search.fanout-sibling-grain-us is -1, or it found none under the sibling grain and the number of idle siblings. |
saturated |
7 |
uint64 |
singular |
The planner found a split at the grain, but the load signal found no idle logical CPU. |
A named search operation. The name is its key in the enclosing ops map.
Source
oneof kind: at most one member can be set.
| Field |
Number |
Type |
Cardinality / group |
Description |
top_docs |
1 |
TopDocs |
oneof kind |
|
fusion |
2 |
Fusion |
oneof kind |
|
field_facet |
8 |
FieldFacet |
oneof kind |
|
range_facet |
9 |
RangeFacet |
oneof kind |
|
query_facet |
10 |
QueryFacet |
oneof kind |
|
expr_op |
15 |
ExprOp |
oneof kind |
|
plugin |
16 |
PluginOp |
oneof kind |
an operation registered by a compiled-in plugin |
domain |
20 |
Domain |
singular |
optional override of the incoming document domain |
flags |
21 |
uint64 |
singular |
Overrides the parent’s packed options, including for this op’s domain, queries and facet literals. Subops inherit this op’s effective options. JSON uses the same lowercase flags name array as SearchRequest. |
flags_set |
22 |
uint64 |
singular |
Override mask. int64_str is request-only: bit 2 is rejected in both flags and flags_set, including an attempted clear. Other validation is the same as SearchRequest.flags_set. Naming date_native in JSON explicitly replaces an inherited date mode. |
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) starts on the receiving thread and adaptively uses idle cores after earning work credit. 1 runs serially on an arena worker; -1 publishes every sibling regardless of credit and load; -2 runs serially inline. gRPC and min_commit continuations start on arena workers for every value. search.fanout-grain-us defaults to 50 us; -1 disables adaptive publication. search.fanout-sibling-grain-us defaults to 1000 us when only SMT siblings are idle; -1 disables that tier. Other values of max_parallel are rejected. |
min_commit |
9 |
string |
singular |
Require a local snapshot at least this new (incarnation:index_gen). Writers reject a different incarnation immediately; followers wait for a switch. |
min_commit_timeout_ms |
10 |
uint64 |
optional |
Search floor deadline. Absent defaults to 30000; zero checks immediately. |
flags |
11 |
uint64 |
singular |
Packed request options. Effective = (inherited & ~flags_set) | (flags & flags_set); the request inherits 0. JSON uses lowercase names, e.g. “flags”: [“date_ms”], rather than numeric flags/flags_set. Date modes control numeric date literal units: ms or ns overrides the field unit; native and iso use the field unit. Value arithmetic is unchanged. |
flags_set |
12 |
uint64 |
singular |
Override mask. Set both date-mode bits (3), or neither. Request-only int64_str (bit 2) quotes JSON int64/uint64 values outside the safe integer range, +/- (2^53 - 1). Unknown bits are rejected in either word. Binary gRPC responses retain their integer types. |
Top-level response to a Search request
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
commit |
7 |
string |
singular |
token of the reader used for this response |
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 |
took_us |
8 |
uint64 |
singular |
Server-side wall time in microseconds from receipt of the complete request message until its final response is ready to serialize. Includes parsing, any min_commit wait, execution, and earlier streamed batches, including any pause while the client reads them. Excludes serializing, queueing, and sending the final response. Final response only. |
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” includes the creator epoch (e.g. “s0a.2”), while generations are the length-prefixed base36 sortable strings embedded in filenames (e.g. live_gen “01” written in epoch 3 -> file “s0a.2__L01.3”). 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
Process-wide service counters since start. Counters reset on restart and cache-control reset_counters does not touch them.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
version |
1 |
string |
singular |
|
cpu_target |
20 |
string |
singular |
The CPU target the binary was built for. |
source_commit |
23 |
string |
singular |
The full Git commit the binary was built from, or “unknown”. |
faiss_simd |
24 |
string |
singular |
The SIMD level FAISS selected for this CPU at startup: NONE, AVX2, AVX512, AVX512_VPOPCNT, AVX512_SPR, ARM_NEON or ARM_SVE. FAISS_SIMD_LEVEL overrides it. |
blas_core |
25 |
string |
singular |
The BLAS kernels selected for this CPU at startup: the OpenBLAS core name, or “Accelerate” on macOS. |
read_only |
2 |
bool |
singular |
|
request_duration_bounds |
3 |
double |
repeated |
Upper bounds, in seconds, of the request, search execution and index batch histograms. |
background_duration_bounds |
4 |
double |
repeated |
Upper bounds, in seconds, of the flush, commit, delete pass, merge, vector build and reader refresh histograms. |
http |
5 |
TransportStats |
singular |
|
grpc |
6 |
TransportStats |
singular |
|
search |
21 |
ActivityStats |
singular |
Searches the engine accepted, from submission to the final response. A gRPC Search call can carry many, so this is the per-search view there. |
search_execution |
7 |
HistogramStats |
singular |
Search body execution, excluding scheduler waits and streaming drains. |
search_resource_exhausted |
8 |
uint64 |
singular |
|
search_warnings |
9 |
uint64 |
singular |
|
index_batches |
10 |
ActivityStats |
singular |
|
documents_accepted |
11 |
uint64 |
singular |
Accepted into indexing (not durably acknowledged) or rejected/rolled back. |
documents_rejected |
12 |
uint64 |
singular |
|
delete_ids_accepted |
13 |
uint64 |
singular |
|
document_errors |
19 |
map<string, uint64> |
map |
Documents rejected with an error of their own, keyed by error kind. The rest of documents_rejected were rolled back with a failed batch. |
flush |
14 |
ActivityStats |
singular |
|
commit |
15 |
ActivityStats |
singular |
|
delete_pass |
22 |
ActivityStats |
singular |
Delete passes, which apply deletes between commits without flushing, syncing or publishing. |
merge |
16 |
ActivityStats |
singular |
|
vector_build |
17 |
ActivityStats |
singular |
|
reader_refresh |
18 |
ActivityStats |
singular |
|
control_threads |
60 |
uint64 |
singular |
The control executor (server.control_threads): administration, schema changes, collection lifecycle, replication transfers and timers, and detailed stats. |
control_busy |
61 |
uint64 |
singular |
tasks running now |
control_queued |
62 |
uint64 |
singular |
tasks waiting for a thread |
control_completed |
63 |
uint64 |
singular |
|
search_fanout |
26 |
SearchFanoutStats |
singular |
|
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
Which statistics to gather. The node scope (no collection, no tenant) always returns the cheap counters: service activity and node memory, read from atomics and allocator statistics. Anything that walks collections, lists directories, or reads the operating system is opt-in. A tenant or a collection scope always walks its collections and returns no node blocks.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
collection |
1 |
string |
singular |
Empty selects every collection of `tenant`, or of every tenant when `tenant` is also empty (administration). |
segments |
2 |
bool |
singular |
Per-segment records. Implies `files`, and `collections` at node scope. |
tenant |
3 |
string |
singular |
Administration only. With a collection, empty is the caller’s tenant. |
collections |
5 |
bool |
singular |
Node scope: also walk every collection (totals, index state, query cache, snapshot pins, inverters). Takes each writer’s index lock briefly; no file I/O. Implied by a tenant or collection scope. |
files |
6 |
bool |
singular |
Also list index directories, filling the `bytes` totals, segment bytes and aux index bytes. Implies `collections` at node scope. |
system |
7 |
bool |
singular |
Node scope only: this process, the data directory’s filesystem and the process’s cgroup v2, read from procfs and cgroupfs (Linux only). |
host |
8 |
bool |
singular |
Node scope only: host-wide CPU, memory, network, TCP, disk and pressure statistics from procfs (Linux only), which node_exporter also reports. Inside a container most of them describe the host, not the container. |
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
| Field |
Number |
Type |
Cardinality / group |
Description |
collections |
1 |
uint64 |
singular |
|
shards |
2 |
uint64 |
singular |
|
segments |
3 |
uint64 |
singular |
|
committed_segments |
4 |
uint64 |
singular |
|
max_docs |
5 |
uint64 |
singular |
|
live_docs |
6 |
uint64 |
singular |
|
deleted_docs |
7 |
uint64 |
singular |
|
bytes |
8 |
uint64 |
optional |
On-disk bytes from a directory listing, present only with StatsRequest.files: the whole index directory, including metadata and in-flight files. Compare committed_bytes. |
committed_bytes |
9 |
uint64 |
singular |
Bytes referenced by the current published snapshot, summed from its file descriptors without touching the filesystem. Excludes in-flight and pin-retained files, so it is normally below `bytes`. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
used_bytes |
1 |
uint64 |
singular |
Allocated RAM file buffers, including output and retained readers. |
limit_bytes |
2 |
uint64 |
singular |
Zero is unlimited. Independent of the indexing budget. |
Chunk settings for one stored-field group (a FieldDef stored_resource). Every setting is optional; absent selects the default. Changes apply to segments written afterwards. A merge recompresses its inputs unless their codec and chunk limits already match; the level alone does not count.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
codec |
1 |
StoredResourceDef.Codec |
optional |
Chunk compression; absent selects lz4. |
zstd_level |
2 |
int32 |
optional |
ZSTD level from 1 (fastest) to 22 (smallest). Absent selects 3. Only valid with codec zstd. |
chunk_size_bytes |
3 |
int32 |
optional |
Target uncompressed bytes per chunk, 1024 to 4194304; absent selects 16384, or 65536 with zstd. Larger chunks compress better, but each retrieval decompresses a whole chunk. |
max_docs_per_chunk |
4 |
int32 |
optional |
Most documents per chunk, 1 to 65536; absent selects 128, or 1024 with zstd. A chunk closes at whichever of the byte and document limits comes first. |
zstd_dictionary |
5 |
bool |
optional |
Enable one ZSTD dictionary per resource, shared by its segments. The first merge with at least 100 times the capacity (at most 8 MiB) of live stored data trains it; earlier segments have none. Helps most with small chunks; decoding can be slower with large chunks. No automatic retraining: changing this setting, the capacity or codec clears it for a later merge to retrain. After restart, use the dictionary from the largest live segment carrying one. Only valid with codec zstd. |
zstd_dictionary_bytes |
6 |
int32 |
optional |
Dictionary capacity upper bound, 1024 to 262144 bytes; absent selects 65536. Training can produce a smaller dictionary. Only valid with zstd_dictionary. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
a |
1 |
string |
singular |
|
b |
2 |
string |
singular |
|
tenant |
3 |
string |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
a |
1 |
string |
singular |
|
b |
2 |
string |
singular |
|
This process, its data filesystem and its cgroup. Collectors that read their sources are listed in `available`; the others in `unavailable`, with their fields omitted.
Source
TCP counters for this network namespace (/proc/net/snmp).
Source
Restricts which terms of a STRING or ID field can become ordinary buckets of a FieldFacet. Every set condition must hold (AND). Counts are exact: the filter chooses buckets after counting and never narrows the query domain, so it is not the same as adding a filter to the search. Terms are tested as indexed: prefix, regex, include, and exclude values are normalized the way the field normalizes query text, and ID fields use them verbatim.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
prefix |
1 |
string |
singular |
Keeps terms starting with this prefix. Empty = unset. |
regex |
2 |
string |
singular |
Keeps terms matching this regular expression in full, with RegexQuery syntax. Empty = unset. |
exclude_regex |
3 |
string |
singular |
Drops terms matching this regular expression in full. Empty = unset. |
include |
4 |
string |
repeated |
Keeps only these exact terms. An empty list is unset, so it cannot be used to match nothing. |
exclude |
5 |
string |
repeated |
Drops these exact terms. |
partition |
6 |
uint32 |
singular |
Keeps terms whose stable hash (64-bit FNV-1a of the indexed term bytes) modulo num_partitions equals partition, so num_partitions requests with partition 0..num_partitions-1 together return every term once. Unset when num_partitions is 0; otherwise partition must be below num_partitions. |
num_partitions |
7 |
uint32 |
singular |
|
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
path |
1 |
string |
singular |
|
query |
2 |
Query |
singular |
|
score |
3 |
string |
singular |
How matching child scores reduce to the owner’s score: max (default), min, sum, avg, or none (the join contributes zero). |
min_children |
4 |
int32 |
optional |
Fewest matching children an owner needs. Unset = 1; must be >= 1. |
max_children |
5 |
int32 |
optional |
Most matching children an owner may have. Unset = unbounded; must be >= min_children. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
row_ops |
26 |
map<string, SearchOp> |
map |
Operations evaluated on each returned row, with that row as incoming domain. |
decorate |
25 |
map<string, Val> |
map |
Plugin result decorators, executed only for emitted rows. |
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. |
count_limit |
5 |
sint64 |
optional |
Match count: unset or 0 omits found; -1 counts exactly; positive N permits stopping at N with found_gte; -2 asks for an estimate, like the estimate_count flag but for this list alone. The flag applies to an unset or positive count_limit, never to an explicit 0 or -1. An exact count is valid for every nonzero value. Must be >= -2. Ops, collapse, diversify, field sorts, nested lists and limit 0 retain exact counting. |
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; placement follows document_format. A name containing ‘*’ is a pattern expanded the same way: the matching retrievable fields; 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 |
placement of returned fields: rows, columns, or adaptive (see DocFormat) |
diversify |
12 |
Diversify |
singular |
Incompatible with collapse; found counts capped documents. |
collapse |
11 |
Collapse |
singular |
limit, offset and found count groups; found_docs counts eligible documents. |
min_score |
14 |
float |
optional |
Minimum score cut-off. When set, documents whose query score is below this value do not match: they are excluded from the returned documents, from the match count, and from the domain of ops (facets and metrics). The score compared is the query’s own relevance score (filters do not score), computed even when the request sorts by fields or does not return scores. Must be finite. As a Fusion source, the cut-off applies to that source’s ranked list. |
ops |
15 |
map<string, SearchOp> |
map |
sub-facets or search operations performed over docs that match this query. |
Request traffic on one transport. Replication routes are not counted.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
operations |
1 |
map<string, ActivityStats> |
map |
Keyed by operation: search, update, schema, collections, stats, health, other. |
errors |
2 |
map<string, uint64> |
map |
Failed requests or calls, keyed by the kind of their first error. A request fails when the transport fails, its response carries a whole-request error, or its stream ends in failure. |
received_bytes |
3 |
uint64 |
singular |
application payload, excluding transport framing |
sent_bytes |
4 |
uint64 |
singular |
application payload submitted for sending |
stream_pauses |
5 |
uint64 |
singular |
response producers paused by flow control |
connections |
6 |
uint64 |
singular |
HTTP only: live sessions, including idle keep-alive |
io_threads |
7 |
int64 |
singular |
HTTP only: running connection shard threads |
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 |
Documents to index. Input fields named _version_ after field mapping are rejected with a document error: the field is assigned by the engine and optimistic concurrency is not supported. |
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. |
commit |
8 |
string |
singular |
Resulting snapshot identity; absent without a completed commit. Snapshot token: incarnation:index_gen. |
replicas |
9 |
ReplicaResult |
singular |
|
commits |
10 |
map<string, CollectionCommit> |
map |
NDJSON URL EOF commit outcomes, including for a single collection. Any collection error sets the response status to ERROR and a top-level error; every admitted collection outcome is retained. HTTP status remains 200. |
took_us |
11 |
uint64 |
singular |
Server-side wall time in microseconds from receipt of the complete request message until its response is ready to serialize, including parsing and any commit and replica wait. Excludes serializing, queueing, and sending the response. HTTP NDJSON stream acknowledgments do not carry this field. |
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 |
|
Approximate nearest-neighbor index settings for a VECTOR field: the codec and parameters of the per-segment IVF overlays built at commit and merge. Read when an overlay is built; each overlay records what it was built with, so a change applies to segments built afterwards. See docs/guide/vector-search.md#index-settings.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
codec |
1 |
VectorAnnDef.Codec |
optional |
absent: rabitq; pq requires explicit selection |
nlist |
2 |
int32 |
optional |
IVF coarse lists per segment overlay. Absent or 0: sqrt(segment vectors), capped at 4096. Clamped to the segment’s vector count. |
rabitq |
3 |
VectorAnnDef.RaBitQ |
singular |
codec rabitq (the default) only |
pq |
4 |
VectorAnnDef.Pq |
singular |
requires explicit codec pq |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
m |
1 |
int32 |
optional |
Sub-quantizers. Positive m requires positive effective (inherited) dims and must divide it. Absent or 0: automatic, including inferred dims. Choose the largest divisor leaving at least 4 dimensions per sub-quantizer, capped at max(32, dims / 8) for every metric. If none does, choose the largest divisor under the same cap. |
bits |
2 |
int32 |
optional |
bits per sub-quantizer code, 1..8. Absent: 8. |
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
bits |
1 |
int32 |
optional |
Bits per dimension, 0..9. Absent or 0: 2 below 384 stored dims, 1 at or above. Above 1 (extended RaBitQ) a 1-bit pass prunes with the error bound and survivors are re-estimated with the extra bits. |
query_bits |
2 |
int32 |
optional |
Query quantization bits, 0..8; 0 scans with the float query. Absent: 4. Read at search time, so a change applies to existing overlays. |
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 |
One search field and its weight. TEXT weights scale term frequency and length in COMBINED; all other weights multiply the field’s score. JSON also accepts a bare field name or “name^weight” as shorthand.
Source
| Field |
Number |
Type |
Cardinality / group |
Description |
field |
1 |
string |
singular |
|
weight |
2 |
float |
optional |
Unset = 1. Must be finite and > 0 in every mode. |
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 |
|
case_insensitive |
3 |
bool |
singular |
Literal characters, after field folding, also match their simple Unicode case alternates (lower, upper and title forms). |
Source
Source
| Value |
Number |
Description |
EXPAND |
0 |
Each document missing any component is a tagged singleton. |
GROUP |
1 |
Preserve present tuple components and tag missing ones as null. |
DROP |
2 |
Exclude documents missing any component. |
Placement of returned document fields: dense columns (DocList.columns) or per-document maps (DocList.docs). A document is the merge of columns row i and docs[i]; a field is never in both. A missing value is an absent key in docs[i] or the column’s missing sentinel. A field with no value in a batch is left out of that batch, except a named field under COLUMNS, whose column is present in every batch. DEFAULT resolves per transport: HTTP/JSON -> ROWS, gRPC -> COLUMNS.
Source
| Value |
Number |
Description |
DEFAULT |
0 |
|
ROWS |
1 |
every field in docs |
COLUMNS |
2 |
every field as a column |
ADAPTIVE |
3 |
per batch and field, whichever encodes the batch more compactly |
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) |
DATE only: unit of numeric ingest and stored epoch values. ISO-8601 text is converted to this precision, truncating toward earlier time. NS reserves the int64 extrema and covers 1677-09-21 to 2262-04-11. The unit is part of the field signature and cannot change on an existing date definition. Absent inherits from the parent, falling back to ms.
Source
| Value |
Number |
Description |
MS |
0 |
milliseconds |
NS |
1 |
nanoseconds |
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 units since the Unix epoch (see unit) |
GEO_POINT |
9 |
latitude/longitude point |
BOOLEAN |
11 |
true/false, stored as 0/1 in the int column |
IP |
12 |
IPv4 or IPv6 address, stored as 16-byte terms |
DECIMAL |
13 |
fixed-point number, stored as int64 value * 10^scale |
NESTED |
14 |
structural path of nested object rows |
LONG_RANGE |
18 |
Single-valued intervals written as {“gte”|“gt”: a, “lte”|“lt”: b}; either side may be omitted for an open end. Ingest rejects fractional long endpoints, out-of-domain endpoints, NaN, and empty intervals. Partial dates name their whole granule, in UTC without an explicit offset. index=range adds a query index; index=none is the default. match and explicit multi_match selectors are supported; wildcard field selectors do not select range fields. Multi-valued ranges are unsupported.
int64 endpoints |
DOUBLE_RANGE |
19 |
double endpoints |
DATE_RANGE |
20 |
DATE endpoints (epoch millis, ISO-8601 or date math) |
Index acceleration. Numeric Match/Range and geographic predicates can scan a column with NONE. Term queries on STRING/TEXT/ID/IP 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, GEO_POINT or range-field 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 |
SINGLE is one value; DEFAULT enables the type’s default multi mode. SET sorts and deduplicates column values; ARRAY keeps their source order and repeats. Stored source keeps order and repeats independently of the column mode. DEFAULT resolves per representation: INT/FLOAT/DOUBLE/DATE/STRING use SET, TEXT/VECTOR/GEO_POINT use ARRAY. Explicit SET is rejected on an array-only primary and resolves to ARRAY on an array-only variant. Explicit ARRAY applies to every representation. ID is reserved for the single-valued id field. Variants inherit the declared mode and cannot override it. Schema JSON views echo the declaration. HTTP JSON accepts false, true (DEFAULT), “set”, or “array”.
Source
Source
| Value |
Number |
Description |
DOCS |
0 |
Count documents. |
GROUPS |
1 |
Distinct keys of the nearest enclosing collapsed list. |
Source
Source
| Value |
Number |
Description |
MIN_MAX |
0 |
(score - min) / (max - min) over the source’s ranked list, so its best document gets 1 and its worst gets 0. A list whose scores are all equal (including a single document) normalizes every document to 1. NaN scores contribute 0 and are left out of min and max; +inf normalizes to 1 and -inf to 0. |
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
| Value |
Number |
Description |
COMBINED |
0 |
TEXT weights scale term frequency and document length at every group size. Other fields are singleton groups with multiplicative weights. |
PER_FIELD |
1 |
One match or phrase per field; each weight multiplies its score. |
Whether the extent is explicit or derived from this facet instance’s values.
Source
| Value |
Number |
Description |
EXPLICIT |
0 |
start and end are required. Fixed DATE grids use the local time of start as their phase; calendar grids step from start for every n. The last fence is clipped to end. |
DATA |
1 |
Span the smallest through largest matching finite values, plus optional start/end widening. Queries, filters and deletions affect the extent; each parent bucket’s child histogram has its own span. Occupancy is from raw values, even when a distinct key is dropped and its measured count is zero. Empty domains return no buckets unless both widening bounds supply a span. NaN/Inf are outside every bucket and never fail DATA. Calendar grids use the 1970 civil epoch (ISO weeks: Monday 1969-12-29); a civil day starts at its first midnight, or first valid instant. selected is unsupported. The 100000-bucket cap applies to the actual span including widening and empty interior cells; use a larger gap. |
Source
| Value |
Number |
Description |
INTERSECTS |
0 |
the stored interval overlaps the query interval |
CONTAINS |
1 |
the stored interval covers the whole query interval |
WITHIN |
2 |
the stored interval lies inside the query interval |
Source
Source
Bit positions in the packed request option word, not masks. The two date bits form one field: native=0, iso=1, ms=2, ns=3.
Source
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 |
LZ4 |
0 |
fast compression and decompression |
ZSTD |
1 |
smaller chunks for repetitive text such as logs, at more CPU |
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. |
Source
| Value |
Number |
Description |
RABITQ |
0 |
IVF + RaBitQ (randomly rotated, centroid-relative bit codes) |
PQ |
1 |
IVF + product quantization |
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`.