gRPC API リファレンス

すべてのサービスは laurus.v1 protobuf パッケージで定義されています。

サービス一覧

HealthService

Check

サーバーの現在のサービング状態を返します。

rpc Check(HealthCheckRequest) returns (HealthCheckResponse);

レスポンスフィールド:

IndexService

CreateIndex

指定されたスキーマで新しいインデックスを作成します。インデックスが既に開いている場合は ALREADY_EXISTS エラーを返します。

rpc CreateIndex(CreateIndexRequest) returns (CreateIndexResponse);

リクエストフィールド:

Schema 構造:

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

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

• fields — フィールド名をキーとしたフィールド定義。
• default_fields — クエリでフィールドを指定しない場合のデフォルト検索対象フィールド名。
• analyzers — 名前をキーとしたカスタムアナライザーパイプライン。TextOption.analyzer で参照。
• embedders — 名前をキーとしたエンベッダー設定。ベクトルフィールドオプション（HnswOption.embedder など）で参照。
• dynamic_field_policy — 投入されたドキュメントに含まれるが fields に宣言されていないフィールドの扱い。UNSPECIFIED（値 0）は後方互換のため DYNAMIC として解釈されます。挙動マトリクスおよび DYNAMIC での情報損失警告は スキーマとフィールド を参照してください。

AnalyzerDefinition:

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

ComponentConfig（文字フィルター、トークナイザー、トークンフィルターに使用）:

EmbedderConfig:

各 FieldOption は以下のフィールドタイプのいずれかを持つ oneof です。

ベクトルフィールドオプションの embedder フィールドには、Schema.embedders で定義したエンベッダー名を指定します。設定すると、インデックス時にドキュメントのテキストフィールドからベクトルを自動生成します。事前計算済みのベクトルを直接供給する場合は空のままにします。

Doc values: doc_values（Issue #1047）は、上記の BytesOption を除く全ての lexical オプションで optional bool であり、term_vectors と同じ tri-state の契約に従います。クライアントが省略するとエンジンのデフォルト（true）になり、明示的な false とは区別されます。フィールドの値を DocValues（ソート・ファセット・集計が読み取る列指向ストア）にもコピーするかどうかを制御し、DocValues 列が書き込まれるのは stored と doc_values の両方が true の場合のみです。BytesOption にはこのフィールドがありません —— Bytes の値は設定にかかわらず DocValues に一切書き込まれないためです。ソートにもファセットにも使わないフィールドで doc_values を無効にするとセグメントの使用容量が削減されます。フィールド自体は引き続き完全に検索・取得可能です。

多値地理・多値日時・多値ブール・多値テキスト・多値バイト（multi-valued geo, datetime, boolean, text and bytes）: GeoOption / Geo3dOption（Issue #1174）、DateTimeOption（Issue #1184）、および BooleanOption（Issue #1180）の multi_valued は proto のフィールド番号 4 です（IntegerOption / FloatOption と異なり、3 は既に doc_values が使用しているため）。TextOption（Issue #1175）ではフィールド番号 6 です（Text は 3〜5 を既に term_vectors・analyzer・doc_values に使用しているため）。BytesOption（Issue #1176）ではフィールド番号 2 です（1 は既に stored が使用しており、BytesOption には indexed も doc_values もありません）。true にすると地理フィールドは GeoArrayValue / Geo3dArrayValue（後述の Value 表を参照）を受け付け、距離 / バウンディングボックスクエリ（および geo3d_nearest）はいずれかのポイントが条件を満たせばドキュメントにマッチし、最も近いポイントでスコアリングされます。日時フィールドは DatetimeArrayValue（repeated int64。datetime_value と同じ UTC の Unix マイクロ秒）を受け付け、範囲クエリはいずれかの時刻が範囲内にあればドキュメントにマッチします（スコアは constant。複数の時刻がマッチしてもドキュメントは 1 回だけ報告されます）。ブールフィールドは BoolArrayValue（repeated bool）を受け付け、term クエリはいずれかの要素がクエリの値と等しければドキュメントにマッチします。各要素はそれぞれ独立した true / false の term posting としてインデックスされ（ブールに BKD ポイントはありません）、要素の重複はヒット数ではなく term frequency（したがって BM25 スコア）を増やします。テキストフィールドは TextArrayValue（repeated string）を受け付け、term クエリはいずれかの要素がタームを含めばドキュメントにマッチします。position_increment_gap（フィールド 7、optional uint32）は連続する要素の間に挿入される位置数で、slop がこの値に達しない限りフレーズクエリが 2 つの要素をまたがないようにします。term_vectors / doc_values と同じ理由で optional になっており、省略時は 0 ではなくエンジンのデフォルト（100）を意味します。バイトフィールドは BytesArrayValue（repeated bytes）を受け付けますが、Bytes の値はそもそもレキシカルインデックスされないため “any match” のクエリ意味論は一切なく、保存時・ワイヤ上の形と取り込み時の許容個数を変えるだけです。また、スカラーの bytes_value と同じく、DataValue::BytesArray が持つ要素ごとの MIME タイプはワイヤ上に表現されません。

