コマンドリファレンス

グローバルオプション

すべてのコマンドで以下のオプションが使用できます:

# 例: カスタムデータディレクトリで JSON 出力を使用
laurus --index-dir /var/data/my_index --format json search "title:rust"

create — リソースの作成

create index

新しいインデックスを作成します。--schema が指定された場合はその TOML ファイルを使用し、省略された場合は対話型スキーマウィザードが起動します。

laurus create index [--schema <FILE>] [--train-pq-codebook <JSONL>]

引数:

スキーマファイルの形式:

スキーマファイルは Laurus ライブラリの Schema 型と同じ構造に従います。詳細はスキーマフォーマットリファレンスを参照してください。例:

default_fields = ["title", "body"]

[fields.title.Text]
stored = true
indexed = true

[fields.body.Text]
stored = true
indexed = true

[fields.category.Text]
stored = true
indexed = true

例:

# スキーマファイルから作成
laurus --index-dir ./my_index create index --schema schema.toml
# Index created at ./my_index.

# 対話型ウィザード（--schema フラグなし）
laurus --index-dir ./my_index create index
# === Laurus Schema Generator ===
# Field name: title
# ...
# Index created at ./my_index.

# 作成と共有 PQ codebook の学習を1ステップで（Issue #920）
laurus --index-dir ./my_index create index --schema schema.toml \
    --train-pq-codebook train.jsonl
# Index created at ./my_index.
# Training PQ codebook for field 'embedding' on 300 vectors...
# Trained codebook 'embedding.pqcb' (m = 4, k = 256, sub_dim = 8, dimension = 32) from 300 vectors.

注意: schema.toml と store/ の両方が存在する場合はエラーが返されます。再作成するにはインデックスディレクトリを削除してください。schema.toml のみ存在する場合（作成が中断された場合など）は、--schema なしで create index を実行すると既存スキーマからストレージが復旧されます。

create schema

対話式ウィザードを通じてスキーマ TOML ファイルを生成します。

laurus create schema [--output <FILE>]

引数:

ウィザードは以下の手順で進みます:

1. フィールド定義 — フィールド名を入力し、型を選択し、型固有のオプションを設定
2. 繰り返し — 必要な数だけフィールドを追加
3. デフォルトフィールド — デフォルトの検索対象とする Lexical フィールドを選択
4. プレビュー — 保存前に生成された TOML を確認
5. 保存 — スキーマファイルを書き出し

サポートされるフィールド型:

例:

# schema.toml を対話的に生成
laurus create schema

# 出力パスを指定
laurus create schema --output my_schema.toml

# 生成されたスキーマからインデックスを作成
laurus create index --schema schema.toml

get — リソースの取得

get stats

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

laurus get stats

テーブル出力の例:

Document count: 42

Vector fields:
╭──────────┬─────────┬───────────╮
│ Field    │ Vectors │ Dimension │
├──────────┼─────────┼───────────┤
│ text_vec │ 42      │ 384       │
╰──────────┴─────────┴───────────╯

JSON 出力の例:

laurus --format json get stats

{
  "document_count": 42,
  "fields": {
    "text_vec": {
      "vector_count": 42,
      "dimension": 384
    }
  }
}

get schema

現在のインデックスのスキーマを JSON 形式で表示します。

laurus get schema

例:

laurus get schema
# {
#   "fields": { ... },
#   "default_fields": ["title", "body"],
#   ...
# }

get docs

外部 ID で全ドキュメント（チャンクを含む）を取得します。

laurus get docs --id <ID>

テーブル出力の例:

╭──────┬─────────────────────────────────────────╮
│ ID   │ Fields                                  │
├──────┼─────────────────────────────────────────┤
│ doc1 │ body: This is a test, title: Hello World │
╰──────┴─────────────────────────────────────────╯

JSON 出力の例:

laurus --format json get docs --id doc1

[
  {
    "id": "doc1",
    "document": {
      "title": "Hello World",
      "body": "This is a test document."
    }
  }
]

add — リソースの追加

add doc

インデックスにドキュメントを追加します。ドキュメントは commit を実行するまで検索対象になりません。

laurus add doc --id <ID> --data <JSON>

引数:

JSON はドキュメントの serde 形式です: fields オブジェクトの各フィールド名に、外部タグ付きの値（Text・Int64・Float64・Bool・VectorValue など）を対応付けます。

