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.9"
tokio = { version = "1", features = ["full"] }

Feature Flags

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

例

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

[dependencies]
laurus = "0.9"

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

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

OpenAI による Vector 検索:

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

すべての機能:

[dependencies]
laurus = { version = "0.9", 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、GeoQuery、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 (all true)
let opt = TextOption::default();

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

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,                                // default scoring weight
    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 インデクシングを参照してください。

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>),          // 多値浮動小数点フィールド
}
}

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
}

予約フィールド

アンダースコア（_）で始まるフィールド名はすべてエンジンの予約領域です。 ユーザーコードからそのような名前でフィールドを定義することはできず、 _ で始まるキーを含むドキュメントは投入時にエラーとなります。

唯一許可される _ プレフィックス名は、次に説明する _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）と Bytes は 自動推論の 対象外です。スキーマへ明示的に宣言してください。なお、同一 object 内で 2D 用キー（lat / lon）と 3D 用キー（x / y / z）を混在させた 場合は曖昧と判定してエラーとなります。いずれか一方の形式のみ使用して ください。

多値数値フィールド

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

多値フィールドに単一値を送った場合は要素 1 個の配列に自動ラップされます。 逆に単一値フィールドに配列を送ると、暗黙の切り捨てではなくエラーになります。

型衝突

既に宣言されているフィールドに別の型の値が到着した場合、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 に含まれている場合、そこからも削除されます。
• フィールドに紐づくアナライザーおよびエンベッダーの登録が解除されます。
• 既にインデックスされたデータは物理的に残りますが、スキーマから削除されたフィールドにはアクセスできなくなります。

共通の注意事項

返却された 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 として登録し、フィールドからは名前で参照します。

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);  // synonyms get 80% weight
}

boost パラメータは、元のトークンに対する同義語の重みを制御します。値 0.8 は、同義語のマッチが完全一致のスコアの 80% を寄与することを意味します。

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

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
}

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
}

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
}

検索時

テキストで検索すると、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 化するため、一貫したベクトル空間が保証されます。

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 on commit()

ステップごとの流れ

1. 解析（Analyze）: テキストが設定されたアナライザー（トークナイザー + フィルター）を通過し、正規化されたタームのストリームが生成される
2. バッファリング（Buffer）: タームはフィールドごとに整理され、インメモリの書き込みバッファに格納される
3. コミット（Commit）: 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 の各エントリには以下の情報が含まれます。

Multi-Level Skip Table

N ≥ 8 ポスティングを持つ posting list はヘッダ直後に Lucene-90 互換のマルチレベルスキップテーブル（v2 フォーマット）を 持ちます。各レベルは 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 から再構築します。

Term Dictionary の 2 層構造

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

• ディスク層 — .dict ファイルは Lucene BlockTreeTermsWriter 風のブロックツリーレイアウト（マジック LTDD、スキーマ v1）。 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                ]  全タームカウント + ブロックカウント

• 検索: 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[".lens (field lengths)"]

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

1. 作成（Create）: commit() が呼び出されるたびに新しいセグメントが作成される
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 はロード時にフォーマットを判定。

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 に切り詰めて返す。

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()
};
}

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 用に枠を予約しています。

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 を埋める方向が 考えられます。

セグメントファイル

各ベクトルインデックスタイプは、データを単一のセグメントファイルに格納します。

コード例

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 のデフォルト設定）。

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,
);
}

GeoQuery

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

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

// Find documents within 10 km (= 10 000 m) of Tokyo Station (35.6812, 139.7671)
let query = GeoQuery::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 = GeoQuery::within_bounding_box(
    "location",
    35.0, 139.0,  // min (lat, lon)
    36.0, 140.0,  // max (lat, lon)
)?;
}

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

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 フィールドに格納されます。

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

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

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]")?;
}

完全な構文リファレンスは 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 の予算を共有します。インデックス設定で制御できます。

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

let mut inverted = InvertedIndexConfig::default();
inverted.enable_posting_cache = false;        // 完全に無効化
inverted.max_cache_memory = 256 * 1024 * 1024; // またはキャッシュ予算（バイト）を変更
let config = LexicalIndexConfig::Inverted(inverted);
}

次のステップ

• 意味的類似性検索: 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();
}

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

スコアモード

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

複数のクエリベクトル（ColBERT スタイルの late interaction、マルチベクトル MaxSim、ensemble reranker など）を含むリクエストに対して、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 フィールドが独自の 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 検索

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();
}

距離メトリクス（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 の両方の結果を制限できます。

