Skip to content

perf(lexical): add a doc_values opt-out for stored-field DocValues duplication #1115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mosuka merged 10 commits into from
Sep 12, 2026
Merged

perf(lexical): add a doc_values opt-out for stored-field DocValues duplication #1115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
8f1506a
fix(lexical): fall back to the stored document when a DocValues read …
mosuka Sep 11, 2026
01fcddf
refactor(index): move alloc_bounds to crate::util so lexical loaders …
mosuka Sep 11, 2026
1c11600
perf(lexical): load DocValues columns lazily per field, with bounds c…
mosuka Sep 11, 2026
60717e6
feat(lexical): add a per-field doc_values option to the schema
mosuka Sep 12, 2026
3627315
feat(lexical): wire doc_values into the write, merge, and field-rebui…
mosuka Sep 12, 2026
4f8deeb
feat(engine): classify doc_values changes in update_field
mosuka Sep 12, 2026
2f63629
feat(server): expose doc_values over gRPC and the HTTP gateway
mosuka Sep 12, 2026
876500a
feat(bindings,cli): expose doc_values in the five bindings and the CL…
mosuka Sep 12, 2026
4f274d0
docs: document the doc_values field option
mosuka Sep 12, 2026
2557427
fix(lexical): add doc_values to the FieldOption enum's doctest example
mosuka Sep 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions docs/ja/src/concepts/schema_and_fields.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,21 +69,32 @@ Lexical フィールドは転置インデックス（Inverted Index）を使用
```rust
use laurus::lexical::TextOption;

// Default: indexed + stored + term vectors (all true)
// Default: indexed + stored + term vectors + doc values (all true)
let opt = TextOption::default();

// Customize
let opt = TextOption::default()
.indexed(true)
.stored(true)
.term_vectors(true);
.term_vectors(true)
.doc_values(true);
```

| オプション | デフォルト | 説明 |
| :--- | :--- | :--- |
| `indexed` | `true` | フィールドが検索可能かどうか |
| `stored` | `true` | 元の値が取得用に保存されるかどうか |
| `term_vectors` | `true` | ターム位置が保存されるかどうか（フレーズクエリ・スパンクエリで使用。ハイライトは常に保存済みテキストを再トークナイズするため使用しない） |
| `doc_values` | `true` | 値を DocValues（[ソート](../laurus/faceting.md)・ファセット・集計が読み取る列指向ストア）にもコピーするかどうか |

`doc_values` は `TextOption` 専用ではありません。`BytesOption` を除く全ての lexical
フィールドオプション（`IntegerOption`, `FloatOption`, `BooleanOption`, `DateTimeOption`,
`GeoOption`, `Geo3dOption`）が同じ設定を持ちます。`BytesOption` にはこの設定がありません
―― `Bytes` の値はソートにもファセットにも使えないため、設定にかかわらず DocValues には
一切書き込まれないからです。実効ルールは次のとおりです: DocValues 列が書き込まれるのは
`stored` と `doc_values` の両方が `true`（かつ値の型が `Bytes` でない）場合のみです。
ソートにもファセットにも使わないフィールドで `doc_values: false` を設定すると、二重目の
コピーを省略できるため、セグメントの使用容量が削減されます。

### Vector フィールド

Expand Down
29 changes: 29 additions & 0 deletions docs/ja/src/laurus-cli/schema_format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,15 @@ default_fields = ["title", "body"]
indexed = true # このフィールドを検索用にインデックスするかどうか
stored = true # 取得用に元の値を保存するかどうか
term_vectors = true # タームの位置を保存するかどうか（フレーズクエリ・スパンクエリ用）
doc_values = true # 値を DocValues にもコピーするかどうか（ソート・ファセット用）
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | このフィールドの検索を有効にする |
| `stored` | `bool` | `true` | 結果に返せるよう元の値を保存する |
| `term_vectors` | `bool` | `true` | フレーズクエリ・スパンクエリが読み取るタームの位置を保存する。ハイライトは常に保存済みテキストを再トークナイズするため使用しない |
| `doc_values` | `bool` | `true` | 値を DocValues（[ソート](../laurus/faceting.md)・ファセット・集計が読み取る列指向ストア）にもコピーする。`stored` も `true` の場合のみ有効 —— 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Integer

