Laurus

Rust 向けの高速で多機能なハイブリッド検索ライブラリ。

Laurus は、Lexical 検索（転置インデックス（Inverted Index）によるキーワードマッチング）と Vector 検索（エンベディングによるセマンティック類似度検索）を単一のエンジンに統合した、純 Rust ライブラリです。外部サーバーを必要とせず、Rust アプリケーションに直接組み込んで使用できます。

主な機能

仕組み

graph LR
    subgraph Your Application
        D["Document"]
        Q["Query"]
    end

    subgraph Laurus Engine
        SCH["Schema"]
        AN["Analyzer"]
        EM["Embedder"]
        LI["Lexical Index\n(Inverted Index)"]
        VI["Vector Index\n(HNSW / Flat / IVF)"]
        FU["Fusion\n(RRF / WeightedSum)"]
    end

    D --> SCH
    SCH --> AN --> LI
    SCH --> EM --> VI
    Q --> LI --> FU
    Q --> VI --> FU
    FU --> R["Ranked Results"]

1. スキーマを定義する — フィールドとその型（text、integer、vector など）を宣言します
2. Engine を構築する — テキスト用のアナライザと Vector 用のエンベッダを接続します
3. ドキュメントをインデックスする — Engine が各フィールドを適切なインデックスに自動的に振り分けます
4. 検索する — Lexical、Vector、またはハイブリッドクエリを実行し、ランク付けされた結果を取得します

ドキュメントマップ

クイックサンプル

use std::sync::Arc;
use laurus::{Document, Engine, Schema, SearchRequestBuilder, Result};
use laurus::lexical::{TextOption, TermQuery};
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Storage
    let storage = Arc::new(MemoryStorage::new(Default::default()));

    // 2. Schema
    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_text_field("body", TextOption::default())
        .add_default_field("body")
        .build();

    // 3. Engine
    let engine = Engine::builder(storage, schema).build().await?;

    // 4. Index a document
    let doc = Document::builder()
        .add_text("title", "Hello Laurus")
        .add_text("body", "A fast search library for Rust")
        .build();
    engine.add_document("doc-1", doc).await?;
    engine.commit().await?;

    // 5. Search
    let request = SearchRequestBuilder::new()
        .lexical_query(
            laurus::lexical::search::searcher::LexicalSearchQuery::Obj(
                Box::new(TermQuery::new("body", "rust"))
            )
        )
        .limit(10)
        .build();
    let results = engine.search(request).await?;

    for r in &results {
        println!("{}: score={:.4}", r.id, r.score);
    }
    Ok(())
}

ライセンス

Laurus は MIT ライセンス のもとで提供されています。

アーキテクチャ

このページでは、Laurus の内部構造について説明します。アーキテクチャを理解することで、スキーマ設計、Analyzer の選択、検索戦略についてより適切な判断ができるようになります。

プロジェクト構成

Laurus は Cargo workspace として 9 つのクレート（コアライブラリ 1、自製バイナリ 3、言語バインディング 5）で構成されています。

graph TB
    CLI["laurus-cli\n(Binary)\nCLI + REPL + serve + mcp"]
    SRV["laurus-server\n(Library + Binary)\ngRPC + HTTP Gateway"]
    MCP["laurus-mcp\n(Binary)\nMCP stdio server"]
    PY["laurus-python\n(cdylib)\nPyO3 / Maturin"]
    NJS["laurus-nodejs\n(cdylib)\nNAPI-RS"]
    WASM["laurus-wasm\n(WebAssembly)\nwasm-bindgen"]
    RB["laurus-ruby\n(cdylib)\nmagnus + rb-sys"]
    PHP["laurus-php\n(PHP extension)\next-php-rs"]
    LIB["laurus\n(Library)\nコア検索エンジン"]

    CLI --> LIB
    CLI --> SRV
    CLI --> MCP
    SRV --> LIB
    MCP --> SRV
    MCP --> LIB
    PY --> LIB
    NJS --> LIB
    WASM --> LIB
    RB --> LIB
    PHP --> LIB

各クレートの詳細については以下を参照してください。

• ライブラリ概要
• CLI 概要
• サーバー概要
• MCP サーバー概要
• Python バインディング概要
• Node.js バインディング概要
• WASM バインディング概要
• Ruby バインディング概要
• PHP バインディング概要

全体概要

Laurus は単一の Engine を中心に構成されており、4 つの内部コンポーネントを統括します。

graph TB
    subgraph Engine
        SCH["Schema"]
        LS["LexicalStore\n(Inverted Index)"]
        VS["VectorStore\n(HNSW / Flat / IVF)"]
        DL["DocumentLog\n(WAL + Document Storage)"]
    end

    Storage["Storage (trait)\nMemory / File / File+Mmap"]

    LS --- Storage
    VS --- Storage
    DL --- Storage

3 つのストアはすべて単一の Storage バックエンドを共有し、キープレフィックス（lexical/、vector/、documents/）によって分離されています。

Engine のライフサイクル

Engine の構築

EngineBuilder が各パーツから Engine を組み立てます。

#![allow(unused)]
fn main() {
let engine = Engine::builder(storage, schema)
    .analyzer(analyzer)      // optional: for text fields
    .embedder(embedder)      // optional: for vector fields
    .build()
    .await?;
}

sequenceDiagram
    participant User
    participant EngineBuilder
    participant Engine

    User->>EngineBuilder: new(storage, schema)
    User->>EngineBuilder: .analyzer(analyzer)
    User->>EngineBuilder: .embedder(embedder)
    User->>EngineBuilder: .build().await
    EngineBuilder->>EngineBuilder: split_schema()
    Note over EngineBuilder: Separate fields into\nLexicalIndexConfig\n+ VectorIndexConfig
    EngineBuilder->>Engine: Create LexicalStore
    EngineBuilder->>Engine: Create VectorStore
    EngineBuilder->>Engine: Create DocumentLog
    EngineBuilder->>Engine: Recover from WAL
    EngineBuilder-->>User: Engine ready

build() 時に Engine は以下の処理を行います。

1. スキーマの分割 — Lexical フィールドは LexicalIndexConfig へ、Vector フィールドは VectorIndexConfig へ振り分けられる
2. プレフィックス付きストレージの作成 — 各コンポーネントが分離された名前空間を取得する（lexical/、vector/、documents/）
3. ストアの初期化 — LexicalStore と VectorStore がそれぞれの設定で構築される
4. WAL からの復旧 — 前回のセッションからの未コミット操作を再生する

スキーマの分割

Schema には Lexical フィールドと Vector フィールドの両方が含まれています。ビルド時に split_schema() がこれらを分離します。

graph LR
    S["Schema\ntitle: Text\nbody: Text\ncategory: Text\npage: Integer\ncontent_vec: HNSW"]

    S --> LC["LexicalIndexConfig\ntitle: TextOption\nbody: TextOption\ncategory: TextOption\npage: IntegerOption\n_id: KeywordAnalyzer"]

    S --> VC["VectorIndexConfig\ncontent_vec: HnswOption\n(dim=384, m=16, ef=200)"]

主なポイント:

• 予約フィールド _id は常に KeywordAnalyzer（完全一致）で Lexical 設定に追加される
• PerFieldAnalyzer はフィールドごとの Analyzer 設定をラップする。単純な StandardAnalyzer を渡した場合、すべてのテキストフィールドのデフォルトとなる
• PerFieldEmbedder も Vector フィールドに対して同様に動作する

インデクシングのデータフロー

engine.add_document(id, doc) を呼び出した場合の処理:

sequenceDiagram
    participant User
    participant Engine
    participant WAL as DocumentLog (WAL)
    participant Lexical as LexicalStore
    participant Vector as VectorStore

    User->>Engine: add_document("doc-1", doc)
    Engine->>WAL: Append to WAL
    Engine->>Engine: Assign internal ID (u64)

    loop For each field in document
        alt Lexical field (text, integer, etc.)
            Engine->>Lexical: Analyze + index field
        else Vector field
            Engine->>Vector: Embed + index field
        end
    end

    Note over Engine: Document is buffered\nbut NOT yet searchable

    User->>Engine: commit()
    Engine->>Lexical: Flush segments to storage
    Engine->>Vector: Flush segments to storage
    Engine->>WAL: Truncate WAL
    Note over Engine: Documents are\nnow searchable

主なポイント:

• WAL 優先: すべての書き込みは、インメモリ構造を変更する前にログに記録される
• デュアルインデクシング: 各フィールドはスキーマに基づいて Lexical ストアまたは Vector ストアのいずれかにルーティングされる
• コミットが必要: ドキュメントは commit() の後にのみ検索可能になる

検索のデータフロー

engine.search(request) を呼び出した場合の処理:

sequenceDiagram
    participant User
    participant Engine
    participant Lexical as LexicalStore
    participant Vector as VectorStore
    participant Fusion

    User->>Engine: search(request)

    opt Filter query present
        Engine->>Lexical: Execute filter query
        Lexical-->>Engine: Allowed document IDs
    end

    par Lexical search
        Engine->>Lexical: Execute lexical query
        Lexical-->>Engine: Ranked hits (BM25)
    and Vector search
        Engine->>Vector: Execute vector query
        Vector-->>Engine: Ranked hits (similarity)
    end

    alt Both lexical and vector results
        Engine->>Fusion: Fuse results (RRF or WeightedSum)
        Fusion-->>Engine: Merged ranked list
    end

    Engine->>Engine: Apply offset + limit
    Engine-->>User: Vec of SearchResult

検索パイプラインは 3 つのステージで構成されています。

1. フィルタ（オプション） — Lexical インデックスに対してフィルタクエリを実行し、許可されたドキュメント ID のセットを取得する
2. 検索 — Lexical クエリと Vector クエリを並列に実行する
3. フュージョン — 両方のクエリタイプが存在する場合、RRF（デフォルト、k=60）または WeightedSum を使用して結果をマージする

ストレージアーキテクチャ

すべてのコンポーネントは単一の Storage trait 実装を共有しますが、キープレフィックスを使用してデータを分離します。

graph TB
    Engine --> PS1["PrefixedStorage\nprefix: 'lexical/'"]
    Engine --> PS2["PrefixedStorage\nprefix: 'vector/'"]
    Engine --> PS3["PrefixedStorage\nprefix: 'documents/'"]

    PS1 --> S["Storage Backend\n(Memory / File / File+Mmap)"]
    PS2 --> S
    PS3 --> S

フィールドごとのディスパッチ

PerFieldAnalyzer が提供されている場合、Engine はフィールド固有の Analyzer に解析処理をディスパッチします。同様のパターンが PerFieldEmbedder にも適用されます。

graph LR
    PFA["PerFieldAnalyzer"]
    PFA -->|"title"| KA["KeywordAnalyzer"]
    PFA -->|"body"| SA["StandardAnalyzer"]
    PFA -->|"description"| JA["JapaneseAnalyzer"]
    PFA -->|"_id"| KA2["KeywordAnalyzer\n(always)"]
    PFA -->|other fields| DEF["Default Analyzer\n(StandardAnalyzer)"]

これにより、同一 Engine 内で異なるフィールドに異なる解析戦略を使用できます。

まとめ

次のステップ

• フィールドタイプとスキーマ設計を理解する: スキーマとフィールド
• テキスト解析について学ぶ: テキスト解析
• Embedding について学ぶ: Embedding

はじめに

Laurus へようこそ! このセクションでは、ライブラリのインストールから最初の検索の実行までをガイドします。

作成するもの

このガイドを終えると、以下の機能を持つ検索エンジンが動作するようになります:

• テキストドキュメントのインデックス
• キーワード（Lexical）検索の実行
• セマンティック（Vector）検索の実行
• ハイブリッド検索による両者の統合

前提条件

• Rust 1.85 以降（edition 2024）
• Cargo（Rust に同梱）
• Tokio ランタイム（Laurus は非同期 API を使用します）

ステップ

1. インストール — Laurus をプロジェクトに追加し、Feature Flags を選択する
2. クイックスタート — 5 つのステップで完全な検索エンジンを構築する

ワークフロー概要

Laurus を使った検索アプリケーションの構築は、一貫したパターンに従います:

graph LR
    A["1. Create\nStorage"] --> B["2. Define\nSchema"]
    B --> C["3. Build\nEngine"]
    C --> D["4. Index\nDocuments"]
    D --> E["5. Search"]

インストール

プロジェクトへの Laurus の追加

Cargo.toml に laurus と tokio（非同期ランタイム）を追加します:

[dependencies]
laurus = "0.12"
tokio = { version = "1", features = ["full"] }

Feature Flags

Laurus はデフォルトで最小限の機能セットで提供されます。必要に応じて追加の機能を有効にしてください:

例

Lexical 検索のみ（エンベディング不要）:

[dependencies]
laurus = "0.12"

ローカルモデルによる Vector 検索（API キー不要）:

[dependencies]
laurus = { version = "0.12", features = ["embeddings-candle"] }

OpenAI による Vector 検索:

[dependencies]
laurus = { version = "0.12", features = ["embeddings-openai"] }

すべての機能:

[dependencies]
laurus = { version = "0.12", features = ["embeddings-all"] }

インストールの確認

Laurus が正しくコンパイルされることを確認するために、最小限のプログラムを作成します:

use laurus::Result;

#[tokio::main]
async fn main() -> Result<()> {
    println!("Laurus version: {}", laurus::VERSION);
    Ok(())
}

cargo run

バージョンが表示されれば、クイックスタートに進む準備が整っています。

クイックスタート

このチュートリアルでは、5 つのステップで完全な検索エンジンを構築する方法を説明します。最後には、ドキュメントをインデックスしてキーワード検索ができるようになります。

ステップ 1 — Storage の作成

Storage は Laurus がインデックスデータを保存する場所を決定します。開発やテストには MemoryStorage を使用します:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::storage::memory::MemoryStorage;
use laurus::Storage;

let storage: Arc<dyn Storage> = Arc::new(
    MemoryStorage::new(Default::default())
);
}

ヒント: 本番環境では FileStorage（オプションで use_mmap によるメモリマップド I/O）の使用を検討してください。詳細はストレージを参照してください。

ステップ 2 — Schema の定義

Schema はドキュメント内のフィールドと、各フィールドのインデックス方法を宣言します:

#![allow(unused)]
fn main() {
use laurus::Schema;
use laurus::lexical::TextOption;

let schema = Schema::builder()
    .add_text_field("title", TextOption::default())
    .add_text_field("body", TextOption::default())
    .add_default_field("body")  // used when no field is specified in a query
    .build();
}

各フィールドには型があります。主な型は以下の通りです:

全一覧はスキーマとフィールドを参照してください。

ステップ 3 — Engine の構築

Engine は Storage、Schema、ランタイムコンポーネントを統合します:

#![allow(unused)]
fn main() {
use laurus::Engine;

let engine = Engine::builder(storage, schema)
    .build()
    .await?;
}

テキストフィールドのみを使用する場合、デフォルトの StandardAnalyzer が自動的に適用されます。解析のカスタマイズや Vector エンベディングの追加については、アーキテクチャを参照してください。

ステップ 4 — ドキュメントのインデックス

DocumentBuilder でドキュメントを作成し、Engine に追加します:

#![allow(unused)]
fn main() {
use laurus::Document;

// Each document needs a unique external ID (string)
let doc = Document::builder()
    .add_text("title", "Introduction to Rust")
    .add_text("body", "Rust is a systems programming language focused on safety and performance.")
    .build();
engine.add_document("doc-1", doc).await?;

let doc = Document::builder()
    .add_text("title", "Python for Data Science")
    .add_text("body", "Python is widely used in machine learning and data analysis.")
    .build();
engine.add_document("doc-2", doc).await?;

let doc = Document::builder()
    .add_text("title", "Web Development with JavaScript")
    .add_text("body", "JavaScript powers interactive web applications and server-side code with Node.js.")
    .build();
engine.add_document("doc-3", doc).await?;

// Commit to make documents searchable
engine.commit().await?;
}

重要: ドキュメントは commit() が呼ばれるまで検索可能になりません。

ステップ 5 — 検索

SearchRequestBuilder とクエリを使ってインデックスを検索します:

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::lexical::TermQuery;
use laurus::lexical::search::searcher::LexicalSearchQuery;

// Search for "rust" in the "body" field
let request = SearchRequestBuilder::new()
    .lexical_query(
        LexicalSearchQuery::Obj(
            Box::new(TermQuery::new("body", "rust"))
        )
    )
    .limit(10)
    .build();

let results = engine.search(request).await?;

for result in &results {
    println!("ID: {}, Score: {:.4}", result.id, result.score);
    if let Some(doc) = &result.document {
        if let Some(title) = doc.get("title") {
            println!("  Title: {:?}", title);
        }
    }
}
}

完全なサンプル

以下は、コピー・ペーストしてそのまま実行できる完全なプログラムです:

use std::sync::Arc;
use laurus::{
    Document, Engine, Result, Schema, SearchRequestBuilder,
};
use laurus::lexical::{TextOption, TermQuery};
use laurus::lexical::search::searcher::LexicalSearchQuery;
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> Result<()> {
    // 1. Storage
    let storage = Arc::new(MemoryStorage::new(Default::default()));

    // 2. Schema
    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_text_field("body", TextOption::default())
        .add_default_field("body")
        .build();

    // 3. Engine
    let engine = Engine::builder(storage, schema).build().await?;

    // 4. Index documents
    for (id, title, body) in [
        ("doc-1", "Introduction to Rust", "Rust is a systems programming language focused on safety."),
        ("doc-2", "Python for Data Science", "Python is widely used in machine learning."),
        ("doc-3", "Web Development", "JavaScript powers interactive web applications."),
    ] {
        let doc = Document::builder()
            .add_text("title", title)
            .add_text("body", body)
            .build();
        engine.add_document(id, doc).await?;
    }
    engine.commit().await?;

    // 5. Search
    let request = SearchRequestBuilder::new()
        .lexical_query(
            LexicalSearchQuery::Obj(
                Box::new(TermQuery::new("body", "rust"))
            )
        )
        .limit(10)
        .build();

    let results = engine.search(request).await?;
    for r in &results {
        println!("{}: score={:.4}", r.id, r.score);
    }

    Ok(())
}

次のステップ

• Engine の内部動作を学ぶ: アーキテクチャ
• Schema とフィールド型を理解する: スキーマとフィールド
• Vector 検索を追加する: Vector 検索
• Lexical と Vector を統合する: ハイブリッド検索

サンプル

laurus/examples/ ディレクトリには、ライブラリのさまざまな機能を示す実行可能なサンプルが含まれています。

サンプルの実行

# Feature Flags なしでサンプルを実行
cargo run --example <name>

# Feature Flags を指定してサンプルを実行
cargo run --example <name> --features <flag>

利用可能なサンプル

quickstart

基本的なワークフローを示す最小限のサンプルです: Storage の作成、Schema の定義、Engine の構築、ドキュメントのインデックス、検索を行います。

cargo run --example quickstart

デモ内容: インメモリストレージ、TextOption、TermQuery、LexicalSearchQuery

lexical_search

すべての Lexical クエリ型を示す包括的なサンプルです。Builder API と QueryParser DSL の両方を使用します。

cargo run --example lexical_search

デモ内容: TermQuery、PhraseQuery、FuzzyQuery、WildcardQuery、NumericRangeQuery、GeoDistanceQuery / GeoBoundingBoxQuery、BooleanQuery、SpanQuery

vector_search

モックエンベッダを使用した Vector 検索のサンプルです。フィルタ付き Vector 検索や DSL 構文も含みます。

cargo run --example vector_search

デモ内容: PerFieldEmbedder、VectorSearchRequestBuilder、フィルタ付き検索、DSL 構文（field:"query"）

hybrid_search

異なる融合アルゴリズムを用いた Lexical 検索と Vector 検索の統合サンプルです。

cargo run --example hybrid_search

デモ内容: Lexical のみ、Vector のみ、ハイブリッド検索。RRF と WeightedSum の両方の融合アルゴリズム。Builder API と DSL。

geo3d_search

Earth-Centered Earth-Fixed (ECEF) 座標系を用いた 3D 地理検索のサンプルです。6 つのランドマーク（東京タワー、東京スカイツリー、富士山頂、自由の女神像、シドニー・オペラハウス、ISS サンプル点）を wgs84_to_ecef で変換してインデックスします。

cargo run --example geo3d_search

デモ内容: Geo3dDistanceQuery（球）、Geo3dBoundingBoxQuery（3D AABB）、Geo3dNearestQuery（k-NN）、および wgs84_to_ecef 変換ユーティリティ。バウンディングボックスクエリは ISS サンプルを意図的に除外し、高度が第三の軸として機能することを示します。

search_with_candle

Hugging Face Candle を使用した実際の BERT エンベディングによる Vector 検索です。初回実行時にモデルが自動的にダウンロードされます（約 80 MB）。

cargo run --example search_with_candle --features embeddings-candle

必要条件: embeddings-candle Feature Flag

デモ内容: CandleBertEmbedder（sentence-transformers/all-MiniLM-L6-v2、384 次元）

search_with_openai

OpenAI Embeddings API を使用した Vector 検索です。

export OPENAI_API_KEY=your-api-key
cargo run --example search_with_openai --features embeddings-openai

必要条件: embeddings-openai Feature Flag、OPENAI_API_KEY 環境変数

デモ内容: OpenAIEmbedder（text-embedding-3-small、1536 次元）

multimodal_search

CLIP モデルを使用したマルチモーダル（テキスト + 画像）検索です。

cargo run --example multimodal_search --features embeddings-multimodal

必要条件: embeddings-multimodal Feature Flag

デモ内容: CandleClipEmbedder、ファイルシステムからの画像インデックス、テキスト→画像クエリおよび画像→画像クエリ

synonym_graph_filter

解析時のトークン展開のための SynonymGraphFilter のデモです。

cargo run --example synonym_graph_filter

デモ内容: シノニム辞書の作成、シノニムによるトークン展開、ブーストの適用、トークンの position および position_length 属性

ヘルパーモジュール: common.rs

common.rs ファイルは、サンプルで使用される共通ユーティリティを提供します:

• memory_storage() – インメモリストレージインスタンスの作成
• per_field_analyzer() – 特定のフィールドに KeywordAnalyzer を設定した PerFieldAnalyzer の作成
• MockEmbedder – 実際のモデルなしで Vector 検索をテストするためのモック Embedder 実装

スキーマとフィールド

Schema はドキュメントの構造を定義します。どのフィールドが存在し、各フィールドがどのようにインデクシングされるかを指定します。Schema は Engine にとって唯一の情報源です。

CLI で使用される TOML ファイル形式については、スキーマフォーマットリファレンスを参照してください。

Schema

Schema は名前付きフィールドのコレクションです。各フィールドはLexical フィールド（キーワード検索用）または Vector フィールド（類似度検索用）のいずれかです。

#![allow(unused)]
fn main() {
use laurus::Schema;
use laurus::lexical::TextOption;
use laurus::lexical::core::field::IntegerOption;
use laurus::vector::HnswOption;

let schema = Schema::builder()
    .add_text_field("title", TextOption::default())
    .add_text_field("body", TextOption::default())
    .add_integer_field("year", IntegerOption::default())
    .add_hnsw_field("embedding", HnswOption::default())
    .add_default_field("body")
    .build();
}

デフォルトフィールド

add_default_field() は、クエリがフィールド名を明示的に指定しない場合に検索対象となるフィールドを指定します。これは Query DSL パーサーで使用されます。

フィールドタイプ

graph TB
    FO["FieldOption"]

    FO --> T["Text"]
    FO --> I["Integer"]
    FO --> FL["Float"]
    FO --> B["Boolean"]
    FO --> DT["DateTime"]
    FO --> G["Geo"]
    FO --> G3["Geo3d"]
    FO --> BY["Bytes"]

    FO --> FLAT["Flat"]
    FO --> HNSW["HNSW"]
    FO --> IVF["IVF"]

Lexical フィールド

Lexical フィールドは転置インデックス（Inverted Index）を使用してインデクシングされ、キーワードベースのクエリをサポートします。

Text フィールドオプション

TextOption はテキストのインデクシング方法を制御します。

#![allow(unused)]
fn main() {
use laurus::lexical::TextOption;

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

// Customize
let opt = TextOption::default()
    .indexed(true)
    .stored(true)
    .multi_valued(false)
    .position_increment_gap(100)
    .term_vectors(true)
    .doc_values(true);
}

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

Vector フィールド

Vector フィールドは近似最近傍（ANN: Approximate Nearest Neighbor）検索のためのベクトルインデックスを使用してインデクシングされます。

HNSW フィールドオプション（最も一般的）

#![allow(unused)]
fn main() {
use laurus::vector::HnswOption;
use laurus::vector::core::distance::DistanceMetric;
use laurus::vector::core::quantization::QuantizationMethod;

let opt = HnswOption {
    dimension: 384,                                  // vector dimensions
    distance: DistanceMetric::Cosine,                // distance metric
    m: 16,                                           // max connections per layer
    ef_construction: 200,                            // construction search width
    default_ef_search: Some(100),                    // schema-level ef_search default (issue #644)
    base_weight: 1.0,                                // 他の vector フィールドに対する相対的な優先度（issue #1084）
    quantizer: QuantizationMethod::Scalar8Bit,       // 必須（デフォルト Scalar8Bit）
    embedder: None,                                  // 任意の embedder 名
};
}

default_ef_search: 検索時の recall 調整パラメータ

ef_search はクエリ時の動的候補リストのサイズを制御するパラメータです（ef_construction がインデックスビルド時にだけ影響するのとは別物です）。値を大きくするほどグラフ近傍の探索範囲が広がり、レイテンシと引き換えに recall が上がります。

• スキーマレベルのデフォルト: HnswOption.default_ef_search = Some(ef) でフィールドごとのデフォルトを引き上げられます。None の場合、サーチャは内部 fallback (50) を使用します。
• クエリごとのオーバーライド: 検索リクエスト側で SearchRequestBuilder::vector_ef_search を指定すると、スキーマデフォルトより優先されます。
• 自動引き上げ: いずれの経路で ef_search を指定した場合でも、サーチャは少なくとも top_k（rerank_factor 併用時は top_k * rerank_factor）まで持ち上げるため、top_k 要求に対して候補ヒープが不足することはありません。
• Issue #644 で対応。

パラメータの詳細なガイダンスについては、Vector インデクシングを参照してください。

MultiVector フィールド

MultiVector フィールドは、文書のトークンベクトルをすべて保持します。たとえば ColBERT 型の late interaction モデルが出力するトークンごとの埋め込み（1 パッセージあたり 128 次元のベクトルが 100〜300 本程度）です。ANN 索引は持ちません。ベクトル検索の対象には ならず、別のクエリ（lexical・vector・hybrid）が見つけた候補を再採点するときにだけ読まれます。

#![allow(unused)]
fn main() {
use laurus::{MultiVectorOption, Schema};
use laurus::vector::core::distance::DistanceMetric;

let schema = Schema::builder()
    .add_multi_vector_field(
        "body_colbert",
        MultiVectorOption::new(128).distance(DistanceMetric::Cosine), // Cosine（既定）または DotProduct
    )
    .build();
}

• オプション: dimension（各トークンベクトルの長さ）、distance、storage、 embedder。distance として受け付けるのは Cosine（書き込み時に L2 正規化 するので、類似度は内積になる。ゼロベクトルはそのまま保存する）と DotProduct だけで、それ以外はインデックスの作成時に拒否されます。storage は各トークン ベクトルのディスク上での要素形式を選びます — F32（デフォルト、厳密）、 F16、Int8 のいずれかで、精度とインデックスサイズのトレードオフです。 サイズと誤差の数値は MultiVector ストレージを参照してください。 embedder には、candle_colbert のようなトークン単位の Embedder の名前を指定します （MultiVectorOption::new(96).embedder("colbert")）。
• 値: DataValue::VectorArray(Vec<Vec<f32>>)。1 本以上 8,192 本以下で、各ベクトルは フィールドの次元を持ち、有限値でなければなりません。JSON では、同じ長さの数値配列の 配列（[[0.1, 0.2, ...], [0.3, 0.4, ...]]）です。トークン単位の Embedder がこの フィールドを担当している場合（embedder で指定するか、EngineBuilder::embedder で登録する）は、テキストの値も使えます。テキストは文書のインデックス時にトークン ベクトルへ埋め込まれます（Issue #1349）。そのような Embedder がないフィールドに テキストを与えた文書は拒否されます。
• 保存しない: トークンベクトルはベクトル索引にだけ置きます（300 本 × 128 次元の f32 で 1 文書約 150 KB）。そのため get_documents や検索結果には含まれません。
• 検索できない: フィールド指定なしのベクトル検索と prefix のフィールド指定は、この フィールドを対象にしません。ベクトル検索や DSL でこのフィールドを指定するとエラーです。
• スキーマの変更: 次元・距離・Embedder の変更、他のベクトルフィールド型との 相互変更は、破壊的な変更（Destructive）です。storage の変更は Reindex 扱いです。既存の値から再エンコードできるため、 Engine::update_field(.., UpdateFieldOptions { reindex: true, .. }) でフィールドの既存セグメントを新しいディスク上の形式へ再構築します。

Document

Document は名前付きフィールド値のコレクションです。DocumentBuilder を使用してドキュメントを構築します。

#![allow(unused)]
fn main() {
use laurus::Document;

let doc = Document::builder()
    .add_text("title", "Introduction to Rust")
    .add_text("body", "Rust is a systems programming language.")
    .add_integer("year", 2024)
    .add_float("rating", 4.8)
    .add_boolean("published", true)
    .build();
}

ドキュメントのインデクシング

Engine はドキュメントを追加するための 2 つのメソッドを提供しており、それぞれ異なるセマンティクスを持ちます。

#![allow(unused)]
fn main() {
// Upsert: replaces any existing document with id "doc1"
engine.put_document("doc1", doc).await?;

// Append: adds another chunk under the same id "doc1"
engine.add_document("doc1", chunk2).await?;

// Always commit after indexing
engine.commit().await?;
}

ドキュメントの取得

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

#![allow(unused)]
fn main() {
let docs = engine.get_documents("doc1").await?;
for doc in &docs {
    if let Some(title) = doc.get("title") {
        println!("Title: {:?}", title);
    }
}
}

ドキュメントの削除

外部 ID を共有するすべてのドキュメントとチャンクを削除します。

#![allow(unused)]
fn main() {
engine.delete_documents("doc1").await?;
engine.commit().await?;
}

ドキュメントのライフサイクル

graph LR
    A["Build Document"] --> B["put/add_document()"]
    B --> C["WAL"]
    C --> D["commit()"]
    D --> E["Searchable"]
    E --> F["get_documents()"]
    E --> G["delete_documents()"]

重要: ドキュメントは commit() が呼び出されるまで検索可能になりません。

DocumentBuilder メソッド

DataValue

DataValue は Laurus におけるフィールド値を表す統合列挙型です。

#![allow(unused)]
fn main() {
pub enum DataValue {
    Null,
    Bool(bool),
    Int64(i64),
    Float64(f64),
    Text(String),
    Bytes(Vec<u8>, Option<String>),  // (data, optional MIME type)
    Vector(Vec<f32>),
    DateTime(DateTime<Utc>),
    Geo(GeoPoint),                   // 2D WGS84 ポイント (latitude, longitude)
    GeoEcef(GeoEcefPoint),           // 3D ECEF 直交座標ポイント (x, y, z)、メートル
    Int64Array(Vec<i64>),            // 多値整数フィールド
    Float64Array(Vec<f64>),          // 多値浮動小数点フィールド
    GeoArray(Vec<GeoPoint>),         // 多値 2D 地理フィールド
    GeoEcefArray(Vec<GeoEcefPoint>), // 多値 3D ECEF フィールド
    DateTimeArray(Vec<DateTime<Utc>>), // 多値日時フィールド
    BoolArray(Vec<bool>),            // 多値ブールフィールド
    TextArray(Vec<String>),          // 多値テキストフィールド
    BytesArray(Vec<(Vec<u8>, Option<String>)>), // 多値バイトフィールド（要素ごとに MIME）
    VectorArray(Vec<Vec<f32>>),      // MultiVector フィールドのトークンベクトル
}
}

DataValue は一般的な型に対して From<T> を実装しているため、.into() 変換が使用できます。

#![allow(unused)]
fn main() {
use laurus::DataValue;

let v: DataValue = "hello".into();       // Text
let v: DataValue = 42i64.into();         // Int64
let v: DataValue = 3.14f64.into();       // Float64
let v: DataValue = true.into();          // Bool
let v: DataValue = vec![0.1f32, 0.2].into(); // Vector
}

予約フィールド

