lakebase_tokenizer

De lakebase_tokenizer extensie voegt configureerbare tokenisatie toe aan PostgreSQL full-text search in Lakebase, inclusief volledige tekstverwerking en morfologische analyse voor Chinese, Japanse en Koreaanse (CJK) tekst. Tekstzoekconfiguraties die met de extensie zijn gebouwd, werken met to_tsvector, de @@ operator, rangschikkingsfuncties en GIN-indexen. Je kunt ook gegenereerde tsvector waarden gebruiken voor lakebase_text BM25-ranking.

De extensie biedt de tokenizer_wholeword en tokenizer_morph sjablonen via de standaard tekstzoekwoordenboekinterface van PostgreSQL. Gebruik tokenizer_wholeword voor volledige tekstverwerking, inclusief normalisatie, stopwoorden, synoniemen en Engelse stemming. Gebruik tokenizer_morph voor CJK-morfologische analyse.

Install

Installeer de extensie in je database. De voorbeelden op deze pagina gebruiken een speciaal schema om de extensieobjecten gemakkelijk te identificeren:

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

De uitbreiding is verplaatsbaar. Je kunt het vervangen tokenizer_ext door een ander schema wanneer je het installeert.

De extensie upgraden

Een nieuwe Lakebase Search-release kan functies, fixes en prestatieverbeteringen toevoegen. PostgreSQL werkt de geïnstalleerde extensieversie niet automatisch bij. Controleer de geïnstalleerde en meest recente beschikbare versies:

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

Werk de extensie bij naar de nieuwste beschikbare versie:

ALTER EXTENSION lakebase_tokenizer UPDATE;

ALTER EXTENSION regenereert geen opgeslagen tsvector waarden en bouwt ook geen afhankelijke GIN of lakebase_bm25 indexen op. Als een update de tokenisatie-output verandert, genereer dan herstelde tsvector waarden opnieuw en volg de release-notities voor eventueel benodigd indexonderhoud.

Het upgraden van 0.1.x naar 0.2.0 verandert de tokenisatie-output niet. Versie 0.2.0 voegt de tokenizer_morph template en de ingebouwde CJK-configuraties toe, en laat je bestaande configuraties ongewijzigd, zodat je geen waarden hoeft te regenereren tsvector of indexen opnieuw op te bouwen.

Snel starten

Kies een pad gebaseerd op de taal van je tekst:

• Voor Engels en andere talen met witruimte wordt een woordenboek gemaakt van het tokenizer_wholeword sjabloon.
• Voor Chinese, Japanse of Koreaanse tekst gebruik je een ingebouwde configuratie. Je hoeft geen woordenboek te maken.

Volledige tekst

Het volgende voorbeeld maakt een woordenboek aan van de tokenizer_wholeword template en koppelt vervolgens veelvoorkomende PostgreSQL-tokentypes aan in een tekstzoekconfiguratie:

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;

Gebruik de configuratie om een tsvector, maak een GIN-index aan en voer full-text queries uit:

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

Gebruik dezelfde tekstzoekconfiguratie voor documenten en zoekopdrachten zodat beide partijen dezelfde tokenisatiestrategie en opties toepassen.

CJK-tekst

Het installeren van de extensie creëert de tokenizer_chinese, tokenizer_japanese, en tokenizer_korean tekstzoekconfiguraties. Gebruik er direct een om een tsvectorte maken, een GIN-index te maken, en full-text queries uit te voeren:

Chinese

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', '现代分布式');

De Japanse taal

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', '関西国際空港');

Korean

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', '선생님께서');

Sjabloon: tokenizer_wholeword

Hoe werkt het?

Voor elk token dat door PostgreSQL's tekstzoekparser naar het woordenboek wordt gestuurd, tokenizer_wholeword past deze bewerkingen toe:

1. Lowercase: Zet de token om in kleine letters.
2. Normalize: Pas Unicode-normalisatie toe.
3. StripAccents: Verwijder accenten.
4. EnglishPossessive: Verwijder een Engels bezitssuffix wanneer er ten minste één teken overblijft.
5. Stopwords: Emitteer geen lexeem en stop de verwerking als het token overeenkomt met een geconfigureerd stopwoord. Het token wordt weggelaten uit het gegenereerde tsvector.
6. Synonyms: Voer de geconfigureerde vervanging uit en stop de verwerking als de token overeenkomt met een synoniem.
7. Stemmer: Als er geen synoniem is gematcht en stemming is ingeschakeld, pas dan de Engelse stemmer toe.

Voeg stopwoorden en synoniemen toe