#![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();
}

完全な例

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

ブーリアン演算子

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

ファジークエリ

編集距離を使用した近似マッチング。~ に続けてオプションで最大編集距離を指定します。

roam~
roam~2

ワイルドカードクエリ

?（1 文字）と *（0 文字以上）を使用します。

te?t
test*

範囲クエリ

包含的な [] または排他的な {} の範囲指定。数値フィールドや日付フィールドに有用です。

price:[100 TO 500]
date:{2024-01-01 TO 2024-12-31}
price:[* TO 100]

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 2)

.bkd セグメントファイルは自己完結型のバイナリで、3 つの領域から成る：

+----------------------------------------+
| File Header                            |   固定長・バージョンタグ付き
+----------------------------------------+
| Leaf Blocks                            |   row-major points + doc_ids
|   leaf 0                               |
|   leaf 1                               |
|   ...                                  |
+----------------------------------------+
| Index Nodes                            |   内部ナビゲーションノード
|   node N-1                             |
|   ...                                  |
|   node 0  (root, written last)         |
+----------------------------------------+

ヘッダ (BKDFileHeader) は magic、version（現在は 2）、num_dims、 bytes_per_dim、総ポイント数、リーフブロック数、全体の軸ごと min/max、 インデックス領域とルートノードへのオフセットを保持する。

Leaf Block レイアウト

各リーフブロックは、その部分木に属するポイントを格納する：

count               u32                       — リーフ内のポイント数
leaf_min            [f64; num_dims]           — リーフレベルの AABB 下端
leaf_max            [f64; num_dims]           — リーフレベルの AABB 上端
point_values        [f64; count * num_dims]   — row-major のポイント座標
doc_ids             [u64; count]              — ドキュメント ID の並列配列

リーフごとに AABB を持たせることで、クエリ領域がリーフの外側にある場合 (Outside) や全内包される場合 (Inside) には、ポイントを 1 つも読まずに リーフ全体を判定できる。

内部 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、 GeoQuery、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.9"

# ローカルBERT Embeddingを使用
[dependencies]
laurus = { version = "0.9", features = ["embeddings-candle"] }

# すべてのFeatureを有効化
[dependencies]
laurus = { version = "0.9", 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）。

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

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 — ドキュメント長と平均ドキュメント長の比率。

(k1, b) の値は現在実装デフォルトに固定です。Lucene / Elasticsearch のデフォルトと同じため、BM25 スコアはチューニングの直感に関してそれらのエンジンと直接比較できます。

フィールドブースト

フィールドごとのスコア乗数は専用のスコアリング構造体ではなく、検索リクエスト上で設定します。

#![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 は無効化と同じです。クエリで指定されたフィールド（またはスキーマの既定検索フィールド）にのみ適用されます。

gRPC / HTTP 経由では同じ設定が SearchRequest.field_boosts（map<string, float>）として公開されます。gRPC API → SearchRequest を参照してください。

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", "Electronics");

// コンポーネントからの階層的ファセット
let facet = FacetPath::new("category", vec![
    "Electronics".to_string(),
    "Computers".to_string(),
    "Laptops".to_string(),
]);

// 区切り文字付き文字列から
let facet = FacetPath::from_delimited("category", "Electronics/Computers/Laptops", "/");
}

FacetPathメソッド

FacetCount

FacetCount はファセット集計の結果を表します。

#![allow(unused)]
fn main() {
pub struct FacetCount {
    pub path: FacetPath,
    pub count: u64,
    pub children: Vec<FacetCount>,
}
}

例: 階層的ファセット

Category
├── Electronics (42)
│   ├── Computers (18)
│   │   ├── Laptops (12)
│   │   └── Desktops (6)
│   └── Phones (24)
└── Books (35)
    ├── Fiction (20)
    └── Non-Fiction (15)

このツリーの各ノードは、ドリルダウンナビゲーション用に children が設定された FacetCount に対応します。

ユースケース

• EC（電子商取引）: カテゴリ、ブランド、価格帯、評価によるフィルタリング
• ドキュメント検索: 著者、部門、日付範囲、ドキュメントタイプによるフィルタリング
• コンテンツ管理: タグ、トピック、コンテンツステータスによるフィルタリング

パフォーマンス

ファセットカウントは stored document ではなく、各フィールドの DocValues 列から読み取られます。 収集された各ヒットについて、コレクターはファセットフィールドの値だけを per-field の DocValues ルックアップで読むため、ファセット対象の全フィールドが DocValues 列を持つ場合（既定では、index 時に 全 stored field が DocValues に書かれるため常に成立）、stored fields blob 全体を decode / clone しません。 DocValues を持たないフィールドは透過的に stored document へフォールバックするため、結果はどちらの経路でも 同一で、変わるのは読み取り経路だけです。

