lakebase_tokenizer

La lakebase_tokenizer extensión añade tokenización configurable a la búsqueda de texto completo de PostgreSQL en Lakebase, incluyendo procesamiento de texto completo y análisis morfológico para texto chino, japonés y coreano (CJK). Las configuraciones de búsqueda de texto construidas con la extensión trabajan con to_tsvector, el @@ operador, funciones de clasificación y índices GIN. También puedes usar valores generados tsvector con lakebase_text para el ranking de BM25.

La extensión proporciona las tokenizer_wholeword plantillas y tokenizer_morph a través de la interfaz estándar de diccionario de búsqueda de texto de PostgreSQL. Úsalos tokenizer_wholeword para procesamiento de texto completo, incluyendo normalización, palabras de parada, sinónimos y stemming en inglés. Úsalo tokenizer_morph para análisis morfológico CJK.

Install

Instala la extensión en tu base de datos. Los ejemplos de esta página utilizan un esquema dedicado para facilitar la identificación de los objetos de extensión:

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

La ampliación es trasladable. Puedes reemplazarlo tokenizer_ext por otro esquema cuando lo instales.

Actualización de la extensión

Una nueva versión de Lakebase Search puede añadir funciones, correcciones y mejoras de rendimiento. PostgreSQL no actualiza automáticamente la versión instalada de la extensión. Consulta las versiones instaladas y las últimas disponibles:

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

Actualizar la extensión a la última versión disponible:

ALTER EXTENSION lakebase_tokenizer UPDATE;

ALTER EXTENSION no regenera los valores almacenados tsvector ni reconstruye GIN o lakebase_bm25 índices dependientes. Si una actualización modifica la salida de tokenización, regenera los valores almacenados tsvector y sigue las notas de lanzamiento para cualquier mantenimiento de índice necesario.

Inicio rápido

Elige un camino basado en el idioma de tu texto:

• Para el inglés y otros idiomas delimitados por espacios en blanco, crea un diccionario a partir de la tokenizer_wholeword plantilla.
• Para texto en chino, japonés o coreano, utiliza una configuración incorporada. No necesitas crear un diccionario.

Texto de palabra entera

El siguiente ejemplo crea un diccionario a partir de la tokenizer_wholeword plantilla y luego mapea los tipos comunes de tokens PostgreSQL a él en una configuración de búsqueda de texto:

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;

Utiliza la configuración para producir un tsvector, crea un índice GIN y ejecuta consultas en texto completo:

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

Utiliza la misma configuración de búsqueda de texto para documentos y consultas, de modo que ambas partes apliquen la misma estrategia y opciones de tokenización.

Texto CJK

Instalar la extensión crea las tokenizer_chineseconfiguraciones , tokenizer_japanese, y tokenizer_korean búsqueda de texto. Utiliza uno de ellos directamente para producir un tsvector, crear un índice GIN y ejecutar consultas en texto completo:

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

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

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

Plantilla: tokenizer_wholeword

Cómo funciona

Para cada token pasado al diccionario por el analizador de búsqueda de texto de PostgreSQL, tokenizer_wholeword se aplican estas operaciones:

1. Lowercase: Convierte la ficha a minúscula.
2. Normalize: Aplicar la normalización Unicode.
3. StripAccents: Quita los acentos.
4. EnglishPossessive: Eliminar un sufijo posesivo inglés cuando queda al menos un carácter.
5. Stopwords: No emitir lexema y detener el procesamiento si el token coincide con una palabra de parada configurada. El token se omite del archivo generado tsvector.
6. Synonyms: Emite el reemplazo configurado y detiene el procesamiento si el token coincide con un sinónimo.
7. Stemmer: Si no se asocia sinónimo y se habilita el stemming, aplica el stemmer en inglés.

Añadir palabras clave y sinónimos

La tokenizer_wholeword plantilla puede cargar palabras de parada y sinónimos personalizados a partir de tablas lakebase_tokenizer_stopwords SQL gestionadas por extensiones y lakebase_tokenizer_synonyms. La name columna agrupa las filas en un conjunto que seleccionas con la Stopwords opción de diccionario o 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');

Consulta los conjuntos cuando crees o modifiques un tokenizer_wholeword diccionario:

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