De tokenizer_wholeword template kan aangepaste stopwoorden en synoniemen laden uit door extensies beheerde SQL-tabellen lakebase_tokenizer_stopwords en lakebase_tokenizer_synonyms. De name kolom groepeert rijen in een set die je selecteert met de Stopwords optie of Synonyms dictionary.

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

Raadpleeg de sets wanneer je een tokenizer_wholeword woordenboek maakt of bewerkt:

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

De extensie vergelijkt stopwoorden en synoniembronwoorden met elk token na het toepassen Lowercasevan , Normalize, StripAccents, en EnglishPossessive, maar voordat Stemmer. Catalogusvermeldingen worden niet automatisch getransformeerd, dus sla ze op in exact de vorm die door die ingeschakelde opties wordt geproduceerd:

• Lowercase = 'true'Gebruik met , kleine letters. Met Lowercase = 'false', moet hoofdletter overeenkomen met de token.
• Met Normalize ingeschakeld sla de vermeldingen op in het geselecteerde Unicode-normalisatieformulier.
• Met , sla StripAccents = 'true'de accentgestreepte vorm op. Bijvoorbeeld, opslaan cafe om te matchen café.
• Bewaar het formulier voordat je stemt. Bijvoorbeeld, met Stemmer = 'english', komt een run invoer niet overeen met running. Voeg die token toe running om te filteren of te vervangen.

Setnamen kunnen tot 256 bytes bevatten. Woorden en synoniemen kunnen tot 1024 bytes bevatten. Elke benoemde stopwoord of synoniemset kan tot 100.000 rijen bevatten.

Een synoniemvervanging wordt exact zoals opgeslagen uitgezonden en wordt niet verwerkt door de stemmer. Synoniemen ondersteunen één vervanging voor elk bronwoord. Om een meerwoordvervanging als één lexeem weer te geven, gebruik een scheidingsteken zoals een onderstreep, zoals in united_states.

Na het wijzigen van een set moet de eigenaar van elk woordenboek dat naar de set verwijst, een no-op ALTER TEXT SEARCH DICTIONARY uitvoeren om een herlaad af te dwingen:

ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);

De dummy optie bestaat niet op tokenizer_wholeword. Het weglaten van een waarde vraagt PostgreSQL om deze niet-bestaande optie te verwijderen, waardoor de cache ongeldig wordt zonder dat een van de geconfigureerde opties van het woordenboek wordt gewijzigd.

Na het herladen van het dictionary genereer je de opgeslagen tsvector waarden opnieuw door de bronrijen te herschrijven:

UPDATE documents SET body = body;

Rollen en toegang

Gebruik twee rollen om applicatietoegang te scheiden van tokenizer-beheer:

• app_role Gebruikt bestaande woordenboeken. Het moet op de relevante schema's en SELECT op de extensiecatalogttabellen staanUSAGE, maar het hoeft niet de woordenboeken te bezitten.
• tokenizer_admin beheert stopwoord- en synoniemverzamelingen, maakt en bezit woordenboeken en tekstzoekconfiguraties, en voert het herlaadcommando uit na het wijzigen van een set.

Verleen toegang tot het extensieschema en catalogustabellen:

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 ook nodig is CREATE op het schema waar woordenboeken en tekstzoekconfiguraties worden opgeslagen. Maak deze objecten als tokenizer_admin, of draag hun eigendom eraan over. Schrijftoegang tot de catalogustabellen verleent geen eigendom van bestaande woordenboeken.

Opties

Specificeer tokenizer_wholeword opties in CREATE TEXT SEARCH DICTIONARY of ALTER TEXT SEARCH DICTIONARY. Optienamen zijn niet hoofdlettergevoelig.

Option	Type	Default	Description
Lowercase	boolean	true	Zet tokens om in kleine letters voordat andere bewerkingen worden toegepast. Stemmer = 'english' vereist Lowercase = 'true'.
Normalize	NFC, NFD, NFKC, NFKD of none	none	Past het geselecteerde Unicode-normalisatieformulier toe. Dit canonicaliseert de representatie, maar verwijdert de personages niet. Bijvoorbeeld, NFC maakt precompositie é en e gevolgd door een gecombineerd acuut accent-equivalent.
EnglishPossessive	boolean	true	Verwijdert een achterliggende 's, ’s, of ＇s wanneer ten minste één teken voorafgaat aan het achtervoegsel. Een zelfstandig achtervoegsel blijft ongewijzigd.
StripAccents	boolean	false	Past NFKD-normalisatie toe en verwijdert het combineren van markeringen. Bijvoorbeeld, café wordt cafe. Wanneer deze optie is ingeschakeld, laat dan weg Normalize omdat de NFKD-stap elke afzonderlijke Unicode-normalisatie overbodig maakt.
Stopwords	Naam van de set	None	Gebruikt de benoemde verzameling uit tokenizer_ext.lakebase_tokenizer_stopwords.
Synonyms	Naam van de set	None	Gebruikt de benoemde verzameling één-op-één vervangingen uit tokenizer_ext.lakebase_tokenizer_synonyms.
Stemmer	english	None	Gebruikt de meegeleverde Snowball 3.1.0 Engelse stemmer. Laat deze optie weg om stemming uit te schakelen. De stemmer bevat geen stopwoordlijst.

