feat(server,cli): bulk document ingestion across gRPC, HTTP, MCP, and CLI (#865)

docs/ja/src/laurus-cli/commands.md

@@ -237,25 +237,45 @@ laurus add doc --id <ID> --data <JSON>
 | `--id <ID>` | はい | 外部ドキュメント ID（文字列） |
 | `--data <JSON>` | はい | JSON 文字列としてのドキュメントフィールド |
 
-JSON フォーマットはフィールド名と値を対応付けたフラットなオブジェクトです:
+JSON はドキュメントの serde 形式です: `fields` オブジェクトの各フィールド名に、外部タグ付きの値（`Text`・`Int64`・`Float64`・`Bool`・`VectorValue` など）を対応付けます。
 
 ```json
 {
-  "title": "Introduction to Rust",
-  "body": "Rust is a systems programming language.",
-  "category": "programming"
+  "fields": {
+    "title": {"Text": "Introduction to Rust"},
+    "body": {"Text": "Rust is a systems programming language."},
+    "year": {"Int64": 2024}
+  }
 }
 ```
 
 **例:**
 
 ```bash
-laurus add doc --id doc1 --data '{"title":"Hello World","body":"This is a test document."}'
+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 回）。
+
+```bash
+laurus add docs --file <JSONL> [--batch-size 1000] [--commit-every 0]
+```
+
+**引数:**
+
+| フラグ | 必須 | 説明 |
+| :--- | :--- | :--- |
+| `--file <JSONL>` | はい | 取り込む JSONL ファイルのパス |
+| `--batch-size <N>` | いいえ | エンジンのバッチ呼び出しあたりのドキュメント数（既定 `1000`） |
+| `--commit-every <N>` | いいえ | N 件適用ごとにコミット。`0` = 最後の 1 回のみ（既定） |
+
+繰り返した ID はチャンクとして蓄積されます。途中で失敗した場合、エラーは該当行を示し、適用済みの prefix はコミットされるため、残りの行から再実行してインジェストを継続できます。
+
 ---
 
 ## `put` — リソースの上書き（Upsert）
@@ -278,12 +298,33 @@ laurus put doc --id <ID> --data <JSON>
 **例:**
 
 ```bash
-laurus put doc --id doc1 --data '{"title":"Updated Title","body":"This replaces the existing document."}'
+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` と同じく**自動的にコミット**します。
+
+```bash
+laurus put docs --file <JSONL> [--batch-size 1000] [--commit-every 0]
+```
+
+引数は `add docs` と同じです。途中で失敗した場合、エラーは該当行を示し、適用済みの prefix はコミットされます。put は冪等なので、ファイル全体（または残りの suffix）の再実行は安全です。
+
+**例:**
+
+```bash
+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`

docs/ja/src/laurus-mcp/tools.md

@@ -183,6 +183,54 @@ document: {"title": "Hello World - Part 2", "body": "これは続きです。"}
 
 ---
 
+## put_documents
+
+1 回の呼び出しで多数のドキュメントを Put（Upsert）します。エントリは入力順に逐次適用され、バッチ全体で WAL fsync は 1 回です — ドキュメントごとに `put_document` を呼ぶよりはるかに高速です。1 バッチ内で重複した ID はデデュープされます（最後の出現が勝ち）。実行後に `commit` を呼び出してください。
+
+### パラメータ
+
+| 名前 | 型 | 必須 | 説明 |
+| :--- | :--- | :--- | :--- |
+| `documents` | array | はい | `{"id": "...", "document": {...}}` エントリの配列。各 `document` は `put_document` と同じ形式 |
+
+### 例
+
+```text
+Tool: put_documents
+documents: [
+  {"id": "doc-1", "document": {"title": "Hello"}},
+  {"id": "doc-2", "document": {"title": "World"}}
+]
+```
+
+結果: `2 documents put (upserted). Call commit to persist changes.`
+
+失敗した場合は該当エントリで中断し、適用済みの prefix はロールバックされないため、バッチ（またはその suffix）の再試行は冪等です。
+
+---
+
+## add_documents
+
+1 回の呼び出しで多数のドキュメントを新しいチャンクとして追加します。`put_documents` と異なり既存ドキュメントは削除されないため、ID を繰り返すと同一論理ドキュメントの複数チャンクになります。バッチ全体で WAL fsync は 1 回です。実行後に `commit` を呼び出してください。
+
+### パラメータ
+
+`put_documents` と同じです。
+
+### 例
+
+```text
+Tool: add_documents
+documents: [
+  {"id": "doc-1", "document": {"title": "Part 1"}},
+  {"id": "doc-1", "document": {"title": "Part 2"}}
+]
+```
+
+結果: `2 documents added as chunks. Call commit to persist changes.`
+
+---
+
 ## get_documents
 
 外部 ID で全ドキュメント（チャンクを含む）を取得します。

docs/ja/src/laurus-server/grpc_api.md

@@ -8,7 +8,7 @@
 | :--- | :--- | :--- |
 | `HealthService` | `Check` | ヘルスチェック |
 | `IndexService` | `CreateIndex`, `GetIndex`, `GetSchema`, `AddField`, `DeleteField` | インデックスのライフサイクルとスキーマ |
-| `DocumentService` | `PutDocument`, `AddDocument`, `GetDocuments`, `DeleteDocuments`, `Commit`, `FlushWal` | ドキュメント CRUD・コミット・WAL flush |
+| `DocumentService` | `PutDocument`, `AddDocument`, `PutDocuments`, `AddDocuments`, `GetDocuments`, `DeleteDocuments`, `Commit`, `FlushWal` | ドキュメント CRUD・バルクインジェスト・コミット・WAL flush |
 | `SearchService` | `Search`, `SearchStream` | 単発検索とストリーミング検索 |
 
 ---
@@ -282,6 +282,39 @@ rpc AddDocument(AddDocumentRequest) returns (AddDocumentResponse);
 
 リクエストフィールドは `PutDocument` と同じです。
 
+### `PutDocuments`
+
+バッチ Upsert。エントリは入力順に逐次適用され、バッチ全体で WAL fsync は 1 回です — ドキュメントごとに `PutDocument` を呼ぶよりはるかに高速です。1 バッチ内で重複した ID は、同じ put を 1 件ずつ発行した場合とまったく同じようにデデュープされます（最後の出現が勝ち）。
+
+```protobuf
+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 をバッチ内で繰り返せます。
+
+```protobuf
+rpc AddDocuments(AddDocumentsRequest) returns (AddDocumentsResponse);
+```
+
+リクエスト/レスポンスのフィールドは `PutDocuments` と対になります。
+
 ### `GetDocuments`
 
 指定された外部 ID に一致するすべてのドキュメントを取得します。

docs/ja/src/laurus-server/http_gateway.md

@@ -38,6 +38,7 @@ laurus serve --config config.toml
 | POST | `/v1/documents/{id}` | `DocumentService/AddDocument` | ドキュメントの追加（チャンク） |
 | GET | `/v1/documents/{id}` | `DocumentService/GetDocuments` | ID でドキュメントを取得 |
 | DELETE | `/v1/documents/{id}` | `DocumentService/DeleteDocuments` | ID でドキュメントを削除 |
+| POST | `/v1/documents:bulk` | `DocumentService/PutDocuments` / `AddDocuments` | ドキュメントのバルクインジェスト（`?mode=put\|add`、既定は `put`） |
 | POST | `/v1/commit` | `DocumentService/Commit` | 保留中の変更をコミット |
 | POST | `/v1/flush_wal` | `DocumentService/FlushWal` | full commit なしでバッファされた WAL レコードを durable 化 |
 | POST | `/v1/search` | `SearchService/Search` | 検索（単発） |
@@ -141,6 +142,24 @@ curl -X POST http://localhost:8080/v1/documents/doc1 \
   }'
 ```
 
+### ドキュメントのバルクインジェスト（POST）
+
+1 回の呼び出しで多数のドキュメントを適用します — エントリは入力順に逐次処理され、バッチ全体で WAL fsync は 1 回です。`?mode=put`（既定）は Upsert（重複 ID はデデュープ、最後が勝ち）、`?mode=add` はチャンク追加（繰り返した ID は蓄積）です。
+
+```bash
+curl -X POST 'http://localhost:8080/v1/documents:bulk?mode=put' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "documents": [
+      {"id": "doc1", "document": {"fields": {"title": "Hello"}}},
+      {"id": "doc2", "document": {"fields": {"title": "World"}}}
+    ]
+  }'
+# => {"applied": 2}
+```
+
+適用できない最初のエントリで fail-fast します。適用済みエントリはロールバックされず（次のコミットで永続化）、エラーには失敗位置が含まれるため、バッチまたはその suffix の再試行は冪等です。
+
 ### ドキュメントの取得
 
 ```bash