ハイライト

ハイライト（Highlighting）は検索結果内のマッチした単語をマークアップし、ドキュメントがクエリにマッチした理由をユーザーに視覚的に提示します。Laurusは設定可能なHTMLタグでハイライトされたテキストフラグメントを生成します。

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メソッド

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 個のフラグメントが fragment_separator で結合されて返却されます

マッチを含むフラグメントがなく、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. クラッシュセーフティ: 書き込みとコミットの間にプロセスがクラッシュした場合、次回起動時にWALがリプレイされます
5. アトミックなファイル書き込み: セグメントファイル（HNSW の .hnsw グラフ・そのメタデータ・削除ビットマップなど）は一時ファイルへ書き込んでからアトミックにリネームして配置されるため、書き込み途中のクラッシュでも切り詰められたファイルではなく直前にコミット済みのファイルがそのまま残ります
6. チェックサム検証: これらのファイルは CRC-32（.hnsw と .hnsw.f32 rerank sidecar は footer、metadata.json と削除ビットマップは framing）を持ち、ロード時に検証されるため、ディスク上の静かな破損を正常データとして読まずに検出できます。チェックサム導入前に書かれたファイルもそのままロードできます（ファイル単位で任意）。また、ローダーはヘッダーを信頼する前にバッファ確保サイズを実ファイルサイズで上限を縛るため、サイズフィールドが破損していても巨大なメモリ確保（OOM）を引き起こさずに破損として拒否します

Write-Ahead Log（WAL）

WALは DocumentLog コンポーネントによって管理され、ストレージバックエンドのルートレベル（engine.wal）に保存されます。

WALエントリタイプ

WALファイル

WALファイル（engine.wal）は追記専用のバイナリログです。各エントリは以下を含む自己完結型です。

• 操作タイプ（add/delete）
• シーケンス番号
• ペイロード（ドキュメントデータまたはID）

リカバリ

エンジンがビルドされる際（Engine::builder(...).build().await）、残っているWALエントリが自動的にチェックされ、リプレイされます（WALはコミット時に切り捨てられるため、残っているエントリはクラッシュしたセッションのものです）。

graph TD
    Start["Engine::build()"] --> Check["Check WAL for\nuncommitted entries"]
    Check -->|"Entries found"| Replay["Replay operations\ninto in-memory buffers"]
    Replay --> Ready["Engine ready"]
    Check -->|"No entries"| Ready

リカバリは透過的に行われるため、手動で処理する必要はありません。

コミットライフサイクル

#![allow(unused)]
fn main() {
// 1. ドキュメントを追加（バッファリングされ、まだ検索不可）
engine.add_document("doc-1", doc1).await?;
engine.add_document("doc-2", doc2).await?;

// 2. コミット — 永続ストレージにフラッシュ
engine.commit().await?;
// ドキュメントが検索可能に

// 3. さらにドキュメントを追加
engine.add_document("doc-3", doc3).await?;

// 4. ここでプロセスがクラッシュした場合、doc-3はWAL内にあり
//    次回起動時にリカバリされます
}

コミットのタイミング

ヒント: コミットはセグメントをストレージにフラッシュするため比較的コストが高い操作です。バルクインデキシングでは、commit() を呼び出す前に多数のドキュメントをバッチ処理してください。

ストレージレイアウト

エンジンは PrefixedStorage を使用してデータを整理します。

<storage root>/
├── lexical/          # 転置インデックスセグメント
│   ├── seg-000/
│   │   ├── terms.dict
│   │   ├── postings.post
│   │   └── ...
│   └── metadata.json
├── vector/           # ベクトルインデックスセグメント
│   ├── seg-000/
│   │   ├── graph.hnsw
│   │   ├── vectors.vecs
│   │   └── ...
│   └── metadata.json
├── documents/        # ドキュメントストレージ
│   └── ...
└── engine.wal        # Write-Ahead Log

次のステップ

• 削除の処理方法: 削除とコンパクション
• ストレージバックエンド: Storage

削除とコンパクション

Laurusは二段階の削除戦略を採用しています。高速な**論理削除（Logical Deletion）と、それに続く定期的な物理コンパクション（Physical Compaction）**です。

ドキュメントの削除

