API リファレンス

Index

検索インデックスの作成・クエリを行うメインエントリポイントです。

静的メソッド

`Index.create(schema?)`

新しいインメモリ（一時）インデックスを作成します。

引数:
- schema (Schema, 省略可) – スキーマ定義
戻り値: Promise<Index>

`Index.open(name, schema?)`

OPFS で永続化されたインデックスを開くか、新規作成します。

引数:
- name (string) – インデックス名（OPFS サブディレクトリ）
- schema (Schema, 省略可) – スキーマ定義
戻り値: Promise<Index>

インスタンスメソッド

`putDocument(id, document)`

ドキュメントを置換（upsert）します。

引数:
- id (string) – ドキュメント識別子
- document (object) – スキーマフィールドに対応するキーバリューペア
戻り値: Promise<void>

`addDocument(id, document)`

ドキュメントバージョンを追加します（マルチバージョン RAG パターン）。

引数・戻り値: putDocument と同じ

`getDocuments(id)`

ドキュメントの全バージョンを取得します。

引数: id (string)
戻り値: Promise<object[]>

`deleteDocuments(id)`

ドキュメントの全バージョンを削除します。

引数: id (string)
戻り値: Promise<void>

`commit()`

書き込みをフラッシュし、変更を検索可能にします。 Index.open() で作成したインデックスの場合、OPFS にも自動永続化されます。

戻り値: Promise<void>

`search(query, limit?, offset?)`

DSL 文字列クエリで検索します。

引数:
- query (string) – クエリ DSL（例: "title:hello"）
- limit (number, デフォルト 10)
- offset (number, デフォルト 0)
戻り値: Promise<SearchResult[]>

`searchTerm(field, term, limit?, offset?)`

完全一致タームで検索します。

引数:
- field (string) – フィールド名
- term (string) – 検索ターム
- limit, offset (number, 省略可)
戻り値: Promise<SearchResult[]>

`searchVector(field, vector, limit?, offset?)`

ベクトル類似度で検索します。

引数:
- field (string) – ベクトルフィールド名
- vector (number[]) – クエリ埋め込みベクトル
- limit, offset (number, 省略可)
戻り値: Promise<SearchResult[]>

`searchVectorText(field, text, limit?, offset?)`

テキストで検索します（登録された埋め込み器で変換）。

引数:
- field (string) – ベクトルフィールド名
- text (string) – 埋め込み対象テキスト
- limit, offset (number, 省略可)
戻り値: Promise<SearchResult[]>

`searchGeo3dDistance(field, x, y, z, distanceM, limit?, offset?)`

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

引数:
- field (string) – Geo3d フィールド名
- x, y, z (number) – 中心 ECEF 座標（メートル）
- distanceM (number) – 中心からの最大距離（メートル）
- limit, offset (number, 省略可)
戻り値: Promise<SearchResult[]>

`searchGeo3dBoundingBox(field, minX, minY, minZ, maxX, maxY, maxZ, limit?, offset?)`

3D ECEF 座標フィールドへの軸並行範囲（AABB）検索。

引数:
- field (string) – Geo3d フィールド名
- minX, minY, minZ, maxX, maxY, maxZ (number) – 範囲境界（メートル）
- limit, offset (number, 省略可)
戻り値: Promise<SearchResult[]>

`searchGeo3dNearest(field, x, y, z, k, limit?, offset?, initialRadiusM?, maxRadiusM?)`

3D ECEF 座標フィールドへの k 最近傍検索。(x, y, z) から最も近い k 件のドキュメントを返します。initialRadiusM / maxRadiusM（オプション）で反復拡張サーチの探索コーンを調整できます。

引数:
- field (string) – Geo3d フィールド名
- x, y, z (number) – 中心 ECEF 座標（メートル）
- k (number) – 返す近傍件数
- limit, offset (number, 省略可)
- initialRadiusM, maxRadiusM (number, 省略可)
戻り値: Promise<SearchResult[]>

`stats()`

インデックス統計を返します。

戻り値: { documentCount: number, vectorFields: { [name]: { count, dimension } } }

Schema

インデックスフィールドと埋め込み器を定義するビルダーです。

メソッド

`addTextField(name, stored?, indexed?, termVectors?, analyzer?)`

全文検索テキストフィールドを追加します。analyzer にはパラメータ不要の組込名（"standard" / "english" / "keyword" / "simple" / "noop"）または addAnalyzer() で登録したランタイム analyzer 名を指定します。

日本語の形態素解析を行う場合は、まず JapaneseAnalyzer を IPADIC のバイト列から構築し、addAnalyzer() で登録してください。 JapaneseAnalyzer.fromBytes と addAnalyzer を参照。

`addIntegerField(name, stored?, indexed?, multiValued?)`