docs/src/laurus-cli/commands.md

@@ -237,25 +237,45 @@ laurus add doc --id <ID> --data <JSON>
 | `--id <ID>` | Yes | External document ID (string) |
 | `--data <JSON>` | Yes | Document fields as a JSON string |
 
-The JSON format is a flat object mapping field names to values:
+The JSON is the document's serde shape: a `fields` object mapping each field name to an externally-tagged value (`Text`, `Int64`, `Float64`, `Bool`, `VectorValue`, ...):
 
 ```json
 {
-  "title": "Introduction to Rust",
-  "body": "Rust is a systems programming language.",
-  "category": "programming"
+  "fields": {
+    "title": {"Text": "Introduction to Rust"},
+    "body": {"Text": "Rust is a systems programming language."},
+    "year": {"Int64": 2024}
+  }
 }
 ```
 
 **Example:**
 
 ```bash
-laurus add doc --id doc1 --data '{"title":"Hello World","body":"This is a test document."}'
+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.
 ```
 
 > **Tip:** Multiple documents can share the same external ID (chunking pattern). Use `add doc` for each chunk.
 
+### `add docs`
+
+Bulk-add document chunks from a JSONL file — one `{"id": "...", "document": {"fields": {...}}}` entry per line, where `document` uses the same JSON shape as `add doc --data`. Entries are applied through the engine's batch API (one WAL fsync per batch) and, unlike `add doc`, the command **commits automatically**: every `--commit-every` applied documents and once at the end.
+
+```bash
+laurus add docs --file <JSONL> [--batch-size 1000] [--commit-every 0]
+```
+
+**Arguments:**
+
+| Flag | Required | Description |
+| :--- | :--- | :--- |
+| `--file <JSONL>` | Yes | Path to the JSONL file to ingest |
+| `--batch-size <N>` | No | Documents per engine batch call (default `1000`) |
+| `--commit-every <N>` | No | Commit every N applied documents; `0` = only the final commit (default) |
+
+Repeated IDs accumulate as chunks. On a mid-file failure the error names the offending line, the applied prefix is committed, and re-running the remaining lines continues the ingest.
+
 ---
 
 ## `put` — Put (Upsert) a Resource