La extensión compara las palabras de oclusiva y las palabras fuente sinónimo con cada token después de aplicar , , , y EnglishPossessive, pero antes de aplicar Stemmer. StripAccentsNormalizeLowercase Las entradas del catálogo no se transforman automáticamente, así que guárdalas en la forma exacta que producen esas opciones habilitadas:

• Con Lowercase = 'true', usa entradas minúsculas. Con Lowercase = 'false', la mayúscula debe coincidir con la ficha.
• Con Normalize activado, almacena las entradas en el formulario seleccionado de normalización Unicode.
• Con , guarda StripAccents = 'true'la forma con acento. Por ejemplo, almacena cafe para que coincida cafécon .
• Guarda el formulario antes de despedazar. Por ejemplo, con Stemmer = 'english', una run entrada no coincide runningcon . Añade running para filtrar o reemplazar ese token.

Los nombres de conjuntos pueden contener hasta 256 bytes. Las palabras y sinónimos pueden contener hasta 1024 bytes. Cada conjunto de palabras clave o sinónimos con nombre puede contener hasta 100.000 filas.

Un reemplazo de sinónimo se emite exactamente como se almacena y no es procesado por el tallo. Los sinónimos soportan un reemplazo para cada palabra fuente. Para representar un reemplazo de varias palabras como un solo lexema, se utiliza un separador como un guion bajo, como en united_states.

Tras cambiar un conjunto, el propietario de cada diccionario que hace referencia al conjunto debe ejecutar un no-op ALTER TEXT SEARCH DICTIONARY para forzar una recarga:

ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);

La dummy opción no existe en tokenizer_wholeword. Omitir un valor pide a PostgreSQL que elimine esta opción inexistente, lo que invalida la caché sin cambiar ninguna de las opciones configuradas del diccionario.

Tras recargar el diccionario, regenera los valores almacenados tsvector reescribiendo las filas fuente:

UPDATE documents SET body = body;

Roles y acceso

Utiliza dos roles para separar el acceso a aplicaciones de la administración del tokenizador:

• app_role utiliza diccionarios existentes. Necesita USAGE los esquemas relevantes y SELECT las tablas de catálogo de extensiones, pero no necesita poseer los diccionarios.
• tokenizer_admin gestiona conjuntos de palabras cerradas y sinónimos, crea y posee diccionarios y configuraciones de búsqueda de texto, y ejecuta el comando de recarga tras cambiar un conjunto.

Concede acceso al esquema de extensión y a las tablas de catálogo:

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 también necesita CREATE en el esquema donde se almacenan los diccionarios y configuraciones de búsqueda de texto. Crea estos objetos como tokenizer_admin, o transfiere su propiedad a ellos. El acceso de escritura a las tablas de catálogo no otorga la propiedad de diccionarios existentes.

Options

Especifica tokenizer_wholeword opciones en CREATE TEXT SEARCH DICTIONARY o ALTER TEXT SEARCH DICTIONARY. Los nombres de las opciones no son indiferentes a mayúsculas.

Option	Tipo	Predeterminado	Description
Lowercase	booleano	true	Convierte los tokens a minúsculas antes de aplicar otras operaciones. Stemmer = 'english' requiere Lowercase = 'true'.
Normalize	NFC, NFD, NFKC, NFKD o none	none	Aplica el formulario seleccionado de normalización Unicode. Esto canónica la representación pero no elimina caracteres. Por ejemplo, NFC hace que el acento agudo sea precompuesto é y e seguido de un acento agudo combinado.
EnglishPossessive	booleano	true	Elimina un elemento final 's, ’s, o ＇s cuando al menos un carácter precede al sufijo. Un sufijo independiente permanece sin cambios.
StripAccents	booleano	false	Aplica la normalización NFKD y elimina las marcas de combinación. Por ejemplo, café se convierte en cafe. Cuando esta opción esté activada, omite Normalize porque el paso NFKD hace que cualquier normalización Unicode separada sea redundante.
Stopwords	Nombre del set	Ninguno	Utiliza el conjunto nombrado de tokenizer_ext.lakebase_tokenizer_stopwords.
Synonyms	Nombre del set	Ninguno	Utiliza el conjunto nombrado de reemplazos uno a uno de tokenizer_ext.lakebase_tokenizer_synonyms.
Stemmer	english	Ninguno	Utiliza el stemmer inglés Snowball 3.1.0 incluido. Omite esta opción para desactivar el stemming. El stemmer no incluye una lista de palabras clave.