アンダースコア（_）で始まるフィールド名はすべてエンジンの予約領域です。 そのような名前のフィールドを宣言すると、インデックス作成時に拒否されます。 _ で始まるキーを含むドキュメントも投入時にエラーとなるため、 いずれにせよそのフィールドが値を持つことはありません。 言語バインディングではさらに早く、フィールド追加メソッド（add_*_field / add*Field）が そのような名前を渡した時点で拒否します。正確なエラー文と、 この検査より前に作成したインデックスの扱いは フィールド命名規則 を参照してください。

唯一許可される _ プレフィックス名は、次に説明する _id システムフィールドです。

_id — 外部ドキュメント ID

put_document / add_document に渡された外部ドキュメント ID を格納します。 KeywordAnalyzer（完全一致）でインデクシングされ、自動的に挿入されるため スキーマに追加する必要はありません。

動的スキーマ

Laurus はスキーマに宣言されていないフィールドを含むドキュメントも受け付けます。 挙動は Schema に設定する DynamicFieldPolicy で制御します:

Builder でポリシーを設定します:

#![allow(unused)]
fn main() {
use laurus::{DynamicFieldPolicy, Schema};

let schema = Schema::builder()
    .dynamic_field_policy(DynamicFieldPolicy::Dynamic)
    .build();
}

型推論ルール（Dynamic ポリシー）

ベクトルフィールド（Hnsw / Flat / Ivf / MultiVector）は 自動推論の対象外です。 次元数・距離関数・embedder の設定は値だけからは復元できないため、 スキーマへ明示的に宣言してください。未宣言のフィールドにトークンベクトルが来た場合は 拒否されます。Bytes の値は上記の {data, mime} オブジェクト形式から解析できるようになりましたが、未宣言の フィールドに Bytes の値が来た場合は、ベクトルフィールドと同様に 自動登録されず拒否されます（Bytes フィールドは常に明示的な宣言が 必要です）。なお、同一 object 内で 2D 用キー（lat / lon）、 3D 用キー（x / y / z）、Bytes 用キー（data）のうち複数を 混在させた場合は曖昧と判定してエラーとなります。いずれか一方の 形式のみ使用してください。

多値（multi-valued）フィールド

Integer と Float フィールドは multi_valued = true を指定することで、 1 ドキュメントに複数の値を保持できます。範囲クエリはいずれかの値が条件を満たせばマッチ する Lucene 流の挙動で、スコアは constant（マッチ件数による加点なし）です。

Geo と Geo3d フィールドも同様に multi_valued = true を指定できます。 多値地理フィールドの各ポイントは、それぞれ独立したエントリとしてフィールドの BKD tree（Geo は 2 次元、Geo3d は 3 次元）に登録されます。そのため距離クエリと バウンディングボックスクエリ（Geo3d では nearest クエリも）は、いずれかのポイントが 条件を満たせばドキュメントにマッチします。ドキュメントは 1 回だけ報告され、 スコアは条件を満たすポイントのうち最も近いもの（2D バウンディングボックスクエリでは ボックス中心に最も近いポイント）で決まります。Dynamic ポリシーでは、2D object と 3D object を 1 つの配列に混在させた場合、および数値と object を混在させた場合は エラーになります。各要素には単一ポイントと同じ範囲検証が適用されます。

DateTime フィールドも同様に multi_valued = true を指定できます（Issue #1184）。 多値日時フィールドの各時刻（instant）は、それぞれ独立した 1 次元のエントリとして フィールドの BKD tree に登録されます。そのため DateTimeRangeQuery、このフィールドに対する NumericRangeQuery、および seen_at:[2024-06-01 TO 2024-12-31] のような DSL の日付範囲は、 いずれかの時刻が範囲内にあればドキュメントにマッチします（Lucene 流の “any match”、 スコアは constant でマッチ件数による加点なし）。複数の時刻がマッチしてもドキュメントは 1 回だけ報告され、秒未満の時刻も尊重されます（境界は小数秒としてエンコードされます）。 Dynamic ポリシーでは、全要素が RFC 3339 文字列である配列は多値 DateTime と推論されます。 ここで日時として認識されるのは RFC 3339 のみで（クエリ DSL が受け付けるオフセットなし・日付のみの形式は 対象外）、RFC 3339 でない要素を含む文字列配列は代わりに多値 Text と推論されます（Issue #1175）—— エラーにはなりません。なお非対称性に注意してください: 単一の RFC 3339 文字列は従来どおり Text と推論されます（既存のテキストフィールドの 挙動を変えないため）が、RFC 3339 文字列の配列は多値 DateTime と推論されます。 単一値の DateTime フィールドが必要な場合はスキーマで明示的に宣言してください。

Boolean フィールドも同様に multi_valued = true を指定できます（Issue #1180）。 ただし仕組みは他の多値型とは異なり、Boolean フィールドは BKD ポイントを持ちません。 多値ブールフィールドの各要素は、それぞれ独立した "true" / "false" の term posting としてインデックスされます。そのため TermQuery や flags:true のような DSL の term クエリは、 いずれかの要素がクエリの値と等しければドキュメントにマッチします（Lucene 流の “any match”）。 複数の要素が同じ値でも、その term についてドキュメントは 1 回だけ報告されます （posting はドキュメント・term ごとに集約されます）。Boolean フィールドが範囲クエリの対象外である点は 従来どおりです。通常の term posting であるため、要素の重複は Lucene と同じように BM25 スコアに影響します: [true, true] は term frequency 2・フィールド長 2 の posting 1 件になるため、flags:true に対して [true] より高くスコアリングされ、[true, false] は長さ正規化（length normalization）のため [true] よりわずかに低くスコアリングされます。重複排除は行わず、term クエリの constant スコアリングも ありません（constant スコアの term クエリは Issue #580 で追跡しています）。 Dynamic ポリシーでは、全要素がブール値である JSON 配列（例: [true, false]）は多値 Boolean と 推論されます。[true, 1] のような混在配列は、既存の「配列フィールドは数値のみ」という趣旨のエラーで 拒否されます。スカラーとの非対称性に注意してください: 単一の "true" 文字列は宣言済みの Boolean フィールドに対して Bool に変換され、["true", "false"] のような文字列配列も宣言済みの多値 Boolean フィールドに送れば同じ規則で要素ごとにパースされます。しかし未宣言のフィールドでは、この配列は Boolean ではなく多値 Text と推論されます（Issue #1175）—— ブールとして推論させたい配列には JSON のブール値を使ってください。 既存の Boolean フィールドで multi_valued を有効にする変更は metadata-only です。無効にする変更は、 フィールドが stored なら再インデックス（Reindex）が必要で、stored: false なら Destructive になります —— BKD ベースの型と異なり、再構築の元になるポイントツリーがなく、保存された値しかないためです。

Text フィールドも同様に multi_valued = true を指定できます（Issue #1175）。あわせて position_increment_gap オプション（デフォルト 100。Lucene / Elasticsearch と同じ値）が追加されています。 多値テキストフィールドの各要素はフィールドの analyzer でそれぞれ独立に解析され、全要素のトークンは **1 本の昇順の位置列（position sequence）**に追記されます: 要素 n + 1 の最初のトークンは、要素 n の 最後のトークンから position_increment_gap 個後ろの位置に置かれます。gap は要素ごとに加算され、 トークンを 1 つも生成しない要素に対しても加算されます。以下の挙動はすべてこの付番から導かれます:

• TermQuery（または tags:rust のような DSL の term）は、いずれかの要素がタームを含めばドキュメントにマッチします（Lucene 流の “any match”）。
• PhraseQuery は、slop が position_increment_gap 以上でない限り 2 つの要素をまたぐことができません —— 閾値はちょうど slop == gap です。デフォルトの gap では、["hello world", "foo bar"] はフレーズ "world foo" に slop 0〜99 ではマッチせず、slop 100 でマッチします。スパンクエリ（SpanNearQuery）も同じ保護を受けます。
• gap を 0 にすると要素を連結したものとして付番されるため、フレーズは要素境界をまたいでマッチします。gap が「0 から付番し直す」という意味になることはありません。
• 複数の要素にまたがるタームの重複は、他の多値型と同じくヒット数ではなく term frequency（したがって BM25 スコア）を増やします。フィールド長はトークン数ではなく position の数です —— 別のトークンにスタックされたシノニム（position_increment = 0）はそのトークンの position を共有し、重ねて数えられません —— そのため gap 自体が BM25 の長さ正規化（length normalization）を膨らませることはありません。
• 2 語以上のフレーズクエリが機能するには位置が保存されている必要があります（term_vectors: true。デフォルト）。位置がなければ検索はクエリエラーで拒否され、これは多値・単一値のどちらのフィールドでも同じです。keyword フィールドに対する tags:"lang/rust" のように 1 トークンに解析される引用符付きの値は Term の一致なので、位置を必要としません。

多値テキストフィールドのハイライトは要素ごとに行われます —— マッチした要素だけがフラグメントを生成し、 フラグメントが 2 つの要素をまたぐことはありません。詳細は ハイライト を参照してください。 Dynamic ポリシーでは、全要素が文字列である JSON 配列は、全要素が RFC 3339 としてパースできれば多値 DateTime、 そうでなければ多値 Text と推論されます（例: ["rust", "search"]）。単一の文字列は従来どおり Text と推論され、 日時と判定されることはありません。既存の Text フィールドで multi_valued を有効にする変更は metadata-only です。 無効にする変更は、フィールドが stored なら再インデックス（Reindex）が必要で、stored: false なら Destructive になります —— Boolean と同じく、再構築の元になる BKD tree がないためです。 position_increment_gap の変更は、フィールドが位置を保存している（term_vectors: true）場合に再インデックスが 必要です（stored なら Reindex、そうでなければ Destructive）。既存の posting は古い gap で付番されているためです。 term_vectors が false なら gap は観測できないため、変更は metadata-only です。

Bytes フィールドも同様に multi_valued = true を指定できます（Issue #1176）。ただし 仕組みは他のどの多値型とも異なり、Boolean よりもさらに徹底しています —— BytesOption には indexed フラグ自体が存在せず、Bytes の値はそもそもレキシカルインデックスされません。 そのため BKD ポイントも term posting も存在せず、multi_valued には “any match” のクエリ 意味論が一切ありません。単に保存時の形と取り込み時の許容個数を変えるだけです。 DataValue::BytesArray は Vec<(Vec<u8>, Option<String>)> で、他の *Array variant が使う 素の Vec<T> とは異なり、各要素がスカラーの Bytes(Vec<u8>, Option<String>) と全く同じ形で 独自の MIME タイプを持ちます。Bytes の値はスカラーでも配列でも、Dynamic ポリシーの下で 未宣言のフィールドに対して推論されることは決してありません（前述の 型推論ルール（Dynamic ポリシー）を参照）。多値 Bytes フィールドは常に明示的な宣言が必要です。宣言済みのフィールドでは、単一の Bytes 値や base64 の Text 文字列は要素 1 個の配列に自動ラップされ（Text 要素はスカラーと同じ規則で base64 デコードされます）、空の数値配列（[]）は空のバイト値リストとして受理されます。 既存の Bytes フィールドで multi_valued を有効にする変更は metadata-only です。無効にする 変更は、フィールドが stored なら再インデックス（Reindex）が必要で、stored: false なら Destructive になります —— Boolean や Text と同じく、再構築の元になるポイントツリーも posting もなく、保存された値しかないためです。

ファセット集計はすべての多値型を要素ごとに展開します（Issue #1187）: 整数・浮動小数点・ブール・ 日時・テキストの各要素がそれぞれ独立したファセット値になり（/ を含むテキスト要素は階層パスになります）、 要素が重複していてもドキュメントごとに 1 回だけ数えられます。地理座標とバイト列の配列はファセットの 対象外で何も寄与しません。要素の文字列形式は ファセット を参照してください。

多値フィールドに単一値を送った場合は要素 1 個の配列に自動ラップされます。 逆に単一値フィールドに配列を送ると、暗黙の切り捨てではなくエラーになります （エラーメッセージは multi_valued = true でフィールドを宣言するよう案内します）。 多値地理・多値日時・多値ブール・多値テキストフィールドに空配列を送った場合は受理され、 ポイント・時刻・term を持たないフィールドになります（どの空間クエリ・範囲クエリ・term クエリ・フレーズクエリにもマッチしません）。 多値バイトフィールドに空配列を送った場合も同様に受理され、単に空リストとして保存されます —— Bytes フィールドはそもそもクエリの対象にならないため、マッチしないクエリというもの自体が存在しません。

多値地理・多値日時・多値ブール・多値テキスト・多値バイトの値を含むセグメントは新しい stored-field 型タグを使用するため、 これらの機能より前のビルドでは読み込めません。フォーマットのバージョンは上げていないため、 古いリーダーはデータを誤読するのではなく、明示的なエラーで失敗します。 保存される多値日時はマイクロ秒精度（時刻ごとに 1 つの i64 Unix マイクロ秒。マイクロ秒未満の桁は 切り捨て）で保持され、単一値の DateTime は完全な精度を保ちます。 保存される多値ブールは要素ごとに 1 バイト（ビットパックなし）で書き込まれます。 保存される多値テキストは、要素数に続けて各文字列を長さプレフィックス付きで書き込みます （本体は単一値のテキストと同じ形式です）。保存される多値バイトは、要素数に続けて各要素を スカラーの Bytes 値と同じ（MIME、続けてデータ）の長さプレフィックス付き形式で書き込みます （空の MIME 文字列は None を意味します）。

型衝突

既に宣言されているフィールドに別の型の値が到着した場合、Laurus は 宣言された型への変換を試みます。変換ルールは以下の通りです:

変換エラーの扱いはポリシーに依存します:

• Strict: ただちにエラーを返す
• Dynamic: エラーを返す（安全とみなせる変換はこの層ですべて試し切っている）
• Ignore: 該当フィールドのみ破棄し、他のフィールドはインデックスする

⚠️ 警告: 静かな情報損失が発生しうる

いくつかの変換は、エラーを返さずに情報を失います:

• Integer フィールドは受け取った Float 値を切り捨てます （3.14 → 3、-3.9 → -3）。投入は成功します
• Float フィールドは f64 仮数部に収まらない巨大な整数で精度を失う可能性があります
• Text フィールドはスカラーを文字列化して受け入れます（元の型情報は消えます）
• Ignore は非互換なフィールドを静かに捨てます

データの正確性を優先したい場合は、DynamicFieldPolicy::Strict を使う（あるいは必要なフィールドをすべて事前に宣言する）ことを推奨します。 Dynamic ポリシーは「ドキュメントを投入できる」ことを「入力データを 1 ビットも失わない」ことより優先します。

Query DSL と未宣言フィールド

スキーマが確定した後、クエリパーサは field:value 句で参照されるフィールドが すべてスキーマに存在することを検証します。titl:hello（title:hello の打ち間違い） のような typo は、結果が無言で空になるのではなく、明確なパースエラーとして返ります。

動的フィールド管理

稼働中のエンジンに対して、フィールドの追加・削除・変更を動的に行えます。

フィールドの追加

Engine::add_field() を使用すると、稼働中のエンジンにフィールドを動的に追加できます。

Lexical フィールドの追加

let updated_schema = engine.add_field(
    "category",
    FieldOption::Text(TextOption::default()),
).await?;

Vector フィールドの追加

let updated_schema = engine.add_field(
    "embedding",
    FieldOption::Flat(FlatOption::default().dimension(384)),
).await?;

既存のドキュメントには影響がありません（新しいフィールドの値が存在しないだけです）。

フィールドの削除

Engine::delete_field() を使用すると、稼働中のエンジンからフィールドを動的に削除できます。

let updated_schema = engine.delete_field("category").await?;

フィールド削除時の動作は以下の通りです。

• スキーマからフィールド定義が削除されます。
• default_fields に含まれている場合、そこからも削除されます。
• フィールドに紐づくアナライザーおよびエンベッダーの登録が解除されます。
• 既にインデックスされたデータは物理的に残りますが、スキーマから削除されたフィールドにはアクセスできなくなります。

フィールドの変更

Engine::update_field() を使用すると、既存フィールドの型・オプションを稼働中のエンジンに対して変更できます。

let outcome = engine.update_field(
    "title",
    FieldOption::Text(TextOption::default().analyzer("english")),
    UpdateFieldOptions { reindex: true, ..Default::default() },
).await?;

変更内容は次の3種類に分類され、outcome.classification で確認できます。

• MetadataOnly（メタデータのみ）: 既存データへの影響がなく、常に適用されます（例: HNSW の default_ef_search）。
• Reindex（再構築が必要）: 保存済みの元データから再構築が可能です（例: text フィールドの analyzer 変更、term_vectors が有効な text フィールドの position_increment_gap 変更、indexed: false → true、HNSW の m/ef_construction 変更）。
• Destructive（破壊的変更）: 元データから再構築できず、既存データを破棄します（例: ベクトルフィールドの dimension/embedder/distance 変更、stored: false フィールドの型変更、stored: false な Boolean / Text / Bytes フィールドの multi_valued を無効にする変更）。

Reindex と Destructive は、明示的に UpdateFieldOptions { reindex: true, .. } を指定しない限り拒否されます（再構築に時間がかかる、あるいはデータを失うため、意図しない実行を防ぐオプトイン方式です）。

Destructive な変更を適用すると、対象フィールド名がスキーマの pending_reindex に記録されます。これは Solr のように「スキーマとインデックスが静かに食い違う」状態を避けるための可視化機構で、GetSchema / laurus get schema から確認できます。既存データを失ったフィールドが分かるので、必要に応じてドキュメントの再投入で解消してください。

UpdateFieldOptions { dry_run: true, .. } を指定すると、実際には何も適用せずに分類結果だけを確認できます。

共通の注意事項

Engine::builder().persist_schema_with(hook) でスキーマ永続化フックを設定していれば、 add_field/delete_field/update_field は返却前に自らそのフックを呼び出してスキーマを永続化します （laurus-cli と laurus-server はどちらもこのフックで schema.toml への書き出しを 行っています）。フックを設定していない場合は、従来どおり返却された Schema を 呼び出し側で永続化する必要があります（例: schema.toml への書き出し）。

スキーマ設計のヒント

1. Lexical フィールドと Vector フィールドを分離する — フィールドは Lexical か Vector のいずれかであり、両方にはなりません。ハイブリッド検索には、別々のフィールドを作成してください（例: テキスト用に body、ベクトル用に body_vec）。

2. 完全一致フィールドには KeywordAnalyzer を使用する — カテゴリ、ステータス、タグフィールドは PerFieldAnalyzer 経由で KeywordAnalyzer を使用し、トークン化を避けてください。

3. 適切なベクトルインデックスを選択する — ほとんどの場合は HNSW、小規模データセットには Flat、非常に大規模なデータセットには IVF を使用してください。詳細は Vector インデクシングを参照。

4. デフォルトフィールドを設定する — Query DSL を使用する場合、デフォルトフィールドを設定することで、ユーザーは body:hello の代わりに hello と記述できます。

5. スキーマジェネレータを使用する — laurus create schema を実行して、手書きの代わりにインタラクティブにスキーマ TOML ファイルを構築できます。詳細は CLI コマンドを参照。

テキスト解析

テキスト解析（Text Analysis）は、生のテキストを検索可能なトークンに変換するプロセスです。ドキュメントがインデクシングされる際、Analyzer がテキストフィールドを個々のタームに分割します。クエリが実行される際も、同じ Analyzer がクエリテキストを処理し、一貫性を確保します。

解析パイプライン

graph LR
    Input["Raw Text\n'The quick brown FOX jumps!'"]
    CF["UnicodeNormalizationCharFilter"]
    T["Tokenizer\nSplit into words"]
    F1["LowercaseFilter"]
    F2["StopFilter"]
    F3["StemFilter"]
    Output["Terms\n'quick', 'brown', 'fox', 'jump'"]

    Input --> CF --> T --> F1 --> F2 --> F3 --> Output

解析パイプラインは以下で構成されます。

1. Char Filter — トークン化の前に文字レベルで生テキストを正規化する
2. Tokenizer — テキストを生トークン（単語、文字、n-gram）に分割する
3. Token Filter — トークンの変換、削除、展開を行う（小文字化、ストップワード除去、ステミング、同義語展開）

Analyzer トレイト

すべての Analyzer は Analyzer トレイトを実装します。

#![allow(unused)]
fn main() {
pub trait Analyzer: Send + Sync + Debug {
    fn analyze(&self, text: &str) -> Result<TokenStream>;
    fn name(&self) -> &str;
    fn as_any(&self) -> &dyn Any;
}
}

TokenStream は Box<dyn Iterator<Item = Token> + Send> であり、トークンの遅延イテレータです。

Token には以下のフィールドが含まれます。

組み込み Analyzer

StandardAnalyzer

デフォルトの Analyzer です。ほとんどの西洋言語に適しています。

パイプライン: RegexTokenizer（Unicode 単語境界） → LowercaseFilter → StopFilter（128 個の一般的な英語ストップワード）

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::standard::StandardAnalyzer;

let analyzer = StandardAnalyzer::default();
// "The Quick Brown Fox" → ["quick", "brown", "fox"]
// ("The" is removed by stop word filtering)
}

JapaneseAnalyzer

日本語テキストの分割に形態素解析を使用します。

パイプライン: UnicodeNormalizationCharFilter（NFKC） → JapaneseIterationMarkCharFilter → LinderaTokenizer → LowercaseFilter → StopFilter（日本語ストップワード）

JapaneseAnalyzer::new は LinderaTokenizer::new と同じ引数（segmentation mode、Lindera 辞書ディレクトリのパス、任意のユーザー辞書パス）を受け取ります。laurus は Lindera の embed-* features をデフォルトで有効化しないため、IPADIC 等の辞書を実ファイルパスとして必ず指定する必要があります。

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::language::japanese::JapaneseAnalyzer;

// Lindera 辞書を展開済みのパスを指定する。
let analyzer = JapaneseAnalyzer::new(
    "normal",
    "/var/lib/lindera/ipadic",
    None,
)?;
// "東京都に住んでいる" → ["東京", "都", "住ん", "いる"]
}

Schema 経由で参照する場合は構造化された AnalyzerSpec 形式でパラメータを渡します（後述の PerFieldAnalyzer を参照）。

KeywordAnalyzer

入力全体を単一のトークンとして扱います。トークン化や正規化は行いません。

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::keyword::KeywordAnalyzer;

let analyzer = KeywordAnalyzer::new();
// "Hello World" → ["Hello World"]
}

完全一致が必要なフィールド（カテゴリ、タグ、ステータスコード）に使用してください。

SimpleAnalyzer

フィルタリングなしでテキストをトークン化します。元の大文字小文字とすべてのトークンが保持されます。解析パイプラインを完全に制御したい場合や、Tokenizer を単独でテストしたい場合に便利です。

パイプライン: ユーザー指定の Tokenizer のみ（Char Filter なし、Token Filter なし）

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::simple::SimpleAnalyzer;
use laurus::analysis::tokenizer::regex::RegexTokenizer;
use std::sync::Arc;

let tokenizer = Arc::new(RegexTokenizer::new()?);
let analyzer = SimpleAnalyzer::new(tokenizer);
// "Hello World" → ["Hello", "World"]
// (no lowercasing, no stop word removal)
}

Tokenizer のテストや、別のステップで手動で Token Filter を適用したい場合に使用してください。

EnglishAnalyzer

英語に特化した Analyzer です。トークン化、小文字化、一般的な英語ストップワードの除去を行います。

パイプライン: RegexTokenizer（Unicode 単語境界） → LowercaseFilter → StopFilter（128 個の一般的な英語ストップワード）

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::language::english::EnglishAnalyzer;

let analyzer = EnglishAnalyzer::new()?;
// "The Quick Brown Fox" → ["quick", "brown", "fox"]
// ("The" is removed by stop word filtering, remaining tokens are lowercased)
}

PipelineAnalyzer

任意の Char Filter、Tokenizer、Token Filter のシーケンスを組み合わせてカスタムパイプラインを構築します。

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::pipeline::PipelineAnalyzer;
use laurus::analysis::char_filter::unicode_normalize::{
    NormalizationForm, UnicodeNormalizationCharFilter,
};
use laurus::analysis::tokenizer::regex::RegexTokenizer;
use laurus::analysis::token_filter::lowercase::LowercaseFilter;
use laurus::analysis::token_filter::stop::StopFilter;
use laurus::analysis::token_filter::stem::StemFilter;

let analyzer = PipelineAnalyzer::new(Arc::new(RegexTokenizer::new()?))
    .add_char_filter(Arc::new(UnicodeNormalizationCharFilter::new(NormalizationForm::NFKC)))
    .add_filter(Arc::new(LowercaseFilter::new()))
    .add_filter(Arc::new(StopFilter::new()))
    .add_filter(Arc::new(StemFilter::new()));  // Porter stemmer
}

PerFieldAnalyzer

PerFieldAnalyzer を使用すると、同一 Engine 内で異なるフィールドに異なる Analyzer を割り当てることができます。

graph LR
    PFA["PerFieldAnalyzer"]
    PFA -->|"title"| KW["KeywordAnalyzer"]
    PFA -->|"body"| STD["StandardAnalyzer"]
    PFA -->|"description_ja"| JP["JapaneseAnalyzer"]
    PFA -->|other fields| DEF["Default\n(StandardAnalyzer)"]

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::analysis::analyzer::standard::StandardAnalyzer;
use laurus::analysis::analyzer::keyword::KeywordAnalyzer;
use laurus::analysis::analyzer::per_field::PerFieldAnalyzer;

// Default analyzer for fields not explicitly configured
let per_field = PerFieldAnalyzer::new(
    Arc::new(StandardAnalyzer::default())
);

// Use KeywordAnalyzer for exact-match fields
per_field.add_analyzer("category", Arc::new(KeywordAnalyzer::new()));
per_field.add_analyzer("status", Arc::new(KeywordAnalyzer::new()));

let engine = Engine::builder(storage, schema)
    .analyzer(Arc::new(per_field))
    .build()
    .await?;
}

注意: _id フィールドは設定に関係なく、常に KeywordAnalyzer で解析されます。

Schema からの per-field analyzer 設定

実装で直接 PerFieldAnalyzer を組み立てる代わりに、スキーマ宣言で analyzer を割り当てる場合がほとんどです。テキストフィールドの analyzer 設定は次の 2 つの形式を受け付けます。

// 1. パラメータ不要の組込 analyzer、または schema.analyzers に登録した名前。
{ "analyzer": "standard" }
{ "analyzer": "english" }
{ "analyzer": "my_custom_pipeline" }

// 2. パラメータ付きの組込プリセット。現状は Japanese プリセットのみで、Lindera 辞書のパスが必須。
{
  "analyzer": {
    "language": "japanese",
    "mode": "normal",
    "dict": "/var/lib/lindera/ipadic"
  }
}

文字列単独の "japanese" は辞書パスを伴わないためエラーとなります。既存スキーマで "analyzer": "japanese" を保存していた場合は、上記の構造化形式に移行してください。

プリセットに収まらないパイプラインを使いたい場合は、schema.analyzers に AnalyzerDefinition として登録し、フィールドからは名前で参照します。パラメータ不要の組込 analyzer の名前は予約されているため、パイプラインには別の名前を付けてください（アナライザの参照 を参照）。

Char Filter

Char Filter は Tokenizer に渡される前の生入力テキストに対して動作します。Unicode 正規化、文字マッピング、パターンベースの置換などの文字レベルの正規化を行います。これにより、Tokenizer がクリーンで正規化されたテキストを受け取ることが保証されます。

すべての Char Filter は CharFilter トレイトを実装します。

#![allow(unused)]
fn main() {
pub trait CharFilter: Send + Sync {
    fn filter(&self, input: &str) -> (String, Vec<Transformation>);
    fn name(&self) -> &'static str;
}
}

Transformation レコードは文字位置がどのようにシフトしたかを記述し、Engine がトークン位置を元テキストにマッピングできるようにします。

UnicodeNormalizationCharFilter

入力テキストに Unicode 正規化を適用します。検索用途では NFKC が推奨されます。互換文字と合成形式の両方を正規化するためです。

#![allow(unused)]
fn main() {
use laurus::analysis::char_filter::unicode_normalize::{
    NormalizationForm, UnicodeNormalizationCharFilter,
};

let filter = UnicodeNormalizationCharFilter::new(NormalizationForm::NFKC);
// "Ｓｏｎｙ" (fullwidth) → "Sony" (halfwidth)
// "㌂" → "アンペア"
}

MappingCharFilter

辞書を使用して文字シーケンスを置換します。Aho-Corasick アルゴリズム（最左最長一致）によりマッチングが行われます。

#![allow(unused)]
fn main() {
use std::collections::HashMap;
use laurus::analysis::char_filter::mapping::MappingCharFilter;

let mut mapping = HashMap::new();
mapping.insert("ph".to_string(), "f".to_string());
mapping.insert("qu".to_string(), "k".to_string());

let filter = MappingCharFilter::new(mapping)?;
// "phone queue" → "fone keue"
}

PatternReplaceCharFilter

正規表現パターンのすべての出現箇所を固定文字列で置換します。

#![allow(unused)]
fn main() {
use laurus::analysis::char_filter::pattern_replace::PatternReplaceCharFilter;

// Remove hyphens
let filter = PatternReplaceCharFilter::new(r"-", "")?;
// "123-456-789" → "123456789"

// Normalize numbers
let filter = PatternReplaceCharFilter::new(r"\d+", "NUM")?;
// "Year 2024" → "Year NUM"
}

JapaneseIterationMarkCharFilter

日本語の踊り字を基本文字に展開します。漢字（々）、ひらがな（ゝ、ゞ）、カタカナ（ヽ、ヾ）の踊り字をサポートします。

#![allow(unused)]
fn main() {
use laurus::analysis::char_filter::japanese_iteration_mark::JapaneseIterationMarkCharFilter;

let filter = JapaneseIterationMarkCharFilter::new(
    true,  // normalize kanji iteration marks
    true,  // normalize kana iteration marks
);
// "佐々木" → "佐佐木"
// "いすゞ" → "いすず"
}

パイプラインでの Char Filter の使用

PipelineAnalyzer に add_char_filter() で Char Filter を追加します。複数の Char Filter は追加された順序で適用され、すべて Tokenizer の実行前に処理されます。

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::analysis::analyzer::pipeline::PipelineAnalyzer;
use laurus::analysis::char_filter::unicode_normalize::{
    NormalizationForm, UnicodeNormalizationCharFilter,
};
use laurus::analysis::char_filter::pattern_replace::PatternReplaceCharFilter;
use laurus::analysis::tokenizer::regex::RegexTokenizer;
use laurus::analysis::token_filter::lowercase::LowercaseFilter;

let analyzer = PipelineAnalyzer::new(Arc::new(RegexTokenizer::new()?))
    .add_char_filter(Arc::new(
        UnicodeNormalizationCharFilter::new(NormalizationForm::NFKC),
    ))
    .add_char_filter(Arc::new(
        PatternReplaceCharFilter::new(r"-", "")?,
    ))
    .add_filter(Arc::new(LowercaseFilter::new()));
// "Ｔｏｋｙｏ-2024" → NFKC → "Tokyo-2024" → remove hyphens → "Tokyo2024" → tokenize → lowercase → ["tokyo2024"]
}

Tokenizer

Token Filter

同義語展開

SynonymGraphFilter は同義語辞書を使用してタームを展開します。

#![allow(unused)]
fn main() {
use laurus::analysis::synonym::dictionary::SynonymDictionary;
use laurus::analysis::token_filter::synonym_graph::SynonymGraphFilter;

let mut dict = SynonymDictionary::new(None)?;
dict.add_synonym_group(vec!["ml".into(), "machine learning".into()]);
dict.add_synonym_group(vec!["ai".into(), "artificial intelligence".into()]);

// keep_original=true means original token is preserved alongside synonyms
let filter = SynonymGraphFilter::new(dict, true)
    .with_boost(0.8);  // 各同義語トークンに保存されるが、スコアリングは今のところ読まない（下記参照）
}

boost パラメータは各同義語 Token に保存されますが、インデクサもクエリパーサもこの値を今のところ読まないため、スコアリングやマッチングには影響しません —— 同義語のマッチは現在、完全一致と全く同じにスコア付けされます（下記同義語を使った検索参照）。独自のパイプラインステージで利用する予定がある場合は設定してください。同義語マッチの重みを下げる目的では使えません。

複数語の見出し語の一致

複数語の見出し語は、連続するトークンがすべて英数字（トークン種別 Alphanum または Num）のとき、またはオフセットが連続している（各トークンの end_offset が次のトークンの start_offset と等しい）ときに一致します。前者により空白で区切られた英単語が一致し、後者により形態素トークナイザが分割した CJK の語が一致します。種別は Token::metadata から読むため、種別のないトークンはオフセットが連続している必要があります。辞書に 東京大学 があるとき、東京 と 大学 に分割されたテキスト 東京大学 は一致しますが、東京 大学 は 2 つのトークンの間に空白があるため一致しません。