{
  "fields": {
    "title": {"Text": "Introduction to Rust"},
    "body": {"Text": "Rust is a systems programming language."},
    "year": {"Int64": 2024}
  }
}

例:

laurus add doc --id doc1 --data '{"fields":{"title":{"Text":"Hello World"},"body":{"Text":"This is a test document."}}}'
# Document 'doc1' added. Run 'commit' to persist changes.

ヒント: 複数のドキュメントが同じ外部 ID を共有できます（チャンキングパターン）。各チャンクに対して add doc を使用してください。

add docs

JSONL ファイルからドキュメントチャンクをバルク追加します — 1 行に 1 エントリの {"id": "...", "document": {"fields": {...}}} 形式で、document は add doc --data と同じ JSON 形式です。エントリはエンジンのバッチ API（バッチごとに WAL fsync 1 回）で適用され、add doc と異なり自動的にコミットします（--commit-every 件ごと + 最後に 1 回）。

laurus add docs --file <JSONL> [--batch-size 1000] [--commit-every 0]

引数:

繰り返した ID はチャンクとして蓄積されます。途中で失敗した場合、エラーは該当行を示し、適用済みの prefix はコミットされるため、残りの行から再実行してインジェストを継続できます。

put — リソースの上書き（Upsert）

put doc

インデックスにドキュメントを上書き（upsert）します。同じ ID のドキュメントが既に存在する場合、全チャンクが削除されてから新しいドキュメントがインデックスされます。ドキュメントは commit を実行するまで検索対象になりません。

laurus put doc --id <ID> --data <JSON>

引数:

例:

laurus put doc --id doc1 --data '{"fields":{"title":{"Text":"Updated Title"},"body":{"Text":"This replaces the existing document."}}}'
# Document 'doc1' put (upserted). Run 'commit' to persist changes.

注意: add doc とは異なり、put doc は指定 ID の既存チャンクをすべて置き換えます。チャンクを追記したい場合は add doc を、ドキュメント全体を置き換えたい場合は put doc を使用してください。

put docs

JSONL ファイルからドキュメントをバルク Upsert します — 1 行に 1 エントリの {"id": "...", "document": {"fields": {...}}} 形式で、エンジンのバッチ API（バッチごとに WAL fsync 1 回）で適用されます。重複した ID は順にデデュープされます（最後の出現が勝ち）。add docs と同じく自動的にコミットします。

laurus put docs --file <JSONL> [--batch-size 1000] [--commit-every 0]

引数は add docs と同じです。途中で失敗した場合、エラーは該当行を示し、適用済みの prefix はコミットされます。put は冪等なので、ファイル全体（または残りの suffix）の再実行は安全です。

例:

cat > docs.jsonl <<'JSONL'
{"id": "doc1", "document": {"fields": {"title": {"Text": "Hello"}}}}
{"id": "doc2", "document": {"fields": {"title": {"Text": "World"}}}}
JSONL
laurus put docs --file docs.jsonl
# 2 documents put (upserted) and committed.

add field

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

laurus add field --index-dir ./data \
    --name category \
    --field-option '{"Text": {"indexed": true, "stored": true}}'

--field-option 引数はスキーマファイルと同じ外部タグ付き JSON 形式を受け付けます。 フィールド追加後、スキーマは自動的に永続化されます。

delete — リソースの削除

delete field

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

laurus delete field --name <FIELD_NAME>

例:

laurus delete field --name category
# Field 'category' deleted.

delete docs

外部 ID で全ドキュメント（チャンクを含む）を削除します。

laurus delete docs --id <ID>

例:

laurus delete docs --id doc1
# Documents 'doc1' deleted. Run 'commit' to persist changes.

commit

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

laurus commit

例:

laurus --index-dir ./my_index commit
# Changes committed successfully.

train

train pq-codebook

HNSW ベクトルフィールド用の共有 PQ codebook を学習します （Issue #631）。codebook を代表サンプルで一度だけ学習し、以後の commit と merge のすべてで再利用します — segment ごとの k-means 再学習が無くなるため PQ フィールドの commit は大幅に高速化し、 小さな per-commit segment も PQ を維持します。

laurus train pq-codebook --field <FIELD> (--input <JSONL> | --from-index) \
    [--sample-size <N>] [--output <NAME>] [--update-schema]

