lakebase_tokenizer

L’extension lakebase_tokenizer ajoute une tokenisation configurable à la recherche en texte intégral PostgreSQL dans Lakebase, incluant un traitement de texte complet et une analyse morphologique pour le texte chinois, japonais et coréen (CJK). Les configurations de recherche textuelle construites avec l’extension travaillent avec to_tsvector, l’opérateur @@ , les fonctions de classement et les index GIN. Vous pouvez aussi utiliser des valeurs générées tsvector avec lakebase_text pour le classement BM25.

L’extension fournit les tokenizer_wholeword modèles et tokenizer_morph via l’interface standard du dictionnaire de recherche de texte de PostgreSQL. Utilisation tokenizer_wholeword pour le traitement de texte complet, y compris la normalisation, les mots stop, les synonymes et le radicing anglais. Utilisation tokenizer_morph pour l’analyse morphologique CJK.

Install

Installez l’extension dans votre base de données. Les exemples de cette page utilisent un schéma dédié pour faciliter l’identification des objets d’extension :

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

L’extension est déplaçable. Vous pouvez le remplacer tokenizer_ext par un autre schéma lors de l’installation.

Mettre à niveau l’extension

Une nouvelle version de Lakebase Search peut ajouter des fonctionnalités, des correctifs et des améliorations de performance. PostgreSQL ne met pas automatiquement à jour la version installée de l’extension. Vérifiez les versions installées et les dernières disponibles :

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

Mettez à jour l’extension vers la dernière version disponible :

ALTER EXTENSION lakebase_tokenizer UPDATE;

ALTER EXTENSION ne régénère pas les valeurs stockées tsvector ni ne reconstruit les GIN ou lakebase_bm25 les index dépendants. Si une mise à jour modifie la sortie de tokenisation, régénérez les valeurs stockées tsvector et suivez les notes de version pour toute maintenance d’index requise.

Passer de la version 0.1.x à la 0.2.0 ne change pas la sortie de tokenisation. La version 0.2.0 ajoute le tokenizer_morph modèle et les configurations CJK intégrées, et laisse vos configurations existantes inchangées, donc vous n’avez pas besoin de régénérer tsvector des valeurs ou de reconstruire des index.

Démarrage rapide

Choisissez un chemin en fonction du langage de votre texte :

• Pour l’anglais et d’autres langues délimitées par les espaces blancs, créez un dictionnaire à partir du tokenizer_wholeword modèle.
• Pour le texte chinois, japonais ou coréen, utilisez une configuration intégrée. Vous n’avez pas besoin de créer un dictionnaire.

Texte entier

L’exemple suivant crée un dictionnaire à partir du tokenizer_wholeword modèle, puis associe les types courants de jetons PostgreSQL à celui-ci dans une configuration de recherche textuelle :

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;

Utilisez la configuration pour produire un tsvector, créez un index GIN et exécutez des requêtes en texte intégral :

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é');

Utilisez la même configuration de recherche textuelle pour les documents et requêtes afin que les deux parties appliquent la même stratégie et options de tokenisation.

Texte CJK

L’installation de l’extension crée les tokenizer_chineseconfigurations , tokenizer_japanese, et tokenizer_korean de recherche de texte. Utilisez l’un d’eux directement pour produire un tsvector, créer un index GIN et exécuter des requêtes en texte intégral :

Chinois

CREATE TABLE chinese_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_chinese', body)
  ) STORED
);

INSERT INTO chinese_documents (body) VALUES
  ('现代分布式文件系统架构');

CREATE INDEX chinese_idx ON chinese_documents USING gin (search_vector);

-- The built-in Chinese configuration uses mixed mode, so use plainto_tsquery instead of to_tsquery.
SELECT id, body
FROM chinese_documents
WHERE search_vector @@ plainto_tsquery('tokenizer_ext.tokenizer_chinese', '现代分布式');

Japanese

CREATE TABLE japanese_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_japanese', body)
  ) STORED
);