Tablas de catálogos

Tabla	Columns	Description
lakebase_tokenizer_stopwords	name text, word text	Tiendas con nombre de conjuntos de palabras para tokenizer_wholeword. La clave principal es (name, word).
lakebase_tokenizer_synonyms	name text, word text, synonym text	Las tiendas nombraron reemplazos uno a uno para tokenizer_wholeword. La clave principal es (name, word).

Plantilla: tokenizer_morph

La tokenizer_morph plantilla ofrece soporte para tokenización de texto en chino, japonés y coreano en la búsqueda de texto completo de PostgreSQL. Utiliza una configuración de búsqueda de texto integrada o define una personalizada para controlar la generación de términos.

Cómo funciona

tokenizer_morph utiliza el analizador Lindera con diccionarios incluidos: Jieba para chino, IPADIC para japonés y MeCab KoDic para coreano.

Para fichas analizadoras coreanas, tokenizer_morph primero se sustituye ㆍ (U+318D) por un límite de ficha.

Para cada token pasado al diccionario por el analizador de búsqueda de texto de PostgreSQL, tokenizer_morph se aplican estas operaciones en orden:

1. Normalize: Aplicar la normalización Unicode al token del analizador.
2. Language: Segmentar el token del analizador con el analizador de lenguaje seleccionado.
3. Filtro de símbolos: Descarta segmentos que no contienen letras ni dígitos.
4. Análisis específico de cada idioma: Convertir cada segmento restante en cero o más términos, como se describe a continuación.
5. Lowercase: Convierte cada término a minúscula.
6. Stemmer: Si está habilitado, términos de raíz compuestos completamente por letras ASCII con el stemmer inglés incluido. Este paso no detiene los términos de CJK.

El paso de análisis específico del lenguaje aplica estas reglas:

Chino

• Expansión de subpalabras: En mixed el modo, añade los términos de dos y tres caracteres que contiene el diccionario incluido.

Japonés

• Filtrado por partes gramaticales: Descartar partículas reconocidas, verbos auxiliares, conjunciones, rellenos, sonidos no verbales, símbolos no alfabéticos y segmentos etiquetados その他,間投.
• Conversión a forma base: Utiliza la forma base del diccionario de cada segmento reconocido restante cuando esté disponible. Por lo demás, conserva su forma superficial.
• Filtrado de palabras clave: Descarta un término que coincida con la lista incorporada de palabras funcionales japonesas comunes.
• Deriva de Katakana: Eliminar un término ー final de al menos cuatro caracteres cuyos caracteres pertenecen todos al bloque katakana (U+30A0 a U+30FF).

coreano

• Descomposición: En discard modos y mixed se divide un compuesto reconocido, se inflexione o se preanaliza un segmento cuando el diccionario proporciona sus componentes. discard emite los componentes en lugar del término completo y mixed emite ambos.
• Filtrado por las partes gramaticales: Aplica el filtrado al término completo y a cada componente de forma independiente. Omite términos etiquetados como partículas, terminaciones, afijos, adverbios, determinantes, interyecciones, puntuación, símbolos o formas no analizables.
• Conversión de lectura en hangul: Utiliza la lectura en hangul del diccionario para un término completo retenido cuando esté disponible. Los componentes mantienen su forma de diccionario.

El analizador de búsqueda de texto de PostgreSQL divide el texto en espacios en blanco y puntuación antes de llamar tokenizer_morpha . Cada token analizador puede contener hasta 2046 bytes, y los tokens más largos se saltan con un NOTICE. La mayoría de los caracteres chinos, japoneses y coreanos usan 3 bytes en UTF-8, por lo que una secuencia de más de 682 de estos caracteres sin espacios en blanco ni puntuación se omite en los to_tsvector resultados.

Lenguajes y modos soportados

Los modos disponibles dependen del idioma. Cada ejemplo muestra el texto fuente → términos emitidos:

Idioma	Mode	Behavior	Example
Chinese	none	Emite palabras de segmentación estándar sin añadir términos de búsqueda más cortos.	现代分布式文件系统架构 → 现代, 分布式文件系统, 架构
Chinese	mixed	Evita que las palabras se segmenten estándar y añade términos de búsqueda más cortos de algunas palabras más largas.	现代分布式文件系统架构 → 现代, 分布式文件系统, 分布, 分布式, 布式, 文件, 系统, 架构
Japanese	none	Prefiere compuestos de diccionario más largos.	関西国際空港へのアクセス → 関西国際空港, アクセス
Japanese	discard	Produce términos de grano más fino para algunos compuestos largos sin conservar también su forma completa.	関西国際空港へのアクセス → 関西, 国際, 空港, アクセス
Korean	none	Mantiene las entradas compuestas e inflexionadas del diccionario como términos completos.	한국어 형태소 분석 → 한국어, 형태소, 분석
Korean	discard	Cuando una forma compuesta o flexionada puede dividirse, emite sus partes en lugar del término completo.	한국어 형태소 분석 → 한국, 어, 형태, 소, 분석
Korean	mixed	Cuando una forma compuesta o inflexionada puede dividirse, emite tanto el término completo como sus partes.	한국어 형태소 분석 → 한국어, 한국, 어, 형태소, 형태, 소, 분석

En mixed modo, consulta con plainto_tsquery. Cuando una palabra de consulta produce múltiples lexemas, to_tsquery, websearch_to_tsquery, y phraseto_tsquery únelas con el <-> operador, lo que requiere posiciones adyacentes. mixed El modo inserta posiciones extra para los términos adicionales, por lo que estas condiciones de frase pueden perder las partidas esperadas. Para consultas basadas en posición, define una configuración personalizada con none modo o discard .

Utiliza las configuraciones integradas

Instalar la extensión crea estas configuraciones de búsqueda de texto:

Configuration	Diccionario	Idioma	Mode
tokenizer_chinese	tokenizer_chinese_dict	Chinese	mixed
tokenizer_japanese	tokenizer_japanese_dict	Japanese	discard
tokenizer_korean	tokenizer_korean_dict	Korean	discard

Los tres diccionarios establecen Stemmer = 'english' y usan los valores por defecto Normalize = 'NFKC' y Lowercase = 'true'.

Para ejemplos de extremo a extremo que usan estas configuraciones, véase texto CJK.

Definir una configuración personalizada

Para elegir otro modo o cambiar las opciones predeterminadas, crea un diccionario a partir de la tokenizer_morph plantilla y una configuración de búsqueda de texto que asigne los tipos de tokens PostgreSQL a él, como se muestra a continuación. Este ejemplo utiliza el modo chino none para consultas de frase:

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

Especifica tokenizer_morph opciones en CREATE TEXT SEARCH DICTIONARY o ALTER TEXT SEARCH DICTIONARY. Los nombres de las opciones no son indiferentes a mayúsculas.

Option	Tipo	Predeterminado	Description
Language	chinese, japanese o korean	Required	Selecciona el analizador específico del idioma.
Mode	none, discard o mixed	Required	Controla la salida compuesta y subpalabra. Los modos soportados dependen de: o para chino, none o discard para japonés, y none, discard, o mixed para coreano.mixednoneLanguage
Normalize	NFC, NFKC o none	NFKC	Normaliza el texto antes de la segmentación. NFC preserva las distinciones de compatibilidad. Por ejemplo, el ancho ＡＢＣ completo se reduce en ａｂｃ minúsculas en lugar de convertirse en abc, por lo que no se tiene tallo.
Lowercase	booleano	true	Convierte los lexemas emitidos en minúsculas. Stemmer = 'english' requiere Lowercase = 'true'.
Stemmer	english	Ninguno	Lexemas de raízes solo formados íntegramente por letras ASCII. Omite esta opción para desactivar el stemming en inglés.

Usa el ranking BM25 con lakebase_text

Las configuraciones de búsqueda de texto construidas con lakebase_tokenizer producen valores estándar de PostgreSQL tsvector compatibles con lakebase_text. Para usar la clasificación de relevancia de BM25 y la recuperación top-K, crea un lakebase_bm25 índice en la misma tsvector columna. Para la sintaxis de instalación, creación de índices y consultas, véase lakebase_text.

Pasos siguientes

• lakebase_text
• Búsqueda de Lakebase