API リファレンス

Index

Laurus 検索エンジンをラップするメインクラスです。

new \Laurus\Index(?string $path = null, ?Schema $schema = null, ?WalSyncPolicy $wal_sync_policy = null, ?CommitPolicy $commit_policy = null)

コンストラクタ

ファイルベースインデックスの作成 vs 再オープン（$path を指定した場合）: <path>/schema.toml がまだ存在しない場合、この呼び出しは新規インデックスを作成し、$schema（省略時は空のスキーマ）をそこに永続化します。<path>/schema.toml が既に存在する場合、この呼び出しは既存インデックスを再オープンします – $schema は省略しなければならず、指定すると ValueError が投げられます（どちらのスキーマを優先すべきか曖昧になるため）。$path がこの規約導入以前のレイアウト（schema.toml が無く、セグメントファイルが $path 直下にある）のインデックスを含んでいる場合も ValueError になります。

メソッド

search の query 引数

$query パラメータは以下のいずれかを受け付けます：

• DSL 文字列（例: "title:hello"、"embedding:\"memory safety\"")
• Lexical クエリオブジェクト（TermQuery、PhraseQuery、BooleanQuery など）
• Vector クエリオブジェクト（VectorQuery、VectorTextQuery）
• SearchRequest（完全な制御が必要な場合）

searchBatch の $queries 配列の各要素も同じ種類の値を受け付けます。DSL 文字列・クエリオブジェクト・SearchRequest を 1 つのバッチ内で混在させることもできます。

ハイライト

search/searchBatch の $highlight パラメータ（Issue #1134）は、各ヒットの SearchResult::getHighlights() にフィールドごとのハイライト済みフラグメントを要求します。以下のいずれかを受け付けます。

• フィールド名のリスト: ["body"]
• 連想配列: 必須の "fields" キーに加えて、HighlightConfig の任意の設定（max_fragments、fragment_size、tag、css_class、require_field_match、max_analyzed_chars、return_entire_field_if_no_highlight）を指定 — 例: ["fields" => ["body"], "tag" => "em", "max_fragments" => 2]

$results = $index->search("body:rust", 10, 0, ["body"]);
$results[0]->getHighlights(); // ["body" => ["<mark>Rust</mark> is a systems programming language."]]

ハイライトは search/searchBatch に渡したクエリ（または SearchRequest の $query/$lexicalQuery、下記参照）に従い、stored: true のテキストフィールドのみハイライト可能です。存在しない、保存されていない、テキスト型でないフィールドは黙ってスキップされます。$highlight を省略すると、すべての結果のハイライトは空のままになります。同じ highlight 引数は SearchRequest のコンストラクタでも使用できます。

WAL 同期ポリシーと耐久性

先行書き込みログ（WAL: Write-Ahead Log）は、コミット済みデータをクラッシュ から保護します。デフォルトでは WAL は完全に耐久的で、すべてのレコードは 書き込みが返る前に fsync されます。group commit（グループコミット） を有効にすると、fsync 呼び出しをまとめることで、耐久性をいくらか引き換えに 書き込みスループットを向上させられます。

WalSyncPolicy

Laurus\WalSyncPolicy は WAL のフラッシュ方法を記述するイミュータブルな 値オブジェクトです。Index コンストラクタの $wal_sync_policy 引数に渡します。

// デフォルト: 書き込みごとに耐久（各レコードを個別に fsync）。
\Laurus\WalSyncPolicy::perRecord(): WalSyncPolicy

// Group commit: fsync をまとめてコストを償却。
\Laurus\WalSyncPolicy::group(
    ?int $max_records = null,      // このレコード数でフラッシュ（デフォルト 1024）
    ?int $max_bytes = null,        // このバイト数でフラッシュ（デフォルト 1 MiB）
    ?int $max_interval_ms = null,  // このミリ秒ごとに定期的にもフラッシュ
): WalSyncPolicy

Group commit は SQLite の synchronous = NORMAL に相当します。クラッシュ時に 失われるのは最後の未同期バッチのレコードまでで、インデックスが破損する ことはありません。レコードは常に commit() 時に耐久化されるため、成功した commit() はポリシーに関わらず耐久バリアとなります。

フラッシュの強制

コミットの合間に耐久バリアを強制するには flushWal() を呼び出します。 例えば、バッチが安全に永続化されたことを通知する前などです。未同期の レコードを同期的に fsync します。デフォルトのレコードごとポリシーでは 実質的に no-op です。

