API リファレンス

Index

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

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

コンストラクタ

メソッド

search の query 引数

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

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

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

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 ごとの学習を維持します。

その他のメソッド

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

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

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

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

エンベダータイプ

距離メトリクス

クエリクラス

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" を設定します。

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

SearchResult

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

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

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

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     -- 元テキスト内の文字開始オフセット
$token->getEndOffset()          // int     -- 元テキスト内の文字終了オフセット
$token->getBoost()              // float   -- スコアブースト係数（1.0 = 調整なし）
$token->isStopped()             // bool    -- ストップフィルターによって除去されたかどうか
$token->getPositionIncrement()  // int     -- 前のトークンの位置との差分
$token->getPositionLength()     // int     -- このトークンがカバーする位置数

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

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