INSERT INTO japanese_documents (body) VALUES
  ('関西国際空港へのアクセス');

CREATE INDEX japanese_idx ON japanese_documents USING gin (search_vector);

SELECT id, body
FROM japanese_documents
WHERE search_vector @@ to_tsquery('tokenizer_ext.tokenizer_japanese', '関西国際空港');

Coréen

CREATE TABLE korean_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_korean', body)
  ) STORED
);

INSERT INTO korean_documents (body) VALUES
  ('선생님께서 도서관에 갑니다');

CREATE INDEX korean_idx ON korean_documents USING gin (search_vector);

SELECT id, body
FROM korean_documents
WHERE search_vector @@ to_tsquery('tokenizer_ext.tokenizer_korean', '선생님께서');

Modèle : tokenizer_wholeword

Fonctionnement

Pour chaque jeton passé au dictionnaire par l’analyseur de recherche de texte de PostgreSQL, tokenizer_wholeword les opérations suivantes sont appliquées :

1. Lowercase: Convertir le jeton en minuscules.
2. Normalize: Appliquer la normalisation Unicode.
3. StripAccents: Enlever les accents.
4. EnglishPossessive: Supprimez un suffixe possessif anglais lorsqu’il reste au moins un caractère.
5. Stopwords: N’émettez aucun lexeme et arrêtez le traitement si le jeton correspond à un mot d’arrêt configuré. Le jeton est omis du fichier généré tsvector.
6. Synonyms: Émettre le remplacement configuré et arrêter le traitement si le jeton correspond à un synonyme.
7. Stemmer: Si aucun synonyme associé et que le stemming n’est activé, appliquer le stemmer anglais.

Ajoutez des mots stoppés et des synonymes

Le tokenizer_wholeword modèle peut charger des stop-mots personnalisés et des synonymes à partir de tables lakebase_tokenizer_stopwords SQL gérées par extensions et lakebase_tokenizer_synonymsde . La name colonne regroupe les lignes en un ensemble que vous sélectionnez avec l’option Stopwords dictionnaire ou 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');

Référencez-vous aux ensembles lorsque vous créez ou modifiez un tokenizer_wholeword dictionnaire :

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

L’extension compare les mots d’arrêt et les mots sources synonymes avec chaque jeton après avoir appliqué , , , et EnglishPossessive, mais avant d’appliquer Stemmer. StripAccentsNormalizeLowercase Les entrées de catalogue ne sont pas transformées automatiquement, donc stockez-les sous la forme exacte produite par ces options activées :

• Avec Lowercase = 'true', utilisez des entrées minuscules. Avec , la Lowercase = 'false'capitalisation doit correspondre au jeton.
• Avec activé, stockez Normalize les entrées dans le formulaire de normalisation Unicode sélectionné.
• Avec , stockez StripAccents = 'true'la forme dénudée par accent. Par exemple, stockez cafe pour faire correspondre café.
• Conservez le coffrage avant de le déposer. Par exemple, avec Stemmer = 'english', une run entrée ne correspond runningpas à . Ajouter running pour filtrer ou remplacer ce jeton.

Les noms d’ensembles peuvent contenir jusqu’à 256 octets. Les mots et synonymes peuvent contenir jusqu’à 1024 octets. Chaque stop-word nommé ou ensemble de synonymes peut contenir jusqu’à 100 000 lignes.

Un remplacement de synonyme est émis exactement tel qu’il est stocké et n’est pas traité par le tige. Les synonymes prennent en charge un remplacement pour chaque mot source. Pour représenter un remplacement multi-mot comme un seul lexeme, utilisez un séparateur tel qu’un sous-trait, comme dans united_states.

Après avoir changé un ensemble, le propriétaire de chaque dictionnaire qui fait référence à cet ensemble doit exécuter un no-op ALTER TEXT SEARCH DICTIONARY pour forcer un rechargement :

ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);

L’option dummy n’existe pas sur tokenizer_wholeword. Omettre une valeur demande à PostgreSQL de supprimer cette option inexistante, ce qui invalide le cache sans modifier aucune des options configurées du dictionnaire.