// group commit を有効にし、必要に応じて耐久性を強制する。
$policy = \Laurus\WalSyncPolicy::group(4096, 4 * 1024 * 1024);
$index = new \Laurus\Index("./myindex", null, $policy);

$index->putDocument("doc1", ["title" => "Hello"]);
$index->flushWal(); // group バッチが満杯でなくてもレコードが永続化される

コミットポリシーと自動コミット

コミットは、バッファリングされた書き込みを Lexical ストアと Vector ストアに 実体化（materialise）し、保留中の変更を検索可能にします。デフォルトでは Laurus が自動でコミットすることはなく、呼び出し側がすべての commit() を 駆動します。代わりに、適用したドキュメント数が一定に達するたびに、あるいは 一定の時間間隔ごとに、エンジンに **自動コミット（auto-commit）**させることも できます。

CommitPolicy

Laurus\CommitPolicy はエンジンがいつコミットするかを記述するイミュータブルな 値オブジェクトです。Index コンストラクタの $commit_policy 引数に渡します。

// デフォルト: 自動コミットなし — 呼び出し側がすべての commit() を駆動。
\Laurus\CommitPolicy::manual(): CommitPolicy

// 適用したドキュメント N 件ごとに自動コミット。
\Laurus\CommitPolicy::everyDocs(
    int $n,   // このドキュメント数を適用するたびにコミット
): CommitPolicy

// 少なくとも N ミリ秒ごとに自動コミット（ネイティブ専用。wasm では no-op）。
\Laurus\CommitPolicy::intervalMs(
    int $ms,   // 少なくともこの間隔（ミリ秒）でコミット
): CommitPolicy

CommitPolicy::everyDocs(0) は有効で、自動コミットを無効化します。 CommitPolicy::manual() と等価です。

コミットポリシーは WAL 同期ポリシーと**直交（orthogonal）**しています。 WalSyncPolicy は耐久性のために WAL をいつ fsync するかを制御するのに対し、 CommitPolicy はストアをいつ実体化し、保留中の変更をいつ検索可能にするかを 制御します。両者は独立して設定します。

// 適用したドキュメント 1000 件ごとに自動コミットし、WAL ポリシーはデフォルトを維持。
$index = new \Laurus\Index(null, $schema, null, \Laurus\CommitPolicy::everyDocs(1000));

foreach ($docs as $id => $doc) {
    $index->putDocument($id, $doc); // エンジンが 1000 件ごとに自動でコミットする
}

Schema

Index のフィールドとインデックスタイプを定義します。

new \Laurus\Schema()

フィールドメソッド

ベクトル量子化とリランクストレージ（HNSW フィールド）:

• quantizer — "scalar_8bit"（デフォルト、4 倍圧縮）または高圧縮率の "product_quantization"。Product quantization では subvectorCount（dimension を割り切れる値）が必須です。
• rerankStorage — "f32" を指定すると完全精度の *.hnsw.f32 サイドカーを書き出し、厳密な Stage-2 リランクを有効化します。省略すると int8 のみのセグメントを維持します。
• pqCodebookPath — 共有 PQ codebook のストレージ相対ファイル名（Issue #631）。laurus train pq-codebook CLI コマンドで一度だけ学習します。$quantizer = "product_quantization" との組み合わせでのみ意味を持ち、以後の commit は segment ごとの k-means 再学習の代わりに学習済み codebook で encode します。省略すると segment ごとの学習を維持します。

上記のどの add*Field メソッドも、name が _（_id を除く）で始まる場合は \ValueError を投げ、フィールドを追加しない。fromToml / fromTomlFile で読み込んだスキーマはそのようなフィールドを引き続き受け付けるため、永続化済みのスキーマも読み込めるが、そこから新しい Index を作成すると \ValueError になる。詳細はフィールド命名規則を参照。

その他のメソッド

Dynamic field policy（動的フィールドポリシー）

ドキュメントに含まれるがスキーマに宣言されていないフィールドの扱いを制御します:

• "strict" — ドキュメントを拒否
• "dynamic"（デフォルト）— 各未宣言フィールドの型を推論してスキーマに追加。警告: integer フィールドに入ってきた float 値は静かに切り捨てられます（3.14 → 3）。厳密さが必要なら "strict" を使用してください
• "ignore" — 未宣言フィールドを静かに破棄

詳細な挙動マトリクスは スキーマとフィールド を参照してください。

エンベダータイプ

各型の説明を含む正規のリファレンスは スキーマフォーマットリファレンス → エンベダー を参照してください。

"candle_colbert" はトークンごとに 1 本のベクトルを出力するため、MultiVector フィールド（addMultiVectorField）専用です。