commit が codebook を使うのは、スキーマの pq_codebook_path が そのファイルを指している場合のみです（スキーマ形式 参照）— 学習と同時に設定するには --update-schema を渡してください。 pq_codebook_path が設定済みで codebook が未学習のまま commit すると、本コマンドを示すエラーで失敗します（per-segment 学習への 無言のフォールバックはありません）。codebook は index open 時に 読み込まれるため、ingest する add / put / commit の前に 学習してください（CLI は呼び出しごとに index を開き直すため、 以後のコマンドはすべて反映済みです）。

例:

cat > train.jsonl <<'JSONL'
{"id": "t1", "document": {"fields": {"embedding": {"Vector": [0.1, 0.2, 0.3, 0.4]}}}}
{"id": "t2", "document": {"fields": {"embedding": {"Vector": [0.5, 0.6, 0.7, 0.8]}}}}
JSONL
laurus train pq-codebook --field embedding --input train.jsonl --update-schema
# Training PQ codebook for field 'embedding' on 2 vectors...
# Trained codebook 'embedding.pqcb' (m = 2, k = 256, sub_dim = 2, dimension = 4) from 2 vectors.
# Updated schema.toml: embedding.pq_codebook_path = "embedding.pqcb".

または、インデックスにコミット済みのベクトルから直接サンプリングします — JSONL エクスポートは不要です:

laurus train pq-codebook --field embedding --from-index --sample-size 5000 --update-schema

search

Query DSL を使用して検索クエリを実行します。

laurus search <QUERY> [--limit <N>] [--offset <N>]

クエリ文字列は、各フィールドに設定されたアナライザー自身で解析されます。例えば schema.toml で日本語（Lindera）アナライザーを設定したフィールドは、インデックス時と同じ方法でクエリ時にも解析されます。スキーマに宣言されていないフィールドを参照すると、そのフィールド名を含むエラーで拒否されます（typo の検出に役立ちます）。予約済みの _id フィールドはスキーマに現れませんが、常に検索可能です。

引数:

クエリ構文の例:

# Term クエリ
laurus search "body:rust"

# Phrase クエリ
laurus search 'body:"machine learning"'

# Boolean クエリ
laurus search "+body:programming -body:python"

# Fuzzy クエリ（タイポ許容）
laurus search "body:programing~2"

# Wildcard クエリ
laurus search "title:intro*"

# Range クエリ
laurus search "price:[10 TO 50]"

# 3D 地理クエリ（球 / バウンディングボックス / k-NN）
laurus search "position:geo3d_distance(-3955182, 3350553, 3700276, 5000)"
laurus search "position:geo3d_bbox(-4000000, 3300000, 3650000, -3900000, 3400000, 3750000)"
laurus search "position:geo3d_nearest(-3955182, 3350553, 3700276, 10)"

テーブル出力の例:

╭──────┬────────┬─────────────────────────────────────────╮
│ ID   │ Score  │ Fields                                  │
├──────┼────────┼─────────────────────────────────────────┤
│ doc1 │ 0.8532 │ body: Rust is a systems..., title: Intr │
│ doc3 │ 0.4210 │ body: JavaScript powers..., title: Web  │
╰──────┴────────┴─────────────────────────────────────────╯

JSON 出力の例:

laurus --format json search "body:rust" --limit 5

[
  {
    "id": "doc1",
    "score": 0.8532,
    "document": {
      "title": "Introduction to Rust",
      "body": "Rust is a systems programming language."
    }
  }
]

repl

対話型 REPL セッションを開始します。詳細は REPL を参照してください。

laurus repl

serve

gRPC サーバー（およびオプションで HTTP Gateway）を起動します。

laurus serve [OPTIONS]

起動オプション、設定、使用例については laurus-server のドキュメントを参照してください:

• はじめに — 起動オプションと gRPC 接続例
• 設定 — TOML 設定ファイル、環境変数、優先順位
• ハンズオンチュートリアル — ステップバイステップの操作ガイド

mcp

Model Context Protocol（MCP）サーバーを stdio 上で起動します。MCP サーバーを介して、Claude Code や Claude Desktop のような AI アシスタントが標準化されたツール群（create_index、add_document、search など）で稼働中の laurus-server を操作できます。

laurus mcp [--endpoint <URL>]

引数:

使用例:

# ローカルの laurus-server に事前接続して MCP サーバーを起動
laurus mcp --endpoint http://localhost:50051

# 未接続で起動し、クライアントが最初に `connect` を呼ぶ運用
laurus mcp

MCP サーバーが公開する全ツールの一覧、および Claude Code や Claude Desktop と連携する設定方法については laurus-mcp のドキュメントを参照してください。