Catalogustabellen

Tabel	Columns	Description
lakebase_tokenizer_stopwords	name text, word text	Winkels met de naam stopwoordsets voor tokenizer_wholeword. De primaire sleutel is (name, word).
lakebase_tokenizer_synonyms	name text, word text, synonym text	Winkels noemden één-op-één vervangers voor tokenizer_wholeword. De primaire sleutel is (name, word).

Sjabloon: tokenizer_morph

Het tokenizer_morph sjabloon biedt tokenisatie-ondersteuning voor Chinese, Japanse en Koreaanse tekst in PostgreSQL full-text search. Gebruik een ingebouwde tekstzoekconfiguratie of definieer een aangepaste om de termgeneratie te regelen.

Hoe werkt het?

tokenizer_morph gebruikt de Lindera-analyzer met gebundelde woordenboeken: Jieba voor Chinees, IPADIC voor Japans en MeCab KoDic voor Koreaans.

Voor Koreaanse parsertokens tokenizer_morph vervangt ㆍ first (U+318D) door een tokengrens.

Voor elk token dat door de tekstzoekparser van PostgreSQL aan het woordenboek wordt doorgegeven, tokenizer_morph past deze bewerkingen in volgorde toe:

1. Normalize: Pas Unicode-normalisatie toe op het parsertoken.
2. Language: Segmenteer het parsertoken met de geselecteerde taalanalyzer.
3. Symboolfilter: Verwijder segmenten die geen letters of cijfers bevatten.
4. Taalspecifieke analyse: Verander elk overgebleven segment in nul of meer termen, zoals hieronder beschreven.
5. Lowercase: Zet elke term om in kleine letters.
6. Stemmer: Als ingeschakeld, stamtermen die volledig uit ASCII-letters bestaan, met de bijgevoegde Engelse stemmer. Deze stap stopt de CJK-termen niet.

De taalspecifieke analysestap past deze regels toe:

Chinees

• Subwoorduitbreiding: In mixed modus voeg je de twee- en drie-tekentermen toe die het meegeleverde woordenboek bevat.

Japanse

• Woordsoortfiltering: Verwijder herkende deeltjes, hulpwerkwoorden, voegwoorden, opvullers, non-verbale klanken, niet-alfabetische symbolen en segmenten die getagd その他,間投zijn.
• Basisvormconversie: Gebruik de woordenboekbasisvorm van elk overgebleven herkend segment wanneer beschikbaar. Anders kun je de oppervlaktevorm behouden.
• Stopwoordfiltering: Gooi een term weg die overeenkomt met de ingebouwde lijst van veelvoorkomende Japanse functiewoorden.
• Katakana-stamming: Verwijder een trailing ー uit een term van ten minste vier karakters waarvan alle karakters in het katakana-blok vallen (U+30A0 tot U+30FF).

Koreaans

• Decompositie: In discard en mixed modi, splits een herkend samengesteld, gebogen, of vooraf geanalyseerd segment wanneer het woordenboek zijn componenten aangeeft. discard de componenten in plaats van de volledige term uitzenden, en mixed beide in de stemming.
• Woordsoortfiltering: Pas filtering toe op de volledige term en op elk component onafhankelijk. Laat termen weg die als deeltjes, uitgangen, affixen, bijwoorden, determinatieven, interjecties, interpunten, symbolen of niet-analyseerbare vormen worden getagd.
• Hangul-lezing: Gebruik de Hangul-lezing van het woordenboek voor een behouden volledig semester wanneer beschikbaar. Componenten behouden hun woordenboekvorm.

De tekstzoekparser van PostgreSQL splitst tekst bij witruimte en interpunctie voordat hij aanroept tokenizer_morph. Elke parsertoken kan tot 2046 bytes bevatten, en langere tokens worden overgeslagen met een NOTICE. De meeste Chinese, Japanse en Koreaanse tekens gebruiken 3 bytes in UTF-8, dus een reeks van meer dan 682 van deze tekens zonder witruimte of interpunctie wordt weggelaten in to_tsvector de resultaten.

Ondersteunde talen en modi

De beschikbare modi hangen af van de taal. Elk voorbeeld toont brontekst → uitgezonden termen:

Language	Mode	Behavior	Example
Chinese	none	Geeft woorden uit standaardsegmentatie zonder kortere zoektermen toe te voegen.	现代分布式文件系统架构 → 现代, 分布式文件系统, 架构
Chinese	mixed	Houdt woorden weg van standaardsegmentatie en voegt kortere zoektermen toe van sommige langere woorden.	现代分布式文件系统架构→ 现代, 分布式文件系统, , 分布分布式, , 布式, 文件, , 系统架构
De Japanse taal	none	Geeft de voorkeur aan langere woordenboeksamenstellingen.	関西国際空港へのアクセス → 関西国際空港, アクセス
De Japanse taal	discard	Produceert fijnkorrelige termen voor sommige lange verbindingen zonder ook hun volledige vorm te behouden.	関西国際空港へのアクセス → 関西, 国際, , 空港, アクセス
Korean	none	Houdt samengestelde en verbogen woordenboekvermeldingen als volledige termen.	한국어 형태소 분석 → 한국어, 형태소, 분석
Korean	discard	Wanneer een samengestelde of gebogende vorm gesplitst kan worden, zendt deze zijn delen uit in plaats van de volledige term.	한국어 형태소 분석→ 한국, 어, , 형태, 소분석
Korean	mixed	Wanneer een samengestelde of verbuigde vorm gesplitst kan worden, zendt zowel de volledige term als de delen ervan uit.	한국어 형태소 분석→ , , , , 형태형태소, , 소, 어한국한국어분석

In mixed modus, zoek met plainto_tsquery. Wanneer één querywoord meerdere lexemen produceert, to_tsquery, websearch_to_tsquery, verbind phraseto_tsquery je deze met de <-> operator, wat aangrenzende posities vereist. mixed Modus voegt extra posities in voor de extra termen, zodat deze phrasevoorwaarden verwachte matches kunnen missen. Definieer voor positiegebaseerde queries een aangepaste configuratie met none of discard modus.

Gebruik de ingebouwde configuraties

Het installeren van de extensie creëert deze tekstzoekconfiguraties:

Configuration	Woordenlijst	Language	Mode
tokenizer_chinese	tokenizer_chinese_dict	Chinese	mixed
tokenizer_japanese	tokenizer_japanese_dict	De Japanse taal	discard
tokenizer_korean	tokenizer_korean_dict	Korean	discard

Alle drie de woordenboeken stellen Stemmer = 'english' en gebruiken de standaard Normalize = 'NFKC' en Lowercase = 'true'.

Voor end-to-end voorbeelden die deze configuraties gebruiken, zie CJK-tekst.

Definieer een aangepaste configuratie

Om een andere modus te kiezen of de standaardopties te wijzigen, maak je een woordenboek aan vanuit het tokenizer_morph sjabloon en een tekstzoekconfiguratie die PostgreSQL-tokentypes eraan koppelt, zoals hieronder weergegeven. Dit voorbeeld gebruikt de Chinese none modus voor frasezoekopdrachten:

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', '分布式文件系统 架构');

Opties

Specificeer tokenizer_morph opties in CREATE TEXT SEARCH DICTIONARY of ALTER TEXT SEARCH DICTIONARY. Optienamen zijn niet hoofdlettergevoelig.

Option	Type	Default	Description
Language	chinese, japanese of korean	Required	Selecteert de taalspecifieke analyzer.
Mode	none, discard of mixed	Required	Regelt de output van samengestelde en subwoorden. Ondersteunde modi zijn afhankelijk van Language: none of mixed voor Chinees, none of discard voor Japans, en none, discard, of mixed voor Koreaans.
Normalize	NFC, NFKC of none	NFKC	Normaliseert tekst vóór segmentatie. NFC behoudt compatibiliteitsverschillen. Bijvoorbeeld, full-width ＡＢＣ wordt met kleine letters naar gemaakt ａｂｃ in plaats van omgezet te worden naar abc, dus het wordt niet gestemd.
Lowercase	boolean	true	Converts stuurden lexemen naar kleine letters. Stemmer = 'english' vereist Lowercase = 'true'.
Stemmer	english	None	Alleen stelen lexemen die volledig uit ASCII-letters bestaan. Laat deze optie weg om Engelse stemming uit te schakelen.

Gebruik BM25-ranking met lakebase_text

Tekstzoekconfiguraties gebouwd met lakebase_tokenizer de standaard PostgreSQL-waarden tsvector produceren die compatibel zijn met lakebase_text. Om de relevantierangschikking van BM25 en top-K retrieval te gebruiken, maak je een lakebase_bm25 index aan op dezelfde tsvector kolom. Voor installatie, indexcreatie en querysyntaxis, zie lakebase_text.

Volgende stappen 

• lakebase_text
• Lakebase Search