トークングラフ

このフィルタは、同義語を展開元の語と同じ位置に積みます（position_increment = 0）。そのため出力はグラフになり、トークンは「位置」から「位置 + position_length」への弧（arc）になります。一致した語とすべての同義語は、同じ開始ノードから同じ終了ノードまで続きます。短い代替語の最後のトークンが残りの位置をまたぎ、一致区間の次のトークンは終了ノードから始まります。ml と machine learning を同義語とした ml tutorial の出力は次のとおりです。

複数語のメンバーは、それぞれ専用の内側のノードを持ちます。そのため、2 つのメンバーの語が同じ弧に入ることはありません。ml と machine learning、statistical machine learning を同義語とした ml の出力は次のとおりです。

インデックスは position_length を保存しないため、グラフを最長の経路に沿って並べ直してから保存します。このとき、メンバーの語は位置を共有します。上の例では、ml・machine・statistical が位置 0、learning・machine が位置 1、learning が位置 2 に保存されます。積まれたトークンは展開元の語と同じ位置に保存されます。それ以外の位置は詰めて振られます。StopFilter が取り除いたストップワードの位置は空きません。この並べ直しはインデックスが行うため、アナライザーに FlattenGraphFilter は不要です。エンジンはクエリも同じアナライザーでパースするので、FlattenGraphFilter を入れると、引用符で囲んだ値をマッチさせるグラフまでフラット化されてしまいます。

同義語を使った検索

エンジンは、フィールドのアナライザーをインデックスとクエリのパースの両方に使います。そのため、同義語は両側で展開されます。引用符なしの語は、その同義語のどれにでもマッチします。引用符で囲んだ値はグラフに沿ってマッチします（フレーズクエリを参照）。big と large を同義語とすると、"big" はどちらの語にもマッチし、"a big dog" は「a large dog」にもマッチします。グループの各メンバーはそれぞれ 1 つのフレーズになります。上の例のメンバーなら、"ml" は ml、machine learning、statistical machine learning にマッチし、「statistical learning」にはマッチしません。同じ長さのメンバーも別々のフレーズになります。引用符で囲んだ値のフレーズはグラフに沿ってまとめてマッチするので、同義語ごとに掛け算で増えるその数に上限はありません。

1 つの位置に複数の代替語（同義語）が積まれている場合、それらは独立したタームのスコアを合算するのではなく、1 つのブレンドされたターム（SynonymQuery）としてスコア付けされます。big と large の両方を含む文書は "big" に対して big を 2 回含む文書と同じスコアになり、2 倍にはなりません。フィールド長もトークン数ではなく位置の数で数えるため、積まれた同義語が文書を長くすることもありません。詳細はBM25（デフォルト）を参照してください。

インデックスは位置を保存しますが position_length は保存しないため、複数語の同義語をインデックス時に展開すると、Lucene と同じく次のようになります。

• フレーズが同義語の途中から始まったり、途中で終わったりしてもマッチします。"learning is" は「ml is fun」にマッチします。同義語を通すと「machine learning is fun」と読めるためです。
• 1 つのグループに複数語のメンバーが複数あると、インデックスではそれらの語が位置を共有します。そのため、1 つのメンバーを含む文書が、2 つのメンバーの語が混ざったフレーズにもマッチします。「ml is fun」は "statistical learning" にマッチします。

そのほかの注意点は次のとおりです。

• keep_original = false は、一致した語をグループのほかのメンバーで置き換えます。そのため、その語自体はインデックスも検索もされません。検索には keep_original = true を使ってください。
• StopFilter・RemoveEmptyFilter・LimitFilter のようにトークンを取り除くフィルターは、SynonymGraphFilter の後ろに置けます。グラフの中でも、取り除いた語の位置は空きません。statue of liberty と lady liberty を同義語とし、of をストップワードとすると、"statue of liberty" は「statue of liberty」と「lady liberty」の両方にマッチします。StopFilter を SynonymGraphFilter より前に置くと、同義語フィルターが見る前に of が取り除かれるため、このメンバーはマッチしなくなります。
• 取り除いた語と同じ位置にほかの選択肢（積まれた 1 語の同義語など）があれば、その位置は選択肢に引き継がれます。the と a を同義語とすると、the を取り除いても a がその位置に残り、その語を飛ばす経路はできません。LimitFilter は、すべての経路を同じトークンで切ります。
• Issue #1252 より前にインデックスした文書は、積まれたトークンに連続した位置を振っています。また Issue #1257 より前にインデックスした文書は、積まれたトークンもすべてフィールド長に数えてしまい、長さが水増しされています。フィールドが SynonymGraphFilter を使う場合は、アップグレード後に文書を投入し直してください。セグメントのマージは保存済みの位置とフィールド長をどちらもそのままコピーするため、マージでは直りません。

Embedding

Embedding は、テキスト（または画像）を意味的な情報を捉えた密なベクトル（数値ベクトル）に変換します。類似した意味を持つ 2 つのテキストは、ベクトル空間内で近い位置のベクトルを生成するため、類似度ベースの検索が可能になります。

Embedder トレイト