Après avoir rechargé le dictionnaire, régénérez les valeurs stockées tsvector en réécrivant les lignes sources :

UPDATE documents SET body = body;

Rôles et accès

Utilisez deux rôles pour séparer l’accès aux applications de l’administration du tokenizer :

• app_role utilise des dictionnaires existants. Il doit USAGE s’occuper des schémas pertinents et SELECT des tableaux de catalogue d’extensions, mais il n’a pas besoin de posséder les dictionnaires.
• tokenizer_admin gère les ensembles de mots stop-word et synonymes, crée et possède des dictionnaires et des configurations de recherche textuelle, et exécute la commande reload après avoir changé un ensemble.

Accordez l’accès au schéma d’extension et aux tables de catalogue :

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 Il faut CREATE également sur le schéma où sont stockés les dictionnaires et les configurations de recherche de texte. Créez ces objets en tant que tokenizer_admin, ou transférez leur propriété à celle-ci. L’accès en écriture aux tables de catalogue ne confère pas la propriété des dictionnaires existants.

Options

Spécifier tokenizer_wholeword les options dans CREATE TEXT SEARCH DICTIONARY ou ALTER TEXT SEARCH DICTIONARY. Les noms des options sont insensibles à la majuscule.

Option	Type	Default	Description
Lowercase	booléen	true	Convertit les jetons en minuscules avant d’appliquer d’autres opérations. Stemmer = 'english' nécessite Lowercase = 'true'.
Normalize	NFC, NFD, NFKC, NFKD ounone	none	Applique le formulaire de normalisation Unicode sélectionné. Cela canonise la représentation mais ne supprime pas les caractères. Par exemple, NFC rend précomposé é et e suivi d’un équivalent aigu combinant.
EnglishPossessive	booléen	true	Supprime un dernier 's, ’s, ou ＇s lorsqu’au moins un caractère précède le suffixe. Un suffixe autonome reste inchangé.
StripAccents	booléen	false	Applique la normalisation NFKD et supprime les marques de combinaison. Par exemple, café devient cafe. Lorsque cette option est activée, omettez-la Normalize car l’étape NFKD rend redondante toute normalisation Unicode séparée.
Stopwords	Nom de l’ensemble	None	Utilise l’ensemble nommé de tokenizer_ext.lakebase_tokenizer_stopwords.
Synonyms	Nom de l’ensemble	None	Utilise l’ensemble nommé des remplacements un-à-un de tokenizer_ext.lakebase_tokenizer_synonyms.
Stemmer	english	None	Utilise le stemmer anglais Snowball 3.1.0 fourni. Omettez cette option pour désactiver le stemming. Le stemmer n’inclut pas de liste de mots secrètes.

Tables de catalogue

Table	Columns	Description
lakebase_tokenizer_stopwords	name text, word text	Les magasins nommés ensembles de mots stop-word pour tokenizer_wholeword. La clé primaire est (name, word).
lakebase_tokenizer_synonyms	name text, word text, synonym text	Les magasins ont nommé des remplaçants un-à-un pour tokenizer_wholeword. La clé primaire est (name, word).

Modèle : tokenizer_morph

Le tokenizer_morph modèle offre un support de tokenisation pour le texte chinois, japonais et coréen dans la recherche en texte intégral PostgreSQL. Utilisez une configuration de recherche textuelle intégrée ou définissez-en une personnalisée pour contrôler la génération des termes.

Fonctionnement

tokenizer_morph utilise l’analyseur Lindera avec des dictionnaires inclus : Jieba pour le chinois, IPADIC pour le japonais et MeCab KoDic pour le coréen.

Pour les jetons analyseurs coréens, tokenizer_morph on remplace ㆍ d’abord (U+318D) par une frontière de jeton.

Pour chaque jeton passé au dictionnaire par l’analyseur de recherche de texte de PostgreSQL, tokenizer_morph applique ces opérations dans l’ordre suivant :