Expand All @@ -60,13 +62,15 @@ term_vectors = true # タームの位置を保存するかどうか（フレー
indexed = true
stored = true
multi_valued = false
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | 範囲クエリおよび完全一致クエリを有効にする |
| `stored` | `bool` | `true` | 元の値を保存する |
| `multi_valued` | `bool` | `false` | 整数の配列を受け付け、範囲クエリは**いずれかの値**が条件を満たせばマッチ（Lucene 流の "any match"、constant スコア） |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Float

Expand All @@ -77,13 +81,15 @@ multi_valued = false
indexed = true
stored = true
multi_valued = false
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | 範囲クエリを有効にする |
| `stored` | `bool` | `true` | 元の値を保存する |
| `multi_valued` | `bool` | `false` | 浮動小数点の配列を受け付け、範囲クエリは**いずれかの値**が条件を満たせばマッチ（Lucene 流の "any match"、constant スコア） |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Boolean

Expand All @@ -93,12 +99,14 @@ multi_valued = false
[fields.published.Boolean]
indexed = true
stored = true
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | ブーリアン値によるフィルタリングを有効にする |
| `stored` | `bool` | `true` | 元の値を保存する |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### DateTime

Expand All @@ -108,12 +116,14 @@ UTC タイムスタンプフィールド。範囲クエリをサポートしま
[fields.created_at.DateTime]
indexed = true
stored = true
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | 日時の範囲クエリを有効にする |
| `stored` | `bool` | `true` | 元の値を保存する |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Geo

Expand All @@ -123,12 +133,14 @@ stored = true
[fields.location.Geo]
indexed = true
stored = true
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | Geo クエリ（半径、バウンディングボックス）を有効にする |
| `stored` | `bool` | `true` | 元の値を保存する |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Geo3d

