lakebase_tokenizer

lakebase_tokenizer拡張機能は、LakebaseのPostgreSQL全文検索に設定可能な全ワードトークン化を追加します。拡張機能で構築されたテキスト検索構成は、 to_tsvector、 @@ 演算子、ランキング関数、GINインデックスと連携します。生成された tsvector 値と lakebase_text を組み合わせてBM25のランキングを作成することもできます。

この拡張機能はPostgreSQLの標準的なテキスト検索辞書インターフェースを通じて tokenizer_wholeword テンプレートを提供します。このテンプレートは小文字変換、Unicode正規化、アクセント除去、英語所有格削除、カスタムストップワード、1対1の同義語、英語の語幹処理をサポートしています。

Install

拡張機能をデータベースにインストールしてください。このページの例は、拡張オブジェクトを容易に識別するために専用のスキーマを使用しています:

CREATE SCHEMA IF NOT EXISTS tokenizer_ext;
CREATE EXTENSION IF NOT EXISTS lakebase_tokenizer WITH SCHEMA tokenizer_ext;

延長は配置可能です。インストール時に別のスキーマに置き換え tokenizer_ext 可能です。

拡張機能をアップグレードする

新しいLakebase Searchリリースは、機能、修正、パフォーマンス向上を追加できます。 PostgreSQLはインストールされた拡張機能のバージョンを自動的に更新しません。インストール済みの最新バージョンを確認してください:

SELECT installed_version, default_version
FROM pg_available_extensions
WHERE name = 'lakebase_tokenizer';

拡張機能を最新の利用可能なバージョンに更新してください:

ALTER EXTENSION lakebase_tokenizer UPDATE;

ALTER EXTENSION 保存された tsvector 値を再生したり、依存するGINや lakebase_bm25 インデックスを再構築したりしません。更新でトークン化出力が変更された場合は、保存された tsvector 値を再生成し、必要なインデックスメンテナンスのためにリリースノートに従ってください。

クイックスタート `tokenizer_wholeword`

以下の例は、 tokenizer_wholeword テンプレートから辞書を作成し、一般的なPostgreSQLトークン型をテキスト検索構成でマッピングします。

CREATE TEXT SEARCH DICTIONARY documents_dict (
  TEMPLATE          = tokenizer_ext.tokenizer_wholeword,
  Lowercase         = 'true',
  StripAccents      = 'true',
  Stemmer           = 'english'
);

CREATE TEXT SEARCH CONFIGURATION documents_cfg (COPY = pg_catalog.simple);

ALTER TEXT SEARCH CONFIGURATION documents_cfg
  ALTER MAPPING FOR asciiword, word, numword, hword_numpart, hword_part, hword_asciipart
  WITH documents_dict;

この構成を使って tsvectorを作成し、GINインデックスを作成し、全文クエリを実行します:

CREATE TABLE documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('documents_cfg', body)
  ) STORED
);

INSERT INTO documents (body) VALUES
  ('Cats are running near the café.'),
  ('A dog is sleeping in the house.');

CREATE INDEX documents_search_idx ON documents USING gin (search_vector);

SELECT id, body
FROM documents
WHERE search_vector @@ plainto_tsquery('documents_cfg', 'running café');

文書とクエリの両方に同じテキスト検索構成を用い、両者が同じトークン化戦略とオプションを適用できるようにします。

テンプレート: `tokenizer_wholeword`

どのように機能するのか

PostgreSQLのテキストサーチパーサーによって辞書に渡された各トークンに対して、 tokenizer_wholeword 以下の操作を適用します:

Lowercase: トークンを小文字に変換してください。
Normalize: Unicode正規化を適用してください。
StripAccentsアクセントを取り除く。
EnglishPossessive: 少なくとも1文字が残っている場合は英語所有接尾辞を外してください。
Stopwords: トークンが設定されたストップワードに一致する場合は、語彙を放出せず処理を停止します。トークンは生成された tsvectorから除外されます。
Synonyms: 設定済みの置換を発行し、トークンが同義語に一致した場合は処理を停止します。
Stemmer: 同義語が一致せず、語幹が有効の場合は英語語幹を適用します。

ストップワードや同義語の追加

tokenizer_wholewordテンプレートは、拡張管理のSQLテーブルlakebase_tokenizer_stopwordsおよびlakebase_tokenizer_synonymsからカスタムストップワードや同義語を読み込むことができます。 name列は行をグループ化し、Stopwordsまたは辞書Synonymsオプションで選択します。

INSERT INTO tokenizer_ext.lakebase_tokenizer_stopwords (name, word) VALUES
  ('app_stopwords', 'the'),
  ('app_stopwords', 'and'),
  ('app_stopwords', 'or');

INSERT INTO tokenizer_ext.lakebase_tokenizer_synonyms (name, word, synonym) VALUES
  ('app_synonyms', 'usa', 'united_states'),
  ('app_synonyms', 'uk', 'united_kingdom');

tokenizer_wholeword辞書を作成または変更する際には、集合を参照してください:

ALTER TEXT SEARCH DICTIONARY documents_dict (
  Stopwords = 'app_stopwords',
  Synonyms  = 'app_synonyms'
);