#![allow(unused)]
fn main() {
// 外部IDでドキュメントを削除
engine.delete_documents("doc-1").await?;
engine.commit().await?;
}

論理削除

ドキュメントが削除された場合、インデックスファイルから即座に削除されるわけではありません。代わりに以下の処理が行われます。

graph LR
    Del["delete_documents('doc-1')"] --> Bitmap["Add internal ID\nto Deletion Bitmap"]
    Bitmap --> Search["Search skips\ndeleted IDs"]

1. ドキュメントの内部IDが**削除ビットマップ（Deletion Bitmap）**に追加されます
2. 検索時にビットマップがチェックされ、削除されたドキュメントが結果からフィルタリングされます
3. 元のデータはセグメントファイルに残ったままです

これはレキシカルインデックスと**ベクトル（HNSW）**インデックスの両方に一様に適用されます。HNSW では 削除されたノードはグラフに残り（グラフの連結性を保つためそのベクトルは引き続き利用されます）、 削除認識トラバーサルが結果から除外します。したがって削除で グラフが再構築されることはなく、コストはインデックスサイズに依らず O(1) のビットマップマークだけです。 物理的な回収は後段のコンパクションで行われます。

論理削除を採用する理由

Upsert（更新 = 削除 + 挿入）

既存の外部IDでドキュメントをインデックスすると、Laurusは自動的にUpsertを実行します。

1. 古いドキュメントが論理削除されます（そのIDが削除ビットマップに追加）
2. 新しい内部IDで新しいドキュメントが挿入されます
3. 外部IDから内部IDへのマッピングが更新されます

#![allow(unused)]
fn main() {
// 最初の挿入
engine.put_document("doc-1", doc_v1).await?;
engine.commit().await?;

// 更新: 古いバージョンが論理削除され、新しいバージョンが挿入される
engine.put_document("doc-1", doc_v2).await?;
engine.commit().await?;
}

物理コンパクション

時間の経過とともに、論理削除されたドキュメントが蓄積されスペースを浪費します。コンパクションは、削除済みエントリを含まないセグメントファイルを再書き込みすることでスペースを回収します。

graph LR
    subgraph "Before Compaction"
        S1["Segment 0\ndoc-1 (deleted)\ndoc-2\ndoc-3 (deleted)"]
        S2["Segment 1\ndoc-4\ndoc-5"]
    end

    Compact["Compaction"]

    subgraph "After Compaction"
        S3["Segment 0\ndoc-2\ndoc-4\ndoc-5"]
    end

    S1 --> Compact
    S2 --> Compact
    Compact --> S3

コンパクションの処理内容

1. 既存セグメントからすべての生存（未削除）ドキュメントを読み取ります
2. 削除済みエントリを含まない転置インデックスやベクトルインデックスを再構築します
3. 新しいクリーンなセグメントファイルを書き込みます
4. 古いセグメントファイルを削除します
5. 削除ビットマップをリセットします

コストと頻度

コンパクションのタイミング

• 書き込みが少ないワークロード: 定期的にコンパクション（例: 毎日または毎週）
• 書き込みが多いワークロード: 削除率がしきい値を超えた場合にコンパクション
• バルク更新後: 大量のUpsertバッチの後にコンパクション

自動コンパクション

HNSW ベクトルインデックスではコンパクションを自動実行できます。DeletionConfig::auto_compaction が有効な場合（既定）、commit() が削除率（削除ノード数 / コミット済み総ノード数）を確認し、 DeletionConfig::compaction_threshold（既定 0.3）に達するとコンパクションを起動します。 コンパクション後は削除率が 0 に戻るため、削除が再度蓄積するまで再発火せず、手動 optimize() なしに tombstone の増加を抑えられます。自分で制御したい場合は auto_compaction を false にします。

削除ビットマップ

削除ビットマップは、どの内部IDが削除されたかを追跡します。

• 保存: 削除済みドキュメントIDの Roaring ビットマップ。 セグメント寿命で累積する密な削除集合では、生のID列より劇的に小さくなります。例えば 10M ドキュメント・10% 削除のセグメントは on-disk で ~8MB ではなく ~125KB です。
• 検索: 分岐の少ないビットテスト。削除集合が大きくても CPU キャッシュに常駐しやすく、 is_deleted は lexical の per-document・vector の per-neighbour 検索ホットパスで呼ばれます。

ビットマップはインデックスセグメントと一緒に（.delmap ファイルとして）永続化され、リカバリ時に WALから再構築されます。on-disk 形式はバージョン管理されており、現在の writer は v4（Roaring）を 書き出し、reader は後方互換のため旧 v1〜v3（生ID列）形式も読み込めます。