すべての Embedder は Embedder トレイトを実装します。

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Embedder: Send + Sync + Debug {
    async fn embed(&self, input: &EmbedInput<'_>) -> Result<Vector>;
    async fn embed_batch(&self, inputs: &[EmbedInput<'_>]) -> Result<Vec<Vector>>;
    fn supported_input_types(&self) -> Vec<EmbedInputType>;
    fn name(&self) -> &str;
    fn as_any(&self) -> &dyn Any;
}
}

embed() メソッドは Vector（Vec<f32> をラップした構造体）を返します。

EmbedInput は 2 つのモダリティをサポートします。

トークン単位の Embedder

ColBERT のような late interaction のモデルは、入力全体で 1 本ではなく、 トークンごとに 1 本のベクトルを出し、クエリと文書を異なる方法で符号化します。 このような Embedder は TokenEmbedder も実装し、Embedder::as_token_embedder で自分自身を返します（Issue #1349）。

#![allow(unused)]
fn main() {
#[async_trait]
pub trait TokenEmbedder: Send + Sync + Debug {
    async fn embed_tokens(&self, inputs: &[EmbedInput<'_>], role: EmbedRole)
        -> Result<Vec<Vec<Vector>>>;
    fn token_dimension(&self) -> usize;
}

pub enum EmbedRole { Query, Document }
}

MultiVector フィールドは、テキストを この trait でだけ埋め込みます。この trait を持たない Embedder（1 入力 1 本の ベクトルを出すモデル）は、1 トークンだけの文書を黙って作るのではなく、 エラーになります。

組み込み Embedder

CandleBertEmbedder

Hugging Face Candle を使用して BERT モデルをローカルで実行します。API キーは不要です。

Feature flag: embeddings-candle

#![allow(unused)]
fn main() {
use laurus::CandleBertEmbedder;

// Downloads model on first run (~80MB)
let embedder = CandleBertEmbedder::new(
    "sentence-transformers/all-MiniLM-L6-v2"  // model name
)?;
// Output: 384-dimensional vector
}

sentence-transformers と同じ方法で符号化し、all-MiniLM-L6-v2 と paraphrase-multilingual-MiniLM-L12-v2 では、出力のベクトルが sentence-transformers と要素ごとに 1e-6 以内で一致します。

• 入力は、sentence_bert_config.json にあるモデルの max_seq_length （all-MiniLM-L6-v2 は 256 トークン、paraphrase-multilingual-MiniLM-L12-v2 は 128） で切り詰めます。特殊トークンも長さに含みます。このファイルがないリポジトリでは、 tokenizer.json の切り詰めの長さ、それもなければモデルの max_position_embeddings を使います。tokenizer.json の padding の設定は使いません。
• ベクトルは、トークンのベクトルの平均を L2 正規化したものです。sentence-transformers では正規化しないモデル（paraphrase-multilingual-MiniLM-L12-v2 など）や、別の方法で pooling するモデルでも、同じようにこの処理を行います。

CandleBertEmbedder::with_options(model, CandleBertOptions::default().revision("<commit>")) で、モデルをコミットに固定できます。

マイグレーション注記（Issue #1340）: 以前の版は attention mask を token type id としてモデルに渡し、すべての入力を tokenizer.json の長さまで PAD で埋めていたため、 ベクトルがずれていました（all-MiniLM-L6-v2 では、短い文で sentence-transformers との cosine が 0.61〜0.70 しかありませんでした）。candle_bert のベクトルは変わり、長い入力は all-MiniLM-L6-v2 で 128 ではなく max_seq_length トークンまで使うようになりました。 candle_bert で作った索引は埋め込み直してください。そうしないと、新しいクエリの ベクトルが古い文書のベクトルと比べられます。

マイグレーション注記（Issue #1355）: 以前の版は、ダウンロードしたモデルを hf-hub 本来のデフォルトである ~/.cache/huggingface/hub/models--* ではなく ~/.cache/huggingface/models--* にキャッシュしており、HF_HUB_CACHE・ XDG_CACHE_HOME も無視していました。モデルは今後 hf-hub 本来のデフォルトの 場所にダウンロードされ、Python の huggingface_hub ライブラリとキャッシュを 共有します。古いパスに残っている既存のダウンロードは再利用されないため、 削除してかまいません。

OpenAIEmbedder

OpenAI Embeddings API を呼び出します。API キーが必要です。

Feature flag: embeddings-openai

#![allow(unused)]
fn main() {
use laurus::OpenAIEmbedder;

let embedder = OpenAIEmbedder::new(
    api_key,
    "text-embedding-3-small".to_string()
).await?;
// Output: 1536-dimensional vector
}

CandleClipEmbedder

マルチモーダル（テキスト + 画像）Embedding のために CLIP モデルをローカルで実行します。

Feature flag: embeddings-multimodal

#![allow(unused)]
fn main() {
use laurus::CandleClipEmbedder;

let embedder = CandleClipEmbedder::new(
    "openai/clip-vit-base-patch32"
)?;
// Text or images → 512-dimensional vector
}

マイグレーション注記（Issue #1355）: 以前の版は、ダウンロードしたモデルを hf-hub 本来のデフォルトである ~/.cache/huggingface/hub/models--* ではなく ~/.cache/huggingface/models--* にキャッシュしており、HF_HUB_CACHE・ XDG_CACHE_HOME も無視していました。モデルは今後 hf-hub 本来のデフォルトの 場所にダウンロードされ、Python の huggingface_hub ライブラリとキャッシュを 共有します。古いパスに残っている既存のダウンロードは再利用されないため、 削除してかまいません。

CandleColbertEmbedder

BERT ベースの ColBERT のチェックポイントをローカルで実行し、トークンごとに 1 本のベクトルを出します。MultiVector フィールドに対する late interaction による再採点 に使います。トークン単位の Embedder 専用で、embed() はエラーを返します。

Feature flag: embeddings-candle

#![allow(unused)]
fn main() {
use laurus::{CandleColbertEmbedder, CandleColbertOptions};

// Uses the checkpoint's own settings (artifact.metadata).
let embedder = CandleColbertEmbedder::new("colbert-ir/colbertv2.0")?;

// Pin the model commit and override the lengths.
let embedder = CandleColbertEmbedder::with_options(
    "answerdotai/answerai-colbert-small-v1",
    CandleColbertOptions::default()
        .revision("934fa8bb4ce2284f4c2baa232d81aca4d076fa5e")
        .doc_maxlen(300),
)?;
}

参照実装の colbert-ai と同じ方法で符号化します。

query:    [CLS] [unused0] w1 … wn [SEP] [MASK] … [MASK]   exactly query_maxlen tokens
document: [CLS] [unused1] w1 … wn [SEP]                   at most doc_maxlen tokens

• クエリの [MASK] による埋め草には attention を向けませんが、そのベクトルは 残します。クエリを拡張する役割を持つためです。
• 文書では、句読点のトークンのベクトルを取り除きます。
• どのベクトルも、チェックポイントの linear 層で射影してから L2 正規化します。

長さ、マーカー、これらの切り替えは、チェックポイントの artifact.metadata から読みます（ファイルがない場合は colbert-ai の既定値の 32 と 220）。 CandleColbertOptions で長さを上書きできます。上の 2 つのチェックポイントでは、 出力のベクトルが colbert-ai と要素ごとに 1e-6 以内で一致します。

推論は CPU 上のブロッキングタスクで、最大 32 件ずつのバッチで行います。 目安として、Apple M4 ではクエリ 1 件が colbertv2.0 で約 55 ms、 answerai-colbert-small-v1 で約 18 ms、約 110 トークンの文書 1 件が約 135 ms と 約 45 ms です。

revision はコミットに固定してください。write-ahead log はまだコミットされて いない文書のテキストを保持し、復旧時に埋め込み直すため、モデルが変わると 異なるベクトルになります。対応するのは BERT ベースのチェックポイントだけです （lightonai/GTE-ModernColBERT-v1 のような ModernBERT ベースのものは対象外）。

PrecomputedEmbedder

Embedding 計算を行わず、事前計算済みのベクトルを直接使用します。ベクトルが外部で生成される場合に便利です。

#![allow(unused)]
fn main() {
use laurus::PrecomputedEmbedder;

let embedder = PrecomputedEmbedder::new();  // no parameters needed
}

PrecomputedEmbedder を使用する場合、ドキュメントには Embedding 用のテキストではなく、ベクトルを直接指定します。

#![allow(unused)]
fn main() {
let doc = Document::builder()
    .add_vector("embedding", vec![0.1, 0.2, 0.3, ...])
    .build();
}

PerFieldEmbedder

PerFieldEmbedder は Embedding リクエストをフィールド固有の Embedder にルーティングします。

graph LR
    PFE["PerFieldEmbedder"]
    PFE -->|"text_vec"| BERT["CandleBertEmbedder\n(384 dim)"]
    PFE -->|"image_vec"| CLIP["CandleClipEmbedder\n(512 dim)"]
    PFE -->|other fields| DEF["Default Embedder"]

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::PerFieldEmbedder;

let bert = Arc::new(CandleBertEmbedder::new("...")?);
let clip = Arc::new(CandleClipEmbedder::new("...")?);


let per_field = PerFieldEmbedder::new(bert.clone());
per_field.add_embedder("text_vec", bert.clone());
per_field.add_embedder("image_vec", clip.clone());

let engine = Engine::builder(storage, schema)
    .embedder(Arc::new(per_field))
    .build()
    .await?;
}

これは以下の場合に特に有用です。

• 異なる Vector フィールドに異なるモデルが必要な場合（例: テキスト用に BERT、画像用に CLIP）
• 異なるフィールドが異なるベクトル次元を持つ場合
• ローカル Embedder とリモート Embedder を混在させたい場合

Embedding の使用方法

インデクシング時

Vector フィールドにテキスト値を追加すると、Engine が自動的に Embedding を生成します。

#![allow(unused)]
fn main() {
let doc = Document::builder()
    .add_text("text_vec", "Rust is a systems programming language")
    .build();
engine.add_document("doc-1", doc).await?;
// The embedder converts the text to a vector before indexing
}

トークン単位の Embedder を持つ MultiVector フィールドも、同じようにテキストを 受け付けます。テキストは文書として、トークンごとに 1 本のベクトルへ埋め込まれます。

検索時

テキストで検索すると、Engine がクエリテキストも同様に Embedding 化します。

#![allow(unused)]
fn main() {
// Builder API
let request = VectorSearchRequestBuilder::new()
    .add_text("text_vec", "systems programming")
    .build();

// Query DSL
let request = vector_parser.parse(r#"text_vec:"systems programming""#).await?;
}

どちらのアプローチも、インデクシング時と同じ Embedder を使用してクエリテキストを Embedding 化するため、一貫したベクトル空間が保証されます。

late interaction による再採点も、クエリをテキストで受け取れます （RescoreOptions::late_interaction_text）。MultiVector フィールドのトークン単位の Embedder が、それをクエリとして埋め込みます。

Feature Flag まとめ

各 Embedder は Cargo.toml で特定の Feature Flag を有効にする必要があります。

embeddings-all Feature ですべての Embedding 機能を一括で有効にできます。詳細は Feature Flags を参照してください。

Embedder の選択

ストレージ

Laurus はプラガブルなストレージレイヤーを使用し、インデックスデータの永続化方法と保存場所を抽象化します。すべてのコンポーネント（Lexical インデックス、Vector インデックス、ドキュメントログ）は単一のストレージバックエンドを共有します。

Storage トレイト

すべてのバックエンドは Storage トレイトを実装します。

#![allow(unused)]
fn main() {
pub trait Storage: Send + Sync + Debug {
    fn loading_mode(&self) -> LoadingMode;
    fn open_input(&self, name: &str) -> Result<Box<dyn StorageInput>>;
    fn create_output(&self, name: &str) -> Result<Box<dyn StorageOutput>>;
    fn file_exists(&self, name: &str) -> bool;
    fn delete_file(&self, name: &str) -> Result<()>;
    fn list_files(&self) -> Result<Vec<String>>;
    fn file_size(&self, name: &str) -> Result<u64>;
    // ... additional methods
}
}

このインターフェースはファイル指向です。すべてのデータ（インデックスセグメント、メタデータ、WAL エントリ、ドキュメント）は名前付きファイルとして保存され、ストリーミング StorageInput / StorageOutput ハンドルを通じてアクセスされます。

ストレージバックエンド

MemoryStorage

すべてのデータがメモリ上に保持されます。高速でシンプルですが、耐久性はありません。

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::Storage;
use laurus::storage::memory::MemoryStorage;

let storage: Arc<dyn Storage> = Arc::new(
    MemoryStorage::new(Default::default())
);
}

FileStorage

標準的なファイルシステムベースの永続化です。各キーがディスク上のファイルにマッピングされます。

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::Storage;
use laurus::storage::file::{FileStorage, FileStorageConfig};

let config = FileStorageConfig::new("/tmp/laurus-data");
let storage: Arc<dyn Storage> = Arc::new(FileStorage::new("/tmp/laurus-data", config)?);
}

メモリマッピング付き FileStorage

FileStorage は use_mmap 設定フラグによるメモリマップドファイル アクセスをサポートします。有効にすると OS がメモリとディスク間の ページングを管理し、レキシカルの posting デコーダ (Issue #504) は StorageInput::as_slice 経由の zero-copy パスを取り、PFOR ビットパック済みブロックを bitpacking::decompress* に直接渡します （Read 経由の Vec<u8> 確保とコピーを省略）。

デフォルトはプラットフォーム依存:

• *Unix (Linux / macOS / BSD): true (Issue #504 以降)。デバッグ セッションや mmap が機能しないホストでバッファード I/O に切り替える には、FileStorageConfig::new 呼び出し時に LAURUS_NO_MMAP=1 環境変数を設定します。
• Windows: false (Issue #508 以降)。Windows はメモリマップ ドファイルに排他ロックを持ち (ERROR_USER_MAPPED_FILE、os error 1224)、reader が mmap を保持したまま writer がセグメント ファイルを truncate / delete することを許可しません。現状の segment file lifecycle はこのロックと整合しません。コミット頻度 が低い read-only / read-mostly ワークロードでは LAURUS_USE_MMAP=1 でオプトイン可能です。Windows mmap の完全 サポートは Issue #508 で 追跡しています。

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::Storage;
use laurus::storage::file::{FileStorage, FileStorageConfig};

// Unix では mmap がデフォルトで有効、Windows では LAURUS_USE_MMAP=1
// を設定しない限り無効。
let config = FileStorageConfig::new("/tmp/laurus-data");
let storage: Arc<dyn Storage> = Arc::new(FileStorage::new("/tmp/laurus-data", config)?);

// 環境変数に触れずに明示的にオプトアウト（OS 不問）。
let mut buffered_config = FileStorageConfig::new("/tmp/laurus-data");
buffered_config.use_mmap = false;

// 明示的にオプトイン（Windows でも有効、OS 不問）。
let mut mmap_config = FileStorageConfig::new("/tmp/laurus-data");
mmap_config.use_mmap = true;
}

StorageFactory

設定を使用してストレージを作成することもできます。

#![allow(unused)]
fn main() {
use laurus::storage::{StorageConfig, StorageFactory};
use laurus::storage::memory::MemoryStorageConfig;

let storage = StorageFactory::create(
    StorageConfig::Memory(MemoryStorageConfig::default())
)?;
}

PrefixedStorage

Engine は PrefixedStorage を使用して、単一のストレージバックエンド内でコンポーネントを分離します。

graph TB
    E["Engine"]
    E --> P1["PrefixedStorage\nprefix = 'lexical/'"]
    E --> P2["PrefixedStorage\nprefix = 'vector/'"]
    E --> P3["PrefixedStorage\nprefix = 'documents/'"]
    P1 --> S["Storage Backend"]
    P2 --> S
    P3 --> S

Lexical ストアがキー segments/seg-001.dict を書き込む場合、実際には基盤バックエンドでは lexical/segments/seg-001.dict として保存されます。これにより、コンポーネント間のキー衝突が防止されます。

PrefixedStorage を自分で作成する必要はありません。EngineBuilder が自動的に処理します。

ColumnStorage

主要なストレージバックエンドに加えて、Laurus はフィールドレベルの高速アクセスのための ColumnStorage レイヤーを提供します。これはファセッティング、ソート、集計などの操作で内部的に使用され、ドキュメント全体をデシリアライズせずに個々のフィールド値にアクセスすることが重要な場合に利用されます。

ColumnValue

ColumnValue は単一の格納されたカラム値を表します。

ColumnStorage は Engine が内部的に管理するため、直接操作する必要はありません。

バックエンドの選択

推奨事項

• 開発 / テスト: ファイルクリーンアップなしで高速に反復するために MemoryStorage を使用
• 本番（一般）: 信頼性の高い永続化のために FileStorage を使用
• 本番（大規模）: 大規模なインデックスがあり OS のページキャッシュを活用したい場合は FileStorage の use_mmap = true を使用

次のステップ

• Lexical インデックスの仕組みを学ぶ: Lexical インデクシング
• Vector インデックスの仕組みを学ぶ: Vector インデクシング

インデキシング（Indexing）

このセクションでは、Laurus がデータを内部的にどのように格納・整理するかについて説明します。インデキシングレイヤーを理解することで、適切なフィールドタイプの選択やパフォーマンスチューニングに役立ちます。

トピック

Lexical インデキシング

転置インデックス（Inverted Index）を使用したテキスト、数値、地理フィールドのインデキシング方法について説明します。

• 転置インデックスの構造（Term Dictionary、Posting Lists）
• 数値範囲クエリのための BKD ツリー
• セグメントファイルとそのフォーマット
• BM25 スコアリング

Vector インデキシング

近似最近傍探索（Approximate Nearest Neighbor Search）のためのベクトルフィールドのインデキシング方法について説明します。

• インデックスタイプ: Flat、HNSW、IVF
• パラメータチューニング（m、ef_construction、n_clusters、n_probe）
• 距離メトリクス（Cosine、Euclidean、DotProduct）
• 量子化（Quantization）: SQ8、PQ

Lexical インデキシング

Lexical インデキシングは、キーワードベースの検索を支える仕組みです。ドキュメントのテキストフィールドがインデキシングされると、Laurus は転置インデックス（Inverted Index） を構築します。これは、タームからそのタームを含むドキュメントへのマッピングを行うデータ構造です。

Lexical インデキシングの仕組み

sequenceDiagram
    participant Doc as Document
    participant Analyzer
    participant Writer as IndexWriter
    participant Seg as Segment

    Doc->>Analyzer: "The quick brown fox"
    Analyzer->>Analyzer: Tokenize + Filter
    Analyzer-->>Writer: ["quick", "brown", "fox"]
    Writer->>Writer: Buffer in memory
    Writer->>Seg: Flush to segment when the buffer fills, and on commit()

ステップごとの流れ

1. 解析（Analyze）: テキストが設定されたアナライザー（トークナイザー + フィルター）を通過し、正規化されたタームのストリームが生成される
2. バッファリング（Buffer）: タームはフィールドごとに整理され、インメモリの書き込みバッファに格納される
3. フラッシュとコミット（Flush and commit）: バッファが max_buffered_docs（デフォルト 10,000 件）か推定メモリ max_buffer_memory（デフォルト 64 MiB）に達すると、まだ見えない新しいセグメントにフラッシュされる。commit() は残りをフラッシュし、それらのセグメントをまとめて公開する

転置インデックス（Inverted Index）

転置インデックスは、基本的にタームからドキュメントリストへのマップです。

graph LR
    subgraph "Term Dictionary"
        T1["'brown'"]
        T2["'fox'"]
        T3["'quick'"]
        T4["'rust'"]
    end

    subgraph "Posting Lists"
        P1["doc_1, doc_3"]
        P2["doc_1"]
        P3["doc_1, doc_2"]
        P4["doc_2, doc_3"]
    end

    T1 --> P1
    T2 --> P2
    T3 --> P3
    T4 --> P4

Posting List の内容

Posting List の各エントリには以下の情報が含まれます。

On-Disk Posting レイアウト

Posting list は structure-of-arrays レイアウトで保存され、各フィールドが それぞれ連続したセクションに書かれます。ドキュメント ID とターム頻度は 固定長の 128 整数ブロック単位でビットパックされ（ドキュメント ID は Frame-of-Reference + ソート済みデルタ）、端数の末尾ブロックは varint に フォールバックします。これは Tantivy および Lucene 9 が採用する on-disk 形式と同じで、bitpacking クレートに よる SIMD デコードが効きます。

[term, total_frequency, doc_frequency, posting_count N, any_positions, any_weights]
[Skip levels              — v2 以降: num_levels + レベルごと (len + u32 doc_ids)]
[Section 1: doc_ids       — N/128 ビットパックブロック + varint 末尾]
[Section 2: frequencies   — N/128 ビットパックブロック + varint 末尾]
[Section 3: weights       — N 個の生 f32（any_weights == 1 のときのみ）]
[Section 4: positions     — ポスティングごとのフラグ + varint デルタ（存在する場合のみ）]

2 つのヘッダフラグが 2 つの省略可能セクションを制御します。any_positions は 従来から Section 4 を制御しており、any_weights は v3 で追加され、同じ形で Section 3 を制御します。Laurus が書き出すポスティングは常に既定値 1.0 の ウェイトを持つため、writer が生成するセグメントでは Section 3 が常に省かれ、 posting list は v2 と比べて 4N - 1 バイト小さくなります ── ポスティング あたり 4 バイトの削減から、リストあたり 1 バイトのフラグを差し引いた値です。 10 億ポスティングでは、書き込み・読み出し・キャッシュのいずれもしなくて 済むバイト数が約 4 GB になります。

この削減によって形式が lossy になることはありません。1.0 以外のウェイトが 1 つでもあればフラグが立って Section 3 が復活し、すべての値が厳密に往復します。

セグメント内のドキュメント ID は u32 に収まる必要があります。u32::MAX を 超える値のエンコードは、ビットパックされたセグメントを黙って破損させないよう、 明確なエラーで即座に失敗します。

デコーダは SoA ネイティブの高速パス（PostingList::decode_soa）を提供し、 中間的な Vec<Posting> の再構築を挟まずに doc_id と frequency の parallel な Vec<u32> スライスをディスクから直接生成します。クエリ イテレータはこのスライスを保持するため、next() は 40 バイトの Posting 構造体をストライドせず、密なスライス上で u32 カーソルを 1 つ進めるだけで 済みます。

Multi-Level Skip Table

N ≥ 8 ポスティングを持つ posting list はヘッダ直後に Lucene-90 互換のマルチレベルスキップテーブル（v2 フォーマットで導入され、 v3 でも変更なし）を持ちます。各レベルは doc_ids 上の固定ストライド窓の “末尾 doc id” を 保持し、レベル 0 は SKIP_INTERVAL = 8 ポスティングごとに 1 エントリ、 レベル 1 は 8²、トップレベルは 1 エントリに収束するまで重ねます。

PostingIterator::skip_to(target) はテーブルをトップダウンに走査し、 各レベルで partition_point により探索窓を SKIP_INTERVAL で 1 段ずつ 絞り込んでから、最下層の最大 8 ポスティング窓を線形スキャンします。 1 回あたりのコストは O(log_8 N + SKIP_INTERVAL) ── N = 1M で約 25 比較。従来の単一レベル block_cache が支払っていた線形 O(N / block_size) ウォークと比べて大幅に少なくなります。

スキップテーブルは Lucene 9 / Tantivy と同様に posting list の ファイル内に同居させ、別ファイル化はしません。古いセグメントもそのまま 読めます ── スキップテーブルを on-disk に持たない v1 形式は SoA デコーダが ロード時に doc_ids から再構築し、v2 形式は無条件のウェイトセクションを そのまま読みます。どのデコーダを使うかは、マジックとバージョン番号を持つ 唯一のセグメント単位ファイルである .dict のバージョンで決まるため、 posting のペイロード自体を推測的に読む必要はありません。

ディスクから読んだスキップテーブルは、デコードした doc_ids から writer が作るものと完全に一致しなければなりません。デコーダはその場で 両者を照合し、一致しない表は破損したセグメントとして拒否します。 skip_to はこの形に頼ってストライドを範囲内に保っており、誤った エントリは一致する文書を飛ばしてしまうためです。

Term Dictionary の 2 層構造

ディクショナリは ディスク と メモリ で別の表現を持ち、 それぞれの最適化目標を分離しています。

• ディスク層 — .dict ファイルは Lucene BlockTreeTermsWriter 風のブロックツリーレイアウト（マジック LTDD、スキーマ v3）。 100k ユニーク 5-10 バイトタームのコーパスで .dict は ~12.5 バイト/ターム と、旧 parallel-array 形式比 約 70% 削減
• メモリ層 — build / load 時に AHashMap<term, ordinal> 索引、 ordinal indexed の Vec<String>、単一コピーの Arc<[TermInfo]> を構築。get / iter / find_prefix / find_range はすべて この in-memory 構造のみを参照するので、per-query レイテンシは 旧 parallel-array 実装と同等（ FST traversal や block 内線形 スキャンのコストを払わない）

ディスク形式のスクラッチ (FST + BlockSection bytes) は [BlockTermDictionary::write_to_storage] でセグメントマージ時に 再エンコードせず再シリアライズするためにのみ保持しています。

[Header                ]  マジック "LTDD" + バージョン
[FstSection            ]  各ブロック末尾タームを key、ブロックの開始
                          バイトオフセットを value とする fst::Map<u64>
[BlockSection          ]  128 ターム単位のブロックを連結。各ブロックは
                          front-coded タームバイト列、bit-packed の
                          固定長 TermInfo ブロック、可変長の per-term
                          Block-Max-WAND メタデータ配列を含む
[Footer                ]  全タームカウント + ブロックカウント
[Checksum footer       ]  上記すべての CRC-32 + マジック "LCRC"

• 検索: FST を 1 回辿って (O(|term|)) target を含むブロックを特定 し、そのブロック内（≤ 128 件）を front-coded で線形スキャン
• イテレーション: FST を経由せず BlockSection を順次走査。各ブロック の front-coding バッファを再利用するため、per-step コストは front-coding decode（≈ 5–10 ns）のみ
• プレフィックススキャン: FST で先頭ブロックを特定し、prefix が一致 しなくなるまで順次ブロックを走査

flat per-term FST と比較して block-head FST は 1〜2 桁小さく、 front-coded タームバイト列と bit-packed TermInfo の組み合わせで production 規模ではディスクサイズが 50〜80 % 削減されます。

数値フィールドと日付フィールド

整数、浮動小数点数、日時フィールドは、BKD ツリー を使用してインデキシングされます。BKD ツリーは範囲クエリに最適化された空間分割データ構造です。

graph TB
    Root["BKD Root"]
    Root --> L["values < 50"]
    Root --> R["values >= 50"]
    L --> LL["values < 25"]
    L --> LR["25 <= values < 50"]
    R --> RL["50 <= values < 75"]
    R --> RR["values >= 75"]

BKD ツリーにより、price:[10 TO 100] や date:[2024-01-01 TO 2024-12-31] のような範囲クエリを効率的に評価できます。

地理フィールド（Geo Fields）

地理フィールドには 2 種類あり、いずれも同じ多次元 BKD-Tree プリミティブにバックアップされています：

Geo3d は高度が一級の次元になる用途（ドローン・衛星・屋内 3D 測位など、 2D の Geo フィールドでは情報が失われたり極で歪んだりするケース）で 適しています。座標系・WGS84 変換ヘルパー・DSL 構文については 3D 地理検索 (ECEF) を参照してください。

セグメント（Segments）

Lexical インデックスはセグメントに分割されて構成されます。各セグメントはイミュータブルで自己完結型のミニインデックスです。

graph TB
    LI["Lexical Index"]
    LI --> S1["Segment 0"]
    LI --> S2["Segment 1"]
    LI --> S3["Segment 2"]

    S1 --- F1[".dict (terms)"]
    S1 --- F2[".post (postings)"]
    S1 --- F3[".bkd (numerics)"]
    S1 --- F4[".docs (doc store)"]
    S1 --- F5[".dv (doc values)"]
    S1 --- F6[".meta (metadata)"]
    S1 --- F7[".norms (field-length norms)"]
    S1 --- F8[".ids (doc ids)"]

セグメントのライフサイクル

1. 作成（Create）: writer のバッファが max_buffered_docs（デフォルト 10,000 件）か max_buffer_memory（デフォルト 64 MiB）に達するたびに新しいセグメントがフラッシュされ、commit() が残りをもう 1 つフラッシュする。commit() はそれらを一度に公開するので、1 回のコミットで複数のセグメントが増えることがある。両方の閾値はインデックス設定で指定する（LexicalIndexConfig::builder().max_buffered_docs(..) / .max_buffer_memory(..)）
2. 検索（Search）: すべてのセグメントが並列に検索され、結果がマージされる
3. マージ（Merge）: 各 commit() 後に自動マージが走り、セグメント数が max_segments を超えると最小のセグメント群がマージされて数が有界に保たれる。手動 optimize() は全セグメントを 1 つに強制マージする
4. 削除（Delete）: ドキュメントが削除された場合、物理的に削除されるのではなく、削除ビットマップに ID が追加される（Deletions & Compaction を参照）

BM25 スコアリング

Laurus は Lexical 検索結果のスコアリングに BM25 アルゴリズムを使用します。BM25 は以下の要素を考慮します。

• ターム頻度（Term Frequency, TF）: ドキュメント内でタームが出現する頻度（多いほど良いが、収穫逓減あり）
• 逆文書頻度（Inverse Document Frequency, IDF）: 全ドキュメントにおけるタームの希少性（希少なほど重要）
• フィールド長の正規化（Field Length Normalization）: 短いフィールドは長いフィールドに対してブーストされる

計算式:

score(q, d) = IDF(q) * (TF(q, d) * (k1 + 1)) / (TF(q, d) + k1 * (1 - b + b * |d| / avgdl))

k1 = 1.2 と b = 0.75 がデフォルトのチューニングパラメータです。

SIMD 最適化

ベクトル距離計算では、利用可能な場合に SIMD（Single Instruction, Multiple Data）命令が活用され、ベクトル検索における類似度計算が大幅に高速化されます。

コード例

use std::sync::Arc;
use laurus::{Document, Engine, Schema};
use laurus::lexical::TextOption;
use laurus::lexical::core::field::IntegerOption;
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> laurus::Result<()> {
    let storage = Arc::new(MemoryStorage::new(Default::default()));
    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_text_field("body", TextOption::default())
        .add_integer_field("year", IntegerOption::default())
        .build();

    let engine = Engine::builder(storage, schema).build().await?;

    // Index documents
    engine.add_document("doc-1", Document::builder()
        .add_text("title", "Rust Programming")
        .add_text("body", "Rust is a systems programming language.")
        .add_integer("year", 2024)
        .build()
    ).await?;

    // Commit to flush segments to storage
    engine.commit().await?;

    Ok(())
}

次のステップ

• ベクトルインデックスの仕組みを学ぶ: Vector インデキシング
• Lexical インデックスに対してクエリを実行する: Lexical 検索

Vector インデキシング

Vector インデキシングは、類似性ベースの検索を支える仕組みです。ドキュメントのベクトルフィールドがインデキシングされると、Laurus はエンベディングベクトルを専用のインデックス構造に格納し、高速な近似最近傍探索（Approximate Nearest Neighbor, ANN）を可能にします。

Vector インデキシングの仕組み

sequenceDiagram
    participant Doc as Document
    participant Embedder
    participant Normalize as Normalizer
    participant Index as Vector Index

    Doc->>Embedder: "Rust is a systems language"
    Embedder-->>Normalize: [0.12, -0.45, 0.78, ...]
    Normalize->>Normalize: L2 normalize
    Normalize-->>Index: [0.14, -0.52, 0.90, ...]
    Index->>Index: Insert into index structure

ステップごとの流れ

1. エンベディング（Embed）: テキスト（または画像）が、設定されたエンベッダーによってベクトルに変換される
2. 正規化（Normalize）: ベクトルは Cosine メトリックの場合のみ L2 正規化される（大きさ不変なメトリック）。Euclidean / DotProduct / Manhattan のフィールドは距離を保つため元のベクトルのまま保存される
3. インデキシング（Index）: ベクトルが設定されたインデックス構造（Flat、HNSW、または IVF）に挿入される
4. コミット（Commit）: commit() の呼び出し時に、インデックスが永続ストレージにフラッシュされる

インデックスタイプ

Laurus は 3 種類のベクトルインデックスタイプをサポートしており、それぞれ異なるパフォーマンス特性を持ちます。

比較

Flat インデックス

最もシンプルなインデックスです。クエリベクトルを格納されたすべてのベクトルと比較します（総当たり）。

#![allow(unused)]
fn main() {
use laurus::vector::FlatOption;
use laurus::vector::core::distance::DistanceMetric;

let opt = FlatOption {
    dimension: 384,
    distance: DistanceMetric::Cosine,
    ..Default::default()
};
}

• 利点: 100% の再現率（厳密な結果）、シンプル、低メモリ
• 欠点: 大規模データセットでは低速（線形スキャン）
• 使用場面: ベクトル数が約 1 万未満の場合、または厳密な結果が必要な場合

HNSW インデックス

Hierarchical Navigable Small World グラフ。デフォルトで最も一般的に使用されるインデックスタイプです。

graph TB
    subgraph "Layer 2 (sparse)"
        A2["A"] --- C2["C"]
    end

    subgraph "Layer 1 (medium)"
        A1["A"] --- B1["B"]
        A1 --- C1["C"]
        B1 --- D1["D"]
        C1 --- D1
    end

    subgraph "Layer 0 (dense - all vectors)"
        A0["A"] --- B0["B"]
        A0 --- C0["C"]
        B0 --- D0["D"]
        B0 --- E0["E"]
        C0 --- D0
        C0 --- F0["F"]
        D0 --- E0
        E0 --- F0
    end

    A2 -.->|"entry point"| A1
    A1 -.-> A0
    C2 -.-> C1
    C1 -.-> C0
    B1 -.-> B0
    D1 -.-> D0

HNSW アルゴリズムは、上位の疎なレイヤーから下位の密なレイヤーへと検索し、各レベルで検索空間を絞り込みます。

#![allow(unused)]
fn main() {
use laurus::vector::HnswOption;
use laurus::vector::core::distance::DistanceMetric;

let opt = HnswOption {
    dimension: 384,
    distance: DistanceMetric::Cosine,
    m: 16,                  // max connections per node per layer
    ef_construction: 200,   // search width during index building
    ..Default::default()
};
}

HNSW パラメータ

チューニングのヒント:

• 再現率を向上させるには m を増やす（例: 32 または 64）。ただしメモリ消費が増加する
• インデックス品質を向上させるには ef_construction を増やす（例: 400）。ただし構築時間が増加する
• 検索時には、検索リクエストで設定する ef_search パラメータが探索幅を制御する

IVF インデックス

Inverted File Index。ベクトルをクラスタに分割し、関連するクラスタのみを検索します。

graph TB
    Q["Query Vector"]
    Q --> C1["Cluster 1\n(centroid)"]
    Q --> C2["Cluster 2\n(centroid)"]

    C1 --> V1["vec_3"]
    C1 --> V2["vec_7"]
    C1 --> V3["vec_12"]

    C2 --> V4["vec_1"]
    C2 --> V5["vec_9"]
    C2 --> V6["vec_15"]

    style C1 fill:#f9f,stroke:#333
    style C2 fill:#f9f,stroke:#333

#![allow(unused)]
fn main() {
use laurus::vector::IvfOption;
use laurus::vector::core::distance::DistanceMetric;

let opt = IvfOption {
    dimension: 384,
    distance: DistanceMetric::Cosine,
    n_clusters: 100,   // number of clusters
    n_probe: 10,       // clusters to search at query time
    ..Default::default()
};
}

IVF パラメータ

チューニングのヒント:

• n_clusters はベクトル数 n に対して sqrt(n) 程度に設定する
• 再現率と速度のバランスを取るため、n_probe を n_clusters の 5-20% に設定する
• IVF はトレーニングフェーズが必要なため、初回のインデキシングが遅くなる場合がある

距離メトリクス（Distance Metrics）

#![allow(unused)]
fn main() {
use laurus::vector::core::distance::DistanceMetric;

let metric = DistanceMetric::Cosine;      // Default for text
let metric = DistanceMetric::Euclidean;    // For spatial data
let metric = DistanceMetric::Manhattan;    // L1 distance
let metric = DistanceMetric::DotProduct;   // For pre-normalized vectors
let metric = DistanceMetric::Angular;      // Angular distance
}

注意: ベクトルがインデキシング前に自動的に L2 正規化されるのは Cosine メトリックの場合のみです。正規化は大きさ不変なので Cosine では安全（かつ int8 量子化の範囲も締まる）ですが、大きさに依存するメトリックでは距離が変わってしまうため、Euclidean / DotProduct / Manhattan のフィールドは正規化せずに保存されます。距離が小さいほど、より類似していることを示します。

マイグレーション注記: この挙動が修正される前に作成した非 Cosine フィールドは、ディスク上に L2 正規化済みのベクトルを持ちます（元の大きさは復元できません）。正しい距離を得るにはインデックスを再構築してください。

量子化（Quantization）

ベクトルはディスク上で 8 ビットスカラー量子化された整数 として保存 されます（Issue #481 Stage 1）。以前の 32 ビット浮動小数点形式と比較 して 約 4 倍小さく、recall 損失は実用上ほぼ無視できる範囲（f32 ground truth に対して Recall@10 ≥ 0.95 — recall テスト laurus/tests/vector_recall_test.rs 参照）です。

#![allow(unused)]
fn main() {
use laurus::vector::HnswOption;
use laurus::vector::core::quantization::QuantizationMethod;

// `quantizer` は `Scalar8Bit` がデフォルト。下記は
// `HnswOption { dimension: 384, ..Default::default() }` と等価。
let opt = HnswOption {
    dimension: 384,
    quantizer: QuantizationMethod::Scalar8Bit,
    ..Default::default()
};
}

破壊的変更（Issue #481 Stage 1）: quantizer フィールドはもはや Option<QuantizationMethod> ではなく必須となり、デフォルトは Scalar8Bit です。f32 のままディスクに保存する形式は廃止されまし た。Stage 1 より前に作成した既存 vector index は意図的に読み取り 不可能で、ソースデータからの再構築が必要です。

Scalar8Bit のしくみ

• 各 segment は flush 時に f32 ベクトル群から global な (offset, scale) ペア 1 組をトレーニング （offset = min, scale = (max - min) / 255）。
• 各 f32 要素は u8 = clamp(round((v - offset) / scale), 0, 255) でエンコード。
• 各ベクトル単位のメタデータ（sum_q: u32, norm_q: f32）を 事前計算して int8 ペイロードと併置するため、cosine 検索の hot loop は int8 SIMD multiply-accumulate 1 回 + scalar 補正 3 回に縮約され、 検索時の per-element dequantize は不要。
• segment ファイルは LVS1 magic + 16 byte header で始まり、reader はロード時にフォーマットを判定。header はバージョン（機能のはしご: v2 = HNSW グラフブロックの ordinal エンコード、v3 = セグメントごとの フィールド名辞書）を持ち、v3 以降は辞書そのものも header に載る — 各レコードはフィールド名をインラインで繰り返す代わりに 16 ビット ID で参照する。

Two-stage rerank（Issue #481 Stage 2）

Stage 1 ではベクトルを int8 のみで保持します。グラフ検索は完全に int8 距離に対して行われ、高速ですがわずかな量子化誤差が入ります。Stage 2 ではフィールド単位で 任意の f32 sidecar を追加し、上位候補を元の 完全精度ベクトルで再スコアできるようにします:

1. HNSW int8 グラフ検索が量子化コサイン距離で最大 ef_search 件の 候補を返す。
2. 上位 top_k * rerank_factor 件を LRS1 sidecar（*.hnsw.f32）から読み込んだ f32 ベクトルで再スコアする。
3. 新しいランキングを top_k に切り詰めて返す。

Issue #932 以降、同じ sidecar 機構は共有 RerankPipeline（#650）を 通じて Flat / IVF でも機能します（以下の説明は Stage 2 の元ホストである HNSW を例にしています）。Stage 2 はフィールド単位で HnswOption.rerank_storage で opt-in します:

#![allow(unused)]
fn main() {
use laurus::vector::HnswOption;
use laurus::vector::core::rerank::RerankStorageKind;

let opt = HnswOption {
    rerank_storage: Some(RerankStorageKind::F32),
    ..HnswOption::default()
};
}

クエリ側は VectorIndexQuery::rerank_factor（low-level）、 SearchRequestBuilder::vector_rerank_factor（engine）、 gRPC / JSON の VectorParams.rerank_factor のいずれかで rerank factor を渡します。

rerank_storage が無効なフィールドでは rerank_factor を指定しても silent に Stage 1 int8 ランキングへフォールバックします — Stage 1 セグメントから f32 情報を復元することはできません。

LRS1 rerank sidecar

sidecar は rerank_storage が有効なときに LVS1 セグメントの隣に 書かれる別ファイルです:

offset  size  field
------  ----  -------------------------------------------
     0     4  magic         ASCII "LRS1"
     4     2  version       u16 LE  (current = 1)
     6     2  storage_kind  u16 LE  (1 = F32; 0 reserved; 2.. future)
     8     8  reserved      zero-padded
    16     4  dim           u32 LE
    20     4  vector_count  u32 LE
    24     -  payload       vector_count * dim * bytes_per_element
   end     8  footer        magic "LRC1" u32 LE + CRC-32 u32 LE
                             （header + payload が対象）

ベクトルは LVS1 セグメントと同じ (doc_id, field_name) 順で書かれる ので、(sidecar position) → (LVS1 position) のマッピングは恒等関数に なります。HNSW reader は storage の loading mode が Eager のとき初期化 時に sidecar を RerankStoragePool にロードします。Lazy mode では memory savings の前提を尊重するため sidecar 読み込みをスキップします （Lazy mode で開いた Stage 2 セグメントは silent に Stage 1 へ degrade します）。

sidecar はスキーマの HNSW オプションの rerank_storage でフィールド ごとに有効化され、その設定はすべての書き込み経路で尊重されます。直接 の commit、アクティブな書き込みセグメント、セグメントの merge いずれも 生成したセグメントに対して sidecar を再出力します。マージ後セグメント の sidecar は ソースセグメントの原 f32 サイドカー から再構築されます （int8 復元値ではなく）。これによりマージはマージごとに量子化誤差を 1 段 ずつ蓄積させず、rerank ベクトルを無損失に保ちます。

新しい sidecar は末尾に header + payload を対象とする 8 バイトの CRC-32 footer を持ち、sidecar を読むすべての経路（searcher のロードと writer の再ロード）で検証されます。これにより、ディスク上の静かな破損 が rerank スコアを歪める代わりに拒否されます。header からコンテンツ長 が一意に決まるため、footer は payload の後ろに残っているバイト数で 検出されます — footer 導入前に書かれた sidecar は末尾バイトがゼロ なのでそのままロードでき、検証はスキップされます。

recall と速度の trade-off

rerank_factor は per-query rerank コスト（top_k * rerank_factor 回の exact distance 計算 — dim 128 で数 µs）と引き換えに Recall@10 の 向上を得る lever です。実際の効果はコーパスとグラフ検索 budget （ef_search）に依存します:

• 実際の clustered な embedding（text-embedding-3、BERT など）は 低い ef_search で Recall@10 ≥ 0.99 に到達し、rerank は微小な latency 増で順位を磨きます。
• 合成 random unit-norm（HNSW 復元の最悪ケース）では int8 グラフが 真の top-10 候補を十分に visit するために高い ef_search が必要で、 rerank は visit 済み候補を並び替えられても visit していないものは 取り戻せません。

recall acceptance は rerank kernel と HNSW フルパイプラインを独立に 落とせるよう、CI gate を 2 段に分けています:

• stage2_brute_force_rerank_recall_at_10_meets_kernel_gate は Recall@10 ≥ 0.99 を assert します。HNSW グラフを完全にバイパス し（brute-force int8 で corpus 全体を採点 → top_k * rerank_factor に絞る → f32 で再スコア）miss すれば rerank kernel の regression と切り分けられます。
• hnsw_quantized_recall_at_10_with_rerank_meets_stage2_recall_gate は Recall@10 ≥ 0.98 を assert します。HNSW build の non-determinism（f32 HNSW baseline でも同様に出るノイズ）を 含むため、合成 adversarial 分布での run-to-run 観測幅に合わせて しきい値を緩めています。実 embedding の clustered 分布や 強めの HNSW config（m=32, ef_construction=500）はこのパス でも ≥ 0.99 に到達します（下の diagnostic sweep を参照）。

companion の stage2_recall_sweep_diagnostic（LAURUS_STAGE2_SWEEP=1 で opt-in）は (ef_search, rerank_factor) を 3 種の corpus / query 分布 × 2 種の HNSW config で sweep するので、production deployment は実際の embedding 分布で budget を calibrate できます。

実データ検証（Issue #498）

3 つめの opt-in CI gate として、 Stage 2 を実 ANN benchmark dataset （TEXMEX の SIFT1M）で検証します。 synthetic data の gate だけが signal にならないようにするためのものです。

• hnsw_quantized_recall_at_10_with_rerank_on_sift_meets_stage2_real_data_recall_gate は SIFT1M の 50 000 ベクトルサブサンプル上で (m=16, ef_construction=200, ef_search=200, rerank_factor=5) の Recall@10 ≥ 0.99 を assert します。
• companion bench bench_hnsw_graph_search_rerank_real_data （laurus/benches/vector_search_bench.rs）は同じ fixture で end-to-end Stage 2 latency を測定します。 同梱の laurus/examples/sift_rerank_probe.rs は (ef_search × rerank_factor × HNSW config) を sweep して (Recall, latency) を per-cell で報告するので、運用側は自分の データに合った operating point を選べます。

両者は LAURUS_REAL_BENCHMARK=1 と .cache/sift/sift/ 配下の SIFT1M .fvecs ファイルの存在で gate されます。 デフォルトの CI runs は変化しません。 ローカルで有効化するには:

./scripts/fetch-sift.sh --large   # ~478MB
LAURUS_REAL_BENCHMARK=1 cargo test --release \
    --test vector_recall_test \
    hnsw_quantized_recall_at_10_with_rerank_on_sift_meets_stage2_real_data_recall_gate \
    -- --nocapture
LAURUS_REAL_BENCHMARK=1 cargo bench --bench vector_search_bench \
    -- "HNSW Graph Search Rerank Real"

Issue #481 の原文は “≥ 3× speedup vs the pre-Stage-1 f32 baseline” を要求していましたが、 SIFT1M-50k での cross-branch Criterion 計測 （30 サンプル中央値、同じ (m, ef_construction, ef_search)）では pre-Stage-1 f32 HNSW path が 625 µs/query、 Stage 2 int8 + rerank path が 323 µs/query となり、 speedup は 1.94× でした。 この 実測結果を受けて Issue #498 では real-data gate を ≥ 1.5× に 下げています（recall 側は元の 0.99 を維持）。 3× との gap は、 rerank が int8 graph traversal で visit 済みの候補を re-rank する だけで、 ef_search を下げると candidate set 自体が狭くなり rerank で回収できないことに起因します。 follow-up としては graph search budget を ef_search から独立に広げる（Lucene 99 pattern）案が あります。

Product Quantization + rerank（Issue #481 Stage 3）

Stage 3 は HNSW index 向けに opt-in の Product Quantization path を 追加します。 各 segment は per-field の codebook（M 個の sub-vector × K = 256 centroid）を k-means++ + Lloyd 反復で学習し、 各ベクトル を M バイトで保存します（sub-vector あたり 1 centroid index）。 検索ホットループでは int8 SIMD kernel を asymmetric distance computation（ADC）に置き換えます: query 1 回ごとに query sub-vector と codebook entry の squared distance を M × K look-up table に展開し、候補ごとに Σ_m lut[m][codes[m]] で スコアリング（1 候補あたり M lookups + M − 1 add）。

PQ は per-field HnswOption.quantizer で有効化:

#![allow(unused)]
fn main() {
use laurus::vector::HnswOption;
use laurus::vector::core::quantization::QuantizationMethod;
use laurus::vector::core::rerank::RerankStorageKind;

let opt = HnswOption {
    dimension: 128,
    quantizer: QuantizationMethod::ProductQuantization { subvector_count: 32 },
    // SIFT1M の PQ-only Recall@10 は 0.78-0.92 で頭打ちのため、
    // production では LRS1 rerank sidecar との組み合わせを推奨
    // （Stage 2 と同じ仕組み、 candidate 生成側のみ int8 から PQ
    // に置き換わる）。
    rerank_storage: Some(RerankStorageKind::F32),
    ..Default::default()
};
}

最小学習サイズ: PQ はサブ量子化器ごとに K = 256 個の k-means セントロイドを学習するため、256 ベクトル未満のセグメントでは意味のある codebook を学習できません。そのようなセグメントは Scalar8Bit で 書き出されます（LVS1 ヘッダは自己記述型のため、reader は保存された 種別で透過的にディスパッチします）。セグメントが成長するか、より大きな セグメントへマージされれば、次の書き込みで設定どおり PQ が学習されます。 subvector_count が dimension を割り切る検証はセグメントサイズに かかわらず常に適用されます。なお、 共有 codebook を設定した場合はこの フォールバックも最小サイズも適用されません — セグメントごとの学習が 発生しないため、小さな per-commit セグメントもそのまま PQ を維持します。

subvector_count は dimension を割り切る値を選択。 dim = 128 での候補: M ∈ {8, 16, 32}（sub_dim 16 / 8 / 4）。 M を大きく すると compression は下がるが recall は上がります。 Issue #481 Stage 3 は 8 bit（K = 256）のみを ship、 on-disk format は 将来の 4 bit（K = 16）variant 用に枠を予約しています。

共有 PQ codebook（Issue #631）

デフォルトでは segment の書き込みごとに codebook をゼロから学習 します — segment-per-commit レイアウト（#634/#889）では、この数秒 オーダーの k-means コストが commit と merge のたびに繰り返され ます。 FAISS / Lucene99 の前例に倣い、 codebook を代表サンプルで 一度だけ学習して以後のすべての segment 書き込みで再利用でき、 encode はテーブル参照だけになります（2,048〜8,192 ベクトルで インライン学習比 約 91-92% 高速の実測値）。

有効化はフィールドに codebook ファイル名を設定して学習するだけです:

[fields.embedding.Hnsw]
dimension = 128
pq_codebook_path = "embedding.pqcb"

[fields.embedding.Hnsw.quantizer.ProductQuantization]
subvector_count = 32

laurus train pq-codebook --field embedding --input vectors.jsonl --update-schema

（--input の代わりに --from-index でインデックスにコミット済みの ベクトルを直接サンプリングすることも、laurus create index --train-pq-codebook <jsonl> で学習をインデックス作成に畳み込んで train-before-first-commit の順序ハザードを完全に解消することもできます — いずれも Issue #920）、または プログラムから Engine::train_pq_codebook （engine.train_pq_codebook("embedding", &vectors, None)。from-index フローには engine.sample_committed_vectors("embedding", Some(n)) を 組み合わせます）を使います。学習は同期・CPU-bound で、代表的な ベクトル数千件で十分です（全コーパスは不要）。

セマンティクス:

• segment format は不変。 共有 codebook も従来どおり各 segment header にインライン埋め込みされるため、共有 codebook の segment と インライン学習の segment はマイグレーション無しで共存でき、生成 される code は同一サンプルでインライン学習した場合と byte-identical です。
• codebook ファイルは index open 時に一度だけ解決されます。 エンジンを開いたまま再学習しても mid-session で hot-swap されません （意図的な仕様 — 1 セッションの commit 間で codebook が変わっては ならないため）。新しいファイルは再オープンで反映されます。
• 失敗ポリシー — 無言のフォールバック無し。 pq_codebook_path が 設定済みで未学習の場合、 open は lenient（学習前にスキーマを作成 できる）ですが、 encode が必要な commit は実行すべき学習コマンドを 示すエラーで失敗します。ファイルは存在するが破損・ジオメトリ不一致の 場合は open 時にエラーです。 laurus が per-segment 学習へ無言で フォールバックすることはありません — 数秒オーダーの学習コストへの 見えない回帰は本機能の意義を損なうためです。
• Cosine メトリックのフィールドでは、 writer がインデックス時に行う L2 正規化と同じ正規化を学習サンプルにも適用し、 codebook の基底を 常に一致させます（#794 の罠への対処）。
• FastScan フィールドにも対応（Issue #920、pq-fastscan feature）: ProductQuantizationFastScan フィールドは同じコマンド・同じファイル フォーマットで k=16 の共有 codebook を学習・エンコードします — .pqcb header は k をそのまま保存するため 2 つの variant は 保存された値で区別され、k 不一致の codebook（例: k=256 のファイルを FastScan フィールドに設定）は両方の値を明示するエラーで commit が 失敗します。

on-disk format

PQ segment は Scalar8Bit と同じ LVS1 header を使用（quant_kind = 2）し、 codebook は per-segment metadata block 内に格納:

[ Fixed header           16 bytes ]
[ PQ params               8 bytes ]    m / k / sub_dim / padding (u16 × 4)
[ Codebook                m × k × sub_dim × 4 bytes ]
[ Per-vector codes        num_vectors × m bytes ]

dim = 128, M = 32, K = 256 の場合 codebook = 32 × 256 × 4 × 4 = 131 072 bytes（128 KB）+ ベクトル 1 件あたり 32 byte。

Recall と speed gate（Issue #481 Stage 3）

• Kernel レベルテスト — synthetic 5 000 ベクトル / dim 128 / 100 query、 (m=16, ef_construction=200, ef_search=200, rerank_factor=10, M=32): hnsw_pq_rerank_recall_at_10_meets_stage3_recall_gate が Recall@10 ≥ 0.95 を assert。 実測 0.9660。
• 実データテスト — SIFT1M-50k subsample（opt-in: LAURUS_REAL_BENCHMARK=1、同設定）: hnsw_pq_rerank_recall_at_10_on_sift_meets_stage3_real_data_recall_gate が Recall@10 ≥ 0.95 を assert。 実測 0.9965。
• 実データ speed bench — bench_hnsw_graph_search_pq_rerank_real_data（opt-in、Criterion）。 同 SIFT1M-50k 設定での cross-branch 計測: pre-Stage-1 f32 HNSW = 625.21 µs/query（PR #500 計測値）、 Stage 3 PQ + rerank = 299.54 µs/query = 2.09× speedup。

Issue #481 の原文は Recall ≥ 0.95 で ≥ 5× speedup を要求していました が、 本 PR の実測で SIFT1M ではその target が到達不可能と判明。 Stage 2（#500）と Stage 3 は両方とも 1.9-2.1× の band で着地しており、 candidate set を recall が回収可能な幅まで広げると rerank がホット パスを支配することが原因です。 これを受けて gate は ≥ 1.5× に 下げられています。 follow-up としては Lucene 99 pattern（graph search の独立 budget）や 4 bit PQ variant でこの gap を埋める方向が 考えられます。

PQ → SQ → f32 の3段 rerank（Issue #673）

Stage 3 の rerank は PQ ADC の候補集合を top_k * rerank_factor まで 広げ、その先頭部分だけを exact な f32 サイドカーに対して rescore します — グラフ探索がその予算を超えて見つけた候補は捨てられます。 以前は PQ フィールドで ef_search をこの予算より広く設定しても、 予算を超えた分には何の効果もありませんでした。#673 以降は、その ef_search サイズの候補集合全体を、狭い exact-stage 予算で 切り出す前に安価な int8 kernel で再ランキングする int8（SQ）段 が追加で有効化されます — グラフがすでに計算済みのサープラス分が、 到着時点の PQ ADC 順序よりもずっと良い代理指標（int8）で競争する 機会を得られるようになり、単純に捨てられることがなくなります。

この int8 ビューは exact 段が読む 同じ LRS1 f32 サイドカーから 導出されます（初回利用時に一度だけ遅延学習し、セグメントの生存期間 中キャッシュされます）— 新たなディスク上サイドカーも、新しい フィールド設定も、新しいクエリパラメータも不要です。3段チェーンは 以下すべてを満たすときにクエリごと自動的に有効化されます:

• フィールドが PQ 量子化されている（ProductQuantization または ProductQuantizationFastScan）
• rerank サイドカー（rerank_storage: Some(F32)）がロード済み
• クエリに rerank_factor が指定されている
• effective_ef_search > top_k * rerank_factor — つまりグラフ探索が 実際に exact 段単体が消費する量より多くの候補を計算している場合。 そうでない場合（ef_search をデフォルトのままにしている一般的な ケース）、SQ 段は何も絞り込まないため skip され、クエリはこれまでと 同一の2段（PQ → f32）経路をたどります。

score_basis の契約（Issue #927）はどちらの場合でも影響を受けません — パイプラインは常に exact な f32 段で終わるため、SQ 段が事前に 走ったかどうかに関わらず、マルチセグメント fan-out はそのスコアを 引き続き exact でセグメント間比較可能な basis として扱います。

MultiVector ストレージ

上記の量子化方式は ANN インデックスタイプ（Flat、HNSW、IVF）に適用され ます。MultiVector フィールド は ANN 索引を持たないため quantizer は適用されません。代わりに独自の storage オプション（Issue #1346）で、各トークンベクトルのディスク上 での要素形式を選びます。

#![allow(unused)]
fn main() {
use laurus::{MultiVectorOption, MultiVectorStorage};

let opt = MultiVectorOption::new(128).storage(MultiVectorStorage::Int8);
}

quantizer の per-segment グローバルスケールとは異なり、Int8 のスケー ルはベクトルごとです: scale = max(abs(vector)) / 127 を各トークン ベクトルごとに個別に計算し、corpus や segment にまたがる学習済み状態は 持ちません。これにより segment のマージ時に行を再量子化せずバイト単位 でコピーできます。

既存フィールドの storage を変更するのは Reindex 扱いの変更です。 Engine::update_field を reindex: true で呼び出すと、フィールドの 既存セグメントを新しいディスク上の形式で再構築します。storage キーを 持たないスキーマ（このオプションが存在する前に書かれたもの）はデフォルト の F32 として扱われ、マイグレーションは不要です。

セグメントファイル

3つのインデックスタイプはすべてデフォルトで segment-per-commit レイアウトを 使用します（下記参照）。単一ファイルの monolithic レイアウトは、インデックスを 直接利用する場合に {Flat,Hnsw,Ivf}IndexConfig { segmented: false, .. } で 引き続き選択できます。

segment-per-commit レイアウト（3タイプ共通のデフォルト）

#634（HNSW）および #889（Flat・IVF）以降、各コミットは 新規追加ベクトルのみを不変の segment_NNNNNN.{hnsw,flat,ivf} ファイルとして seal し、原子的・チェックサム付きの segments.json manifest に登録します — コミットあたりのコストは O(インデックス) から O(新規ドキュメント) に下がり、 既存セグメントの全面的な作り直しも発生しません。

• 検索は sealed セグメント群を（新しい世代から順に）fan-out し、 同一ドキュメントの複製を newest-wins マスキングで重複排除します。 再インデックスされたドキュメントは常に最新の埋め込みで解決されます。 マージ待ちの stale 複製が深く積もっている場合も、セグメントごとの over-fetch 予算を幾何級数的に拡張し、マスキング後も十分な生存 hit が 残るまで再取得する適応的 over-fetch により、結果品質は安定します。
• マージ: 世代連続・サイズ類似の tiered マージポリシーがインジェストの 進行に応じてセグメント列を集約し（各ベクトルの生涯書き直し回数は O(log N)）、optimize() は全セグメントを 1 つに force-merge します。 IVF のマージはセグメントごとの cluster ID を引き継ごうとしません （セグメントをまたいだ意味を持たないため）— 重複排除済みの生存ベクトルを 平坦化し、union サイズに応じて適応的に再計算した cluster 数で centroid を ゼロから再学習します。Flat には f32 rerank サイドカーによるフォールバックが ないため、マージのたびに dequantize → scalar quantization パラメータの 再学習 → requantize が発生し、HNSW/IVF のほぼロスレスな再量子化経路とは 異なり、マージを重ねるごとにわずかな量子化ドリフトが蓄積します。
• セグメントごとの学習: HNSW のグラフと IVF の centroid はいずれも セグメントごとに独立して構築されます（IVF はスキーマの n_clusters を 上限としてセグメント自身のサイズに適応した cluster 数を学習します）。 検索はセグメントごとに fan-out して top-k をマージするため、 どちらのインデックスタイプもセグメント間の合意は不要です。
• 削除は論理削除です。インデックスレベルの bitmap（{name}.delmap）を すべてのセグメントリーダーが参照し、マージ時に物理回収されます。
• 移行はゼロコピーです。既存の monolithic セグメントファイルは初回 オープン時にそのまま最初のセグメントとして登録されます — manifest への 1書き込みのみで、データ移動はありません。
• 耐久性: セグメントファイルと manifest は temp ファイル + fsync + 原子的 rename で書かれ、manifest はカバー対象の状態がすべて durable に なった後にのみ公開される WAL checkpoint を保持します — 永続化を参照。

コミット跨ぎの writer 保持（monolithic レイアウトのみ）

writer の保持は monolithic レイアウト（segmented: false）にのみ 適用されます。segmented な writer は常に空のバッファから始まるため、 保持すべき状態がそもそも存在しません。monolithic レイアウトの HNSW では、 ストアは writer をコミットを跨いでキャッシュし続けます（Issue #864）。 コミット直後の writer のメモリ内状態は、たった今書き出したファイルと等価で あるため、コミット後最初の upsert はストレージから .hnsw 全体をリロード （+ 全 dequantize）する代わりに、その場で writer を拡張します — コミットの多いインジェストでは、このリロードがサイクルあたり O(インデックス サイズ) のコストでした。ただし、writer の裏でインデックスが書き換えられる 場合 — コミット中の auto-compaction 発火、または明示的な optimize() — はキャッシュを破棄します。どちらも fresh writer 経由でファイルを再構築して deletion bitmap をクリアするため、stale な保持 writer は回収済みベクトルを 書き戻してしまうからです。また、コミットが途中で失敗した場合も writer と ディスクの一致が不明になるため破棄します。副次効果として、保留変更のない 保持 writer はインデックス書き出し自体をスキップするため、変更なしの commit() は .hnsw への書き込みコストがゼロになります。monolithic の Flat と IVF は従来のコミット時破棄の挙動を維持しており、同じ不変条件の 監査はまだ済んでいません — 現在この経路に到達するには segmented デフォルトを 明示的にオプトアウトする必要があります。

コード例

use std::sync::Arc;
use laurus::{Document, Engine, Schema};
use laurus::lexical::TextOption;
use laurus::vector::HnswOption;
use laurus::vector::core::distance::DistanceMetric;
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> laurus::Result<()> {
    let storage = Arc::new(MemoryStorage::new(Default::default()));
    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_hnsw_field("embedding", HnswOption {
            dimension: 384,
            distance: DistanceMetric::Cosine,
            m: 16,
            ef_construction: 200,
            ..Default::default()
        })
        .build();

    // With an embedder, text in vector fields is automatically embedded
    let engine = Engine::builder(storage, schema)
        .embedder(my_embedder)
        .build()
        .await?;

    // Add text to the vector field — it will be embedded automatically
    engine.add_document("doc-1", Document::builder()
        .add_text("title", "Rust Programming")
        .add_text("embedding", "Rust is a systems programming language.")
        .build()
    ).await?;

    engine.commit().await?;

    Ok(())
}

次のステップ

• ベクトルインデックスを検索する: Vector 検索
• Lexical 検索と組み合わせる: ハイブリッド検索

検索（Search）

このセクションでは、インデキシングされたデータに対するクエリの実行方法を説明します。Laurus は 3 つの検索モードをサポートしており、それぞれ独立して使用することも、組み合わせて使用することもできます。

トピック

Lexical 検索

転置インデックスを使用したキーワードベースの検索について説明します。

• すべてのクエリタイプ: Term、Phrase、Boolean、Fuzzy、Wildcard、Range、Geo、Span
• BM25 スコアリングとフィールドブースト
• テキストベースのクエリのための Query DSL の使用方法

Vector 検索

ベクトルエンベディングを使用した意味的類似性検索について説明します。

• VectorSearchRequestBuilder API
• マルチフィールド Vector 検索とスコアモード
• フィルター付き Vector 検索

ハイブリッド検索

Lexical 検索と Vector 検索を組み合わせた、両方の長所を活かす検索について説明します。

• SearchRequestBuilder API
• フュージョンアルゴリズム（RRF、WeightedSum）
• フィルター付きハイブリッド検索
• offset/limit によるページネーション

スペル修正については、ライブラリセクションの Spelling Correction を参照してください。

Lexical 検索

Lexical 検索は、転置インデックスに対してキーワードをマッチングすることでドキュメントを検索します。Laurus は、完全一致、フレーズ一致、あいまい一致など、豊富なクエリタイプを提供します。

基本的な使い方

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::lexical::TermQuery;
use laurus::lexical::search::searcher::LexicalSearchQuery;

let request = SearchRequestBuilder::new()
    .lexical_query(
        LexicalSearchQuery::Obj(
            Box::new(TermQuery::new("body", "rust"))
        )
    )
    .limit(10)
    .build();

let results = engine.search(request).await?;
}

クエリタイプ

TermQuery

特定のフィールドに完全一致するタームを含むドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::TermQuery;

// Find documents where "body" contains the term "rust"
let query = TermQuery::new("body", "rust");
}

注意: タームは解析後にマッチングされます。フィールドが StandardAnalyzer を使用している場合、インデキシングされたテキストとクエリタームの両方が小文字化されるため、TermQuery::new("body", "rust") は元テキスト内の “Rust” にもマッチします。

PhraseQuery

正確なタームの並びを含むドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::phrase::PhraseQuery;

// Find documents containing the exact phrase "machine learning"
let query = PhraseQuery::new("body", vec!["machine".to_string(), "learning".to_string()]);

// Or use the convenience method from a phrase string:
let query = PhraseQuery::from_phrase("body", "machine learning");
}

フレーズクエリは、ターム位置情報が格納されている必要があります（TextOption のデフォルト設定）。多値テキストフィールド（multi_valued = true）では、各要素がフィールドの position_increment_gap（デフォルト 100）で区切られた 1 本の位置列を共有するため、slop がその gap に達しない限りフレーズが 2 つの要素をまたぐことはありません —— 詳細は スキーマとフィールド を参照してください。

BooleanQuery

複数のクエリをブーリアン論理で結合します。

#![allow(unused)]
fn main() {
use laurus::lexical::query::boolean::{BooleanQuery, BooleanQueryBuilder, Occur};

let query = BooleanQueryBuilder::new()
    .must(Box::new(TermQuery::new("body", "rust")))       // AND
    .must(Box::new(TermQuery::new("body", "programming"))) // AND
    .must_not(Box::new(TermQuery::new("body", "python")))  // NOT
    .build();
}

FuzzyQuery

指定された編集距離（レーベンシュタイン距離）内のタームをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::fuzzy::FuzzyQuery;

// Find documents matching "programing" within edit distance 2
// This will match "programming", "programing", etc.
let query = FuzzyQuery::new("body", "programing");  // default max_edits = 2
}