Expand All @@ -138,12 +150,14 @@ stored = true
[fields.position.Geo3d]
indexed = true
stored = true
doc_values = true
```

| オプション | 型 | デフォルト | 説明 |
| :--- | :--- | :--- | :--- |
| `indexed` | `bool` | `true` | 3D 地理クエリ（`geo3d_distance`、`geo3d_bbox`、`geo3d_nearest`）を有効にする |
| `stored` | `bool` | `true` | 元の `(x, y, z)` 値を保存する |
| `doc_values` | `bool` | `true` | 詳細は後述の [共通オプション: `doc_values`](#共通オプション-doc_values) を参照 |

#### Bytes

Expand All @@ -158,6 +172,21 @@ stored = true
| :--- | :--- | :--- | :--- |
| `stored` | `bool` | `true` | バイナリデータを保存する |

`BytesOption` に `doc_values` 設定はありません。`Bytes` の値はソートにもファセットにも
使えないため、設定にかかわらず DocValues には一切書き込まれないからです。

#### 共通オプション: `doc_values`

上記の lexical フィールドオプションのうち `BytesOption` を除く全てが `doc_values` オプションを
持ち、値を DocValues ―― [ソート](../laurus/faceting.md)・ファセット・集計が読み取る列指向ストア
―― にもコピーするかどうかを制御します。実効ルールは次のとおりです: DocValues 列が書き込まれる
のは `stored` と `doc_values` の両方が `true` の場合のみです。`doc_values: false` と
`stored: false` の組み合わせは（エラーにせず）黙って無視されます。ソートにもファセットにも
使わないフィールドで `doc_values` を無効にすると、値が二重（stored document と DocValues）
ではなく一度（stored document のみ）しか書き込まれなくなるため、セグメントの使用容量が
削減されます。フィールド自体は引き続き完全に検索・取得可能で、ソートやファセットを行う際は
単に stored document へフォールバックします。

### Vector フィールド

Vector フィールドは近似最近傍探索（ANN: Approximate Nearest Neighbor）用にインデックスされます。`dimension`（各ベクトルの長さ）と `distance` メトリクスの指定が必要です。
Expand Down
16 changes: 8 additions & 8 deletions docs/ja/src/laurus-nodejs/api_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,14 +196,14 @@ class Schema {

| メソッド | 説明 |
| :--- | :--- |
| `addTextField(name, stored?, indexed?, termVectors?, analyzer?)` | 全文検索フィールド（転置インデックス、BM25）。`analyzer` にはパラメータ不要の組込名（`"standard"` / `"english"` / `"keyword"` / `"simple"` / `"noop"`、または `addAnalyzer` で登録したカスタム名）を指定します。Lindera 辞書パスが必要な Japanese プリセットを使う場合は、`lindera` tokenizer を含むカスタム analyzer を登録して、その名前を参照してください。 |
| `addIntegerField(name, stored?, indexed?, multiValued?)` | 64 ビット整数フィールド。`multiValued: true` で整数配列を受け付け（範囲クエリは "any match"）。 |
| `addFloatField(name, stored?, indexed?, multiValued?)` | 64 ビット浮動小数点フィールド。`multiValued: true` で浮動小数点配列を受け付け（範囲クエリは "any match"）。 |
| `addBooleanField(name, stored?, indexed?)` | 真偽値フィールド。 |
| `addBytesField(name, stored?)` | バイナリデータフィールド。 |
| `addGeoField(name, stored?, indexed?)` | 地理座標フィールド。 |
| `addGeo3dField(name, stored?, indexed?)` | 3D ECEF カルテシアン座標フィールド（x, y, z はメートル）。詳細は [Geo3d の概念](../concepts/geo3d.md)。 |
| `addDatetimeField(name, stored?, indexed?)` | UTC 日時フィールド。 |
| `addTextField(name, stored?, indexed?, termVectors?, docValues?, analyzer?)` | 全文検索フィールド（転置インデックス、BM25）。`docValues` は値を DocValues（ソート・ファセット・集計が読み取る列指向ストア）にもコピーするかどうかを制御します（Issue #1047、デフォルト `true`）。`stored` も `true` の場合のみ有効です。`analyzer` にはパラメータ不要の組込名（`"standard"` / `"english"` / `"keyword"` / `"simple"` / `"noop"`、または `addAnalyzer` で登録したカスタム名）を指定します。Lindera 辞書パスが必要な Japanese プリセットを使う場合は、`lindera` tokenizer を含むカスタム analyzer を登録して、その名前を参照してください。 |
| `addIntegerField(name, stored?, indexed?, multiValued?, docValues?)` | 64 ビット整数フィールド。`multiValued: true` で整数配列を受け付け（範囲クエリは "any match"）。`docValues` は上記を参照。 |
| `addFloatField(name, stored?, indexed?, multiValued?, docValues?)` | 64 ビット浮動小数点フィールド。`multiValued: true` で浮動小数点配列を受け付け（範囲クエリは "any match"）。`docValues` は上記を参照。 |
| `addBooleanField(name, stored?, indexed?, docValues?)` | 真偽値フィールド。`docValues` は上記を参照。 |
| `addBytesField(name, stored?)` | バイナリデータフィールド。`docValues` オプションはありません —— `Bytes` の値は設定にかかわらず DocValues に一切書き込まれないためです。 |
| `addGeoField(name, stored?, indexed?, docValues?)` | 地理座標フィールド。`docValues` は上記を参照。 |
| `addGeo3dField(name, stored?, indexed?, docValues?)` | 3D ECEF カルテシアン座標フィールド（x, y, z はメートル）。詳細は [Geo3d の概念](../concepts/geo3d.md)。`docValues` は上記を参照。 |
| `addDatetimeField(name, stored?, indexed?, docValues?)` | UTC 日時フィールド。`docValues` は上記を参照。 |
| `addHnswField(name, dimension, distance?, m?, efConstruction?, defaultEfSearch?, embedder?, quantizer?, subvectorCount?, rerankStorage?, pqCodebookPath?, baseWeight?)` | HNSW ベクトルフィールド。`baseWeight` は他の vector フィールドと同時に検索されたときの相対的なスコアリング優先度（Issue #1084）。[ウェイト](../concepts/search/vector_search.md#ウェイト)を参照。 |
| `addFlatField(name, dimension, distance?, embedder?, baseWeight?)` | Flat（全探索）ベクトルフィールド。 |
| `addIvfField(name, dimension, distance?, nClusters?, nProbe?, embedder?, baseWeight?)` | IVF ベクトルフィールド。 |
Expand Down
16 changes: 8 additions & 8 deletions docs/ja/src/laurus-php/api_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,14 +163,14 @@ new \Laurus\Schema()

| メソッド | 説明 |
| :--- | :--- |
| `addTextField(string $name, bool $stored = true, bool $indexed = true, bool $termVectors = false, ?string $analyzer = null): void` | 全文フィールド（転置インデックス、BM25）。`$analyzer` にはパラメータ不要の組込名（`"standard"` / `"english"` / `"keyword"` / `"simple"` / `"noop"`、または `addAnalyzer` で登録したカスタム名）を指定します。Lindera 辞書パスが必要な Japanese プリセットは、`lindera` tokenizer を含むカスタム analyzer として登録し、名前で参照してください。 |
| `addIntegerField(string $name, bool $stored = true, bool $indexed = true, bool $multiValued = false): void` | 64 ビット整数フィールド。`$multiValued = true` で整数配列を受け付け（範囲クエリは "any match"）。 |
| `addFloatField(string $name, bool $stored = true, bool $indexed = true, bool $multiValued = false): void` | 64 ビット浮動小数点フィールド。`$multiValued = true` で浮動小数点配列を受け付け（範囲クエリは "any match"）。 |
| `addBooleanField(string $name, bool $stored = true, bool $indexed = true): void` | ブールフィールド。 |
| `addBytesField(string $name, bool $stored = true): void` | 生バイトフィールド。 |
| `addGeoField(string $name, bool $stored = true, bool $indexed = true): void` | 地理座標フィールド（緯度/経度）。 |
| `addGeo3dField(string $name, bool $stored = true, bool $indexed = true): void` | 3D ECEF カルテシアン座標フィールド（x, y, z はメートル）。詳細は [Geo3d の概念](../concepts/geo3d.md)。 |
| `addDatetimeField(string $name, bool $stored = true, bool $indexed = true): void` | UTC 日時フィールド。 |
| `addTextField(string $name, bool $stored = true, bool $indexed = true, bool $termVectors = true, bool $docValues = true, ?string $analyzer = null): void` | 全文フィールド（転置インデックス、BM25）。`$docValues` は値を DocValues（ソート・ファセット・集計が読み取る列指向ストア）にもコピーするかどうかを制御します（Issue #1047）。`$stored` も `true` の場合のみ有効です。`$analyzer` にはパラメータ不要の組込名（`"standard"` / `"english"` / `"keyword"` / `"simple"` / `"noop"`、または `addAnalyzer` で登録したカスタム名）を指定します。Lindera 辞書パスが必要な Japanese プリセットは、`lindera` tokenizer を含むカスタム analyzer として登録し、名前で参照してください。 |
| `addIntegerField(string $name, bool $stored = true, bool $indexed = true, bool $multiValued = false, bool $docValues = true): void` | 64 ビット整数フィールド。`$multiValued = true` で整数配列を受け付け（範囲クエリは "any match"）。`$docValues` は上記を参照。 |
| `addFloatField(string $name, bool $stored = true, bool $indexed = true, bool $multiValued = false, bool $docValues = true): void` | 64 ビット浮動小数点フィールド。`$multiValued = true` で浮動小数点配列を受け付け（範囲クエリは "any match"）。`$docValues` は上記を参照。 |
| `addBooleanField(string $name, bool $stored = true, bool $indexed = true, bool $docValues = true): void` | ブールフィールド。`$docValues` は上記を参照。 |
| `addBytesField(string $name, bool $stored = true): void` | 生バイトフィールド。`$docValues` オプションはありません —— `Bytes` の値は設定にかかわらず DocValues に一切書き込まれないためです。 |
| `addGeoField(string $name, bool $stored = true, bool $indexed = true, bool $docValues = true): void` | 地理座標フィールド（緯度/経度）。`$docValues` は上記を参照。 |
| `addGeo3dField(string $name, bool $stored = true, bool $indexed = true, bool $docValues = true): void` | 3D ECEF カルテシアン座標フィールド（x, y, z はメートル）。詳細は [Geo3d の概念](../concepts/geo3d.md)。`$docValues` は上記を参照。 |
| `addDatetimeField(string $name, bool $stored = true, bool $indexed = true, bool $docValues = true): void` | UTC 日時フィールド。`$docValues` は上記を参照。 |
| `addHnswField(string $name, int $dimension, ?string $distance = "cosine", int $m = 16, int $efConstruction = 200, ?int $defaultEfSearch = null, ?string $embedder = null, ?string $quantizer = null, ?int $subvectorCount = null, ?string $rerankStorage = null, ?string $pqCodebookPath = null, float $baseWeight = 1.0): void` | HNSW 近似最近傍ベクトルフィールド。`$baseWeight` は他の vector フィールドと同時に検索されたときの相対的なスコアリング優先度（Issue #1084）。[ウェイト](../concepts/search/vector_search.md#ウェイト)を参照。 |
| `addFlatField(string $name, int $dimension, ?string $distance = "cosine", ?string $embedder = null, float $baseWeight = 1.0): void` | Flat（総当たり）ベクトルフィールド。 |
| `addIvfField(string $name, int $dimension, ?string $distance = "cosine", int $nClusters = 100, int $nProbe = 1, ?string $embedder = null, float $baseWeight = 1.0): void` | IVF 近似最近傍ベクトルフィールド。 |
Expand Down
Loading