この拡張機能は、 Lowercase、 Normalize、 StripAccents、 EnglishPossessiveを適用した後、かつ Stemmerを適用する前に、各トークンとストップワードや同義語のソースワードを比較します。カタログエントリーは自動的に変換されないため、有効にしたオプションで生成される正確な形式で保存してください。

Lowercase = 'true'では小文字のエントリを使いましょう。 Lowercase = 'false'では、大文字の大きさがトークンと一致しなければなりません。
Normalizeを有効にした状態で、選択したUnicode正規化フォームにエントリーを保存します。
StripAccents = 'true'ではアクセントのないフォームを保管してください。例えば、caféに合わせてcafeを保存します。
ステムをする前にフォームを保管してください。例えば、 Stemmer = 'english'の場合、 run の項目は runningと一致しません。 runningを追加してそのトークンをフィルターしたり置き換えたりしてください。

セット名は最大256バイトまで含めることができます。単語や同義語は最大1024バイトまで含めることができます。各名前付きストップワードまたはシノニムセットは最大100,000行を含みます。

同義語置換は保存されたままのまま放射され、ステマーによって処理されません。同義語は、各出典語に対して1つの置き換えを推奨します。複数語置換を1つの語素として表現するには、 united_statesのようにアンダースコアなどの区切り子を使います。

セットを変更した後、その集合を参照する各辞書の所有者は、リロードを強制するために no-op ALTER TEXT SEARCH DICTIONARY を実行しなければなりません。

ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);

dummyオプションはtokenizer_wholewordには存在しません。値を省略すると、PostgreSQLにこの存在しないオプションを削除してもらい、辞書の設定オプションを変更することなくキャッシュが無効化されます。

辞書を再読み込みした後、元の行を書き換えて保存された tsvector 値を再生成します:

UPDATE documents SET body = body;

役割とアクセス

アプリケーションアクセスとトークナイザー管理を分離するために2つの役割を使いましょう:

app_role 既存の辞書を使用しています。関連するスキーマや拡張カタログテーブルのSELECTUSAGEが必要ですが、辞書を所有する必要はありません。
tokenizer_admin ストップワードおよびシノニムセットの管理、辞書およびテキスト検索構成の作成・所有、セット変更後にリロードコマンドを実行します。

拡張スキーマとカタログテーブルへのアクセスを許可する:

GRANT USAGE ON SCHEMA tokenizer_ext TO app_role, tokenizer_admin;

GRANT SELECT ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO app_role;

GRANT SELECT, INSERT, UPDATE, DELETE ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO tokenizer_admin;

tokenizer_admin 辞書やテキスト検索設定が格納されているスキーマにも CREATE が必要です。これらのオブジェクトを tokenizer_adminとして作成するか、所有権を移転します。カタログテーブルへの書き込みアクセスは既存の辞書の所有権を付与しません。

オプション

tokenizer_wholeword選択肢をCREATE TEXT SEARCH DICTIONARYまたはALTER TEXT SEARCH DICTIONARYで指定してください。オプション名は大文字と大文字を区別しません。

オプション	タイプ	Default	Description
`Lowercase`	boolean	`true`	他の操作を適用する前にトークンを小文字に変換します。 `Stemmer = 'english'` には `Lowercase = 'true'`が必要です。
`Normalize`	`NFC`、`NFD`、`NFKC`、`NFKD`、または `none`	`none`	選択したUnicode正規化形式を適用します。これにより表現は正統化されますが、キャラクターは削除されません。例えば、 `NFC` はあらかじめ構成された `é` と `e` を、その後に結合した急性アクセントの等価音を作っています。
`EnglishPossessive`	boolean	`true`	接尾辞の前に少なくとも1文字の文字が続く場合は、 `'s`、 `’s`、または `＇s` の後ろを除去します。独立した接尾辞は変更されていません。
`StripAccents`	boolean	`false`	NFKD正規化を適用し、結合マークを除去します。たとえば、`café` を `cafe` にします。このオプションを有効にすると、NFKDステップにより個別のUnicode正規化が不要になるため、 `Normalize` を省略してください。
`Stopwords`	セット名	なし	`tokenizer_ext.lakebase_tokenizer_stopwords`の命名された集合を使用しています。
`Synonyms`	セット名	なし	`tokenizer_ext.lakebase_tokenizer_synonyms`の1対1の代替セットを使用しています。
`Stemmer`	`english`	なし	バンドルされたSnowball 3.1.0英語ステマーを使用しています。ステミングを無効にするこのオプションは省略してください。ステマーにはストップワードリストは含まれていません。

カタログテーブル

テーブル	Columns	Description
`lakebase_tokenizer_stopwords`	`name text`、`word text`	トークナイザーテンプレート用の名前付きストップワードセットをストアし、 `Stopwords`をサポートします。主キーは `(name, word)` です。
`lakebase_tokenizer_synonyms`	`name text`、`word text`、`synonym text`	ストアは `Synonyms`をサポートするトークナイザーテンプレートの1対1の代替を指定しました。主キーは `(name, word)` です。

BM25のランキングをlakebase_textで使う

lakebase_tokenizerで構築されたテキスト検索構成は、lakebase_textと互換性のある標準的なPostgreSQLのtsvector値を生成します。 BM25の関連性ランキングとトップK検索を利用するには、同じtsvector列にlakebase_bm25インデックスを作成します。インストール、インデックス作成、クエリ構文については lakebase_textを参照してください。

次のステップ

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-09-30