$schema->addEmbedder("colbert", ["type" => "candle_colbert", "model" => "colbert-ir/colbertv2.0"]);
$schema->addMultiVectorField("body_colbert", 128, null, "colbert");

アナライザーコンポーネント

addAnalyzer(string $name, array $tokenizer, ?array $charFilters = null, ?array $tokenFilters = null) および [analyzers.<name>] TOML セクションで使用します。$tokenizer は単一の 連想配列、$charFilters/$tokenFilters は連想配列の配列で、配列の順序で 適用されます。

各コンポーネントの説明を含む正規のリファレンスは スキーマフォーマットリファレンス → アナライザ を参照してください。

トークナイザー（$tokenizer、必ず1つ）:

Char filter（$charFilters、トークン化前の生テキストに適用）:

Token filter（$tokenFilters、トークン化後のトークン列に適用）:

$schema = new Laurus\Schema();
$schema->addAnalyzer(
    "ja_ipadic",
    ["type" => "lindera", "mode" => "normal", "dict" => "/var/lib/lindera/ipadic"],
    [
        ["type" => "unicode_normalization", "form" => "nfkc"],
        ["type" => "japanese_iteration_mark"],
    ],
    [["type" => "lowercase"]],
);
$schema->addTextField("title", analyzer: "ja_ipadic");

距離メトリクス

addMultiVectorField が受け付けるのは "cosine" と "dot_product" だけです。

クエリクラス

TermQuery

new \Laurus\TermQuery(string $field, string $term)

指定フィールドに完全一致する語句を含むドキュメントを検索します。

PhraseQuery

new \Laurus\PhraseQuery(string $field, array $terms)

指定した語句が順序どおりに含まれるドキュメントを検索します。$terms は文字列の配列です。

FuzzyQuery

new \Laurus\FuzzyQuery(string $field, string $term, int $maxEdits = 2)

編集距離が $maxEdits 以内の近似一致を検索します。

WildcardQuery

new \Laurus\WildcardQuery(string $field, string $pattern)

ワイルドカードパターン検索。* は任意の文字列、? は任意の1文字に一致します。

NumericRangeQuery

new \Laurus\NumericRangeQuery(string $field, mixed $min, mixed $max, ?string $numericType = "integer")

[$min, $max] の範囲内の数値を検索します。開いた境界には null を指定します。$numericType には "integer" または "float" を設定します。

DateTimeRangeQuery

new \Laurus\DateTimeRangeQuery(string $field, ?string $min = null, ?string $max = null)

[$min, $max] の範囲内（両端を含む）の DateTime 値を検索します。開いた境界には null を指定します。境界は Query DSL が受け付ける任意の形式の文字列リテラルです: RFC 3339（"2024-01-01T09:00:00+09:00"、UTC に正規化）、オフセットなしの "YYYY-MM-DDTHH:MM:SS[.fff]"（UTC）、または "YYYY-MM-DD"（その日の 0 時 UTC）。DateTimeInterface は $dt->format(DATE_RFC3339) で渡します。ext-php-rs のコンストラクタは失敗できないため、不正な境界はクエリの使用時（Index::search、BooleanQuery、SearchRequest）に \Throwable として報告されます。

GeoDistanceQuery

\Laurus\GeoDistanceQuery::withinRadius(
    string $field, float $lat, float $lon, float $distanceM,
): GeoDistanceQuery

地理的距離検索（半径指定）。指定した地点から $distanceM メートル以内の (lat, lon) 座標を持つドキュメントを返します。

GeoBoundingBoxQuery

\Laurus\GeoBoundingBoxQuery::withinBoundingBox(
    string $field,
    float $minLat, float $minLon,
    float $maxLat, float $maxLon,
): GeoBoundingBoxQuery

地理的範囲（バウンディングボックス）検索。軸並行 [$minLat, $maxLat] × [$minLon, $maxLon] 内の (lat, lon) 座標を持つドキュメントを返します。

Geo3dDistanceQuery

\Laurus\Geo3dDistanceQuery::withinSphere(
    string $field,
    float $x, float $y, float $z,
    float $distanceM,
): Geo3dDistanceQuery

3D ECEF 座標フィールドへの球距離検索。中心 (x, y, z) から $distanceM メートル以内 の座標を持つドキュメントを返します。ECEF の理論については Geo3d の概念 を参照。

Geo3dBoundingBoxQuery

\Laurus\Geo3dBoundingBoxQuery::withinBox(
    string $field,
    float $minX, float $minY, float $minZ,
    float $maxX, float $maxY, float $maxZ,
): Geo3dBoundingBoxQuery