1. Normalize: Appliquer la normalisation Unicode au jeton analyseur.
2. Language: Segmentez le jeton analyseur syntaxique avec l’analyseur de langage sélectionné.
3. Filtre de symboles : Rejetez les segments qui ne contiennent ni lettres ni chiffres.
4. Analyse spécifique à la langue : Transformer chaque segment restant en zéro ou plus de termes, comme décrit ci-dessous.
5. Lowercase: Convertir chaque terme en minuscules.
6. Stemmer: Si activé, les termes de racine sont entièrement composés de lettres ASCII avec le stemmer anglais regroupé. Cette étape ne remet pas en cause les termes de CJK.

L’étape d’analyse spécifique à la langue applique ces règles :

Chinois

• Extension de sous-mot : En mixed mode, ajoutez les termes de deux et trois caractères que contient le dictionnaire fourni.

Japonais

• Filtrage des parties du discours : Écartez les particules reconnues, les verbes auxiliaires, les conjonctions, les remplisseurs, les sons non verbaux, les symboles non alphabétiques et les segments identifiés その他,間投.
• Conversion en forme de base : Utilisez la forme de base du dictionnaire de chaque segment reconnu restant lorsque disponible. Sinon, conservez sa forme de surface.
• Filtrage des mots stop-word : Écartez un terme qui correspond à la liste intégrée des mots fonctionnels japonais courants.
• Dérivation du katakana : Retirer un terme de fin ー d’au moins quatre caractères dont les caractères appartiennent tous au bloc katakana (U+30A0 à U+30FF).

Coréen

• Décomposition : modes In discardmixed et séparer un composé reconnu, un segment fléchi ou préanalysé lorsque le dictionnaire fournit ses composantes. discard émet les composantes à la place du terme complet, et mixed émet les deux.
• Filtrage des parties du discours : Appliquer le filtrage au terme complet et à chaque composant indépendamment. Omettez les termes étiquetés comme particules, terminaisons, affixes, adverbes, déterminants, interjections, ponctuation, symboles ou formes inanalysables.
• Conversion de lecture en hangul : Utilisez la lecture en hangul du dictionnaire pour conserver un terme complet lorsque cela est disponible. Les composants conservent leur forme de dictionnaire.

L’analyseur de recherche de texte de PostgreSQL divise le texte à l’espace blanc et à la ponctuation avant d’appeler tokenizer_morph. Chaque jeton analyseur peut contenir jusqu’à 2046 octets, et les jetons plus longs sont sautés avec un NOTICE. La plupart des caractères chinois, japonais et coréens utilisent 3 octets en UTF-8, donc une série de plus de 682 caractères sans espaces blancs ni ponctuation est omise des to_tsvector résultats.

Langages et modes pris en charge

Les modes disponibles dépendent de la langue. Chaque exemple montre le texte source → les termes émis :

Langue	Mode	Behavior	Example
Chinois	none	Émets des mots à partir de segmentation standard sans ajouter de termes de recherche plus courts.	现代分布式文件系统架构 → 现代, 分布式文件系统, 架构
Chinois	mixed	Empêche les mots de segmenter standard et ajoute des termes de recherche plus courts à partir de mots plus longs.	现代分布式文件系统架构 → 现代, 分布式文件系统, 分布, 分布式, 布式, 文件, 系统, 架构
Japanese	none	Favorise les composés de dictionnaire plus longs.	関西国際空港へのアクセス → 関西国際空港, アクセス
Japanese	discard	Produit des termes plus fins pour certains composés longs sans conserver leur forme complète.	関西国際空港へのアクセス → 関西, 国際, 空港, アクセス
Coréen	none	Garde les entrées composées et flexionnées du dictionnaire comme des termes entiers.	한국어 형태소 분석 → 한국어, 형태소, 분석
Coréen	discard	Lorsqu’une forme composée ou fléchie peut être scindée, elle émet ses parties au lieu du terme complet.	한국어 형태소 분석 → 한국, 어, 형태, 소, 분석
Coréen	mixed	Lorsqu’une forme composée ou fléchie peut être scindée, elle émet à la fois le terme complet et ses parties.	한국어 형태소 분석 → 한국어, 한국, 어, 형태소, 형태, 소, 분석