WildcardQuery

ワイルドカードパターンを使用してタームをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::wildcard::WildcardQuery;

// '?' matches exactly one character, '*' matches zero or more
let query = WildcardQuery::new("filename", "*.pdf")?;
let query = WildcardQuery::new("body", "pro*")?;
let query = WildcardQuery::new("body", "col?r")?;  // matches "color" and "colour"
}

PrefixQuery

特定のプレフィックスで始まるタームを含むドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::prefix::PrefixQuery;

// Find documents where "body" contains terms starting with "pro"
// This matches "programming", "program", "production", etc.
let query = PrefixQuery::new("body", "pro");
}

RegexpQuery

正規表現パターンにマッチするタームを含むドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::regexp::RegexpQuery;

// Find documents where "body" contains terms matching the regex
let query = RegexpQuery::new("body", "^pro.*ing$")?;

// Match version-like patterns
let query = RegexpQuery::new("version", r"^v\d+\.\d+")?;
}

注意: RegexpQuery::new() は Result を返します。正規表現パターンは構築時にバリデーションされ、無効なパターンの場合はエラーが返されます。

NumericRangeQuery

数値フィールドの値が指定された範囲内にあるドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::NumericRangeQuery;
use laurus::lexical::core::field::NumericType;

// Find documents where "price" is between 10.0 and 100.0 (inclusive)
let query = NumericRangeQuery::new(
    "price",
    NumericType::Float,
    Some(10.0),   // min
    Some(100.0),  // max
    true,         // include min
    true,         // include max
);

// Open-ended range: price >= 50
let query = NumericRangeQuery::new(
    "price",
    NumericType::Float,
    Some(50.0),
    None,     // no upper bound
    true,
    false,
);
}

数値範囲クエリは**定数スコア（constant scoring）**です。マッチしたすべての ドキュメントは同じスコア（クエリの boost、デフォルト 1.0）を受け取ります。 これは Lucene の PointRangeQuery のセマンティクスに従うものです。マッチングには セグメントに BKD tree があればそれを使用し、対象フィールドの BKD tree を持たない セグメント（例: そのフィールドを持つドキュメントが 1 件もないセグメントや、 indexed = false, stored = true と設定されたフィールド）では、そのセグメントに 実際に存在する保存済みドキュメントのみを走査するフォールバックを使用します。

DateTimeRangeQuery

DateTime フィールドの値が指定された範囲内にあるドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use chrono::{TimeZone, Utc};
use laurus::lexical::DateTimeRangeQuery;

// Find documents where "created_at" is within 2024 (both bounds inclusive)
let query = DateTimeRangeQuery::between(
    "created_at",
    Utc.with_ymd_and_hms(2024, 1, 1, 0, 0, 0).unwrap(),
    Utc.with_ymd_and_hms(2024, 12, 31, 23, 59, 59).unwrap(),
);

// Open-ended range: created_at > 2024-06-15T12:00:00Z (exclusive)
let query = DateTimeRangeQuery::after(
    "created_at",
    Utc.with_ymd_and_hms(2024, 6, 15, 12, 0, 0).unwrap(),
);

// From textual bounds, using the same literal grammar as the query DSL
let query = DateTimeRangeQuery::from_literals(
    "created_at",
    Some("2024-01-01"),            // min (date only = midnight UTC)
    Some("2024-12-31T23:59:59Z"),  // max
    true,                          // include min
    true,                          // include max
)?;
}

new(field, lower, upper, lower_inclusive, upper_inclusive) は境界を Option<DateTime<Utc>> で受け取ります。片側だけのヘルパーとして on_or_after・before・on_or_before もあり、.with_boost() で定数スコアを 設定します。クエリはフィールドの 1 次元 BKD ポイント（マイクロ秒の小数部を持つ秒。 秒未満の境界も正確に比較されます）に対して評価され、定数スコアと保存済み ドキュメントへのフォールバックは NumericRangeQuery と同じです。from_literals は RFC 3339、オフセットなしの YYYY-MM-DDTHH:MM:SS[.fff]（UTC）、YYYY-MM-DD （その日の 0 時 UTC）を受け付け、DSL の created_at:[2024-01-01 TO 2024-12-31] が 構築するクエリと同一です（Query DSL 参照）。 DateTime フィールドに対してエポック秒を境界とする NumericRangeQuery も 従来どおり動作します。

GeoDistanceQuery / GeoBoundingBoxQuery

2D 地理座標（WGS84 緯度・経度）に基づいてドキュメントをマッチングします。

#![allow(unused)]
fn main() {
use laurus::lexical::query::geo::{GeoBoundingBoxQuery, GeoDistanceQuery};

// Find documents within 10 km (= 10 000 m) of Tokyo Station (35.6812, 139.7671)
let query = GeoDistanceQuery::within_radius("location", 35.6812, 139.7671, 10_000.0)?; // distance in metres

// Find documents within a bounding box (min_lat, min_lon, max_lat, max_lon)
let query = GeoBoundingBoxQuery::within_bounding_box(
    "location",
    35.0, 139.0,  // min (lat, lon)
    36.0, 140.0,  // max (lat, lon)
)?;
}

どちらのクエリも距離ベースでスコアリングします（近いドキュメントほど高スコア。 円の中心、またはボックスの中心からの線形減衰）。マッチングにはセグメントに BKD tree があればそれを使用し、座標は tree 自体から直接読み取ります — そのためインデックスのみのフィールド（indexed = true, stored = false）でも 保存済みドキュメントなしで動作します。対象フィールドの BKD tree を持たない セグメント（例: そのフィールドを持つドキュメントが 1 件もないセグメントや、 indexed = false, stored = true と設定されたフィールド）では、そのセグメントに 実際に存在する保存済みドキュメントのみを走査するフォールバックを使用します。

Geo3dDistanceQuery / Geo3dBoundingBoxQuery / Geo3dNearestQuery

3 種類のクエリが、ECEF 直交座標（メートル）にバックアップされた 3D の Geo3d フィールドを対象とします。高度が意味を持つ用途や、2D の Geo フィールドでは極特異点が問題になるケースで使ってください。座標系・WGS84 変換ヘルパー・実例については 3D 地理検索 を参照してください。

#![allow(unused)]
fn main() {
use laurus::GeoEcefPoint;
use laurus::lexical::query::geo3d::{
    Geo3dDistanceQuery, Geo3dBoundingBoxQuery, Geo3dNearestQuery,
};

let centre = GeoEcefPoint::new(-3_955_182.0, 3_350_553.0, 3_700_276.0);

// 球: `centre` から 5 km 以内のドキュメント
let q = Geo3dDistanceQuery::new("position", centre, 5_000.0);

// 軸並行 3D バウンディングボックス（コンストラクタが軸ごとに min ≤ max を検証）
let min = GeoEcefPoint::new(-4_000_000.0, 3_300_000.0, 3_650_000.0);
let max = GeoEcefPoint::new(-3_900_000.0, 3_400_000.0, 3_750_000.0);
let q = Geo3dBoundingBoxQuery::new("position", min, max)?;

// k-NN: 最も近い 10 件、半径スケジュールをカスタマイズ
let q = Geo3dNearestQuery::new("position", centre, 10)
    .with_initial_radius(500.0)
    .with_max_radius(1_000_000.0);
}

geo3d クエリはフィールドがインデックスされていること（indexed = true、 デフォルト）を必要とします。これらは完全にフィールドの BKD tree 上で動作し、 BKD tree を持たないセグメントからはヒットを返しません — 3D クエリには 保存済みドキュメントへのフォールバックはありません。

SpanQuery

ドキュメント内のタームの近接度に基づいてマッチングします。SpanTermQuery と SpanNearQuery を使用して近接クエリを構築します。

#![allow(unused)]
fn main() {
use laurus::lexical::query::span::{SpanQuery, SpanTermQuery, SpanNearQuery};

// Find documents where "quick" appears near "fox" (within 3 positions)
let query = SpanNearQuery::new(
    "body",
    vec![
        Box::new(SpanTermQuery::new("body", "quick")) as Box<dyn SpanQuery>,
        Box::new(SpanTermQuery::new("body", "fox")) as Box<dyn SpanQuery>,
    ],
    3,    // slop (max distance between terms)
    true, // in_order (terms must appear in order)
);
}

スコアリング

Lexical 検索結果は BM25 を使用してスコアリングされます。スコアは、ドキュメントがクエリに対してどの程度関連性があるかを反映します。

• ドキュメント内のターム頻度が高いほどスコアが上昇する
• インデックス全体でタームが希少なほどスコアが上昇する
• 短いドキュメントは長いドキュメントに対してブーストされる

フィールドブースト

特定のフィールドをブーストして関連性に影響を与えることができます。

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::lexical::search::searcher::LexicalSearchQuery;

let request = SearchRequestBuilder::new()
    .lexical_query(LexicalSearchQuery::Obj(Box::new(query)))
    .add_field_boost("title", 2.0)  // title matches count double
    .add_field_boost("body", 1.0)
    .build();
}

Lexical 検索オプション（SearchRequestBuilder 経由）

Lexical 検索の動作パラメータは SearchRequestBuilder のメソッドで設定します。これらは SearchRequest の lexical_options フィールドに格納されます。

フィールドソート検索（sort_by: Field { .. }）は常に全候補ドキュメントを走査します。 スコアソートで利用可能な block-max ベースの早期終了とは異なり、フィールドソートには早期終了が ありません。これにより返るヒットは早期終了による近似ではなく真の top-K であることが保証され、 total_hits も走査打ち切りによる件数ではなく真のマッチ数を反映します。

timeout_ms を設定すると、時間予算は検索の実行中に協調的に適用されます。スキャンループ （マルチセグメント fanout の各セグメントを含む）が定期的に deadline をチェックし、予算を使い切った時点で 即座に中断してタイムアウトエラーを返します（従来のようにクエリを完走してから判定するのではありません）。 チェックはバッチ化されている（数千ドキュメント走査ごと）ため、timeout_ms 未設定時や予算内に収まる 通常ケースでは計測可能なオーバーヘッドはありません。

ビルダーメソッド

SearchRequestBuilder を使用してクエリとオプションを設定します。

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::lexical::TermQuery;
use laurus::lexical::search::searcher::{LexicalSearchQuery, SortField, SortOrder};

let request = SearchRequestBuilder::new()
    .lexical_query(LexicalSearchQuery::Obj(Box::new(TermQuery::new("body", "rust"))))
    .lexical_min_score(0.5)
    .lexical_timeout_ms(5000)
    .lexical_parallel(true)
    .sort_by(SortField::Field { name: "date".to_string(), order: SortOrder::Desc })
    .add_field_boost("title", 2.0)
    .add_field_boost("body", 1.0)
    .limit(20)
    .build();
}

.highlight(fields) と .highlight_config(config) は各ヒットのハイライト済みフラグメントを要求します。詳細はハイライトを参照してください。

Query DSL の使用

プログラマティックにクエリを構築する代わりに、テキストベースの Query DSL を使用できます。

#![allow(unused)]
fn main() {
use laurus::lexical::QueryParser;
use laurus::analysis::analyzer::standard::StandardAnalyzer;
use std::sync::Arc;

let analyzer = Arc::new(StandardAnalyzer::default());
let parser = QueryParser::new(analyzer).with_default_field("body");

// Simple term
let query = parser.parse("rust")?;

// Boolean
let query = parser.parse("rust AND programming")?;

// Phrase
let query = parser.parse("\"machine learning\"")?;

// Field-specific
let query = parser.parse("title:rust AND body:programming")?;

// Fuzzy
let query = parser.parse("programing~2")?;

// Range
let query = parser.parse("year:[2020 TO 2024]")?;

// DateTime range (date-only bounds are midnight UTC)
let query = parser.parse("created_at:[2024-01-01 TO 2024-12-31]")?;
}

完全な構文リファレンスは Query DSL を参照してください。

フィルタ結果キャッシュ（Filter Result Cache）

テナント・カテゴリ・ステータスフラグなどの filter 句は、多数のリクエストで繰り返し 再利用されます。毎回ゼロから評価すると同じ posting list を何度も走査することになります。 laurus は filter がマッチするドキュメント ID の集合をメモ化し、繰り返しの filter を posting 走査ではなく単一のルックアップで済ませます。

• スナップショット連動・自己無効化（snapshot-scoped, self-invalidating）。 キャッシュは reader 上に存在し、reader は commit() / optimize() / refresh() の たびに再構築されます。各 reader は point-in-time スナップショットなので、手動の無効化は 不要です。インデックス変更後の次の検索は空のキャッシュから始まり、常にコミット済みの データを反映します。
• スコア非依存（score-independent）。 filter は relevance に影響せずドキュメントを 選別するだけなので、キャッシュ値は単なる doc-id 集合（Roaring ビットマップ）です。 ハイブリッド検索 / フィルタ検索 の filter_query に使われ、 lexical 側・vector 側の両方に供給されます。
• BooleanQuery 内でも再利用。 BooleanQuery 内の Occur::Filter 句 （例: must(user_query).filter(tenant_filter)）も、posting 再走査ではなくキャッシュから マッチ集合を取得します。マルチセグメント時の per-segment fanout 経路でも有効です。
• 構造的に安全（safe by construction）。 canonical なキーを持つクエリのみキャッシュ されます。Term・Phrase・Prefix・Wildcard・Regexp・Fuzzy・Range・Geo・Geo3d クエリは キャッシュ可能で、キャッシュ可能な句のみで構成され、かつ少なくとも 1 つの正句 （Must / Should / Filter）を持つ BooleanQuery も同様です。正句のない BooleanQuery・ Span クエリ・マルチフィールドクエリは毎回新規評価され（キャッシュされず）、結果は常に 正しくなります。

キャッシュはデフォルトで有効です。インデックス設定で調整・無効化できます。

#![allow(unused)]
fn main() {
use laurus::lexical::store::config::LexicalIndexConfig;

let config = LexicalIndexConfig::builder()
    .query_filter_cache_capacity(4096) // スナップショットあたりのエントリ数。0 で無効化
    .build();
}

パース済みクエリキャッシュ（Parsed Query Cache）

DSL 文字列での検索（SearchRequest::from_dsl や LexicalSearchQuery::Dsl）は、毎回 pest 文法でパースし、語を analyzer で再トークン化します。オートコンプリートや人気クエリでは同じ 文字列が繰り返されるため、laurus は DSL 文字列 → パース済みクエリ をメモ化します。繰り返し の DSL 文字列は一度だけパースされ、以降は再利用されます（パース済みクエリツリーの安価な複製）。

フィルタキャッシュと同様にスナップショット連動です。キャッシュは searcher 上に存在し、 commit() / optimize() / refresh() のたびに再構築されます。analyzer と default fields は その searcher で固定なので DSL 文字列のみがキーになり、スキーマ/analyzer 変更時は空の新しい キャッシュになります。デフォルトで有効。インデックス設定で調整・無効化できます。

#![allow(unused)]
fn main() {
use laurus::lexical::store::config::LexicalIndexConfig;

let config = LexicalIndexConfig::builder()
    .parsed_query_cache_capacity(2048) // スナップショットあたりのエントリ数。0 で無効化
    .build();
}

Posting キャッシュ（Posting Cache）

語の評価ではセグメントの .post ファイルから posting list を読み、デコードします （varint doc-id、削除フィルタ、skip table）。キャッシュがないと同じ語のクエリごとに read + デコードを繰り返し、クラウド/リモートストレージでは read が支配的になります。各セグメント リーダーはデコード済み・削除フィルタ後の posting list を小さくキャッシュし、スナップショット 内の同一 (field, term) 参照を再利用します。

セグメントはスナップショット内で immutable なので、キャッシュ済みリストは常にその削除と整合 します。commit すると空キャッシュの新しいセグメントリーダーが構築されます。キャッシュは byte-budget で上限制御され（posting list はサイズ分散が大きい）、予算超過で least-recently-used リストを退避し、予算全体より大きい単一リストはキャッシュしません。 デフォルトで有効です。セグメントごとのキャッシュがそれぞれ max_cache_memory の予算（デフォルト 128 MiB。reader の term-info キャッシュの上限も兼ねる）を持つため、最悪の使用量はセグメント数に比例して 増えます。インデックス設定で制御できます。

#![allow(unused)]
fn main() {
use laurus::lexical::store::config::LexicalIndexConfig;

let config = LexicalIndexConfig::builder()
    .enable_posting_cache(false) // 完全に無効化
    .build();

let config = LexicalIndexConfig::builder()
    .max_cache_memory(256 * 1024 * 1024) // またはセグメントごとの予算（バイト）を変更
    .build();
}

次のステップ

• 意味的類似性検索: Vector 検索
• Lexical + Vector の組み合わせ: ハイブリッド検索
• DSL の完全な構文リファレンス: Query DSL

Vector 検索

Vector 検索は、意味的類似性によってドキュメントを検索します。キーワードのマッチングではなく、ベクトル空間におけるクエリの意味とドキュメントエンベディングを比較します。

基本的な使い方

Builder API

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::vector::VectorSearchRequestBuilder;

let request = SearchRequestBuilder::new()
    .vector_query(
        VectorSearchRequestBuilder::new()
            .add_text("embedding", "systems programming language")
            .limit(10)
            .build()
    )
    .build();

let results = engine.search(request).await?;
}

add_text() メソッドはテキストをクエリペイロードとして格納します。検索時に、エンジンが設定されたエンベッダーを使用してテキストをエンベディングし、ベクトルインデックスを検索します。

Query DSL

#![allow(unused)]
fn main() {
use laurus::vector::VectorQueryParser;

let parser = VectorQueryParser::new(embedder.clone())
    .with_default_field("embedding");

let request = parser.parse(r#"embedding:"systems programming""#).await?;
}

VectorSearchRequestBuilder

Builder API により、きめ細かな制御が可能です。

#![allow(unused)]
fn main() {
use laurus::vector::VectorSearchRequestBuilder;
use laurus::vector::store::request::QueryVector;

let request = VectorSearchRequestBuilder::new()
    // Text query (will be embedded at search time)
    .add_text("text_vec", "machine learning")

    // Or use a pre-computed vector directly
    .add_vector("embedding", vec![0.1, 0.2, 0.3, /* ... */])

    // Search parameters
    .limit(20)

    .build();
}

メソッド

マルチフィールド Vector 検索

単一のリクエストで複数のベクトルフィールドを横断して検索できます。

#![allow(unused)]
fn main() {
let request = VectorSearchRequestBuilder::new()
    .add_text("text_vec", "cute kitten")
    .add_text("image_vec", "fluffy cat")
    .build();
}

各クエリ句はベクトルを生成し、対応するフィールドに対して検索されます。結果は設定されたスコアモードで結合されます。

スコアモード

マルチベクトル検索の並列実行

複数のクエリベクトル（複数のフィールドや、スコアモードで結合する複数の クエリ埋め込みなど）を含むリクエストに対して、Laurus は rayon を使ってクエリごとの類似度検索を並列に実行します。

動作:

• 並列化は VectorIndexSearcher::search_batch トレイトメソッドの デフォルト実装内に置かれています。ネイティブビルド（native feature が デフォルトで有効）では、queries.len() が searcher の parallel_threshold（デフォルト 4、 searcher 単位で override 可能） に達した時点で、HNSW / Flat / IVF のクエリごとの検索が rayon のグローバル スレッドプール上で並列実行されます。これを下回るとシリアルループのほうが 速くなります（rayon のディスパッチオーバーヘッド ~1-2 µs が、単一クエリの 50-200 µs を上回りやすいため）。
• wasm32 ターゲットでは rayon が使用できないため、常にシリアルパスを 通ります。
• 集約（スコアモードによるマージ）と最終ソートはクエリ並列フェーズの後に シリアル実行されます。スコアが同点の場合は doc_id の昇順でタイブレーク するため、rayon のワークスチール順序に依存しない決定的な結果になります。

外部 API（VectorStore::search、gRPC の Search、REST の POST /v1/search、各言語バインディング）は一切変更されません。並列実行は 完全に内部最適化で、laurus をアップグレードするだけで有効になります。 speedup はホストの利用可能コア数に応じてスケールアップします（4 物理コア / 8 スレッドの HT 有効ラップトップ CPU では、B = 64 クエリ時にスループットが およそ 2× 向上します。これは物理コア数と HT 共有による上限に近い値です）。

ブルートフォーススキャンの並列化

Flat と IVF インデックスは、グラフ探索ではなく総当たりの距離スキャンで候補を ランク付けします。1 つのクエリの候補数が内部しきい値（2048）に達すると、 そのスキャンは rayon のグローバルスレッドプールに分散されます。 これを下回るとシリアルループのほうが速くなります（rayon のジョブごとの ディスパッチ ~1-2 µs が小さなスキャンを上回るため）。

これは上記のクエリ単位の並列化とは直交します。バッチはクエリ間で並列化し、 さらに各大規模クエリは同じプール上で自身のスキャンを並列化します。ワーク スチールにより全体の並列度はプールサイズに制限されます（OS スレッドの oversubscription は発生しません）。距離カーネルは副作用を持たないため、結果は 任意の順序で収集された後にソートされ、出力は決定的に保たれます。wasm32 （rayon なし）では常にシリアルです。

speedup はホストの物理コア数に応じてスケールし、大きな Flat インデックスや 広い IVF n_probe で最大になります。しきい値未満のスキャンは影響を受けません。

IVF クラスタ選択

距離スキャンの前に、IVF クエリはまず どの クラスタをスキャンするかを選びます。 クエリを全セントロイドと照合し、最も近い n_probe 個を残します。プローブした クラスタはこの後にマージされ類似度で再ランク付けされるため、セントロイドの 相対順序は無関係です。したがって最近傍 n_probe 個は、K 個全体の完全ソート （O(K log K)）ではなく O(K) の部分選択（select_nth_unstable_by）で取得 します。削減効果はクラスタ数 K が大きいほど増え、K = 2048 ではクエリ あたりの粗選択ステップを約 18% 短縮しました（Issue #668）。セントロイド スキャン自体はシリアルのままです。各セントロイドは単一の距離計算であり、 現実的なクラスタ数（K ≈ √N）では rayon へのディスパッチが節約分を上回る ためです。

ウェイト

DSL では ^ ブースト構文を使用するか、QueryVector の weight で各フィールドの寄与度を調整します。

text_vec:"cute kitten"^1.0 image_vec:"fluffy cat"^0.5

これは、テキストの類似度が画像の類似度の 2 倍の重みを持つことを意味します。

vector フィールドのスキーマレベルの base_weight（Issue #1084）も同様に 機能しますが、クエリ単位の上書きではなくフィールド単位のデフォルト値 である点が異なります。上記のクエリ重みに乗算されるため、base_weight と ^/weight は組み合わさります。どちらも vector 側自体のスコアリング にしか影響しないため、ハイブリッド検索の lexical-vs-vector のバランス を変えることはできません。FusionAlgorithm::RRF はランクのみを見て元の スコアを完全に無視しますし、FusionAlgorithm::WeightedSum は lexical_weight/vector_weight を適用する前に各側を min-max 正規化 するため、フィールド単位の一様なスカラー倍は打ち消されます。両方の 重み付け機構が実際に影響するのは、1 回のクエリで複数の vector フィール ドを対象にしたときの、フィールド間の相対的な優先度です。

このフィールド単位の加算が行われるのは、クエリが対象フィールドを明示 した場合のみです。フィールド未指定のクエリには参照すべき単一フィール ドが無いため base_weight を適用できず（Issue #1084）、同一次元を持つ 複数フィールドに文書がマッチした場合は、加算ではなくその文書の最も 良くマッチしたフィールドを採用します（Issue #1343。後述の フィールドルーティング を参照）。

フィールドルーティング

マルチフィールドスキーマでは、各 vector フィールドが独自の HNSW graph を 持ちます。デフォルトではクエリは全 vector フィールドを検索しますが、指定し たフィールドのみに限定すると、それ以外のフィールドの graph 探索を完全に 省略できます。

2 つのルーティング入力が、以下の優先順位で尊重されます。

1. per-query — QueryVector.fields。DSL パーサがクエリ句の指定する フィールドからこれを設定するため、image_vec:"fluffy cat" は image_vec のみを検索します。
2. request-level — VectorSearchParams.fields（セレクタのリスト）:
   • Exact("image_vec") — フィールド名の完全一致。
   • Prefix("image_") — 指定 prefix で始まる全フィールドに一致 （インデックスのフィールド名から解決）。

どちらも未指定の場合は全フィールドを検索します（デフォルト）。フィールドに ルーティングされたクエリは、そのフィールドに vector を持たないドキュメントを 返しません。

検索対象の複数フィールドに vector を持つ文書も、返るのは 1 回だけです。 フィールド未指定のクエリの fan-out は、その文書の最も良くマッチした フィールドに畳み込まれるため（Issue #1343）、limit/top_k は (文書, フィールド) のペアではなく文書を数えます。これは、フィールドを 明示した複数フィールドクエリ（fields: [Exact("a"), Exact("b")]）が 各フィールドのスコアを加算するのとは異なります。詳しくは前述の ウェイト を参照してください。

フィルター付き Vector 検索

Lexical フィルターを適用して Vector 検索の結果を絞り込むことができます。

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;
use laurus::lexical::TermQuery;
use laurus::vector::VectorSearchRequestBuilder;

// Vector search with a category filter
let request = SearchRequestBuilder::new()
    .vector_query(
        VectorSearchRequestBuilder::new()
            .add_text("embedding", "machine learning")
            .build()
    )
    .filter_query(Box::new(TermQuery::new("category", "tutorial")))
    .limit(10)
    .build();

let results = engine.search(request).await?;
}

フィルタークエリはまず Lexical インデックス上で実行されて許可されるドキュメント ID のセットを特定し、その後 Vector 検索がそれらの ID に制限されます。

filter-aware HNSW トラバーサル

HNSW フィールドでは、許可 ID セットは検索後に適用するだけでなく、graph 探索 そのものに渡されます。探索中、フロンティアはすべての近傍（非マッチの 近傍も含む）を経由して展開されるため、graph 上の非マッチ領域を横断して マッチに到達できますが、結果セットに入るのはマッチするドキュメントのみです。