MultiVector フィールド: MultiVectorOption（FieldOption のフィールド番号 12、Issue #1177）は、文書ごとのトークンベクトル（ColBERT 型のトークンごとの埋め込みなど）を late interaction の再採点のために保持するフィールドを宣言します。ANN 索引は持たず、ベクトル検索の対象にはなりません。query_vectors でこのフィールドを指定すると拒否されます。distance は COSINE（書き込み時に L2 正規化する）か DOT_PRODUCT でなければなりません。値は VectorArrayValue（下の Value の表を参照）です。このフィールドは保存されないため、サーバーが返す文書には含まれません。embedder（フィールド番号 3、Issue #1349）には、Schema.embedders で宣言したトークン単位のエンベッダー（"candle_colbert"）の名前を指定します。指定すると、文書はこのフィールドに text_value を与えられ、テキストはトークンベクトルに埋め込まれます。MultiVector フィールドに置けるのは "candle_colbert" か "precomputed" のエンベッダーだけで、他のベクトルフィールドには "candle_colbert" を置けません。

MultiVector のストレージ: オプションの storage フィールド（フィールド番号 4、enum MultiVectorStorage、Issue #1346）は、各トークンベクトルのディスク上の要素形式を選びます。UNSPECIFIED は F32 と同じ、F32（デフォルト。4 バイト/要素、誤差なし）、F16（2 バイト/要素、要素あたり相対誤差 ~2⁻¹¹）、INT8（約 1 バイト/要素に加えてベクトルごとの小さなスケールのオーバーヘッド — 1 行あたり dimension + 2 バイト — ベクトルごとのスケール max(abs(vector)) / 127 を使用し、セグメント単位やコーパス全体で学習するものではありません）のいずれかです。300 トークン × 128 次元（F32 で約 150 KB/文書）の場合、F16 は約 75 KB/文書、INT8 は約 38 KB/文書になります。未設定時は F32 のままです。

距離メトリクス: COSINE, EUCLIDEAN, MANHATTAN, DOT_PRODUCT, ANGULAR

量子化手法: SCALAR_8BIT（デフォルト）, PRODUCT_QUANTIZATION（Issue #481 Stage 3。HNSW インデックスがサポート — Flat / IVF は書き込み時に拒否）

NONE（量子化なし）は Issue #481 Stage 1 で廃止されました。proto enum 値 0（QUANTIZATION_METHOD_NONE）は wire 互換のため予約されていますが、サーバ側で受信すると Default::default()（SCALAR_8BIT）にフォールバックします。

Rerank storage: オプションの rerank_storage フィールド（enum RerankStorageKind: UNSPECIFIED = サイドカーなし、F32）は Stage-2 rerank サイドカー（Issue #481 / #793）を有効化します。HNSW フィールドで F32 を設定すると、commit 時に完全精度の .hnsw.f32 サイドカーを追加で書き出し、rerank_factor を指定した検索が int8 候補を元のベクトルで再スコアします。フィールドを省略（または UNSPECIFIED）すると Stage-1 の int8 のみのランキングになります。#932 以降、サイドカーは 3 つのベクトルインデックスタイプ（HNSW / Flat / IVF）すべてで出力・利用されます（Flat / IVF の再スコアはフィールド指定クエリに適用）。

共有 PQ codebook: HnswOption のオプションフィールド pq_codebook_path（Issue #631）は、laurus train pq-codebook CLI コマンドで一度だけ学習するストレージ相対の共有 PQ codebook ファイルを指定します。設定すると segment は commit / merge のたびに k-means を再学習する代わりに、学習済み codebook で encode されます。PRODUCT_QUANTIZATION quantizer との組み合わせでのみ意味を持ち、設定済みで未学習の場合、commit は学習コマンドを示すエラーで失敗します（per-segment 学習への無言のフォールバック無し）。未設定なら per-segment 学習のままです。