軸並行 3D 範囲（AABB）検索。

Geo3dNearestQuery

\Laurus\Geo3dNearestQuery::kNearest(
    string $field,
    float $x, float $y, float $z,
    int $k,
    ?float $initialRadiusM = null,
    ?float $maxRadiusM = null,
): Geo3dNearestQuery

3D ECEF 座標フィールドへの k 最近傍検索。$initialRadiusM / $maxRadiusM （オプション）で反復拡張サーチの探索コーンを調整できます。

BooleanQuery

$bq = new \Laurus\BooleanQuery();
$bq->must($query);
$bq->should($query);
$bq->mustNot($query);

複合ブールクエリ。must 節はすべて一致する必要があり、mustNot 節は一致してはなりません。should 節はスコアリングに寄与し、must 節が無い場合は少なくとも1つが一致する必要があります。

SpanQuery

// 単一語句
\Laurus\SpanQuery::term(string $field, string $term): SpanQuery

// Near: slop 位置以内の語句
\Laurus\SpanQuery::near(string $field, array $terms, int $slop = 0, bool $ordered = true): SpanQuery

// NearSpans: slop 位置以内のネストされた SpanQuery 句
\Laurus\SpanQuery::nearSpans(string $field, array $clauses, int $slop = 0, bool $ordered = true): SpanQuery

// Containing: big スパンが little スパンを含む
\Laurus\SpanQuery::containing(string $field, SpanQuery $big, SpanQuery $little): SpanQuery

// Within: 最大距離での include スパンと exclude スパン
\Laurus\SpanQuery::within(string $field, SpanQuery $include, SpanQuery $exclude, int $distance): SpanQuery

位置・近接スパンクエリ。near は語句文字列の配列を受け取り、nearSpans は ネスト式のために SpanQuery オブジェクトの配列を受け取ります（各句のフィールド は外側の $field に再ルートされます）。

VectorQuery

new \Laurus\VectorQuery(string $field, array $vector)

事前計算済みエンベディングベクトルを使った近似最近傍検索を行います。$vector は Float の配列です。

VectorTextQuery

new \Laurus\VectorTextQuery(string $field, string $text)

クエリ時に $text をエンベディングに変換してベクトル検索を行います。インデックスにエンベダーの設定が必要です。

SearchRequest

高度な制御が必要な場合の完全なリクエストクラスです。

new \Laurus\SearchRequest(
    mixed $query = null,
    mixed $lexicalQuery = null,
    mixed $vectorQuery = null,
    mixed $filterQuery = null,
    mixed $fusion = null,
    int $limit = 10,
    int $offset = 0,
    ?array $highlight = null,
    ?LateInteractionRescore $rescore = null,
)

SearchRequest を Index->search() に渡すと、リクエスト自身の $limit・$offset・$highlight・$rescore が使われ、search の他の引数は無視されます。

LateInteractionRescore

上位の検索結果を late interaction（ColBERT の MaxSim）で再採点します（Issue #1351）。Index->search() の 5 番目の引数、または SearchRequest の $rescore に渡します。仕組みは Vector 検索 → Late Interaction による再採点 を参照してください。

new \Laurus\LateInteractionRescore(string $field, string|array $query, ?int $windowSize = null)

メソッド

並び順とスコア

1 段目（lexical・vector・ハイブリッド）の上位 $windowSize 件を、フィールドに対する MaxSim で並べ替えます。再採点した結果の getScore() は MaxSim の値です。window の外の結果は 1 段目の順位とスコアのまま、再採点した結果の後に続きます（フィールドにトークンベクトルを持たない window 内の結果は、両者の間に 1 段目の順で並びます）。2 種類のスコアは比較できません。

エラー

• コンストラクタは、$query が文字列でも数値リストのリストでもない場合に \TypeError（query must be a string or a list of numeric lists）を、トークンベクトルが bool や string など数値以外を含む場合に \Exception（token vector N must hold only numbers）を投げます。
• Index->search() と SearchRequest は、$rescore にそれ以外のオブジェクトを渡すと \TypeError（rescore must be a Laurus\LateInteractionRescore）を投げます。
• それ以外の値は検索時、検索を始める前にエンジンがチェックし、rescore: ... を含むメッセージの \ValueError を投げます。フィールドが存在しないか MultiVector フィールドでない場合、クエリがフィールドの次元を持つ有限値のベクトルを 1〜1,024 本含まない場合、テキストのクエリが空かフィールドにトークン単位のエンベダーがない場合、$windowSize が 1..=10,000 の範囲外の場合です。