これは選択的フィルターで重要になります。単純な post-filter は最近傍の固定 ef_search ウィンドウだけを見てマッチしたものを残すため、マッチが希少だと ウィンドウの外に完全に外れてしまい、到達可能なマッチが存在しても結果が実際 より大幅に少なく（時にはゼロに）なります。filter-aware トラバーサルは十分な マッチを集めるまで探索を続け、非常に選択的なフィルターでは内部の訪問上限 （ef_search の定数倍）で latency を抑えます。

フィルターなしの経路は不変です（フィルターがなければ従来どおりの挙動）。 Flat / IVF フィールドは許可セットをインラインで適用します。ドキュメント ID が セットに含まれない候補は距離カーネルの実行前にスキップされるため、選択的フィルター では post-filter が払う無駄な距離計算を回避できます。いずれにせよスキャンは網羅的 なので recall は変わりません。store 側の post-filter は冗長な安全網として後段で 引き続き実行されます。

許可セットが ef_search より小さい場合、HNSW フィールドは graph 探索を完全に スキップし、許可されたドキュメントを直接採点します。候補がこれほど少ないと graph で「探す」ものは無く、直接スキャンは許可ドキュメントだけを（graph 探索が 触れる数を超えずに）採点し、しかも exact です。そのため非常に選択的な フィルターでは、近似ではなく真の最近傍マッチが返ります。許可セットが大きい場合は 上記の filter-aware トラバーサルを引き続き使います。

deletion-aware HNSW トラバーサル

論理削除されたドキュメントはコンパクションまで HNSW graph に残るため （削除とコンパクション を参照）、トラバーサルは フィルター除外と同じ方法で削除ノードをスキップする必要があります。graph 探索は 単一の admission ルールを適用します。ノードが結果集合に入るのは、フィルターに マッチし（フィルターがある場合）かつ 削除されていない場合のみで、frontier は 連結性を保つために削除ノードも通過します。

これにより削除が蓄積しても recall が正しく保たれます。削除ノードを result heap に 入れてしまうと、固定の ef_search スロットを占有して生存ネイバーを押し出し、 最悪の場合は ef_search ウィンドウが削除ドキュメントだけで埋まって何も返らなく なります。トラバーサル中にスキップすれば同じスロットが生存結果で埋まるため、 最近傍のドキュメントを削除しても 10 件のページは満杯のままです。上記の小さな 許可セットの exact スキャンや Flat / IVF のインライン経路も同じ削除チェックを 適用します。

高速経路は維持されます。フィルターも削除も無い検索では、トラバーサルは従来の ループをそのまま実行し、ネイバーごとの admission 用ブックキーピングのコストを 一切払いません。

許可セットの表現（Allow-Set Representation）

許可セットは形状に応じて型が選ばれます。密なフィルターには Roaring ビットマップ、 疎なフィルターにはハッシュセットを使います。フィルター付きハイブリッド検索では、 lexical 側がマッチ集合をビットマップとして既に構築している （lexical の フィルタ結果キャッシュ 参照）ため、そのビットマップを vector 側にそのまま渡します。これにより集合は クエリ全体で一度だけ実体化され、両側で再構築されません。これは内部最適化であり、 公開フィルター API は不変です。

数値範囲によるフィルター

#![allow(unused)]
fn main() {
use laurus::lexical::NumericRangeQuery;
use laurus::lexical::core::field::NumericType;

let request = SearchRequestBuilder::new()
    .vector_query(
        VectorSearchRequestBuilder::new()
            .add_text("embedding", "type systems")
            .build()
    )
    .filter_query(Box::new(NumericRangeQuery::new(
        "year", NumericType::Integer,
        Some(2020.0), Some(2024.0), true, true
    )))
    .limit(10)
    .build();
}

Late Interaction による再採点（Rescore）

late interaction による再採点（Issue #1345）は、lexical・vector・ハイブリッドの どの検索でも、上位の候補を ColBERT 型の late interaction で並べ替えます。 各文書は MultiVector フィールド にトークンごとのベクトルを持ち、クエリも同じくトークンベクトルの集合です。 文書のスコアは、クエリの各ベクトルについて文書のベクトルの中で最もよく合う ものとの類似度を求め、それを合計した値（MaxSim）です。

score(q, d) = Σ_i max_j (q_i · d_j)

トークン単位で照合するため、文書全体を 1 本の埋め込みにすると平均化されて 失われる細部を拾えます。一方で 1 段目の検索が速度を保ちます。再採点するのは 上位の候補だけなので、MultiVector フィールドに ANN 索引は要りません。

クエリ ─→ 1 段目: lexical / vector / ハイブリッド（通常の検索）
              │ 上位 window_size 件（既定 100）
              ▼
          再採点: MultiVector フィールドに対する MaxSim
              ▼
          offset / limit → 文書を取得

MultiVector フィールドにトークン単位の Embedder（candle_colbert など。CandleColbertEmbedder を参照）が あれば、文書をテキストのまま取り込め、クエリもテキストで渡せます。

#![allow(unused)]
fn main() {
use laurus::{RescoreOptions, SearchRequestBuilder};

let request = SearchRequestBuilder::new()
    .query_dsl("body:lifetimes body_vec:\"how do lifetimes work\"")
    .rescore(
        RescoreOptions::late_interaction_text("body_colbert", "how do lifetimes work")
            .window_size(100),
    )
    .limit(10)
    .build();
let results = engine.search(request).await?;
}

Embedder がない場合は、文書のトークンベクトルを作ったのと同じモデルで、 クエリのトークンベクトルを計算して渡します。

#![allow(unused)]
fn main() {
use laurus::RescoreOptions;
use laurus::vector::Vector;

let query_tokens: Vec<Vector> = colbert_query_vectors("how do lifetimes work");
let rescore = RescoreOptions::late_interaction("body_colbert", query_tokens);
}

再採点は、Rust API のほか、gRPC、 HTTP gateway、 MCP の search ツール、 laurus search、 Python・ Ruby・ PHP・ Node.js・ WASM の各バインディングでも使えます。

オプション

テキストのクエリは、1 段目の検索の前に、フィールドのトークン単位の Embedder が クエリとして埋め込みます。 EngineBuilder::embedding_cache_capacity を設定していれば、同じクエリ（次のページなど）はキャッシュから返ります。

クエリのベクトルは 1〜1,024 本で、どれもフィールドの次元と一致し、有限値で なければなりません。オプションが不正な場合、対象が MultiVector フィールドで ない場合、テキストのクエリが空かフィールドにトークン単位の Embedder がない場合、 フィールドによるソート（sort_by に SortField::Field）を同時に指定した場合は、 検索を始める前に LaurusError::InvalidArgument で失敗します。フィールドによる ソートはスコアで並べないため、再採点する対象がないからです。

並び順とスコア

1. window（1 段目の上位 window_size 件）を MaxSim の降順に並べます。 同点は内部の文書 ID の順にするため、並び順は決定的です。
2. フィールドにトークンベクトルを持たない window 内の候補を、1 段目の順で 続けます。
3. window の外の候補を、元の順のまま最後に続けます。

再採点した結果の score は MaxSim の値になり、それ以外の結果は 1 段目の スコアのままです。2 種類のスコアは比較できないため、グループはスコアでは なく位置で並べます。

1 段目は max(window_size, offset + limit) 件の候補を取得するため、どの ページも同じ再採点済みの順位から切り出されます。ページを 1 つずつ取得して つなげると、1 回で大きなページを取得したときと同じ順位になります。ページが window の外に及ぶ場合も同じです。window を広げると 1 段目で下位だった文書を 引き上げられますが、コストは window に比例して増えます。1 段目で取得されな かった文書は、再採点でも拾えません。

類似度

クエリのベクトルと文書のベクトルの類似度は内積です。 DistanceMetric::Cosine（デフォルト）のフィールドでは、文書のベクトルを 書き込み時に、クエリのベクトルを検索時に L2 正規化するため、各ペアはコサイン 類似度になり、スコアはクエリのベクトルの本数を超えません。 DistanceMetric::DotProduct ではベクトルをそのまま使います。

フィールドに保存されたベクトルは圧縮されている場合もあります。 storage オプション は、既定の厳密な F32 の代わりに F16 や Int8 でトークンベクトルを 符号化でき、インデックスを小さくする代わりにスコアの精度をわずかに 犠牲にします — F16 は要素あたり約 2⁻¹¹ の相対誤差、Int8 の誤差は ベクトルごとのスケール（max(abs(vector)) / 127）で上界が決まります。

コスト

再採点の計算量は window_size × クエリのベクトル数 × 文書のベクトル数 回の 内積です。ネイティブビルドでは候補を rayon のグローバル スレッドプールで並列に採点し、wasm32 では 1 件ずつ採点します。目安として、 128 次元のベクトルを 300 本持つ候補 100 件を 32 本のクエリで再採点すると （約 1 億 2,300 万回の積和）、Apple M4 で 1 回の検索あたり約 2 ms、1 スレッド では約 7 ms でした。

距離メトリクス（Distance Metrics）

距離メトリクスはスキーマでフィールドごとに設定されます（Vector インデキシング を参照）。

コード例: 完全な Vector 検索

use std::sync::Arc;
use laurus::{Document, Engine, Schema, SearchRequestBuilder, PerFieldEmbedder};
use laurus::lexical::TextOption;
use laurus::vector::HnswOption;
use laurus::vector::VectorSearchRequestBuilder;
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> laurus::Result<()> {
    let storage = Arc::new(MemoryStorage::new(Default::default()));

    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_hnsw_field("text_vec", HnswOption {
            dimension: 384,
            ..Default::default()
        })
        .build();

    // Set up per-field embedder
    let embedder = Arc::new(my_embedder);
    let pfe = PerFieldEmbedder::new(embedder.clone());
    pfe.add_embedder("text_vec", embedder.clone());

    let engine = Engine::builder(storage, schema)
        .embedder(Arc::new(pfe))
        .build()
        .await?;

    // Index documents (text in vector field is auto-embedded)
    engine.add_document("doc-1", Document::builder()
        .add_text("title", "Rust Programming")
        .add_text("text_vec", "Rust is a systems programming language.")
        .build()
    ).await?;
    engine.commit().await?;

    // Search by semantic similarity
    let results = engine.search(
        SearchRequestBuilder::new()
            .vector_query(
                VectorSearchRequestBuilder::new()
                    .add_text("text_vec", "systems language")
                    .build()
            )
            .limit(5)
            .build()
    ).await?;

    for r in &results {
        println!("{}: score={:.4}", r.id, r.score);
    }

    Ok(())
}

次のステップ

• キーワード検索と組み合わせる: ハイブリッド検索
• Vector クエリの DSL 構文: Query DSL

ハイブリッド検索（Hybrid Search）

ハイブリッド検索は、Lexical 検索（キーワードマッチング）と Vector 検索（意味的類似性）を組み合わせることで、精度と意味的な関連性の両方を兼ね備えた結果を提供します。これは Laurus の最も強力な検索モードです。

なぜハイブリッド検索なのか

仕組み

sequenceDiagram
    participant User
    participant Engine
    participant Lexical as LexicalStore
    participant Vector as VectorStore
    participant Fusion

    User->>Engine: SearchRequest\n(lexical + vector)

    par Execute in parallel
        Engine->>Lexical: BM25 keyword search
        Lexical-->>Engine: Ranked hits (by relevance)
    and
        Engine->>Vector: ANN similarity search
        Vector-->>Engine: Ranked hits (by distance)
    end

    Engine->>Fusion: Merge two result sets
    Note over Fusion: RRF or WeightedSum
    Fusion-->>Engine: Unified ranked list
    Engine-->>User: Vec of SearchResult

基本的な使い方

Builder API

#![allow(unused)]
fn main() {
use laurus::{SearchRequestBuilder, FusionAlgorithm};
use laurus::lexical::TermQuery;
use laurus::lexical::search::searcher::LexicalSearchQuery;
use laurus::vector::VectorSearchRequestBuilder;

let request = SearchRequestBuilder::new()
    // Lexical component
    .lexical_query(
        LexicalSearchQuery::Obj(
            Box::new(TermQuery::new("body", "rust"))
        )
    )
    // Vector component
    .vector_query(
        VectorSearchRequestBuilder::new()
            .add_text("text_vec", "systems programming")
            .build()
    )
    // Fusion algorithm
    .fusion_algorithm(FusionAlgorithm::RRF { k: 60.0 })
    .limit(10)
    .build();

let results = engine.search(request).await?;
}

Query DSL

単一のクエリ文字列内で Lexical 句と Vector 句を混在させることができます。

#![allow(unused)]
fn main() {
use laurus::UnifiedQueryParser;
use laurus::lexical::QueryParser;
use laurus::vector::VectorQueryParser;

let unified = UnifiedQueryParser::new(
    QueryParser::new(analyzer).with_default_field("body"),
    VectorQueryParser::new(embedder),
);

// Lexical + vector in one query
let request = unified.parse(r#"body:rust text_vec:"systems programming""#).await?;
let results = engine.search(request).await?;
}

Vector 句の識別はスキーマのフィールド型に基づいて行われます。ベクトルフィールドとして定義されたフィールド名を持つ句は Vector クエリとして、それ以外は Lexical クエリとして解析されます。

フュージョンアルゴリズム（Fusion Algorithms）

Lexical と Vector の両方の結果が存在する場合、それらを単一のランキングリストにマージする必要があります。Laurus は 2 つのフュージョンアルゴリズムをサポートしています。

RRF（Reciprocal Rank Fusion）

デフォルトのアルゴリズムです。生のスコアではなく、ランク位置に基づいて結果を結合します。

score(doc) = sum( 1 / (k + rank_i) )

rank_i は各結果リストにおけるドキュメントの位置、k はスムージングパラメータ（デフォルト 60）です。

#![allow(unused)]
fn main() {
use laurus::FusionAlgorithm;

let fusion = FusionAlgorithm::RRF { k: 60.0 };
}

利点:

• Lexical と Vector の結果間のスコア分布の違いに対してロバスト
• ウェイトのチューニングが不要
• すぐに使える（out of the box）

WeightedSum

正規化された Lexical スコアと Vector スコアを線形結合します。

score(doc) = lexical_weight * lexical_score + vector_weight * vector_score

#![allow(unused)]
fn main() {
use laurus::FusionAlgorithm;

let fusion = FusionAlgorithm::WeightedSum {
    lexical_weight: 0.3,
    vector_weight: 0.7,
};
}

使用場面:

• Lexical と Vector の関連性のバランスを明示的に制御したい場合
• 一方のシグナルが他方よりも重要であることがわかっている場合

SearchRequest のフィールド

SearchResult

各結果には以下が含まれます。

ハイブリッド検索でのハイライトはリクエストの lexical クエリによって駆動されるため、Vector 側だけでヒットした結果の highlights は空になります。詳細はハイライトを参照してください。

フィルター付きハイブリッド検索

フィルターを適用して、Lexical と Vector の両方の結果を制限できます。

#![allow(unused)]
fn main() {
let request = SearchRequestBuilder::new()
    .lexical_query(
        LexicalSearchQuery::Obj(Box::new(TermQuery::new("body", "rust")))
    )
    .vector_query(
        VectorSearchRequestBuilder::new()
            .add_text("text_vec", "systems programming")
            .build()
    )
    // Only search within "tutorial" category
    .filter_query(Box::new(TermQuery::new("category", "tutorial")))
    .fusion_algorithm(FusionAlgorithm::RRF { k: 60.0 })
    .limit(10)
    .build();
}

フィルタリングの仕組み

1. フィルタークエリが Lexical インデックス上で実行され、許可されるドキュメント ID のセットが生成される
2. Lexical 検索: フィルターがユーザークエリとブーリアン AND で結合される
3. Vector 検索: 許可された ID が ANN 検索の制限として渡される

ページネーション

offset と limit を使用してページネーションを実現します。

#![allow(unused)]
fn main() {
// Page 1: results 0-9
let page1 = SearchRequestBuilder::new()
    .lexical_query(/* ... */)
    .vector_query(/* ... */)
    .offset(0)
    .limit(10)
    .build();

// Page 2: results 10-19
let page2 = SearchRequestBuilder::new()
    .lexical_query(/* ... */)
    .vector_query(/* ... */)
    .offset(10)
    .limit(10)
    .build();
}

フュージョン結果の再採点（Rescore）

ハイブリッド検索は、late interaction による再採点の 1 段目に適しています。 フュージョンがキーワードと意味のどちらかに合う候補を集め、再採点がその上位 window_size 件を MultiVector フィールドに対するトークン単位の MaxSim で 並べ替えます。

#![allow(unused)]
fn main() {
use laurus::RescoreOptions;

let request = SearchRequestBuilder::new()
    .lexical_query(/* ... */)
    .vector_query(/* ... */)
    .fusion_algorithm(FusionAlgorithm::RRF { k: 60.0 })
    .rescore(RescoreOptions::late_interaction("body_colbert", query_tokens))
    .limit(10)
    .build();
}

再採点はフュージョンの後、offset / limit の前に実行されるため、 ページネーションは再採点の有無にかかわらず同じように動作します。オプション、 並び順の規則、コストは late interaction による再採点 を参照してください。

完全な例

use std::sync::Arc;
use laurus::{
    Document, Engine, Schema, SearchRequestBuilder,
    FusionAlgorithm, PerFieldEmbedder,
};
use laurus::lexical::{TextOption, TermQuery};
use laurus::lexical::core::field::IntegerOption;
use laurus::lexical::search::searcher::LexicalSearchQuery;
use laurus::vector::{HnswOption, VectorSearchRequestBuilder};
use laurus::storage::memory::MemoryStorage;

#[tokio::main]
async fn main() -> laurus::Result<()> {
    let storage = Arc::new(MemoryStorage::new(Default::default()));

    // Schema with both lexical and vector fields
    let schema = Schema::builder()
        .add_text_field("title", TextOption::default())
        .add_text_field("body", TextOption::default())
        .add_text_field("category", TextOption::default())
        .add_integer_field("year", IntegerOption::default())
        .add_hnsw_field("body_vec", HnswOption {
            dimension: 384,
            ..Default::default()
        })
        .build();

    // Configure analyzer and embedder (see Text Analysis and Embeddings docs)
    // let analyzer = Arc::new(StandardAnalyzer::new()?);
    // let embedder = Arc::new(CandleBertEmbedder::new("sentence-transformers/all-MiniLM-L6-v2")?);
    let engine = Engine::builder(storage, schema)
        // .analyzer(analyzer)
        // .embedder(embedder)
        .build()
        .await?;

    // Index documents with both text and vector fields
    engine.add_document("doc-1", Document::builder()
        .add_text("title", "Rust Programming Guide")
        .add_text("body", "Rust is a systems programming language.")
        .add_text("category", "programming")
        .add_integer("year", 2024)
        .add_text("body_vec", "Rust is a systems programming language.")
        .build()
    ).await?;
    engine.commit().await?;

    // Hybrid search: keyword "rust" + semantic "systems language"
    let results = engine.search(
        SearchRequestBuilder::new()
            .lexical_query(
                LexicalSearchQuery::Obj(Box::new(TermQuery::new("body", "rust")))
            )
            .vector_query(
                VectorSearchRequestBuilder::new()
                    .add_text("body_vec", "systems language")
                    .build()
            )
            .fusion_algorithm(FusionAlgorithm::RRF { k: 60.0 })
            .limit(10)
            .build()
    ).await?;

    for r in &results {
        println!("{}: score={:.4}", r.id, r.score);
    }

    Ok(())
}

次のステップ

• クエリ構文の完全なリファレンス: Query DSL
• ID 解決の仕組み: ID Management
• データの永続性: Persistence & WAL

Query DSL

Laurus は統合 Query DSL（Domain Specific Language）を提供しており、Lexical（キーワード）検索と Vector（意味的）検索を単一のクエリ文字列で記述できます。UnifiedQueryParser は入力を Lexical 部分と Vector 部分に分割し、適切なサブパーサーに委譲します。

概要

title:hello AND content:"cute kitten"^0.8
|--- lexical --|    |--- vector --------|

Vector 句と Lexical 句の区別は、フィールド名に基づいて行われます。スキーマ上でベクトルフィールドとして定義されたフィールド名が指定された場合、その句は Vector クエリとして扱われます。

フィールド検証

クエリ中の field:value 句は、パース時にスキーマと照合されます。スキーマに宣言されていないフィールドを参照したクエリは、結果が黙って空になるのではなく、エラーとして返されます。これにより typo（例: title:hello のつもりで titl:hello）を早期に検出できます。

未知のフィールドを含むドキュメントを受け付けたい場合は、スキーマの dynamic_field_policy を設定して、投入時にフィールドを追加する動作を有効にしてください。一度フィールドがスキーマに登録されれば、それを参照するクエリは正常に動作します。

Lexical クエリ構文

Lexical クエリは、完全一致または近似のキーワードマッチングを使用して転置インデックスを検索します。

Term クエリ

フィールド（またはデフォルトフィールド）に対して単一のタームをマッチングします。

hello
title:hello

フィールドのアナライザーが引用符なしの語を複数のトークンに分割する場合 （例: 形態素解析（Lindera）アナライザーを通した日本語の文、あるいは デフォルトの \w+ トークナイザーを通した rust-lang のようなハイフン 入り単語）、それらのトークンは正確な語順のフレーズとしてではなく OR で結合されます（Lucene の match クエリと同様）。厳密な隣接一致 が必要な場合は、引用符付きのフレーズクエリを使用してください。

ブーリアン演算子

AND と OR（大文字小文字を区別しない）で句を結合します。

title:hello AND body:world
title:hello OR title:goodbye

AND は対称的に動作します。両側の句を必須（Must）にマークするため、title:hello AND body:world は 両方 の句にマッチするドキュメントだけを返します。連鎖（a AND b AND c）でも 3 つすべてが必須となります。ただし +（必須）または -（禁止）が明示されている句は元の意図が維持され、AND で上書きされることはありません。

明示的な演算子なしでスペース区切りされた句は、暗黙的なブーリアン（スコアリング付きの OR として動作）を使用します。例えば a b AND c は「a は任意、b と c の両方が必須」と解釈されます。

必須 / 禁止句

+（必ずマッチ）と -（マッチ禁止）を使用します。

+title:hello -title:goodbye

フレーズクエリ

ダブルクォートを使用して正確なフレーズをマッチングします。オプションの近接度（~N）で、ターム間に N 語を許可します。

"hello world"
"hello world"~2

多値テキストフィールドでは、フレーズ（および ~N の近接ウィンドウ）は、N がフィールドの position_increment_gap（デフォルト 100）に達しない限り、ある要素から次の要素へまたぐことはありません。

引用符で囲んだ値がフィールドのアナライザーで 1 トークンになる場合は、Term クエリと同じ完全一致になります（~N は無視されます）。引用符なしの形では書けない値、たとえば .、/、: を含むパス・URL・ID を keyword フィールドで検索するときは、この形を使います。

path:"file:///notes/a.md"
links:"https://example.com/a"

SynonymGraphFilter のように、フィールドのアナライザーが 1 つの位置に複数のトークンを積む場合、それらはその位置の代替語になります。big と large を同義語とすると、"big" はどちらかの語を含む文書にマッチし、"a big dog" は「a large dog」にもマッチします。1 つの位置の代替語は合算ではなく 1 つのブレンドされたターム（SynonymQuery）としてスコア付けされるため、big と large の両方を含む文書が big を 2 回含む文書より高いスコアになることはありません。複数語の同義語は代替語ごとに 1 つのフレーズになり、どれか 1 つがマッチすれば値がマッチします。ml と machine learning を同義語とすると、"ml" は ml か、フレーズ machine learning にマッチします。これらのフレーズは 1 つずつではなくグラフに沿ってまとめてマッチするので、値が生むフレーズの数に上限はなく、文書はいくつのフレーズを含んでも 1 つのフレーズとしてスコアが付きます。同義語展開を参照してください。

2 位置以上のフレーズはタームの位置情報（ポジション）を比較します。ポジションは term_vectors: true（デフォルト）のフィールドにだけ保存されます。term_vectors: false のフィールドに対するフレーズは、0 件を返すのではなくクエリエラーで拒否されます。フィールドを指定しないフレーズがデフォルトフィールドに展開され、その中に term_vectors: false のフィールドが含まれる場合も同様です。上の "ml" のように、複数語の同義語でフレーズになる引用符付きの語も同様です。

ファジークエリ

編集距離を使用した近似マッチング。~ に続けてオプションで最大編集距離を指定します。

roam~
roam~2

ワイルドカードクエリ

?（1 文字）と *（0 文字以上）を使用します。

te?t
test*

範囲クエリ

包含的な [] または排他的な {} の範囲指定。数値フィールドや日付フィールドに有用です。

price:[100 TO 500]
date:{2024-01-01 TO 2024-12-31}
price:[* TO 100]

日付・日時の境界

境界が日時リテラルである範囲は DateTimeRangeQuery を構築し、数値範囲と同様に定数スコアでフィールドの BKD tree に対して評価されます。数値でない境界は、次の順に解釈を試みます。

# 日付のみの境界（上限は 2024-12-31T00:00:00Z。下記参照）
created_at:[2024-01-01 TO 2024-12-31]

# オフセット付き RFC 3339（09:00+09:00 は 00:00Z）
created_at:[2024-06-15T09:00:00+09:00 TO 2024-06-16T09:00:00+09:00]

# オフセットなし日時は UTC。* で上限を開放
created_at:[2024-06-15T12:34:56 TO *]

# 両端を含まない
created_at:{2024-01-01 TO 2025-01-01}

• 日付のみの境界はその日の 0 時（UTC）を意味するため、[2024-01-01 TO 2024-12-31] は 2024-12-31T00:00:00Z を含み、同日のそれ以降は含みません。年全体を対象にするには、上限に時刻を付ける（[2024-01-01 TO 2024-12-31T23:59:59.999999]）か、翌日を上限とする排他的範囲（{2024-01-01 TO 2025-01-01}。{} は下限の瞬間 2024-01-01T00:00:00Z も除外する点に注意）を使います。
• * はその側を開放します。
• 数値のみの境界は従来どおり数値範囲です。DateTime フィールドではエポック秒として扱われ、NumericRangeQuery を構築します。
• 数値の境界と日時の境界の混在（[1704067200 TO 2024-12-31]）や、日時の境界と日時リテラルでない文字列の混在（[2024-01-01 TO tomorrow]）は、黙って空の結果を返すのではなくパースエラーになります。数値でも日時リテラルでもない境界の範囲（title:[A TO Z]）は従来どおりパースは通りますが、何にもマッチしません。

ドキュメント投入時のテキストから DateTime フィールドへの型変換は RFC 3339 のみを 受け付けます。オフセットなし日時と日付のみの形式はクエリリテラル専用です。

2D 地理クエリ（geo_*)

2 種類の関数形式を Geo（2D 緯度 / 経度）フィールドに対して使えます。 緯度・経度は度単位、距離はメートル単位の符号付き浮動小数点数：

location:geo_distance(lat, lon, distance_m)
location:geo_bbox(min_lat, min_lon, max_lat, max_lon)

例：

# 東京から 10 km（= 10 000 m）以内（35.6895, 139.6917）
location:geo_distance(35.6895, 139.6917, 10000)

# 軸並行緯度・経度範囲
location:geo_bbox(35.0, 139.0, 36.0, 140.0)

クエリ対象フィールドはスキーマで Geo フィールドとして宣言されている必要が あります。緯度は [-90, 90]、経度は [-180, 180] の範囲外を拒否します。

3D 地理クエリ（geo3d_*）

3 種類の関数形式を Geo3d（3D ECEF 直交座標）フィールドに対して使えます。 k 以外の引数はすべてメートル単位の符号付き浮動小数点数、k のみ符号なし整数：

position:geo3d_distance(x, y, z, distance_m)
position:geo3d_bbox(min_x, min_y, min_z, max_x, max_y, max_z)
position:geo3d_nearest(x, y, z, k)

例：

# 東京タワーから 5 km 以内（ECEF 座標）
position:geo3d_distance(-3955182, 3350553, 3700276, 5000)

# 軸並行 ECEF バウンディングボックス内
position:geo3d_bbox(-4000000, 3300000, 3650000, -3900000, 3400000, 3750000)

# 最も近い 10 件
position:geo3d_nearest(-3955182, 3350553, 3700276, 10)

クエリ対象フィールドはスキーマで Geo3d として宣言されている必要があります。 座標系・WGS84 変換ヘルパー・詳細な意味論については 3D 地理検索 を参照してください。

ブースト

^ で句のウェイトを増加させます。

title:hello^2
"important phrase"^1.5

グルーピング

括弧でサブ式を囲みます。

(title:hello OR title:hi) AND body:world

Lexical PEG 文法

完全な Lexical 文法（parser.pest）:

query          = { SOI ~ boolean_query ~ EOI }
boolean_query  = { clause ~ (boolean_op ~ clause | clause)* }
clause         = { required_clause | prohibited_clause | sub_clause }
required_clause   = { "+" ~ sub_clause }
prohibited_clause = { "-" ~ sub_clause }
sub_clause     = { grouped_query | field_query | term_query }
grouped_query  = { "(" ~ boolean_query ~ ")" ~ boost? }
boolean_op     = { ^"AND" | ^"OR" }
field_query    = { field ~ ":" ~ field_value }
field_value    = { geo3d_query | geo_query | range_query | phrase_query
                 | fuzzy_term | wildcard_term | simple_term }
geo3d_query    = { geo3d_distance | geo3d_bbox | geo3d_nearest }
geo3d_distance = { ^"geo3d_distance" ~ "(" ~ signed_float ~ "," ~ signed_float
                 ~ "," ~ signed_float ~ "," ~ signed_float ~ ")" }
geo3d_bbox     = { ^"geo3d_bbox" ~ "(" ~ signed_float ~ "," ~ signed_float
                 ~ "," ~ signed_float ~ "," ~ signed_float ~ ","
                 ~ signed_float ~ "," ~ signed_float ~ ")" }
geo3d_nearest  = { ^"geo3d_nearest" ~ "(" ~ signed_float ~ "," ~ signed_float
                 ~ "," ~ signed_float ~ "," ~ unsigned_int ~ ")" }
geo_query      = { geo_distance | geo_bbox }
geo_distance   = { ^"geo_distance" ~ "(" ~ signed_float ~ "," ~ signed_float
                 ~ "," ~ signed_float ~ ")" }
geo_bbox       = { ^"geo_bbox" ~ "(" ~ signed_float ~ "," ~ signed_float
                 ~ "," ~ signed_float ~ "," ~ signed_float ~ ")" }
phrase_query   = { "\"" ~ phrase_content ~ "\"" ~ proximity? ~ boost? }
proximity      = { "~" ~ number }
fuzzy_term     = { term ~ "~" ~ fuzziness? ~ boost? }
wildcard_term  = { wildcard_pattern ~ boost? }
simple_term    = { term ~ boost? }
boost          = { "^" ~ boost_value }

Vector クエリ構文

Vector クエリは、解析時にテキストをベクトルにエンベディングし、類似性検索を実行します。

基本構文

field:"text"
field:text
field:"text"^weight

Vector クエリの例

# Single field (quoted text)
content:"cute kitten"

# Single field (unquoted text)
content:python

# With boost weight
content:"cute kitten"^0.8

# Multiple clauses
content:"cats" image:"dogs"^0.5

# Nested field name (dot notation)
metadata.embedding:"text"

複数句

複数の Vector 句はスペースで区切ります。すべての句が実行され、スコアは score_mode（デフォルト: WeightedSum）を使用して結合されます。

content:"cats" image:"dogs"^0.5

この場合のスコア計算:

score = similarity("cats", content) * 1.0
      + similarity("dogs", image)   * 0.5

Vector DSL には AND/OR 演算子はありません。Vector 検索は本質的にランキング操作であり、ウェイト（^）が各句の寄与度を制御します。

スコアモード

スコアモードは DSL 構文からは設定できません。Rust API を使用してオーバーライドします。