次のステップ

• データの永続化方法: 永続化とWAL
• IDの管理と内部/外部IDのマッピング: ID管理

エラーハンドリング

Laurusはすべての操作に統一的なエラー型を使用します。エラーシステムを理解することで、障害を適切に処理する堅牢なアプリケーションを作成できます。

LaurusError

Laurusのすべての操作は Result<T> を返します。これは std::result::Result<T, LaurusError> のエイリアスです。

LaurusError は、各カテゴリの障害に対応するバリアントを持つenumです。

基本的なエラーハンドリング

? 演算子の使用

最もシンプルなアプローチ – エラーを呼び出し元に伝播します。

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

async fn index_documents(engine: &Engine) -> Result<()> {
    let doc = laurus::Document::builder()
        .add_text("title", "Rust Programming")
        .build();

    engine.put_document("doc1", doc).await?;
    engine.commit().await?;
    Ok(())
}
}

エラーバリアントのマッチング

エラータイプごとに異なる動作が必要な場合:

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

async fn safe_search(engine: &Engine, query: &str) {
    match engine.search(/* request */).await {
        Ok(results) => {
            for result in results {
                println!("{}: {}", result.id, result.score);
            }
        }
        Err(LaurusError::Query(msg)) => {
            eprintln!("Invalid query syntax: {}", msg);
        }
        Err(LaurusError::Io(e)) => {
            eprintln!("Storage I/O error: {}", e);
        }
        Err(e) => {
            eprintln!("Unexpected error: {}", e);
        }
    }
}
}

downcast によるエラータイプの確認

LaurusError は std::error::Error を実装しているため、標準的なエラーハンドリングパターンを使用できます。

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

fn is_retriable(error: &LaurusError) -> bool {
    matches!(error, LaurusError::Io(_) | LaurusError::ResourceExhausted(_))
}
}

よくあるエラーシナリオ

スキーマの不一致

スキーマに一致しないフィールドを持つドキュメントの追加:

#![allow(unused)]
fn main() {
// スキーマには "title"（Text）と "year"（Integer）がある
let doc = Document::builder()
    .add_text("title", "Hello")
    .add_text("unknown_field", "this field is not in schema")
    .build();

// スキーマにないフィールドはインデキシング時に黙って無視されます。
// エラーは発生しません -- スキーマで定義されたフィールドのみが処理されます。
}

クエリ解析エラー

無効なQuery DSL構文は Query エラーを返します。

#![allow(unused)]
fn main() {
use laurus::engine::query::UnifiedQueryParser;

let parser = UnifiedQueryParser::new();
match parser.parse("title:\"unclosed phrase") {
    Ok(request) => { /* ... */ }
    Err(LaurusError::Query(msg)) => {
        // msgには解析失敗の詳細が含まれます
        eprintln!("Bad query: {}", msg);
    }
    Err(e) => { /* その他のエラー */ }
}
}

ストレージI/Oエラー

ファイルベースのストレージではI/Oエラーが発生する可能性があります。

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

match StorageFactory::open(StorageConfig::File {
    path: "/nonexistent/path".into(),
    loading_mode: Default::default(),
}) {
    Ok(storage) => { /* ... */ }
    Err(LaurusError::Io(e)) => {
        eprintln!("Cannot open storage: {}", e);
    }
    Err(e) => { /* その他のエラー */ }
}
}

便利なコンストラクタ

LaurusError はカスタム実装でエラーを作成するためのファクトリメソッドを提供しています。

これらはカスタム Analyzer、Embedder、またはStorage トレイトを実装する際に有用です。

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

fn validate_dimension(dim: usize) -> Result<()> {
    if dim == 0 {
        return Err(LaurusError::invalid_argument("dimension must be > 0"));
    }
    Ok(())
}
}

自動変換

LaurusError は一般的なエラー型に対して From を実装しているため、? で自動変換されます。

次のステップ

• 拡張性 – 適切なエラーハンドリングでカスタムトレイトを実装
• APIリファレンス – 完全なメソッドシグネチャと戻り値の型

拡張性

Laurusはコアコンポーネントにトレイトベースの抽象化を採用しています。これらのトレイトを実装することで、カスタムAnalyzer、Embedder、およびStorageバックエンドを提供できます。

カスタムAnalyzer

Analyzer トレイトを実装して、カスタムテキスト解析パイプラインを作成します。

