API リファレンス

Index

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

class Index:
    def __init__(self, path: str | None = None, schema: Schema | None = None) -> None: ...

コンストラクタ

メソッド

search の query 引数

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

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

Schema

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

class Schema:
    def __init__(self) -> None: ...

フィールドメソッド

その他のメソッド

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

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

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

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

エンベダータイプ

距離メトリクス

クエリクラス

TermQuery

TermQuery(field: str, term: str)

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

PhraseQuery

PhraseQuery(field: str, terms: list[str])

指定した語句が順序どおりに含まれるドキュメントを検索します。

FuzzyQuery

FuzzyQuery(field: str, term: str, *, max_edits: int = 2)

編集距離が max_edits 以内の近似一致を検索します。max_edits はキーワード専用引数です。

WildcardQuery

WildcardQuery(field: str, pattern: str)

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

NumericRangeQuery

NumericRangeQuery(field: str, *, min: int | float | None = None, max: int | float | None = None)

[min, max] の範囲内の数値を検索します。開いた境界には None を指定する （または省略する）と開放されます。min と max はキーワード専用引数です。 数値型（整数または浮動小数点）は min/max の Python 型から推論されます。

GeoDistanceQuery

GeoDistanceQuery.within_radius(
    field: str, lat: float, lon: float, distance_m: float,
)

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

GeoBoundingBoxQuery

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

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

Geo3dDistanceQuery

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

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

Geo3dBoundingBoxQuery

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

軸並行 3D 範囲（AABB）検索。[min_x, max_x] × [min_y, max_y] × [min_z, max_z] 内 にある ECEF 座標を持つドキュメントを返します。

Geo3dNearestQuery

Geo3dNearestQuery.k_nearest(
    field: str,
    x: float, y: float, z: float,
    k: int,
    *,
    initial_radius_m: float | None = None,
    max_radius_m: float | None = None,
)

3D ECEF 座標フィールドへの k 最近傍検索。(x, y, z) から最も近い k 件のドキュ メントを返します。initial_radius_m / max_radius_m は反復拡張サーチの探索コーン を調整します。

BooleanQuery

bq = BooleanQuery()
bq.must(query)
bq.should(query)
bq.must_not(query)

複合ブールクエリ。引数なしでコンストラクタを呼び出し、must / should / must_not メソッドで節を一つずつ追加します。各メソッドは任意のクエリ オブジェクト（ネストされた BooleanQuery も含む）を受け付けます。

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

SpanQuery

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

# Near: slop 位置以内の語句
SpanQuery.near(field: str, terms: list[str], *, slop: int = 0, ordered: bool = True)

# ネストされた SpanQuery 句を使った Near
SpanQuery.near_spans(field: str, clauses: list[SpanQuery], *, slop: int = 0, ordered: bool = True)

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

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

位置・近接スパンクエリ。静的ファクトリメソッドで構築します。near は語句 文字列のリストを受け取り、near_spans はネスト式のために SpanQuery オブジェクトのリストを受け取ります。slop と ordered はキーワード専用 引数です。

VectorQuery

VectorQuery(field: str, vector: list[float])

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

VectorTextQuery

VectorTextQuery(field: str, text: str)

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

SearchRequest

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

class SearchRequest:
    def __init__(
        self,
        *,
        query=None,
        lexical_query=None,
        vector_query=None,
        filter_query=None,
        fusion=None,
        limit: int = 10,
        offset: int = 0,
    ) -> None: ...

SearchResult

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

class SearchResult:
    id: str          # 外部ドキュメント識別子
    score: float     # 関連性スコア
    document: dict | None  # 取得されたフィールド値。stored=False の場合は None

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

RRF

RRF(k: float = 60.0)

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

WeightedSum

WeightedSum(lexical_weight: float = 0.5, vector_weight: float = 0.5)

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

テキスト解析

SynonymDictionary

class SynonymDictionary:
    def __init__(self) -> None: ...
    def add_synonym_group(self, synonyms: list[str]) -> None: ...

WhitespaceTokenizer

class WhitespaceTokenizer:
    def __init__(self) -> None: ...
    def tokenize(self, text: str) -> list[Token]: ...

SynonymGraphFilter

class SynonymGraphFilter:
    def __init__(
        self,
        dictionary: SynonymDictionary,
        keep_original: bool = True,
        boost: float = 1.0,
    ) -> None: ...
    def apply(self, tokens: list[Token]) -> list[Token]: ...

Token

class Token:
    text: str
    position: int
    start_offset: int
    end_offset: int
    boost: float
    stopped: bool
    position_increment: int
    position_length: int

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

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