API リファレンス

Index

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

Laurus::Index.new(path: nil, schema: nil)

コンストラクタ

メソッド

search の query 引数

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

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

Schema

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

Laurus::Schema.new

フィールドメソッド

その他のメソッド

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

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

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

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

エンベダータイプ

距離メトリクス

クエリクラス

TermQuery

Laurus::TermQuery.new(field, term)

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

PhraseQuery

Laurus::PhraseQuery.new(field, terms)

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

FuzzyQuery

Laurus::FuzzyQuery.new(field, term, max_edits: 2)

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

WildcardQuery

Laurus::WildcardQuery.new(field, pattern)

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

NumericRangeQuery

Laurus::NumericRangeQuery.new(field, min: nil, max: nil)

[min, max] の範囲内の数値を検索します。開いた境界には nil を指定します。型（整数または浮動小数点）は min/max の Ruby 型から推論されます。

GeoDistanceQuery

Laurus::GeoDistanceQuery.within_radius(field, lat, lon, distance_m)

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

GeoBoundingBoxQuery

Laurus::GeoBoundingBoxQuery.within_bounding_box(
  field, min_lat, min_lon, max_lat, max_lon,
)

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

Geo3dDistanceQuery

Laurus::Geo3dDistanceQuery.within_sphere(field, x, y, z, distance_m)

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

Geo3dBoundingBoxQuery

Laurus::Geo3dBoundingBoxQuery.within_box(
  field,
  min_x, min_y, min_z,
  max_x, max_y, max_z,
)

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

Geo3dNearestQuery

Laurus::Geo3dNearestQuery.k_nearest(
  field, x, y, z, k,
  initial_radius_m: nil,
  max_radius_m: nil,
)

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

BooleanQuery

bq = Laurus::BooleanQuery.new
bq.must(query)
bq.should(query)
bq.must_not(query)

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

SpanQuery

# 単一語句
Laurus::SpanQuery.term(field, term)

# Near: slop 位置以内の語句
Laurus::SpanQuery.near(field, terms, slop: 0, ordered: true)

# ネストされた SpanQuery 句を使った Near
Laurus::SpanQuery.near_spans(field, clauses, slop: 0, ordered: true)

# Containing: big スパンが little スパンを含む
Laurus::SpanQuery.containing(field, big, little)

# Within: 最大距離での include スパンと exclude スパン
Laurus::SpanQuery.within(field, include_span, exclude_span, distance)

位置・近接スパンクエリ。near は語句文字列の配列を受け取り、near_spans はネスト式のために SpanQuery オブジェクトの配列を受け取ります。

VectorQuery

Laurus::VectorQuery.new(field, vector)

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

VectorTextQuery

Laurus::VectorTextQuery.new(field, text)

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

SearchRequest

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

Laurus::SearchRequest.new(
  query: nil,
  lexical_query: nil,
  vector_query: nil,
  filter_query: nil,
  fusion: nil,
  limit: 10,
  offset: 0,
)

SearchResult

Index#search が返すクラスです。

result.id        # => String   -- 外部ドキュメント識別子
result.score     # => Float    -- 関連性スコア
result.document  # => Hash|nil -- 取得されたフィールド値。削除済みの場合は nil

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

RRF

Laurus::RRF.new(k: 60.0)

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

WeightedSum

Laurus::WeightedSum.new(lexical_weight: 0.5, vector_weight: 0.5)

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

テキスト解析

SynonymDictionary

dict = Laurus::SynonymDictionary.new
dict.add_synonym_group(["fast", "quick", "rapid"])

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

WhitespaceTokenizer

tokenizer = Laurus::WhitespaceTokenizer.new
tokens = tokenizer.tokenize("hello world")

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

SynonymGraphFilter

filter = Laurus::SynonymGraphFilter.new(dictionary, keep_original: true, boost: 1.0)
expanded = filter.apply(tokens)

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

Token

token.text                # => String  -- トークンテキスト
token.position            # => Integer -- トークンストリーム内の位置
token.start_offset        # => Integer -- 元テキスト内の文字開始オフセット
token.end_offset          # => Integer -- 元テキスト内の文字終了オフセット
token.boost               # => Float   -- スコアブースト係数（1.0 = 調整なし）
token.stopped             # => Boolean -- ストップフィルターによって除去されたかどうか
token.position_increment  # => Integer -- 前のトークンの位置との差分
token.position_length     # => Integer -- このトークンがカバーする位置数

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

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