64 ビット整数フィールドを追加します。multiValued: true を指定すると整数配列を受け付け、範囲クエリはいずれかの値が条件を満たせばマッチ（Lucene 流の “any match”、constant スコア）します。

`addFloatField(name, stored?, indexed?, multiValued?)`

64 ビット浮動小数点フィールドを追加します。multiValued: true を指定すると浮動小数点配列を受け付け、範囲クエリはいずれかの値が条件を満たせばマッチ（Lucene 流の “any match”、constant スコア）します。

`addBooleanField(name, stored?, indexed?)`

真偽値フィールドを追加します。

`addDatetimeField(name, stored?, indexed?)`

日時フィールドを追加します。

`addGeoField(name, stored?, indexed?)`

地理座標フィールドを追加します。

`addGeo3dField(name, stored?, indexed?)`

3D ECEF カルテシアン座標フィールド（x, y, z はメートル）を追加します。値は { x, y, z } オブジェクトで投入します。詳細は Geo3d の概念を参照。

WASM バインディングは Geo3dDistanceQuery / Geo3dBoundingBoxQuery / Geo3dNearestQuery を JS クラスとして公開していません（wasm-bindgen は dyn Query トレイトオブジェクトを公開できないため）。代わりに上記の Index.searchGeo3dDistance / Index.searchGeo3dBoundingBox / Index.searchGeo3dNearest メソッドを使用してください。

`addBytesField(name, stored?)`

バイナリデータフィールドを追加します。

`addHnswField(name, dimension, distance?, m?, efConstruction?, embedder?)`

HNSW ベクトルインデックスフィールドを追加します。

distance: "cosine"（デフォルト）、"euclidean"、"dot_product"、"manhattan"、"angular"
m: 分岐係数（デフォルト 16）
efConstruction: 構築時の探索幅（デフォルト 200）

`addFlatField(name, dimension, distance?, embedder?)`

全探索ベクトルインデックスフィールドを追加します。

`addIvfField(name, dimension, distance?, nClusters?, nProbe?, embedder?)`

IVF ベクトルインデックスフィールドを追加します。

nClusters: パーティショニングクラスタ数（デフォルト 100）
nProbe: 検索時にプローブするクラスタ数（デフォルト 1）

`addAnalyzer(name, analyzer)`

事前に構築した analyzer インスタンスを name で登録します。テキストフィールドが Named 形式で analyzer を参照するときに、組込名や schema.analyzers 定義よりも先に解決されます。

現状は JapaneseAnalyzer.fromBytes で構築した JapaneseAnalyzer のみ受け付けます。ブラウザ WASM では { "language": "japanese", "dict": ... } プリセットがファイルシステムパスを解決できないため、ランタイムレジストリ経由が日本語 analyzer を利用する唯一の現実的な経路です。

import { JapaneseAnalyzer, Schema } from "laurus-wasm";
import { downloadDictionary, loadDictionaryFiles } from "laurus-wasm/opfs";

await downloadDictionary("./dict/lindera-ipadic.zip", "ipadic");
const f = await loadDictionaryFiles("ipadic");
const ja = JapaneseAnalyzer.fromBytes(
  f.metadata, f.dictDa, f.dictVals, f.dictWordsIdx,
  f.dictWords, f.matrixMtx, f.charDef, f.unk, "normal",
);

const schema = new Schema();
schema.addAnalyzer("ja-ipadic", ja);
schema.addTextField("body", undefined, undefined, undefined, "ja-ipadic");

`addEmbedder(name, config)`

名前付き埋め込み器を登録します。WASM では以下の 2 種類の type をサポートします:

"precomputed" — 埋め込みは行いません。ベクトルは putDocument() / searchVector() 経由で直接渡します。
"callback" — JavaScript コールバック embed: (text) => Promise<number[]> を登録します。エンジンがインジェスト時および searchVectorText() で呼び出します。 Transformers.js などのブラウザ内埋め込みライブラリと組み合わせることで、エンジン内自動埋め込みが可能になります。

// Precomputed embedder
schema.addEmbedder("precomputed-embedder", { type: "precomputed" });

// Callback embedder（例: Transformers.js）
schema.addEmbedder("callback-embedder", {
  type: "callback",
  embed: async (text) => {
    const output = await pipeline(text, { pooling: "mean", normalize: true });
    return Array.from(output.data);
  },
});

`setDefaultFields(fields)`

デフォルト検索フィールドを設定します。

`setDynamicFieldPolicy(policy)`

ドキュメントに含まれるがスキーマに宣言されていないフィールドの扱いを設定します。policy は "strict" / "dynamic"（デフォルト）/ "ignore" のいずれか（大文字小文字を無視）。不正な値を渡すと例外をスローします。

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

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

`dynamicFieldPolicy()`