@@ -278,12 +298,33 @@ laurus put doc --id <ID> --data <JSON>
 **Example:**
 
 ```bash
-laurus put doc --id doc1 --data '{"title":"Updated Title","body":"This replaces the existing document."}'
+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.
 ```
 
 > **Note:** Unlike `add doc`, `put doc` replaces all existing chunks for the given ID. Use `add doc` when you want to append chunks, and `put doc` when you want to replace the entire document.
 
+### `put docs`
+
+Bulk-upsert documents from a JSONL file — one `{"id": "...", "document": {"fields": {...}}}` entry per line, applied through the engine's batch API (one WAL fsync per batch). Duplicate IDs dedup in order (the last occurrence wins). Like `add docs`, the command **commits automatically**.
+
+```bash
+laurus put docs --file <JSONL> [--batch-size 1000] [--commit-every 0]
+```
+
+Arguments are the same as `add docs`. On a mid-file failure the error names the offending line and the applied prefix is committed; because puts are idempotent, re-running the whole file (or its remaining suffix) is safe.
+
+**Example:**
+
+```bash
+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`

docs/src/laurus-mcp/tools.md

@@ -239,6 +239,54 @@ Result: `Document 'doc-1' added as chunk. Call commit to persist changes.`
 
 ---
 
+## put_documents
+
+Put (upsert) many documents in one call. Entries are applied sequentially, in input order, with one WAL fsync for the whole batch — much faster than calling `put_document` per document. Duplicate IDs within one batch dedup (the last occurrence wins). Call `commit` afterwards.
+
+### Parameters
+
+| Name | Type | Required | Description |
+| :--- | :--- | :--- | :--- |
+| `documents` | array | Yes | Array of `{"id": "...", "document": {...}}` entries; each `document` has the same shape as `put_document`'s |
+
+### Example
+
+```text
+Tool: put_documents
+documents: [
+  {"id": "doc-1", "document": {"title": "Hello"}},
+  {"id": "doc-2", "document": {"title": "World"}}
+]
+```
+
+Result: `2 documents put (upserted). Call commit to persist changes.`
+
+A failure aborts at the offending entry without rolling back the already-applied prefix, so retrying the batch (or its suffix) is idempotent.
+
+---
+
+## add_documents
+
+Add many documents as new chunks in one call. Unlike `put_documents`, existing documents are never deleted, so repeating an ID adds multiple chunks of the same logical document. One WAL fsync covers the whole batch. Call `commit` afterwards.
+
+### Parameters
+
+Same as `put_documents`.
+
+### Example
+
+```text
+Tool: add_documents
+documents: [
+  {"id": "doc-1", "document": {"title": "Part 1"}},
+  {"id": "doc-1", "document": {"title": "Part 2"}}
+]
+```
+
+Result: `2 documents added as chunks. Call commit to persist changes.`
+
+---
+
 ## get_documents
 
 Retrieve all stored documents (including chunks) by external ID.