Base weight: HnswOption/FlatOption/IvfOption の base_weight は optional float（Issue #1084）です。クライアントが省略するとエンジンのデフォルト（1.0）が使われ、これは明示的な 0.0 とは区別されます。他の vector フィールドと同時にクエリ対象になったときの、そのフィールドの相対的なスコアリング優先度を設定します。何に効いて何に効かないかはウェイトを参照してください。

QuantizationConfig 構造:

例:

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

GetIndex

インデックスの統計情報を取得します。

rpc GetIndex(GetIndexRequest) returns (GetIndexResponse);

レスポンスフィールド:

各 VectorFieldStats には vector_count と dimension が含まれます。

GetSchema

現在のインデックススキーマを取得します。

rpc GetSchema(GetSchemaRequest) returns (GetSchemaResponse);

レスポンスフィールド:

AddField

稼働中のインデックスにフィールドを動的に追加します。

rpc AddField(AddFieldRequest) returns (AddFieldResponse);

リクエストフィールド:

レスポンスフィールド:

HTTP ゲートウェイ: POST /v1/schema/fields

DeleteField

稼働中のインデックスからフィールドを動的に削除します。既にインデックスされたデータは残りますが、削除されたフィールドにはアクセスできなくなります。

rpc DeleteField(DeleteFieldRequest) returns (DeleteFieldResponse);

message DeleteFieldRequest {
  string name = 1;
}

message DeleteFieldResponse {
  Schema schema = 1;
}

リクエストフィールド:

レスポンス: 更新後の Schema を返します。

DocumentService

PutDocument

ID を指定してドキュメントを挿入または置換します。同じ ID のドキュメントが既に存在する場合は置換されます。

rpc PutDocument(PutDocumentRequest) returns (PutDocumentResponse);

リクエストフィールド:

Document 構造:

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

各 Value は以下の型のいずれかを持つ oneof です。

Geo3dPoint:

座標系の詳細および wgs84_to_ecef / ecef_to_wgs84 の変換ユーティリティについては 3D 地理検索 (ECEF) を参照してください。

AddDocument

ドキュメントを追加します。PutDocument と異なり、同じ ID の既存ドキュメントを置換しません。複数のドキュメントが同じ ID を共有できます（チャンキングパターン）。

rpc AddDocument(AddDocumentRequest) returns (AddDocumentResponse);

リクエストフィールドは PutDocument と同じです。

PutDocuments

バッチ Upsert。エントリは入力順に逐次適用され、バッチ全体で WAL fsync は 1 回です — ドキュメントごとに PutDocument を呼ぶよりはるかに高速です。1 バッチ内で重複した ID は、同じ put を 1 件ずつ発行した場合とまったく同じようにデデュープされます（最後の出現が勝ち）。

rpc PutDocuments(PutDocumentsRequest) returns (PutDocumentsResponse);

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

message PutDocumentsRequest {
  repeated DocumentEntry documents = 1;
}

message PutDocumentsResponse {
  uint32 applied = 1; // 成功時はリクエストサイズと一致
}

適用できない最初のエントリで fail-fast します。適用済みエントリはロールバックされず（次のコミットで永続化）、エラーステータスのメッセージに失敗位置・その ID・適用済み件数が含まれるため、バッチ（またはその suffix）の再試行は冪等です。呼び出し側の誤り（スキーマ違反など）で失敗したバッチは INVALID_ARGUMENT、ストレージ障害は INTERNAL を返します。

AddDocuments

バッチチャンク追加。PutDocuments と同様ですが既存ドキュメントを削除しないため、同一論理ドキュメントの複数チャンクを追加する目的で ID をバッチ内で繰り返せます。

rpc AddDocuments(AddDocumentsRequest) returns (AddDocumentsResponse);

リクエスト/レスポンスのフィールドは PutDocuments と対になります。

GetDocuments

指定された外部 ID に一致するすべてのドキュメントを取得します。

rpc GetDocuments(GetDocumentsRequest) returns (GetDocumentsResponse);

リクエストフィールド:

レスポンスフィールド:

DeleteDocuments

指定された外部 ID に一致するすべてのドキュメントを削除します。

rpc DeleteDocuments(DeleteDocumentsRequest) returns (DeleteDocumentsResponse);

Commit

保留中の変更（追加および削除）をインデックスにコミットします。コミットされるまで、変更は検索に反映されません。

rpc Commit(CommitRequest) returns (CommitResponse);

FlushWal

バッファされた WAL レコードを full commit なしで durable 化します。両メッセージとも空です。デフォルトの per-record sync ポリシーでは near no-op です（各書き込みは既に fsync 済み）。グループコミットポリシーでは、現在の partial batch をオンデマンドで flush し、クラッシュ時の損失窓を抑えます。Commit と異なりセグメントを materialize しないため、バッファされた変更は後続の Commit まで検索に反映されません。