現在のポリシーを小文字の文字列で返します。

`fieldNames()`

定義済みフィールド名の配列を返します。

`toString()`

スキーマの文字列表現（"Schema(fields=[...])" 形式）を返します。

SearchResult

interface SearchResult {
  id: string;
  score: number;
  document: object | null;
}

Analysis

JapaneseAnalyzer

Lindera 辞書のバイト列から構築する日本語形態素解析 analyzer。ブラウザ WASM には実ファイルシステムが無いため、標準の { "language": "japanese", "dict": "/path/to/ipadic" } プリセットは利用できません。代わりに Lindera 辞書アーカイブ（典型的には lindera-ipadic-X.Y.Z.zip）を取得して OPFS ヘルパで OPFS に保存し、8 つのコンポーネントバイト配列を JapaneseAnalyzer.fromBytes に渡してください。

`JapaneseAnalyzer.fromBytes(metadata, dictDa, ..., mode?)`

IPADIC のバイト列から analyzer を構築する static ファクトリ。

引数（mode 以外はすべて Uint8Array）:

引数	対応するファイル
`metadata`	`metadata.json`
`dictDa`	`dict.da`（Double-Array Trie）
`dictVals`	`dict.vals`
`dictWordsIdx`	`dict.wordsidx`
`dictWords`	`dict.words`
`matrixMtx`	`matrix.mtx`
`charDef`	`char_def.bin`
`unk`	`unk.bin`
`mode`	`"normal"`（デフォルト）/ `"search"` / `"decompose"`

いずれかのコンポーネントの deserialization に失敗した場合、または mode 文字列が不正な場合は throw します。

import { JapaneseAnalyzer } from "laurus-wasm";
import { loadDictionaryFiles } from "laurus-wasm/opfs";

const f = await loadDictionaryFiles("ipadic");
const ja = JapaneseAnalyzer.fromBytes(
  f.metadata, f.dictDa, f.dictVals, f.dictWordsIdx,
  f.dictWords, f.matrixMtx, f.charDef, f.unk,
  "normal",
);

パイプラインは NFKC 正規化 → 日本語 iteration mark 正規化 → Lindera 形態素解析 → lowercase → 日本語 stop word フィルタ で、ネイティブ側の japanese プリセットと完全に一致します。

OPFS ヘルパ

laurus-wasm/opfs サブパスは、Lindera 辞書をブラウザの Origin Private File System にダウンロード・保存・読込するヘルパを提供します。 JapaneseAnalyzer.fromBytes と組み合わせて使用します。

import {
  downloadDictionary,
  loadDictionaryFiles,
  hasDictionary,
  listDictionaries,
  removeDictionary,
} from "laurus-wasm/opfs";

関数	説明
`downloadDictionary(url, name, options?)`	`.zip` を fetch し、Web の `DecompressionStream` API で展開して、Lindera 8 ファイルを OPFS の `laurus/dictionaries/<name>/` 配下に保存します。`options.onProgress({ phase, loaded?, total? })` で進捗通知を受け取れます。
`loadDictionaryFiles(name)`	8 ファイルを `{ metadata, dictDa, dictVals, dictWordsIdx, dictWords, matrixMtx, charDef, unk }` オブジェクトとして読み出し、`JapaneseAnalyzer.fromBytes` にそのまま渡せる形にします。
`hasDictionary(name)`	辞書ディレクトリが OPFS にあれば `true`。
`listDictionaries()`	保存済み辞書名の配列を返します。
`removeDictionary(name)`	辞書ディレクトリを削除します。

ブラウザ CORS の制約により GitHub Releases から直接 fetch できないため、 zip はアプリと同一オリジンで配信してください（Laurus デモではデプロイ時に ./dict/lindera-ipadic.zip を WASM と同じパスに同梱します）。

WhitespaceTokenizer

const tokenizer = new WhitespaceTokenizer();
const tokens = tokenizer.tokenize("hello world");
// [{ text, position, startOffset, endOffset, boost, stopped, positionIncrement, positionLength }]

空白を境界としてテキストを分割し、Token オブジェクトの配列を返します。

SynonymDictionary

const dict = new SynonymDictionary();
dict.addSynonymGroup(["ml", "machine learning"]);

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

SynonymGraphFilter

new SynonymGraphFilter(dictionary, keepOriginal = true, boost = 1.0)

dictionary (SynonymDictionary) — 同義語グループのソース。
keepOriginal (boolean, デフォルト true) — 元のトークンを挿入された同義語と並べて保持します。
boost (number, デフォルト 1.0) — 挿入される同義語トークンに適用されるスコアブースト。

const filter = new SynonymGraphFilter(dict, true, 0.8);
const expanded = filter.apply(tokens);

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

Keyboard shortcuts

Laurus ドキュメント