例

$schema = new Laurus\Schema();
$schema->addTextField("title");
$schema->addMultiVectorField("tokens", 2, "dot_product");

$index = new Laurus\Index(null, $schema);
$index->putDocument("a", ["title" => "rust", "tokens" => [[0.1, 0.0]]]);
$index->putDocument("b", ["title" => "rust language", "tokens" => [[0.9, 0.2]]]);
$index->commit();

$rescore = new Laurus\LateInteractionRescore("tokens", [[1.0, 0.0], [0.0, 1.0]], 50);
$results = $index->search("title:rust", 10, 0, null, $rescore);
$results[0]->getId();    // "b"
$results[0]->getScore(); // ≈ 1.1 = 0.9 + 0.2（MaxSim）

// SearchRequest で同じ再採点を行う（9 番目の引数）
$results = $index->search(new Laurus\SearchRequest("title:rust", null, null, null, null, 10, 0, null, $rescore));

// テキストのクエリには、フィールドにトークン単位のエンベダーが必要（「エンベダータイプ」を参照）
$rescore = new Laurus\LateInteractionRescore("body_colbert", "how do lifetimes work");

SearchResult

Index->search() が返すクラスです。

$result->getId()          // string   -- 外部ドキュメント識別子
$result->getScore()       // float    -- 関連性スコア
$result->getDocument()    // array|null -- 取得されたフィールド値。stored=false の場合は null
$result->getHighlights()  // array    -- 要求したフィールドごとのハイライト済みフラグメント

getHighlights() は $highlight で指定した各フィールドをハイライト済みフラグメント（最も良いものが先頭）にマッピングします。ハイライトされなかったフィールドは配列に現れず、$highlight を要求しなかった場合は [] を返します。詳細はハイライトを参照してください。

フュージョンアルゴリズム

RRF

new \Laurus\RRF(float $k = 60.0)

逆順位フュージョン（Reciprocal Rank Fusion）。Lexical と Vector の結果リストを順位位置によってマージします。$k は平滑化定数で、値が大きいほど上位ランクの影響が小さくなります。

WeightedSum

new \Laurus\WeightedSum(float $lexicalWeight = 0.5, float $vectorWeight = 0.5)

両スコアリストをそれぞれ正規化した後、$lexicalWeight * lexical_score + $vectorWeight * vector_score として結合します。

テキスト解析

SynonymDictionary

$dict = new \Laurus\SynonymDictionary();
$dict->addSynonymGroup(["fast", "quick", "rapid"]);

同義語グループの辞書です。グループ内のすべての語句は互いの同義語として扱われます。

WhitespaceTokenizer

$tokenizer = new \Laurus\WhitespaceTokenizer();
$tokens = $tokenizer->tokenize("hello world");

空白で分割してテキストをトークン化し、Token オブジェクトの配列を返します。

SynonymGraphFilter

new \Laurus\SynonymGraphFilter(SynonymDictionary $dictionary, bool $keepOriginal = true, float $boost = 1.0)

$filter = new \Laurus\SynonymGraphFilter($dictionary, true, 1.0);
$expanded = $filter->apply($tokens);

SynonymDictionary の同義語でトークンを展開するトークンフィルターです。

Token

$token->getText()               // string  -- トークンテキスト
$token->getPosition()           // int     -- トークンストリーム内の位置
$token->getStartOffset()        // int     -- 元テキスト内の UTF-8 バイト開始オフセット
$token->getEndOffset()          // int     -- 元テキスト内の UTF-8 バイト終了オフセット
$token->getBoost()              // float   -- スコアブースト係数（1.0 = 調整なし）
$token->isStopped()             // bool    -- ストップフィルターによって除去されたかどうか
$token->getPositionIncrement()  // int     -- 前のトークンの位置との差分
$token->getPositionLength()     // int     -- このトークンがカバーする位置数
$token->getTokenType()          // ?string -- トークン種別（例: "alphanum"）

オフセットは PHP の文字列と同じくバイト数なので、substr($text, $start, $end - $start) でトークンのテキストを取り出せます。

getTokenType() は "alphanum"、"num"、"cjk"、"katakana"、"hiragana"、"hangul"、"punctuation"、"whitespace"、"synonym"、"email"、"url"、"other" のいずれか、または null を返します。SynonymGraphFilter::apply() は各トークンのオフセットと種別を保ち、挿入する同義語には種別 "synonym" と、置き換える語のオフセットを付けます。

フィールド値の型マッピング

PHP の値は自動的に Laurus の DataValue 型に変換されます：