rpc FlushWal(FlushWalRequest) returns (FlushWalResponse);

message FlushWalRequest {}

message FlushWalResponse {}

WAL の耐久性ポリシーはサーバ側の [index.wal] 設定セクションで構成します。設定 → [index.wal] セクション および 永続化と WAL → WAL 耐久性ポリシー を参照してください。

HTTP ゲートウェイ: POST /v1/flush_wal

SearchService

Search

検索クエリを実行し、結果を単一のレスポンスとして返します。

rpc Search(SearchRequest) returns (SearchResponse);

レスポンスフィールド:

SearchStream

検索クエリを実行し、結果を 1 件ずつストリーミングで返します。

rpc SearchStream(SearchRequest) returns (stream SearchResult);

SearchRequest フィールド

query または query_vectors のいずれか 1 つ以上を指定する必要があります。

3D 地理クエリ

3D ECEF の地理クエリは SearchRequest.query に渡す Lexical DSL 文字列で表現します。専用のメッセージ型はなく、コアライブラリで使用される DSL 形式がそのまま gRPC 経由でも動作します。3 種類の形式があります（構文の詳細は Query DSL → 3D 地理クエリ を参照）:

• position:geo3d_distance(x, y, z, distance_m) — (x, y, z) を中心とした最大距離（メートル単位）の球
• position:geo3d_bbox(min_x, min_y, min_z, max_x, max_y, max_z) — 3D 軸並行バウンディングボックス
• position:geo3d_nearest(x, y, z, k) — (x, y, z) に最も近い k 個の近傍点

position はフィールド名で、スキーマで宣言した実際の Geo3d 型フィールドに置き換えてください。すべての数値引数は符号付きの double 値で、k は符号なし整数です。

QueryVector

FusionAlgorithm

以下の 2 つのオプションを持つ oneof です。

• RRF (Reciprocal Rank Fusion): k パラメータ（デフォルト: 60）
• WeightedSum: lexical_weight と vector_weight

LexicalParams

SortSpec

VectorParams

HighlightParams

指定したフィールドのハイライト済みフラグメントを要求します（Issue #1134）。ハイライトは SearchRequest.query（DSL クエリの lexical 節）— つまり lexical スコアリングを駆動するのと同じクエリ — によって行われます。filter_query はハイライト対象の語を提供せず、lexical クエリを持たない Vector-only のリクエストはハイライトを生成しません。stored: true のテキストフィールドのみハイライト可能で、それ以外のフィールド名は黙ってスキップされます。詳細な意味論はハイライトを参照してください。

Highlights

RescoreParams

1 段目（lexical・vector・ハイブリッド）の上位 window_size 件を、MultiVector フィールドに対する ColBERT 型の late interaction で並べ替えます（Issue #1351）。 採点と並び順の規則は late interaction による再採点 を参照してください。

LateInteractionRescore:

値はエンジンが検査します。範囲外の window、MultiVector でないフィールド、 ベクトルの本数や次元の誤り、トークン単位のエンベッダーがないフィールドへの テキスト、lexical_params.sort_by との併用は、INVALID_ARGUMENT で拒否されます。 late_interaction やクエリのない RescoreParams も同じです。

SearchResult

例

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

例: ハイライト

{
  "query": "body:rust",
  "limit": 10,
  "highlight": {"fields": ["body"], "max_fragments": 2, "tag": "em"}
}

マッチしたヒットの SearchResult は以下のようになります。

{
  "id": "doc1",
  "score": 1.2,
  "document": {"fields": {"body": {"text_value": "Rust is great"}}},
  "highlights": {"body": {"fragments": ["<em>Rust</em> is great"]}}
}

例: 再採点

ハイブリッドの 1 段目の上位 100 件を、body_colbert の ColBERT エンベッダーで 再採点します。

{
  "query": "body:lifetimes body_vec:\"how do lifetimes work\"",
  "limit": 10,
  "rescore": {
    "window_size": 100,
    "late_interaction": {"field": "body_colbert", "text": "how do lifetimes work"}
  }
}

テキストの代わりに、計算済みのクエリのトークンベクトルを渡す場合:

{
  "late_interaction": {
    "field": "body_colbert",
    "vectors": {"dimension": 2, "values": [1.0, 0.0, 0.0, 1.0]}
  }
}

エラーハンドリング

gRPC エラーは標準の Status コードとして返されます。