En mixed mode, requête avec plainto_tsquery. Lorsqu’un mot de requête produit plusieurs lexemes, to_tsquery, , et phraseto_tsquery les rejoignez avec l’opérateur<->, ce qui nécessite des websearch_to_tsquerypositions adjacentes. mixed Le mode insère des positions supplémentaires pour les termes supplémentaires, de sorte que ces conditions de phrase peuvent manquer les correspondances attendues. Pour les requêtes basées sur la position, définissez une configuration personnalisée avec none ou discard mode.

Utilisez les configurations intégrées

L’installation de l’extension crée ces configurations de recherche de texte :

Configuration	Dictionnaire	Langue	Mode
tokenizer_chinese	tokenizer_chinese_dict	Chinois	mixed
tokenizer_japanese	tokenizer_japanese_dict	Japanese	discard
tokenizer_korean	tokenizer_korean_dict	Coréen	discard

Les trois dictionnaires définissent Stemmer = 'english' et utilisent par défaut Normalize = 'NFKC' et Lowercase = 'true'.

Pour des exemples de bout en bout utilisant ces configurations, voir texte CJK.

Définir une configuration personnalisée

Pour choisir un autre mode ou modifier les options par défaut, créez un dictionnaire à partir du tokenizer_morph modèle et une configuration de recherche textuelle qui associe les types de jetons PostgreSQL, comme montré ci-dessous. Cet exemple utilise le mode chinois none pour les requêtes de phrases :

CREATE TEXT SEARCH DICTIONARY chinese_none_dict (
  TEMPLATE = tokenizer_ext.tokenizer_morph,
  Language = 'chinese',
  Mode = 'none',
  Stemmer = 'english'
);

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

ALTER TEXT SEARCH CONFIGURATION chinese_none_cfg
  ALTER MAPPING FOR asciiword, word, numword, hword_asciipart, hword_part, hword_numpart
  WITH chinese_none_dict;

SELECT to_tsvector('chinese_none_cfg', '现代分布式文件系统架构')
  @@ phraseto_tsquery('chinese_none_cfg', '分布式文件系统 架构');

Options

Spécifier tokenizer_morph les options dans CREATE TEXT SEARCH DICTIONARY ou ALTER TEXT SEARCH DICTIONARY. Les noms des options sont insensibles à la majuscule.

Option	Type	Default	Description
Language	chinese, japanese ou korean	Required	Sélectionne l’analyseur spécifique à la langue.
Mode	none, discard ou mixed	Required	Contrôle la sortie des composés et sous-mots. Les modes pris en charge dépendent de : ou pour le chinois, none ou discard pour le japonais, et none, discard, ou mixed pour le coréen.mixednoneLanguage
Normalize	NFC, NFKC ou none	NFKC	Normalise le texte avant la segmentation. NFC préserve les distinctions de compatibilité. Par exemple, la largeur ＡＢＣ pleine est en minuscule au ａｂｃ lieu d’être convertie en abc, donc elle n’est pas en stemme.
Lowercase	booléen	true	Convertit les lexèmes émis en minuscules. Stemmer = 'english' nécessite Lowercase = 'true'.
Stemmer	english	None	Les lèvèmes uniquement sont composés uniquement de lettres ASCII. Omettez cette option pour désactiver le stemming anglais.

Utilisez le classement BM25 avec lakebase_text

Les configurations de recherche de texte construites avec lakebase_tokenizer produisent des valeurs PostgreSQL tsvector standard compatibles avec lakebase_text. Pour utiliser le classement de pertinence BM25 et la récupération en top-K, créez un lakebase_bm25 index sur la même tsvector colonne. Pour l’installation, la création d’index et la syntaxe des requêtes, voir lakebase_text.

Étapes suivantes

• lakebase_text
• Recherche Lakebase