#![allow(unused)]
fn main() {
let mut request = parser.parse(r#"content:"cats" image:"dogs""#).await?;
request.score_mode = VectorScoreMode::MaxSim;
}

Vector PEG 文法

完全な Vector 文法（parser.pest）:

query          = { SOI ~ vector_clause+ ~ EOI }
vector_clause  = { field_prefix ~ (quoted_text | unquoted_text) ~ boost? }
field_prefix   = { field_name ~ ":" }
field_name     = @{ (ASCII_ALPHA | "_") ~ (ASCII_ALPHANUMERIC | "_" | ".")* }
quoted_text    = ${ "\"" ~ inner_text ~ "\"" }
unquoted_text  = @{ (!(WHITE_SPACE | "^" | "\"") ~ ANY)+ }
inner_text     = @{ (!("\"") ~ ANY)* }
boost          = { "^" ~ float_value }
float_value    = @{ ASCII_DIGIT+ ~ ("." ~ ASCII_DIGIT+)? }

統合（ハイブリッド）クエリ構文

UnifiedQueryParser を使用すると、単一のクエリ文字列内で Lexical 句と Vector 句を自由に混在させることができます。

title:hello content:"cute kitten"^0.8

仕組み

1. 分割（Split）: スキーマのフィールド型に基づいて、各句が Lexical か Vector かを判定する。ベクトルフィールドとして定義されたフィールド名を持つ句は Vector 句として抽出される
2. 委譲（Delegate）: Vector 部分は VectorQueryParser に、残りは Lexical の QueryParser に渡される
3. フュージョン（Fuse）: Lexical と Vector の両方の結果が存在する場合、フュージョンアルゴリズムで結合される

曖昧性の解消

Vector 句と Lexical 句の区別は、スキーマのフィールド型に基づいて行われます。フィールド名がスキーマ上でベクトルフィールド（HNSW、Flat、IVF など）として定義されている場合、その句は Vector クエリとして扱われます。Lexical 構文の ~（例: roam~2、"hello world"~10）はファジークエリや近接度クエリとして引き続き正しく解析されます。

フュージョンアルゴリズム

クエリに Lexical 句と Vector 句の両方が含まれる場合、結果はフュージョンされます。

注意: フュージョンアルゴリズムは DSL 構文では指定できません。UnifiedQueryParser の構築時に .with_fusion() で設定します。デフォルトは RRF（k=60）です。コード例はカスタムフュージョンを参照してください。

ハイブリッド AND/OR セマンティクス（+ プレフィックス）

デフォルトでは、ハイブリッドクエリは union（OR） を使用します。Lexical 結果または Vector 結果のいずれかに含まれるドキュメントが返されます。Vector 句に + プレフィックスを付けると intersection（AND） に切り替わり、両方の結果セットに存在するドキュメントのみが返されます。

ルール:

• Vector 句に + プレフィックスがない場合、フュージョンは Lexical と Vector の結果を union（OR） で結合します
• 1 つでも Vector 句に + プレフィックスがある場合、フュージョンは intersection（AND） に切り替わり、Lexical と Vector の両方の結果セットに存在するドキュメントのみが返されます
• Lexical フィールドの +（例: +title:Rust）は、Lexical クエリパーサーによって required clause（必須句）として解釈されます。これは既存の Tantivy/Lucene スタイルの動作であり、それ自体ではハイブリッドフュージョンの intersection モードをトリガーしません

統合クエリの例

# Lexical only — no fusion
title:hello AND body:world

# Vector only — no fusion
content:"cute kitten"

# Vector only — unquoted text
content:python

# Hybrid — fusion applied automatically (OR / union)
title:hello content:"cute kitten"

# Hybrid with AND / intersection — both result sets required
title:hello +content:"cute kitten"

# Hybrid with boolean operators
title:hello AND category:animal content:"cute kitten"^0.8

# Multiple vector clauses + lexical
category:animal content:"cats" image:"dogs"^0.5

コード例

DSL による Lexical 検索

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::analysis::analyzer::standard::StandardAnalyzer;
use laurus::lexical::query::QueryParser;

let analyzer = Arc::new(StandardAnalyzer::new()?);
let parser = QueryParser::new(analyzer)
    .with_default_field("title");

let query = parser.parse("title:hello AND body:world")?;
}

DSL による Vector 検索

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::vector::query::VectorQueryParser;

let parser = VectorQueryParser::new(embedder)
    .with_default_field("content");

let request = parser.parse(r#"content:"cute kitten"^0.8"#).await?;
}

統合 DSL によるハイブリッド検索

#![allow(unused)]
fn main() {
use laurus::engine::query::UnifiedQueryParser;

let unified = UnifiedQueryParser::new(lexical_parser, vector_parser);

let request = unified.parse(
    r#"title:hello content:"cute kitten"^0.8"#
).await?;
// request.query  -> SearchQuery::Hybrid { lexical: ..., vector: ... }
// request.fusion_algorithm  -> Some(RRF)  — fusion algorithm
}

カスタムフュージョン

#![allow(unused)]
fn main() {
use laurus::engine::search::FusionAlgorithm;

let unified = UnifiedQueryParser::new(lexical_parser, vector_parser)
    .with_fusion(FusionAlgorithm::WeightedSum {
        lexical_weight: 0.3,
        vector_weight: 0.7,
    });
}

BKD-Tree

Laurus は数値・日時・地理ポイントなどのデータを BKD-Tree (Block KD-Tree) に格納する。BKD-Tree はディスク常駐の多次元インデックスで、レンジ・バウンディング ボックス・距離・k 近傍 (k-NN) の各クエリを単一のファイル形式で扱える。

「空間的な形」を持つあらゆるフィールド型はこの BKD プリミティブを共有する：

新しい空間フィールド型を追加する作業は、次元数を選んでクエリ側の IntersectVisitor を書くだけに帰着する。 ライタ・リーダ・オンディスクレイアウトはそのまま再利用される。

ファイルフォーマット (Version 4)

.bkd セグメントファイルは自己完結型のバイナリで、3 つの領域と、その後ろのチェックサム footer から成る：

+----------------------------------------+
| File Header                            |   固定長・バージョンタグ付き
+----------------------------------------+
| Leaf Blocks                            |   bit-packed points + doc_ids
|   leaf 0                               |
|   leaf 1                               |
|   ...                                  |
+----------------------------------------+
| Index Nodes                            |   内部ナビゲーションノード
|   node N-1                             |
|   ...                                  |
|   node 0  (root, written last)         |
+----------------------------------------+
| Footer                                 |   上記すべての CRC-32
|                                        |   + マジック "LCRC"（8 バイト）
+----------------------------------------+

ヘッダはリーフと索引の書き込み位置を記録するので、writer はヘッダの領域を先に確保し、後ろをすべて書いてから最後にヘッダを埋める。それでも footer の CRC は、ファイル上の並び順のバイト列を覆う（Issue #1214）。footer 導入前に書かれたファイルは、代わりに 4 バイトの trailer で終わる。

ヘッダ (BKDFileHeader) は magic、version（現在は 4）、num_dims、 bytes_per_dim、総ポイント数、リーフブロック数、block_size （writerが設定したリーフあたりの最大ポイント数。読み込み時にリーフの count を検証する上限として使う、Issue #1142）、全体の軸ごと min/max、インデックス領域とルートノードへのオフセットを保持する。

Leaf Block レイアウト

各リーフブロックは、その部分木に属するポイントを bit-pack して格納する （Issue #549、以前は生の f64/u64 だった）。Issue #1142以降は、 再帰的な構築が残す空間分割順ではなくdoc_id昇順で格納される：

count               u32               — リーフ内のポイント数
leaf_min            [f64; num_dims]   — リーフレベルの AABB 下端
leaf_max            [f64; num_dims]   — リーフレベルの AABB 上端
doc_id_base         u64               — リーフ内の doc_id の最小値
doc_id_bits         u8                — 連続するdoc_id差分の最大値のbit幅
packed_dim[0]       バイト整列        — `sortable(point) - sortable(leaf_min[d])` をbit-pack
packed_dim[1..]     ...               — 次元ごとに1セクション
packed_doc_ids      バイト整列        — 連続差分をbit-pack（後述）

各次元のbit幅は、leaf_min[d]/leaf_max[d] を（f64::total_cmp と同じ IEEE 754 の全順序を保つ）u64 に写像した値から導出され、ディスクには 保存しない。書き込み側と読み込み側が同じ式で計算するため、両者がずれる 心配がない。リーフ全体で定数の次元は幅0bitに導出され、1バイトも消費しない。

packed_doc_ids はdoc_id_baseからの独立差分ではなく連続差分を 格納する: 値iはdoc_id[i-1] + delta（doc_id[-1] := doc_id_base） であり、先頭のdeltaは常に0になる（読み込み側は先頭deltaが非ゼロの 場合を破損として拒否する）。したがってdoc_id_bitsは bits_needed(max-min)ではなくbits_needed(連続差分の最大値)となり、 連続差分の合計は常にリーフのmax-minと等しくなる（テレスコーピング和） ため理論上これより大きくなることはなく、doc_idがリーフの全範囲に 均等に広がっているのではなく局所的に密集している場合に大幅に小さく なりうる。doc_id_bitsだけは唯一ディスクに保存される幅で（doc_id側 には導出元となる「最大値」ヘッダフィールドが無いため）、読み込み時に 64 を超える値は破損として拒否する。doc_idによるソートは安定 ソートであり、同一doc_idを持つ複数の点（多値の数値・日時・地理フィールド）は元の 相対順序を保つ — これはGeoBoxPointsVisitorの「最初に見つかった点が 勝つ」という重複排除方式が依存している性質である。

削減率はデータの相関度に依存する。旧v2形式（生のリーフフォーマット）に 対する比率は、一様乱数の1次元/2次元/3次元データでおよそ2.16倍/1.67倍/ 1.50倍、単調増加するフィールド（タイムスタンプや自動採番カウンタなど） では2.66倍程度 — v3（Issue #1142以前）の1.96倍/1.59倍/1.45倍/2.28倍 から改善している。これは、連続差分によるdoc_id符号化が、単一アンカー からの独立差分では捉えられなかった局所的なdoc_idの密集を活用できる ためである。これは量子化ではなく可逆な差分符号化方式であり、±0.0 や ±Infinity を含め全てのポイントがビット完全に往復する。

リーフごとに AABB を持たせることで、クエリ領域がリーフの外側にある場合 (Outside) や全内包される場合 (Inside) には、ポイントを1つもデコードせずに リーフ全体を判定できる。Inside の場合はpacked pointセクションを1回の シークでスキップし、doc_ids のみをデコードする。

内部 Index Node レイアウト

内部ノードは分割情報に加え、子ごとの AABB も保持する：

split_dim           u32                       — 分割する軸
split_value         f64                       — 分割しきい値
left_min            [f64; num_dims]           — 左部分木の AABB 下端
left_max            [f64; num_dims]           — 左部分木の AABB 上端
right_min           [f64; num_dims]           — 右部分木の AABB 下端
right_max           [f64; num_dims]           — 右部分木の AABB 上端
left_offset         u64                       — 左子ノードのファイルオフセット
right_offset        u64                       — 右子ノードのファイルオフセット

ノードごとの AABB（v2 で追加）は、分割値だけを持っていた v1 レイアウトを 置き換える。これにより Inside / Outside の枝刈りが、再帰的な 探索ではなく定数時間の矩形判定で済むようになった。

ビルドアルゴリズム

BKDWriter::write は、平坦な row-major のポイントバッファと並列の doc_ids バッファからツリーを構築する。構築は 最も広い軸で分割する (widest-axis split) ヒューリスティクスで進む：

1. 入力部分集合の AABB を計算する。
2. (max - min) レンジが最も広い軸を選ぶ（同点時は次元番号の小さい方を 採用して決定的にする）。
3. インデックスの並びをその軸でソートし、中央値で分割する。
4. 部分木が block_size（既定 512）以下のポイント数になるまで再帰し、 そうなったらリーフとして書き出す。
5. 子が flush された後、各親の left_offset / right_offset を後埋めする。

ビルダはポイント／doc_id バッファ自体ではなくインデックスの並び （permutation）をソートするため、ポイント数に関わらずポイント単位の ヒープ確保を一切おこなわない。

数値ロバスト性

座標は全順序で比較できる必要がある。BKDWriter::write は NaN を明示的に 拒否する。NaN には順序が定義されておらず、分割判定とノードごとの AABB 不変条件を破壊するためである。±INFINITY は両方とも受理され、クエリでは 「無限大」を表す自然なセンチネルとして機能する。

IntersectVisitor プロトコル

BKD インデックスへのクエリは IntersectVisitor の実装として表現する。リーダはツリーを辿りながら、ビジタに 3 種類の 情報を尋ねる：

#![allow(unused)]
fn main() {
pub enum CellRelation {
    Inside,   // 部分木全体がヒット — ポイント単位の照合不要
    Outside,  // 部分木全体をスキップできる
    Crosses,  // 再帰、もしくはリーフをポイント単位で照合
}

pub trait IntersectVisitor {
    fn compare(&self, cell: &AABB) -> CellRelation;
    fn visit_inside(&mut self, doc_id: u64);
    fn visit(&mut self, doc_id: u64, point: &[f64]);
}
}

リーダのトラバーサルは次のように進む：

graph TD
    A["compare(node.aabb)"]
    A -->|Inside| B["部分木の各 doc_id を visit_inside(doc_id) で報告<br/>（座標は読まない）"]
    A -->|Outside| C["部分木をスキップ"]
    A -->|Crosses, 内部ノード| D["子ノードへ再帰"]
    A -->|Crosses, リーフ| E["各ポイントについて visit(doc_id, point)<br/>ヒット判定はビジタに委ねる"]

この 3 値分類こそが枝刈りを実現する鍵である。常に Crosses を返すビジタを 書いても結果は正しい — 単にリーフ全件走査に退化するだけだ。

レンジクエリ

レガシーの BKDTree::range_search API は intersect の薄いラッパに なっている。RangeQueryVisitor を半開区間／閉区間のパラメータから組み立て、 無限大の None スロットを ±INFINITY に変換する。境界の包含・排他は ビジタ自身が処理する。

3D 地理クエリ

3 つのビジタが laurus::lexical::query::geo3d に存在し、 Geo3d (3D ECEF) フィールドをターゲットにする：

同じプリミティブで将来のあらゆる空間クエリ（ポリゴンクエリや 2D Geo の大円距離クエリなど）を新しいビジタとして実装できる。

リーダの内部実装

BKDReader::intersect は 1 クエリにつき 1 つのスクラッチバッファ (IntersectScratch) を使う。バッファは出会った最大のリーフサイズまで 拡大されたあと、後続のリーフでも再利用される。結果として、何枚のリーフを 辿っても、1 クエリの間にアロケータに触れる回数はごく少数で済む。

単一リーフだけのツリー（非常に小さなフィールド）は特別扱いされる： 「ルートオフセット」がそのまま唯一のリーフを指すため、内部ノードの 降下処理は完全にスキップされる。

関連項目

• 3D 地理検索 (ECEF) — ECEF 距離・バウンディング ボックス・k-NN を実装した具体的な BKD ベースのビジタ。
• Lexical インデクシング — .bkd セグメントファイルがセグメント全体のレイアウト内のどこに位置するか。
• Lexical 検索 — NumericRangeQuery、 GeoDistanceQuery / GeoBoundingBoxQuery、Geo3dDistanceQuery の Rust API エントリポイント。

3D 地理検索 (ECEF)

Laurus は用途の異なる 2 種類の地理フィールド型を提供する：

両者は同じ BKD-Tree プリミティブを共有しており、Geo3d は単に第 3 の次元と異なるクエリ語彙を加えただけである。

なぜ ECEF なのか

(緯度, 経度, 高度) の組は人間にとっては便利だが、ユークリッド距離が そのままでは使えない：経度 1 度は赤道で約 111 km だが極では 0 km、 そして「高度」は地球表面に沿って曲がっている。

ECEF (Earth-Centered Earth-Fixed) はこれを直交座標系にフラット化する：

• 原点は地球の質量中心。
• +X 軸は赤道上の経度 0° を貫く。
• +Y 軸は赤道上の経度 90° E を貫く。
• +Z 軸は地理北極を貫く。
• 3 軸とも単位はメートル。

この座標系では 2 点間の直線距離が単なるユークリッドノルムになる — 球面三角法も極特異点も経度のラップアラウンドも要らない。これこそが、 Geo3d クエリを 3D BKD-Tree 上で（特殊な空間コードなしで）使える 理由である。

Geo3d フィールドの定義

#![allow(unused)]
fn main() {
use laurus::Schema;
use laurus::lexical::core::field::Geo3dOption;

let schema = Schema::builder()
    .add_geo3d_field("position", Geo3dOption::default())
    .build();
}

Geo3dOption は他の lexical フィールドオプションと同じく indexed / stored を提供する。インデックス済みの値はフィールドの 3D BKD-Tree に格納され、stored な値は get_documents で返ってくる。

TOML 形式（laurus-cli で使用）：

[fields.position.Geo3d]
indexed = true
stored = true

3D ポイントのインデクシング

DocumentBuilder::add_geo_ecef を使って、メートル単位の生の直交座標で ポイントを追加する：

#![allow(unused)]
fn main() {
use laurus::Document;

// (lat=35.6586°, lon=139.7454°, height=250m) のポイント
// 既に ECEF へ変換済み（後述「座標変換」参照）。
let doc = Document::builder()
    .add_geo_ecef("position", -3_955_182.0, 3_350_553.0, 3_700_276.0)
    .build();

engine.put_document("tokyo-tower", doc).await?;
engine.commit().await?;
}

値が既に GeoEcefPoint として手元にある場合は、統一 DataValue API を 使う：

#![allow(unused)]
fn main() {
use laurus::{DataValue, GeoEcefPoint};

let p = GeoEcefPoint::new(-3_955_182.0, 3_350_553.0, 3_700_276.0);
let doc = Document::builder()
    .add_field("position", DataValue::GeoEcef(p))
    .build();
}

座標変換 (WGS84 ↔ ECEF)

入力は通常 (緯度°, 経度°, 高度 m) でやって来る。Laurus は laurus::util::ecef で標準的な相互変換を提供する：

#![allow(unused)]
fn main() {
use laurus::util::ecef::{wgs84_to_ecef, ecef_to_wgs84};

// 順変換: lat/lon/height → ECEF
let p = wgs84_to_ecef(35.6586, 139.7454, 250.0);

// 逆変換: ECEF → lat/lon/height
let (lat, lon, height) = ecef_to_wgs84(&p);
}

逆変換は地表下から LEO 軌道高度をはるかに超える領域まで、各軸で サブ µm の精度で往復する。極付近では、cos(lat) → 0 で発散する 標準形 h = p / cos(lat) - N の代わりに、子午線形 h = z / sin(lat) - N(1 - e²) に切り替える。

内部で使う WGS84 楕円体定数は pub const として公開されている （WGS84_A, WGS84_F, WGS84_B, WGS84_E2, WGS84_E_PRIME_SQ）ので、 外部コードからも laurus が使っているのと同じ値を参照できる。

クエリ種別

Geo3d フィールドを対象とするクエリは 3 種類ある。いずれも 3D BKD-Tree を共有する IntersectVisitor の実装である。

球（半径） — Geo3dDistanceQuery

中心点から distance_m メートル以内に格納済みポイントが入っているドキュメントを すべて返す。スコアは 1 - distance / radius を [0, 1] にクランプした 値。

#![allow(unused)]
fn main() {
use laurus::lexical::query::geo3d::Geo3dDistanceQuery;
use laurus::GeoEcefPoint;

let centre = GeoEcefPoint::new(-3_955_182.0, 3_350_553.0, 3_700_276.0);
let query = Geo3dDistanceQuery::new("position", centre, 5_000.0); // 5 km 半径
}

ビジタは Outside 判定に AABB::min_distance_sq_to_point、 Inside 判定に AABB::max_distance_sq_to_point を使う。どちらも 2 乗距離空間で比較するため、sqrt を回避できる。

バウンディングボックス — Geo3dBoundingBoxQuery

(min_x, min_y, min_z) と (max_x, max_y, max_z) で定義された軸並行 3D ボックスにポイントが入っているドキュメントを返す。

#![allow(unused)]
fn main() {
use laurus::lexical::query::geo3d::Geo3dBoundingBoxQuery;
use laurus::GeoEcefPoint;

let min = GeoEcefPoint::new(-4_000_000.0, 3_300_000.0, 3_650_000.0);
let max = GeoEcefPoint::new(-3_900_000.0, 3_400_000.0, 3_750_000.0);
let query = Geo3dBoundingBoxQuery::new("position", min, max)?;
}

コンストラクタが Result を返すのは、すべての軸で min[i] ≤ max[i] を 満たす必要があるため。境界がおかしい場合は構築時点で拒否され、 「黙って空結果」を防げる。

注意点。 クエリボックスは ECEF 直交座標で軸並行になっている。 (lat, lon, height) の 2 つの隅をそれぞれ ECEF に変換して作った ボックスは、ユーザーが直感的に思い描く球殻領域とは違う形をしている。 地表上の領域クエリを書くなら、Geo3dDistanceQuery（真の 3D 球）の方が 多くの場合ユーザー直感に近い。

k 近傍 — Geo3dNearestQuery

クエリ点に最も近い k 件のドキュメントを返す。クエリは小さなプローブ球 （既定 1 km）から始め、以下のいずれかを満たすまで半径を倍加していく：

1. 重複なしで k 件以上の候補を集めた、
2. 倍加しても何も新しいヒットが見つからなくなった、
3. 半径が max_radius_m（既定 1.0e10 m＝10⁷ km）に達した。

#![allow(unused)]
fn main() {
use laurus::lexical::query::geo3d::Geo3dNearestQuery;
use laurus::GeoEcefPoint;

let centre = GeoEcefPoint::new(-3_955_182.0, 3_350_553.0, 3_700_276.0);
let query = Geo3dNearestQuery::new("position", centre, 10) // 上位 10 件
    .with_initial_radius(500.0)         // 500 m から開始
    .with_max_radius(1_000_000.0);      // 1 000 km で打ち切り
}

結果が k 件未満になるのは、単に max_radius_m 以内に k 件のポイントが 存在しないことを意味する。スコアは「最も近いヒットが 1.0、返却された 集合内で最も遠いヒットが 0.0」となるよう正規化される。

k-NN ビジタは compare から CellRelation::Inside を返さない — Outside か Crosses のみ — ので、すべての候補がその座標と一緒に visit へ届けられ、k-NN の順序付けに真の距離を使える。

Query DSL

Geo3d クエリは統一 Query DSL からも使える（Query DSL → Geo3d 関数 を参照）：

position:geo3d_distance(-3955182, 3350553, 3700276, 5000)
position:geo3d_bbox(-4000000, 3300000, 3650000, -3900000, 3400000, 3750000)
position:geo3d_nearest(-3955182, 3350553, 3700276, 10)

数値引数はすべて符号付き浮動小数。geo3d_nearest の k のみ符号なし整数。

ワイヤーフォーマット

gRPC

Protocol Buffers では、3D 地理を専用の Value バリアント、Geo3dPoint メッセージ、Geo3dOption スキーマオプションとして公開している：

message Geo3dPoint {
  double x = 1;
  double y = 2;
  double z = 3;
}

message Value {
  oneof kind {
    // ...
    Geo3dPoint geo3d_value = 12;
  }
}

message Geo3dOption {
  bool indexed = 1;
  bool stored = 2;
}

完全な定義は common.proto と index.proto を参照。

HTTP gateway / MCP

JSON ドキュメントでは Geo3d 値を { "x": …, "y": …, "z": … } の オブジェクトとして受け付ける：

{
  "position": { "x": -3955182.0, "y": 3350553.0, "z": 3700276.0 }
}

HTTP gateway はこれをエンジンへ転送する前に DataValue::GeoEcef に変換する。 MCP サーバーも同じ規約に従う。

Geo3d を使うべきでないケース

• 純粋な 2D 地図クエリ（地表上の座標からの半径検索、タイル地図上の 単純なバウンディングボックスなど） — 引き続き Geo を使うこと。 2D BKD はひとつ次元が軽く、WGS84 入力もユーザー直感に近い。
• 学習済みロケーション埋め込みの近似的な意味類似度 — それはベクトル フィールド（Hnsw, Flat, Ivf）の領分であって、Geo3d ではない。

関連項目

• BKD-Tree — Integer, Float, DateTime, 2D Geo も含めて支える、共通の多次元インデックス。
• スキーマとフィールド — Geo3d を含む フィールド型の一覧。
• Query DSL — geo3d DSL 文法の詳細。
• Lexical 検索 — Lexical クエリ全般の Rust API エントリポイント。
• laurus-wasm/examples/geo3d/ — ブラウザ向けデモ。CesiumJS の 3D 地球儀上に人工衛星のライブ位置を プロットし、geo3d_bbox と geo3d_nearest を実演します。

ライブラリ概要

laurus クレートは検索エンジンのコアライブラリです。Lexical検索（転置インデックス（Inverted Index）によるキーワードマッチング）、Vector検索（Embeddingによるセマンティック類似度検索）、およびハイブリッド検索（両者の組み合わせ）を統一的なAPIで提供します。

モジュール構成

graph TB
    LIB["laurus (lib.rs)"]

    LIB --> engine["engine\nEngine, EngineBuilder\nSearchRequest, FusionAlgorithm"]
    LIB --> analysis["analysis\nAnalyzer, Tokenizer\nToken Filters, Char Filters"]
    LIB --> lexical["lexical\nInverted Index, BM25\nQuery Types, Faceting, Highlighting"]
    LIB --> vector["vector\nFlat, HNSW, IVF\nDistance Metrics, Quantization"]
    LIB --> embedding["embedding\nCandle BERT, OpenAI\nCLIP, Precomputed"]
    LIB --> storage["storage\nMemory, File, Mmap\nColumnStorage"]
    LIB --> store["store\nDocumentLog (WAL)"]
    LIB --> spelling["spelling\nSpelling Correction\nSuggestion Engine"]
    LIB --> util["util\n共通ヘルパとマクロ"]
    LIB --> data["data\nDataValue, Document"]
    LIB --> error["error\nLaurusError, Result"]

主要な型

Feature Flag

laurus クレートはデフォルトではFeatureが有効化されていません。必要に応じてEmbeddingサポートを有効にしてください。

# Lexical検索のみ（Embeddingなし）
[dependencies]
laurus = "0.12"

# ローカルBERT Embeddingを使用
[dependencies]
laurus = { version = "0.12", features = ["embeddings-candle"] }

# すべてのFeatureを有効化
[dependencies]
laurus = { version = "0.12", features = ["embeddings-all"] }

セクション

• Engine – EngineとEngineBuilderの内部構造
• スコアリングとランキング – BM25、TF-IDF、およびベクトル類似度スコアリング
• ファセット – 階層的なファセット検索
• ハイライト – 検索結果のハイライト表示
• スペル修正 – スペル候補の提案と自動修正
• ID管理 – 二層構造のドキュメントID管理
• 永続化とWAL – Write-Ahead Loggingとデータの耐久性
• 削除とコンパクション – 論理削除と領域の再利用
• エラーハンドリング – LaurusErrorとResult型
• 拡張性 – カスタムAnalyzer、Embedder、Storageバックエンド
• APIリファレンス – 主要な型とメソッドの一覧

Engine

Engine はLaurusの中心的な型です。Lexicalインデックス、Vectorインデックス、およびドキュメントログを単一の非同期APIで統合します。

Engine構造体

#![allow(unused)]
fn main() {
pub struct Engine {
    schema: Schema,
    lexical: LexicalStore,
    vector: VectorStore,
    log: Arc<DocumentLog>,
}
}

EngineBuilder

EngineBuilder を使用してEngineを設定・構築します。

#![allow(unused)]
fn main() {
use std::sync::Arc;
use laurus::{Engine, Schema};
use laurus::lexical::TextOption;
use laurus::storage::memory::MemoryStorage;

let storage = Arc::new(MemoryStorage::new(Default::default()));
let schema = Schema::builder()
    .add_text_field("title", TextOption::default())
    .add_text_field("body", TextOption::default())
    .add_default_field("body")
    .build();

let engine = Engine::builder(storage, schema)
    .analyzer(my_analyzer)            // オプション: カスタムテキストAnalyzer
    .embedder(my_embedder)            // オプション: ベクトルEmbedder
    .embedding_cache_capacity(1024)   // オプション: クエリEmbeddingをキャッシュ
    .build()
    .await?;
}

Builderメソッド

クエリEmbeddingキャッシュ

embedding_cache_capacity(n) は クエリ時 のEmbeddingに対するLRU キャッシュを有効化します（ドキュメント取り込み時のEmbeddingは対象外）。 Vector / hybrid 検索でクエリペイロードをEmbeddingする際、結果を (field, embedder 名, payload ハッシュ) をキーにキャッシュし、以降の同一 クエリで再利用します。DSL パス（例: content:"cute kitten"）と事前 Embedding 済みの Payloads パスは同じキャッシュを共有します。

これにより、繰り返しクエリのワークロード（オートコンプリート、ダッシュ ボード更新、A/B 評価など）で、ローカル Embedder のモデル推論やリモート Embedder のネットワークラウンドトリップを回避できます。デフォルトでは 無効です。識別可能なクエリの working set に応じてメモリを抑える容量を 指定してください。

1 つのクエリ内では、その全 payload を 1 回の Embedder::embed_batch 呼び出しでEmbedding します（キャッシュミスのみ、PerFieldEmbedder では field ごとにグルーピング）。これにより、バッチ対応 Embedder ではマルチ ベクトルクエリでも payload ごとではなく 1 往復で済みます（Issue #671）。

late interaction による再採点のテキストのクエリから作ったトークンベクトルも、 同じ容量の別の LRU にキャッシュします。キーはフィールド、フィールドの Embedder、役割（クエリか文書か）、クエリのテキストです。別にしているのは、 大きなトークンのエントリが 1 本のベクトルのエントリを追い出さないためです （Issue #1349）。ベクトルフィールドを追加・削除・作り直すと、フィールド名の 裏の Embedder が変わりうるため、両方のキャッシュを空にします。

Buildライフサイクル

build() が呼び出されると、以下の処理が実行されます。

sequenceDiagram
    participant User
    participant EngineBuilder
    participant Engine

    User->>EngineBuilder: .build().await
    EngineBuilder->>EngineBuilder: split_schema()
    Note over EngineBuilder: Separate fields into<br/>LexicalIndexConfig<br/>+ VectorIndexConfig
    EngineBuilder->>Engine: Create PrefixedStorage (lexical/, vector/, documents/)
    EngineBuilder->>Engine: Create LexicalStore
    EngineBuilder->>Engine: Create VectorStore
    EngineBuilder->>Engine: Create DocumentLog
    EngineBuilder->>Engine: Recover from WAL
    EngineBuilder-->>User: Engine ready

1. スキーマの分割 – Lexicalフィールド（Text、Integer、Floatなど）は LexicalIndexConfig に、Vectorフィールド（HNSW、Flat、IVF）は VectorIndexConfig に分割されます
2. プレフィックス付きストレージの作成 – 各コンポーネントに独立した名前空間が割り当てられます（lexical/、vector/、documents/）
3. ストアの初期化 – LexicalStore と VectorStore がそれぞれの設定で作成されます
4. WALからのリカバリ – 前回のセッションでコミットされなかった操作がリプレイされます

スキーマの分割

Schemaにはlexicalフィールドとvectorフィールドの両方が含まれています。ビルド時に split_schema() がこれらを分離します。

graph LR
    S["Schema<br/>title: Text<br/>body: Text<br/>page: Integer<br/>content_vec: HNSW"]

    S --> LC["LexicalIndexConfig<br/>title: TextOption<br/>body: TextOption<br/>page: IntegerOption<br/>_id: KeywordAnalyzer"]

    S --> VC["VectorIndexConfig<br/>content_vec: HnswOption<br/>(dim=384, m=16, ef=200)"]

予約フィールド _id は、完全一致検索のために KeywordAnalyzer を用いて常にLexical設定に追加されます。

フィールドごとのディスパッチ

PerFieldAnalyzer

PerFieldAnalyzer が指定された場合、テキスト解析はフィールドごとのAnalyzerにディスパッチされます。

graph LR
    PFA["PerFieldAnalyzer"]
    PFA -->|"title"| KA["KeywordAnalyzer"]
    PFA -->|"body"| SA["StandardAnalyzer"]
    PFA -->|"description"| JA["JapaneseAnalyzer"]
    PFA -->|"_id"| KA2["KeywordAnalyzer<br/>(always)"]
    PFA -->|other fields| DEF["Default Analyzer"]

PerFieldEmbedder

同様に、PerFieldEmbedder はフィールドごとのEmbedderにEmbedding処理をルーティングします。

graph LR
    PFE["PerFieldEmbedder"]
    PFE -->|"text_vec"| BERT["CandleBertEmbedder<br/>(384 dim)"]
    PFE -->|"image_vec"| CLIP["CandleClipEmbedder<br/>(512 dim)"]
    PFE -->|other fields| DEF["Default Embedder"]

Engineメソッド

ドキュメント操作

検索

search() メソッドは SearchRequest を受け取ります。SearchRequestにはLexicalクエリ、Vectorクエリ、またはその両方を含めることができます。両方が指定された場合、結果は指定された FusionAlgorithm で統合されます。