#![allow(unused)]
fn main() {
use laurus::analysis::analyzer::analyzer::Analyzer;
use laurus::analysis::token::{Token, TokenStream};
use laurus::Result;

#[derive(Debug)]
struct ReverseAnalyzer;

impl Analyzer for ReverseAnalyzer {
    fn analyze(&self, text: &str) -> Result<TokenStream> {
        let tokens: Vec<Token> = text
            .split_whitespace()
            .enumerate()
            .map(|(i, word)| Token {
                text: word.chars().rev().collect(),
                position: i,
                ..Default::default()
            })
            .collect();
        Ok(Box::new(tokens.into_iter()))
    }

    fn name(&self) -> &str {
        "reverse"
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
}
}

必須メソッド

カスタムAnalyzerの使用

Analyzerを EngineBuilder に渡します。

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

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

フィールドごとのAnalyzerには PerFieldAnalyzer でラップします。

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

let per_field = PerFieldAnalyzer::new(Arc::new(StandardAnalyzer::new()?));
per_field.add_analyzer("custom_field", Arc::new(ReverseAnalyzer));

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

カスタムEmbedder

Embedder トレイトを実装して、独自のベクトルEmbeddingモデルを統合します。

#![allow(unused)]
fn main() {
use async_trait::async_trait;
use laurus::embedding::embedder::{Embedder, EmbedInput, EmbedInputType};
use laurus::vector::core::vector::Vector;
use laurus::{LaurusError, Result};

#[derive(Debug)]
struct MyEmbedder {
    dimension: usize,
}

#[async_trait]
impl Embedder for MyEmbedder {
    async fn embed(&self, input: &EmbedInput<'_>) -> Result<Vector> {
        match input {
            EmbedInput::Text(text) => {
                // Embeddingロジックをここに記述
                let vector = vec![0.0f32; self.dimension];
                Ok(Vector::new(vector))
            }
            _ => Err(LaurusError::invalid_argument(
                "this embedder only supports text input",
            )),
        }
    }

    fn supported_input_types(&self) -> Vec<EmbedInputType> {
        vec![EmbedInputType::Text]
    }

    fn name(&self) -> &str {
        "my-embedder"
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
}
}

必須メソッド

オプションメソッド

カスタムEmbedderの使用

#![allow(unused)]
fn main() {
let embedder = Arc::new(MyEmbedder { dimension: 384 });
let engine = Engine::builder(storage, schema)
    .embedder(embedder)
    .build()
    .await?;
}

フィールドごとのEmbedderには PerFieldEmbedder でラップします。

#![allow(unused)]
fn main() {
use laurus::embedding::per_field::PerFieldEmbedder;

let per_field = PerFieldEmbedder::new(Arc::new(MyEmbedder { dimension: 384 }));
per_field.add_embedder("image_vec", Arc::new(ClipEmbedder::new()?));

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

カスタムStorage

Storage トレイトを実装して、新しいストレージバックエンドを追加します。

#![allow(unused)]
fn main() {
use laurus::storage::{Storage, StorageInput, StorageOutput, LoadingMode, FileMetadata};
use laurus::Result;

#[derive(Debug)]
struct S3Storage {
    bucket: String,
    prefix: String,
}

impl Storage for S3Storage {
    fn loading_mode(&self) -> LoadingMode {
        LoadingMode::Eager  // S3は完全なダウンロードが必要
    }

    fn open_input(&self, name: &str) -> Result<Box<dyn StorageInput>> {
        // S3からダウンロードしてリーダーを返す
        todo!()
    }

    fn create_output(&self, name: &str) -> Result<Box<dyn StorageOutput>> {
        // S3へのアップロードストリームを作成
        todo!()
    }

    fn create_output_append(&self, name: &str) -> Result<Box<dyn StorageOutput>> {
        todo!()
    }

    fn file_exists(&self, name: &str) -> bool {
        todo!()
    }

    fn delete_file(&self, name: &str) -> Result<()> {
        todo!()
    }

    fn list_files(&self) -> Result<Vec<String>> {
        todo!()
    }

    fn file_size(&self, name: &str) -> Result<u64> {
        todo!()
    }

    fn metadata(&self, name: &str) -> Result<FileMetadata> {
        todo!()
    }

    fn rename_file(&self, old_name: &str, new_name: &str) -> Result<()> {
        todo!()
    }

    fn create_temp_output(&self, prefix: &str) -> Result<(String, Box<dyn StorageOutput>)> {
        todo!()
    }

    fn sync(&self) -> Result<()> {
        todo!()
    }

    fn close(&mut self) -> Result<()> {
        todo!()
    }
}
}

必須メソッド

オプションメソッド

スレッドセーフティ

3つのトレイトすべてが Send + Sync を要求します。つまり、実装はスレッド間で安全に共有できる必要があります。共有可能な可変状態には Arc<Mutex<_>> またはロックフリーデータ構造を使用してください。

次のステップ

• エラーハンドリング – カスタム実装でのエラー処理
• テキスト解析 – 組み込みのAnalyzerとパイプラインコンポーネント
• Embedding – 組み込みのEmbedderオプション
• Storage – 組み込みのStorageバックエンド

APIリファレンス

このページでは、Laurusの最も重要な型とメソッドのクイックリファレンスを提供します。完全な詳細については、Rustdocを生成してください。

cargo doc --open

Engine

すべてのインデキシングと検索操作を統合する中心的なコーディネーターです。

put_document と add_document の違い: put_document はUpsertを実行します。同じ外部IDのドキュメントが既に存在する場合、削除して置き換えます。add_document は常に追加し、複数のドキュメントチャンクが同じ外部IDを共有できます。詳細は Schema & Fields – ドキュメントのインデキシング を参照してください。

EngineBuilder

Schema

ドキュメント構造を定義します。

SchemaBuilder

Document

名前付きフィールド値のコレクションです。

DocumentBuilder

Search

SearchRequestBuilder

VectorSearchRequestBuilder

SearchResult

FusionAlgorithm

クエリタイプ（Lexical）

クエリパーサー

Analyzer

Embedder

Storage

DataValue

CLI 概要

Laurus はコマンドラインツール laurus を提供しており、コードを書かずにインデックスの作成、ドキュメントの管理、検索クエリの実行が可能です。

機能

• インデックス管理 – TOML スキーマファイルからインデックスを作成・検査。対話式スキーマジェネレーター付き
• ドキュメント CRUD – JSON によるドキュメントの追加、取得、削除
• 検索 – Query DSL を使用したクエリ実行
• デュアル出力 – 人間が読みやすいテーブル形式または機械処理向け JSON 形式
• 対話型 REPL – ライブセッションでインデックスを操作
• gRPC サーバー – laurus serve で gRPC サーバーを起動

はじめに

# インストール
cargo install laurus-cli

# スキーマを対話的に生成
laurus create schema

# スキーマからインデックスを作成
laurus --index-dir ./my_index create index --schema schema.toml

# ドキュメントを追加
laurus --index-dir ./my_index add doc --id doc1 --data '{"title":"Hello","body":"World"}'

# 変更をコミット
laurus --index-dir ./my_index commit

# 検索
laurus --index-dir ./my_index search "body:world"

詳細はサブセクションを参照してください:

• インストール – CLI のインストール方法
• コマンドリファレンス – 全コマンドの詳細
• スキーマフォーマット – スキーマ TOML フォーマットのリファレンス
• REPL – 対話モード

インストール

crates.io からインストール

cargo install laurus-cli

これにより laurus バイナリが ~/.cargo/bin/ にインストールされます。

ソースからインストール

git clone https://github.com/mosuka/laurus.git
cd laurus
cargo install --path laurus-cli

確認

laurus --version

ハンズオンチュートリアル

このチュートリアルでは、laurus CLI を使った一連のワークフローを体験します。スキーマの作成、インデックスの構築、ドキュメントの登録、検索、更新、削除、そしてインタラクティブ REPL の使い方を順を追って説明します。

前提条件

• laurus CLI がインストール済み（インストール を参照）

Step 1: スキーマの作成

まず、インデックスの構造を定義するスキーマファイルを作成します。対話形式で生成することもできます:

laurus create schema

対話ウィザードがフィールドの定義をガイドします。このチュートリアルでは、手動でスキーマファイルを作成します:

cat > schema.toml << 'EOF'
default_fields = ["title", "body"]

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

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

[fields.category.Text]
indexed = true
stored = true
term_vectors = false
EOF

3 つのテキストフィールドを定義しています。default_fields を設定することで、フィールド指定なしのクエリは title と body の両方を検索します。

Step 2: インデックスの作成

スキーマを使ってインデックスを作成します:

laurus --index-dir ./tutorial_data create index --schema schema.toml

インデックスが作成されたことを確認します:

laurus --index-dir ./tutorial_data get stats

ドキュメント数が 0 であることが表示されます。

Step 3: ドキュメントの登録

ドキュメントをインデックスに追加します。各ドキュメントには ID と JSON 形式のフィールド値が必要です:

laurus --index-dir ./tutorial_data add doc \
  --id doc001 \
  --data '{"title":"Introduction to Rust Programming","body":"Rust is a modern systems programming language that focuses on safety, speed, and concurrency.","category":"programming"}'

laurus --index-dir ./tutorial_data add doc \
  --id doc002 \
  --data '{"title":"Web Development with Rust","body":"Building web applications with Rust has become increasingly popular. Frameworks like Actix and Rocket make it easy to create fast and secure web services.","category":"web-development"}'

laurus --index-dir ./tutorial_data add doc \
  --id doc003 \
  --data '{"title":"Python for Data Science","body":"Python is the most popular language for data science and machine learning. Libraries like NumPy and Pandas provide powerful tools for data analysis.","category":"data-science"}'

Step 4: 変更のコミット

ドキュメントはコミットするまで検索対象になりません:

laurus --index-dir ./tutorial_data commit

Step 5: ドキュメントの検索

基本的な検索

“rust” を含むドキュメントを検索します:

laurus --index-dir ./tutorial_data search "rust"

デフォルトフィールド（title と body）が検索されます。doc001 と doc002 が返されます。

フィールド指定検索

title フィールドのみを検索します:

laurus --index-dir ./tutorial_data search "title:python"

doc003 のみが返されます。

カテゴリ検索

laurus --index-dir ./tutorial_data search "category:programming"

doc001 のみが返されます。

ブーリアンクエリ

+（必須）と -（除外）で条件を組み合わせます:

laurus --index-dir ./tutorial_data search "+body:rust -body:web"

“rust” を含み “web” を含まない doc001 のみが返されます。

フレーズ検索

完全一致するフレーズを検索します:

laurus --index-dir ./tutorial_data search 'body:"data science"'

doc003 のみが返されます。

あいまい検索

~ を使ってタイプミスに対応した検索を行います:

laurus --index-dir ./tutorial_data search "body:programing~1"

タイプミスがあっても “programming” にマッチします。

JSON 出力

プログラムでの利用に向けて JSON 形式で結果を取得します:

laurus --index-dir ./tutorial_data --format json search "rust"

Step 6: ドキュメントの取得

ID を指定して特定のドキュメントを取得します:

laurus --index-dir ./tutorial_data get docs --id doc001

Step 7: ドキュメントの削除

ドキュメントを削除してコミットします:

laurus --index-dir ./tutorial_data delete docs --id doc003
laurus --index-dir ./tutorial_data commit

削除されたことを確認します:

laurus --index-dir ./tutorial_data search "python"

結果は返されません。

Step 8: REPL を使う

REPL はインデックスを対話的に操作するためのインタラクティブセッションです:

laurus --index-dir ./tutorial_data repl

REPL で以下のコマンドを試してみてください:

> get stats
> search rust
> add doc doc004 {"title":"Go Programming","body":"Go is a statically typed language designed for simplicity and efficiency.","category":"programming"}
> commit
> search programming
> get docs doc004
> delete docs doc004
> commit
> quit

REPL はコマンド履歴（上下キー）や行編集に対応しています。

Step 9: クリーンアップ

チュートリアルで作成したデータを削除します:

rm -rf ./tutorial_data schema.toml

次のステップ

• スキーマフォーマットで高度なフィールド設定を学ぶ
• コマンドリファレンスで全コマンドを確認する
• REPLでインタラクティブな操作を深める
• サーバーチュートリアルで gRPC/HTTP アクセスを試す

コマンドリファレンス

グローバルオプション

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

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

create — リソースの作成

create index

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

laurus create index [--schema <FILE>]

引数:

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

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

default_fields = ["title", "body"]

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

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

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

例:

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

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

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

create schema

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

laurus create schema [--output <FILE>]

引数:

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

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

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

例:

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

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

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

get — リソースの取得

get stats

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

laurus get stats

テーブル出力の例:

Document count: 42

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

JSON 出力の例:

laurus --format json get stats

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

get schema

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

laurus get schema

例:

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

get docs

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

laurus get docs --id <ID>

テーブル出力の例:

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

JSON 出力の例:

laurus --format json get docs --id doc1

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

add — リソースの追加

add doc

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

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

引数:

JSON フォーマットはフィールド名と値を対応付けたフラットなオブジェクトです:

{
  "title": "Introduction to Rust",
  "body": "Rust is a systems programming language.",
  "category": "programming"
}

例:

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

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

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

put doc

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

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

引数:

例:

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

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

add field

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

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