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 で定義したエンベッダー名を指定します。設定すると、インデックス時にドキュメントのテキストフィールドからベクトルを自動生成します。事前計算済みのベクトルを直接供給する場合は空のままにします。

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

量子化手法: SCALAR_8BIT（デフォルト）, PRODUCT_QUANTIZATION（Issue #481 Stage 3 で予約、現状 Unimplemented）

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 のみのランキングになります。スキーマの round-trip 整合のため FlatOption / IvfOption にも保持されますが、これらのインデックスはまだサイドカーを出力しません。

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 と同じです。

GetDocuments

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

rpc GetDocuments(GetDocumentsRequest) returns (GetDocumentsResponse);

リクエストフィールド:

レスポンスフィールド:

DeleteDocuments

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

rpc DeleteDocuments(DeleteDocumentsRequest) returns (DeleteDocumentsResponse);

Commit

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

rpc Commit(CommitRequest) returns (CommitResponse);

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

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
  }
}

エラーハンドリング

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