#![allow(unused)]
fn main() {
use laurus::{SearchRequestBuilder, FusionAlgorithm};
use laurus::lexical::TermQuery;
use laurus::lexical::search::searcher::LexicalSearchQuery;

// Lexicalのみの検索
let request = SearchRequestBuilder::new()
    .lexical_query(LexicalSearchQuery::Obj(Box::new(TermQuery::new("body", "rust"))))
    .limit(10)
    .build();

// RRFフュージョンによるハイブリッド検索
let request = SearchRequestBuilder::new()
    .lexical_query(lexical_query)
    .vector_query(vector_query)
    .fusion_algorithm(FusionAlgorithm::RRF { k: 60.0 })
    .limit(10)
    .build();

let results = engine.search(request).await?;
}

ウォームアップ

engine.warmup()（Issue #677）は Vector searcher を事前に準備し、初回の Vector / ハイブリッドクエリが one-time のセットアップコストを払わないようにします。 Engine 構築後、トラフィック処理を始める前に一度呼び出します:

let engine = builder.build()?;
engine.warmup()?;   // オプション: 初回クエリの latency を起動時に移す

Vector searcher を先行構築・キャッシュし（reader をロード — InMemory は ファイル→メモリ、Mmap はオフセット表）、HNSW の Mmap モードではディスク上の Vector データを OS page cache に pre-fault します。HNSW グラフは常に eager に ロードされるため、warming が必要なのは Vector データのみです。warmup() は 複数回呼んでも安全で、lexical のみのワークロードでは no-op です。

SearchRequest

LexicalSearchOptions

FusionAlgorithm

関連項目: アーキテクチャ – 高レベルのデータフロー図

スコアリングとランキング

Laurus は Lexical 検索に BM25、Vector 検索に距離ベースの類似度、そしてハイブリッド検索ではこの 2 つを統合する設定可能なフュージョンアルゴリズムを使用します。本ページでは各スコアリング経路と、公開 API から介入する方法を説明します。

Lexical スコアリング

BM25（デフォルト）

BM25 は Lexical 検索のスコアリング関数です。単語頻度（term frequency）とドキュメント長正規化のバランスを取ります。

score = IDF * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (doc_len / avg_doc_len)))

各パラメータ:

• tf — ドキュメント内の単語頻度。
• IDF — 逆文書頻度（全ドキュメントに対する単語の希少度）。
• k1 — 単語頻度の飽和パラメータ。Laurus は 1.2 を使用。
• b — ドキュメント長正規化の係数。Laurus は 0.75 を使用。
• doc_len / avg_doc_len — ドキュメント長と平均ドキュメント長の比率。doc_len はトークン数ではなく position の数です —— アナライザーが別のトークンにスタックする同義語（position_increment = 0）はそのトークンの position を共有し、長さに加算されません。Lucene の discountOverlaps と同じ挙動です。

(k1, b) の値は現在実装デフォルトに固定です。Lucene / Elasticsearch のデフォルトと同じため、BM25 スコアはチューニングの直感に関してそれらのエンジンと直接比較できます。

クオート済み・未クオートを問わず、アナライザーが 1 つの位置に複数の代替語（同義語）を積む値は、独立したタームのスコアを合算するのではなく、1 つのブレンドされたタームとしてスコア付けされます。そのため、すべての代替語を含んでいるからといって文書のスコアが不当に高くなることはありません。詳細は同義語を使った検索を参照してください。

フィールドブースト

フィールドごとのスコア乗数は専用のスコアリング構造体ではなく、検索リクエスト上で設定します。

#![allow(unused)]
fn main() {
use laurus::SearchRequestBuilder;

let request = SearchRequestBuilder::new()
    .query_dsl("rust programming")
    .add_field_boost("title", 2.0) // title のマッチはスコア 2 倍
    .add_field_boost("body", 1.0)  // body のマッチはスコア 1 倍（デフォルト）
    .limit(10)
    .build();
}

ブーストはそのフィールドにマッチした BM25 スコア寄与に乗算されます。1.0 は無効化と同じです。クエリで指定されたフィールド（またはスキーマの既定検索フィールド）にのみ適用されます。例外は CombinedFields のマルチフィールドクエリで、ブーストはスコアの乗数ではなく、BM25F の内側の重みになります。

gRPC / HTTP 経由では同じ設定が SearchRequest.field_boosts（map<string, float>）として公開されます。gRPC API → SearchRequest を参照してください。

マルチフィールドクエリ

MultiFieldQuery は、1 つのターム（TermQuery と同じく解析しない）を複数のフィールドから検索します。フィールドごとにブーストを指定できます。フィールドの組み合わせ方は MultiFieldQueryType で決まります。

BestFields と MostFields は、各フィールドをそのフィールド自身の統計でスコア付けします。あるフィールドで珍しいタームはそのフィールドで IDF が高くなるため、同じテキストでも、どのフィールドに入ったかでスコアが変わります。CombinedFields は統計をブレンドし、各ドキュメントを次の値の BM25 で 1 回だけスコア付けします。

tf          = Σ w_f · tf_f                     （各フィールドでのドキュメントの単語頻度）
doc_len     = Σ w_f · len_f                    （タームを含むかどうかに関係なく、すべてのフィールド）
avg_doc_len = Σ w_f · avg_len_f · doc_count_f / max(doc_count_f)
df          = max(df_f)                        （IDF 用）

w_f はフィールドのブーストです。BM25F の内側の重みとして働き、2.0 は、フィールドのスコアを 2 倍にするのではなく、そのフィールドのテキストを 2 回索引したものとして数えます。ブーストは有限で 0.0 より大きい値でなければならず、それ以外の値では検索が InvalidArgument を返します。Lucene と Elasticsearch は 1.0 未満のブーストを拒否しますが、Laurus は受け付けます。

TermQuery と同じく、文書頻度はインデックス全体の値を使います。一方、複数セグメントのインデックスでは、平均長は各セグメント自身の値を使います。

#![allow(unused)]
fn main() {
use laurus::lexical::query::advanced_query::{MultiFieldQuery, MultiFieldQueryType};

let query = MultiFieldQuery::new("smith".to_string())
    .add_field("first_name".to_string(), 1.0)
    .add_field("last_name".to_string(), 1.0)
    .query_type(MultiFieldQueryType::CombinedFields);
}

Vector スコアリング

Vector 検索は距離ベースの類似度で結果をランク付けします。距離メトリックはベクトルインデックス（HNSW / Flat / IVF）のフィールドごとに設定します。

距離は類似度スコア（「高いほど良い」）に変換され、Lexical 結果と Vector 結果のいずれにおいてもこの規約が保たれます。下記のフュージョンアルゴリズムはこの前提に依存します。

ハイブリッド検索フュージョン

検索リクエストが Lexical 句と Vector 句の両方を持つ場合、2 つの結果リストをマージする必要があります。Laurus は FusionAlgorithm で 2 種類のフュージョンアルゴリズムを公開しています。

RRF（Reciprocal Rank Fusion）

RRF は生のスコアではなくランクを統合することでスコア正規化を完全に回避します。

rrf_score(doc) = Σ 1 / (k + rank_i(doc))

合計はドキュメントが含まれる各結果リストにわたって取ります。k パラメータ（デフォルト 60.0）は分布を平滑化します — 値が大きいほど上位ランクの結果の貢献が薄まります。

#![allow(unused)]
fn main() {
use laurus::{FusionAlgorithm, SearchRequestBuilder};

let request = SearchRequestBuilder::new()
    .query_dsl("title:rust ~\"systems programming\"")
    .fusion_algorithm(FusionAlgorithm::Rrf { k: 60.0 })
    .build();
}

WeightedSum

WeightedSum は各リストのスコアを個別に min-max 正規化したうえで、重み付き線形結合を取ります。

norm(score)  = (score - min) / (max - min)
final(doc)   = lexical_weight * norm(lexical_score(doc))
             + vector_weight  * norm(vector_score(doc))

#![allow(unused)]
fn main() {
use laurus::{FusionAlgorithm, SearchRequestBuilder};

let request = SearchRequestBuilder::new()
    .query_dsl("title:rust ~\"systems programming\"")
    .fusion_algorithm(FusionAlgorithm::WeightedSum {
        lexical_weight: 0.6,
        vector_weight: 0.4,
    })
    .build();
}

両方の重みは [0.0, 1.0] にクランプされます。特定の重みを設定する理由がない場合は RRF を選んでください — パラメータが少なく、リスト間のスケール差にも頑健です。

関連項目

• API リファレンス → FusionAlgorithm — バリアントのシグネチャ
• ハイブリッド検索 — どのフュージョンを選ぶかの目安
• Vector 検索 — 距離メトリックのトレードオフ

ファセット

ファセット（Faceting）は、フィールド値によって検索結果をカウント・分類する機能です。検索UIでナビゲーションフィルタを構築するために一般的に使用されます（例: 「エレクトロニクス (42)」「書籍 (18)」）。

概念

FacetPath

FacetPath は階層的なファセット値を表します。例えば、商品カテゴリ「Electronics > Computers > Laptops」は3階層のFacetPathです。

#![allow(unused)]
fn main() {
use laurus::lexical::search::features::facet::FacetPath;

// 単一レベルのファセット
let facet = FacetPath::from_value("category".into(), "Electronics".into());

// コンポーネントからの階層的ファセット
let facet = FacetPath::new("category".into(), vec![
    "Electronics".to_string(),
    "Computers".to_string(),
    "Laptops".to_string(),
]);

// 区切り文字付き文字列から
let facet = FacetPath::from_delimited("category".into(), "Electronics/Computers/Laptops", "/");
}

from_delimited はコレクターと同じく空の成分を捨てます。そのため "/Electronics//Computers" は ["Electronics", "Computers"] になります。

FacetPathメソッド

FacetCount

FacetCount はファセット集計の結果を表します。

#![allow(unused)]
fn main() {
pub struct FacetCount {
    pub path: FacetPath,
    pub count: u64,
    pub children: Vec<FacetCount>,
}
}

FacetConfig

FacetConfig は、コレクターが何を数えて何を返すかを指定します。

集計したドキュメントのどれも持たない値は返らないため、min_count の 0 は 1 と同じ動作になります。

ファセットの集計

一致した各ドキュメントを FacetCollector に渡し、最後に finalize を呼びます。

#![allow(unused)]
fn main() {
use laurus::lexical::search::features::facet::{FacetCollector, FacetConfig};

let mut collector = FacetCollector::new(FacetConfig::default(), vec!["category".to_string()]);
for doc_id in matching_doc_ids {
    collector.collect_doc(doc_id, reader.as_ref())?;
}
let results = collector.finalize()?;

for facet in results.get_field_facets("category").into_iter().flatten() {
    println!("{} ({})", facet.path.to_string_with_delimiter("/"), facet.count);
}
}

ファセットのフィールドを stored document から読む必要があり、その読み取りに失敗すると、 collect_doc はエラーを返します。エラーの後はコレクターの件数が不完全なので、そのコレクターは 破棄してください。

階層的ファセット

/ を含む Text 値は階層パスです。Electronics/Computers/Laptops は 3 階層です。コレクターは パスとその各祖先を、ドキュメントごとに 1 回ずつ数えます。finalize はフィールドごとに 1 つの ツリーを返します。トップレベルの値は get_field_facets(field) に、それより深い階層は親の children に入ります。

Category
├── Electronics (42)
│   ├── Computers (18)
│   │   ├── Laptops (12)
│   │   └── Desktops (6)
│   └── Phones (24)
└── Books (35)
    ├── Fiction (20)
    └── Non-Fiction (15)

ノードの count は、値がそのパス、またはその下にあるドキュメントの数です。したがって、子の件数が 親を上回ることはありません。フラットな値と、階層的な値の根は同じノードです。例えば cat = "a" の ドキュメントと cat = "a/b" のドキュメントからは、子 b (1) を 1 つ持つ a (2) が 1 つだけ できます。

各階層は、それぞれ独立に絞り込み・並べ替え・切り詰めが行われます。

• min_count は、値をその部分木全体と一緒に落とします。
• max_facets_per_field は、トップレベルと各ノードの子に別々に適用されます。そのため、祖先が 子孫の枠を使い切ることはありません。
• 件数が同じ値はラベル順に並ぶので、どの値が残るかがハッシュの順序に左右されません。これは Lucene・Tantivy と同じです。

空の成分は捨てられます。"/a/b" と "a//b" はどちらも a/b に、"a/" は a になり、"" と "/" は何も数えません。Lucene は索引時にこのような成分を拒否します。laurus はファセットを検索時に 通常のテキスト値から作るので、検索を失敗させる代わりに捨てます。

ユースケース

• EC（電子商取引）: カテゴリ、ブランド、価格帯、評価によるフィルタリング
• ドキュメント検索: 著者、部門、日付範囲、ドキュメントタイプによるフィルタリング
• コンテンツ管理: タグ、トピック、コンテンツステータスによるフィルタリング

多値フィールド

多値フィールド（multi_valued = true。多値フィールド を参照）は 1 ドキュメントに配列を保持し、コレクターはそれを展開します: 各要素がそれぞれ 独立したファセットパスになります（Issue #1187）。/ を含む TextArray の要素は、スカラーの Text 値とまったく同じ規則で階層パスに分割されます。そのため tags = ["rust", "search"] は rust と search をそれぞれ 1 回ずつ数え、cat = ["a/b", "a/c"] は a/b・a/c と、両者が 共有する祖先 a を数えます。

カウントは Lucene の SortedSetDocValuesFacetCounts に倣ってドキュメント単位です: 1 ドキュメント内で 2 回現れる要素（["rust", "rust"]）は 1 回だけ数えられ、2 つの要素から 到達する祖先も同様です（上の a は 2 ではなく 1）。したがって FacetCount::count は常に 「マッチしたドキュメント数」を意味します。空配列は何も寄与しません。

配列の要素は、同じ型のスカラー値とまったく同じ形式で文字列化されます:

Null、地理座標（Geo・GeoEcef とそれらの配列）、Vector、Bytes はファセットの対象外で、 何も寄与しません。DocValues がヒットしてファセット値が 0 個になった場合でも、stored document へのフォールバックは行いません。

パフォーマンス

ファセットカウントは stored document ではなく、各フィールドの DocValues 列から読み取られます。 収集された各ヒットについて、コレクターはファセットフィールドの値だけを per-field の DocValues ルックアップで読むため、ファセット対象の全フィールドが DocValues 列を持つ場合（stored: true な フィールドは既定でこれに該当します。ただし後述のとおり型によって除外される場合や、doc_values オプションが明示的に false に設定されている場合を除きます）、stored fields blob 全体を decode / clone しません。DocValues を持たないフィールド ―― オプトアウトしている、stored ではない、あるいは Bytes/Vector の値（DocValues には設定にかかわらず一切格納されません） であるため ―― は透過的に stored document へフォールバックするため、結果はどちらの経路でも 同一で、変わるのは読み取り経路だけです。多値フィールドの配列値は DocValues に丸ごと （1 ドキュメント 1 エントリ）格納され、ファセット時に要素へ分割されるため、展開によって DocValues の読み取り回数が増えることはありません。

ソートにもファセットにも使わないフィールドで doc_values: false を設定すると、値が二重（stored document と DocValues）ではなく一度（stored document のみ）しか書き込まれなくなるため、 セグメントの使用容量が削減されます。

ハイライト

ハイライト（Highlighting）は検索結果内のマッチした単語をマークアップし、ドキュメントがクエリにマッチした理由をユーザーに視覚的に提示します。Laurusは設定可能なHTMLタグでハイライトされたテキストフラグメントを生成します。

検索結果のハイライト

ハイライトを取得する最も簡単な方法は、検索 API 自体に要求することです。SearchRequest でハイライトを指定すると、各ヒットの SearchResult::highlights に結果が入って返ってきます。

#![allow(unused)]
fn main() {
use laurus::{HighlightConfig, SearchRequestBuilder};

let request = SearchRequestBuilder::new()
    .lexical_query(query)
    .highlight(vec!["body".to_string()])
    .highlight_config(HighlightConfig::default().tag("em".to_string()))
    .build();

let results = engine.search(request).await?;
for result in &results {
    if let Some(fragments) = result.highlights.get("body") {
        println!("{}", fragments.join(" ... "));
    }
}
}

highlight(fields) と highlight_config(config) は独立した SearchRequestBuilder のメソッドで、どちらを先に呼んでも構いません。highlight を再度呼ぶとフィールド一覧は置き換わり、highlight_config も同様です。highlight を呼ばない（または空のフィールド一覧を渡す）場合、すべてのヒットの highlights は空のままになります。この場合エンジンはハイライト処理を一切行いません。

押さえておくべき挙動:

• フィールド選択: highlight(fields) で指定したフィールドのうち、stored: true のテキストフィールドのみが対象になります。ドキュメントに存在しない、stored でない、テキスト型でないフィールドは黙ってスキップされ、highlights のキーには現れません。多値テキストフィールド（multi_valued: true、Issue #1175）は要素ごとにハイライトされます: マッチした要素だけがフラグメントを生成し、フラグメントが 2 つの要素をまたぐことはなく、連結後のフラグメント一覧は max_fragments を守ります。
• アナライザ: 各フィールドはそのフィールド自身のインデックス時アナライザでトークナイズされます（フィールド別アナライザは自動的に適用されます）。そのため、ハイライトは汎用トークナイザではなく、インデックス時に実際にマッチした内容を反映します。
• どのクエリがハイライトされるか: ハイライトはリクエストの lexical クエリで駆動されます。これはハイブリッド検索でも同様で、vector-only のリクエストはハイライトを生成しません。リクエストレベルの filter_query だけが持ち込む語はハイライトされません。フィルタは検索対象への適合性を表すものであり、検索意図そのものではないためです。
• 結果が空の場合: マッチするフラグメントがないフィールド（または return_entire_field_if_no_highlight を設定していない場合）は、空リストとしてではなく highlights から完全に除外されます。
• コスト: ハイライトはページネーション後に実行されるため、コストはマッチ総数ではなく limit × フィールド数 に比例します。

Engine::search を経由しないテキストをハイライトするなど、検索 API の外でハイライトを直接制御したい場合は、以下で説明する Highlighter を使ってください。

HighlightConfig

HighlightConfig はハイライトの生成方法を制御します。

#![allow(unused)]
fn main() {
use laurus::lexical::search::features::highlight::HighlightConfig;

let config = HighlightConfig::default()
    .tag("mark")
    .css_class("highlight")
    .max_fragments(3)
    .fragment_size(200);
}

設定オプション

Builderメソッド

対応クエリ

ハイライト対象の語はクエリの説明文字列ではなくクエリ木（Query::collect_highlight_terms）から取得され、ハイライタのアナライザ（既定は StandardAnalyzer。日本語テキストなどフィールドのアナライザに合わせるには Highlighter::with_analyzer を使う）が生成したトークンと照合されます。

既定ではハイライト対象フィールドを対象とする語のみが使われます（require_field_match）。クエリ内の全フィールドの語でハイライトするには false に設定してください。

HighlightFragment

各ハイライト結果は HighlightFragment です。

#![allow(unused)]
fn main() {
pub struct HighlightFragment {
    pub text: String,
}
}

text フィールドには、マッチした単語が設定されたHTMLタグで囲まれたフラグメントが含まれます。

出力例

body = "Rust is a systems programming language focused on safety and performance." というドキュメントに対して “rust programming” で検索した場合:

<mark>Rust</mark> is a systems <mark>programming</mark> language focused on safety and performance.

css_class("highlight") を指定した場合:

<mark class="highlight">Rust</mark> is a systems <mark class="highlight">programming</mark> language focused on safety and performance.

フラグメント選択

フィールドが長い場合、Laurusは最も関連性の高いフラグメントを選択します。

1. テキストが fragment_size 文字のウィンドウに分割されます
2. 各フラグメントは含まれるクエリ単語の数でスコアリングされます
3. 上位 max_fragments 個のフラグメントが、元の出現順のまま Vec<HighlightFragment> として返却されます（結合や整形は呼び出し側が行います）

多値テキストフィールドでは上記の手順が要素ごとに実行されるため、フラグメントが 2 つの要素をまたぐことはありません。max_fragments は全要素を連結した一覧に対する上限です。

マッチを含むフラグメントがなく、return_entire_field_if_no_highlight が true の場合、フィールド全体の値が代わりに返却されます。

スペル修正

Laurusにはスペル修正システムが組み込まれており、誤入力されたクエリ単語の修正候補を提案し、「もしかして？（Did you mean?）」機能を提供します。

概要

スペル修正器は、編集距離（Levenshtein距離（Levenshtein Distance））と単語頻度データを組み合わせて修正候補を提案します。以下の機能をサポートしています。

• 単語レベルの候補提案 – 個々の誤入力単語を修正
• 自動修正 – 高信頼度の修正を自動的に適用
• 「もしかして？」 – ユーザーに代替クエリを提案
• クエリ学習 – ユーザーのクエリから学習して候補を改善
• カスタム辞書 – 独自の単語リストを使用

基本的な使い方

SpellingCorrector

#![allow(unused)]
fn main() {
use laurus::spelling::corrector::SpellingCorrector;

// 組み込みの英語辞書で修正器を作成
let mut corrector = SpellingCorrector::new();

// クエリを修正
let result = corrector.correct("programing langauge");

// 候補が利用可能か確認
if result.has_suggestions() {
    for (word, suggestions) in &result.word_suggestions {
        println!("'{}' -> {:?}", word, suggestions);
    }
}

// 最良の修正済みクエリを取得
if let Some(corrected) = result.query() {
    println!("Corrected: {}", corrected);
}
}

「もしかして？」

DidYouMean ラッパーは検索UIに適した高レベルのインターフェースを提供します。

#![allow(unused)]
fn main() {
use laurus::spelling::corrector::{SpellingCorrector, DidYouMean};

let corrector = SpellingCorrector::new();
let mut did_you_mean = DidYouMean::new(corrector);

if let Some(suggestion) = did_you_mean.suggest("programing") {
    println!("Did you mean: {}?", suggestion);
}
}

設定

CorrectorConfig を使用して動作をカスタマイズできます。

#![allow(unused)]
fn main() {
use laurus::spelling::corrector::{CorrectorConfig, SpellingCorrector};

let config = CorrectorConfig {
    max_distance: 2,              // 最大編集距離（デフォルト: 2）
    max_suggestions: 5,           // 単語あたりの最大候補数（デフォルト: 5）
    min_frequency: 1,             // 最小単語頻度しきい値（デフォルト: 1）
    auto_correct: false,          // 自動修正を有効化（デフォルト: false）
    auto_correct_threshold: 0.8,  // 自動修正の信頼度しきい値（デフォルト: 0.8）
    use_index_terms: true,        // インデックスの単語を辞書として使用（デフォルト: true）
    learn_from_queries: true,     // ユーザーのクエリから学習（デフォルト: true）
};
}

設定オプション

CorrectionResult

correct() メソッドは詳細な情報を含む CorrectionResult を返します。

ヘルパーメソッド

カスタム辞書

組み込みの英語辞書の代わりに独自の辞書を提供できます。

#![allow(unused)]
fn main() {
use laurus::spelling::corrector::SpellingCorrector;
use laurus::spelling::dictionary::SpellingDictionary;

// カスタム辞書を構築
let mut dictionary = SpellingDictionary::new();
dictionary.add_word("elasticsearch", 100);
dictionary.add_word("lucene", 80);
dictionary.add_word("laurus", 90);

let corrector = SpellingCorrector::with_dictionary(dictionary);
}

インデックス単語からの学習

use_index_terms が有効な場合、修正器は検索インデックスの単語から学習できます。

#![allow(unused)]
fn main() {
let mut corrector = SpellingCorrector::new();

// インデックスの単語を修正器に提供
let index_terms = vec!["rust", "programming", "search", "engine"];
corrector.learn_from_terms(&index_terms);
}

これにより、ドメイン固有の語彙が組み込まれ、候補の品質が向上します。

統計情報

stats() で修正器の状態を監視できます。

#![allow(unused)]
fn main() {
let stats = corrector.stats();
println!("Dictionary words: {}", stats.dictionary_words);
println!("Total frequency: {}", stats.dictionary_total_frequency);
println!("Learned queries: {}", stats.queries_learned);
}

次のステップ

• Lexical検索 – クエリタイプを使用した全文検索
• Query DSL – 人間が読みやすいクエリ構文

ID管理

Laurusは、分散環境における効率的なドキュメントの検索、更新、集約を実現するために、二層構造のID管理戦略を採用しています。

1. 外部ID（String）

外部ID（External ID）は、ユーザーやアプリケーションがドキュメントを一意に識別するための論理的な識別子です。

• 型: String
• 役割: UUID、URL、データベースの主キーなど、任意の一意な値を使用できます。
• 保存: Lexicalインデックス内の予約システムフィールド名 _id として透過的に永続化されます。
• 一意性: システム全体でユニークであることが期待されます。
• 更新: 既存の external_id でドキュメントをインデックスすると、自動的に「削除してから挿入（Delete-then-Insert）」（Upsert）操作がトリガーされ、古いバージョンが最新のものに置き換わります。

2. 内部ID（u64 / Stable ID）

内部ID（Internal ID）は、Laurusのエンジン（LexicalおよびVector）が高性能な操作のために内部的に使用する物理的なハンドルです。

• 型: 符号なし64ビット整数（u64）
• 役割: ビットマップ操作、ポイント参照、分散ノード間のルーティングに使用されます。
• 不変性（Stable）: 一度割り当てられた内部IDは、インデックスのマージ（セグメントコンパクション）や再起動によって変更されることはありません。これにより、削除ログやキャッシュの不整合を防止します。

ID構造（Shard-Prefixed）

Laurusはマルチノード分散環境向けに設計されたShard-Prefixed Stable ID方式を採用しています。

この構造を採用する理由

1. ゼロコスト集約: u64 IDがグローバルにユニークであるため、アグリゲータはノード間のID衝突を気にせずに高速なソートと重複排除を実行できます。
2. 高速ルーティング: アグリゲータは上位ビットを見るだけで、ドキュメントの担当物理ノードを即座に特定でき、コストの高いハッシュ検索を回避できます。
3. 高性能フェッチ: 内部IDは物理データ構造に直接マッピングされます。これにより、Laurusは検索時に「外部IDから内部IDへの変換」ステップをスキップし、O(1) のアクセス速度を実現します。

IDライフサイクル

1. 登録（engine.put_document() / engine.add_document()）: ユーザーが外部IDを持つドキュメントを提供します。
2. ID割り当て: Engine が現在の shard_id と新しいLocal IDを組み合わせて、Shard-Prefixed内部IDを発行します。
3. マッピング: エンジンが外部IDと新しい内部IDの対応関係を維持します。
4. 検索: 検索結果は内部IDから解決された外部ID（String）を返します。
5. 取得/削除: ユーザー向けAPIは利便性のために外部IDを受け付けますが、エンジンは内部的に内部IDに変換してほぼ即座に処理を行います。

永続化とWAL

Laurusはデータの耐久性を確保するために**Write-Ahead Log（WAL）**を使用します。すべての書き込み操作はインメモリ構造を変更する前にWALに永続化され、プロセスがクラッシュした場合でもデータが失われないことを保証します。

書き込みパス

sequenceDiagram
    participant App as Application
    participant Engine
    participant WAL as DocumentLog (WAL)
    participant Mem as In-Memory Buffers
    participant Disk as Storage (segments)

    App->>Engine: add_document() / delete_documents()
    Engine->>WAL: 1. Append operation to WAL
    Engine->>Mem: 2. Update in-memory buffers

    Note over Mem: Document is buffered but\nNOT yet searchable

    App->>Engine: commit()
    Engine->>Disk: 3. Flush segments to storage
    Engine->>WAL: 4. Truncate WAL
    Note over Disk: Documents are now\nsearchable and durable

主要な原則

1. WALファースト: すべての書き込み（追加または削除）はインメモリ構造を更新する前にWALに追記されます
2. バッファリング書き込み: インメモリバッファが commit() が呼ばれるまで変更を蓄積します
3. アトミックコミット: commit() はすべてのバッファリングされた変更をセグメントファイルにフラッシュし、WALを切り捨てます
4. コミットスコープの可視性: Lexical セグメントは writer のバッファが埋まった時点で書き出されます。これは commit() よりずっと前に起こり得るため、セグメントファイルがストレージ上に存在することは、その文書が検索可能になったことを意味しません。公開とは commit() だけが追加する manifest エントリのことであり、セグメントの探索は manifest しか読みません。したがって「文書が検索可能になるのは commit() の後」という契約は、searcher がいつ構築されたかに関わらず成立します。削除も同じ手順の中で、ビットマップが永続化された後に公開されるため、セグメントを見られる reader は必ずその削除も適用できます
5. クラッシュセーフティ: 書き込みとコミットの間にプロセスがクラッシュした場合、次回起動時にWALがリプレイされます
6. アトミックなファイル書き込み: セグメントファイル（HNSW の .hnsw グラフ・そのメタデータ・削除ビットマップなど）は一時ファイルへ書き込んでからアトミックにリネームして配置されるため、書き込み途中のクラッシュでも切り詰められたファイルではなく直前にコミット済みのファイルがそのまま残ります
7. チェックサム検証: これらのファイルは CRC-32（.hnsw と .hnsw.f32 rerank sidecar は footer、metadata.json は framing）を持ち、ロード時に検証されるため、ディスク上の静かな破損を正常データとして読まずに検出できます。チェックサム導入前に書かれたファイルもそのままロードできます（ファイル単位で任意）。語彙インデックスのセグメントパート（.dict・.post・.docs・.norms・.ids・.bkd）、削除ビットマップ（.delmap）、チェックサム付き manifest は、末尾に 8 バイトの footer を持ちます。footer は、それより前の全バイトの CRC-32 と、マジック LCRC からなります。先頭から順に読むパートは、セグメントを開いて読み込むときに検証されます。.post と .bkd はランダムアクセスで読むので、マージがセグメントを読むときに検証されます。これで、破損したデータが新しいチェックサムを付けてマージ後のセグメントへ移ることを防ぎます。マージ後のセグメントは、全パートが検証されます。document store のセグメント（doc_segment_NNNNNN.docs）も同じ footer を持ちます。書き込みや再オープンの後に初めて読むとき、offset index を作る際に全体が検証されます。破損していれば、そのセグメントは読むたびにエラーになります。この footer より前に書かれたファイルは、最後の書き込みだけを覆う 4 バイトの trailer で終わります。これらもそのままロードできますが、検証はされません。例外は manifest と .ids で、最後の書き込みがペイロード全体なので、trailer で引き続き検証されます。また、ローダーはヘッダーを信頼する前にバッファ確保サイズを実ファイルサイズで上限を縛るため、サイズフィールドが破損していても巨大なメモリ確保（OOM）を引き起こさずに破損として拒否します。語彙インデックスの Term Dictionary と posting list のデコーダも同様に、各ブロック・FST ヘッダー・スキップテーブルを writer が書く内容と照合するため、破損していれば panic せずに破損エラーを返します。デコードはできても辻褄の合わないデータも、誤った検索結果を返さずに破損として拒否します。対象は、順序が乱れた key や UTF-8 として不正な key、昇順でない block-max や NaN・負の factor を持つ block-max、重複・逆行したりセグメントの範囲外にある doc id、そして term・長さ・文書数・ブロックの境界が辞書のエントリと食い違う posting list です
8. バージョン付きセグメントヘッダー: ベクトルセグメントは共有ヘッダーにフォーマットバージョンを持ち、機能のはしごを形成します。バージョン 2（HNSW のみ）はグラフブロックを 64 ビットのドキュメント ID の代わりにセグメントローカルな 32 ビット ordinal で格納します（ディスク上のグラフブロックはおよそ半分になります）。バージョン 3（全ベクトルインデックス型）はセグメントごとのフィールド名辞書を追加し、各レコードはフィールド名をインラインで繰り返す代わりに 16 ビットの ID で参照します（レコードごとに名前の長さ + 2 バイト分縮小されます）。新しいセグメントはバージョン 3 で書き込まれ、古いビルドが書いたセグメント（バージョン 1・2）もそのままロードでき、次の書き直し（コンパクションやマージ）で更新されます

Write-Ahead Log（WAL）

WALは DocumentLog コンポーネントによって管理され、ストレージバックエンドのルートレベル（engine.wal）に保存されます。

WALエントリタイプ

WALファイル

WALファイル（engine.wal）は追記専用のバイナリログです。各エントリは以下を含む自己完結型です。

• 操作タイプ（add/delete）
• シーケンス番号
• ペイロード（ドキュメントデータまたはID）

オンディスクのフレーミング

ファイルは 5 バイトのヘッダ（b"LWAL" マジック + バージョンバイト）で始まり、長さプレフィックス付きレコードが続きます。フレーミングは 3 種類あり、各ファイルは生涯を通じて単一のフレーミングを保持します（古いファイルは次の commit/truncate 時にのみ現行フォーマットへ書き換えられ、1 ファイル内でフォーマットが混在することはありません）。