Implementar búsqueda de texto completo en chino con pg_jieba en ServBay

Descripción general

En idiomas como el inglés, la funcionalidad de búsqueda de texto completo incorporada en PostgreSQL funciona eficazmente usando análisis léxico basado en espacios y signos de puntuación. Sin embargo, el texto chino no cuenta con espacios naturales entre palabras, por lo que se necesita una herramienta especializada de segmentación para dividir la secuencia de caracteres chinos en palabras con significado independiente.

pg_jieba es una extensión de terceros para bases de datos PostgreSQL que integra la popular librería de segmentación de chino Jieba. Con pg_jieba, podrás realizar una segmentación eficiente y precisa del texto en chino, y construir funciones avanzadas de búsqueda de texto completo en este idioma directamente en PostgreSQL.

ServBay, como entorno de desarrollo web local integrado, ya incluye la extensión pg_jieba preinstalada, lo que elimina la necesidad de compilar e instalar manualmente. De esta forma, puedes comenzar rápidamente a programar y probar búsqueda de texto completo en chino en tu entorno local.

A continuación, aprenderás cómo activar, configurar y utilizar pg_jieba en el entorno de ServBay.

Requisitos previos

Antes de usar pg_jieba, asegúrate de haber completado los siguientes pasos:

1. Haber instalado ServBay en macOS y tener PostgreSQL ejecutándose correctamente.
2. Tener conocimientos básicos sobre el manejo de bases de datos PostgreSQL, incluyendo cómo conectarse y ejecutar sentencias SQL.

Instalación y activación de pg_jieba

ServBay ya empaqueta la extensión pg_jieba junto a PostgreSQL. No necesitas descargar ni compilar nada manualmente; simplemente ejecuta un comando SQL sencillo en la base de datos de destino para activarla.

Pasos para habilitar la extensión pg_jieba:

1. Conéctate a tu base de datos PostgreSQL:
   Abre la terminal y utiliza la herramienta en línea de comandos psql para conectarte a tu base de datos PostgreSQL. Sustituye your_username por tu usuario de PostgreSQL y your_database por el nombre de tu base de datos. Por defecto, el usuario y la base de datos en ServBay suelen ser servbay o postgres.

   psql -U your_username -d your_database

   Por ejemplo, usando el usuario y base de datos por defecto:

   psql -U servbay -d servbay

2. Crear y habilitar la extensión pg_jieba:
   En la línea de comandos de psql, ejecuta el siguiente comando SQL:

   CREATE EXTENSION pg_jieba;

   Si la extensión ya había sido creada, podrías obtener un mensaje de error al repetir este comando; esto es completamente normal.

3. Verifica que pg_jieba está activo:
   Ejecuta el siguiente comando para listar las extensiones instaladas en tu base de datos:

   \dx

   Si ves pg_jieba en la lista, la extensión está correctamente activada.

Configuración de pg_jieba para búsqueda de texto completo en chino

Una vez activado pg_jieba, necesitas configurar la funcionalidad de búsqueda de texto (Text Search) en PostgreSQL, indicando que deseas usar pg_jieba como el analizador de segmentación.

Configuración del Texto de Búsqueda (Text Search Configuration)

La configuración de búsqueda de texto determina cómo se procesan los documentos para búsquedas de texto completo, incluyendo qué analizador (parser) se utiliza y cómo se manejan los diferentes tipos de tokens.

1. Crear una configuración de búsqueda de texto:
   Crea una configuración de búsqueda de texto llamada chinese y especifícale que use pg_jieba como su analizador.

   CREATE TEXT SEARCH CONFIGURATION chinese (PARSER = pg_jieba);

   Esta configuración le dice a PostgreSQL que use pg_jieba para segmentar el texto durante el procesamiento.

2. Agregar mapas de tokens (Mapping) para los resultados de segmentación:
   El analizador pg_jieba generará tokens de diferentes tipos según la categoría gramatical (part of speech). Para incluir estos tokens en el índice y hacerlos buscables, necesitas mapearlos a un diccionario específico. En este caso, los tipos más comunes (como sustantivos n, verbos v, adjetivos a, etc.) se asignarán al diccionario incorporado de PostgreSQL llamado simple, el cual utiliza los resultados del parser directamente, sin más transformaciones.

   ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR n,v,a,i,e,l WITH simple;

   Aquí, n,v,a,i,e,l son etiquetas para clases de palabras que puede identificar pg_jieba. Puedes ajustar o agregar etiquetas según tus necesidades. Algunas etiquetas comunes incluyen:

   • n: Sustantivo
   • v: Verbo
   • a: Adjetivo
   • i: Idioma/expresión
   • e: Interjección
   • l: Frase hecha/modismo
   • nr: Nombre de persona
   • ns: Nombre geográfico
   • nt: Institución/grupo
   • nz: Otros nombres propios
   • m: Numeral
   • q: Contador
   • t: Expresión temporal
   • s: Lugar/localidad
   • f: Orientación
   • p: Preposición
   • c: Conjunción
   • u: Partícula
   • xc: Otros funcionales
   • w: Signos de puntuación
   • eng: Palabras en inglés
   • x: Sin morfema

   Por lo general, solo querrás indexar y buscar palabras con significado real como sustantivos, verbos y adjetivos.

Ejemplo de búsqueda de texto completo con pg_jieba

Una vez realizado el ajuste de configuración, puedes utilizar pg_jieba para búsquedas de texto completo en chino. Veamos un ejemplo sencillo:

Crear tabla y datos de ejemplo

Primero, crea una tabla para almacenar los documentos e inserta algunos datos de muestra con texto en chino.

1. Crear la tabla:

   CREATE TABLE documents (
       id SERIAL PRIMARY KEY,
       content TEXT
   );

2. Insertar datos de ejemplo:

   INSERT INTO documents (content) VALUES
   ('我爱自然语言处理技术'),
   ('中文分词是文本处理的重要步骤'),
   ('pg_jieba是一个很好的中文分词工具，它基于结巴分词库'),
   ('ServBay 让本地开发变得简单高效');

Crear un índice para búsqueda de texto completo

Para mejorar el rendimiento de las consultas, especialmente con grandes volúmenes de datos, se recomienda crear un índice en la(s) columna(s) que usarás para buscar. El tipo de índice GIN (Generalized Inverted Index) de PostgreSQL es ideal para este propósito.

1. Crear un índice GIN:
   Usando la función to_tsvector y la configuración chinese creada antes, crea un índice GIN sobre la columna content.
   to_tsvector('chinese', content) convierte el contenido a un tipo tsvector usando el segmentador pg_jieba.

   CREATE INDEX idx_gin_content ON documents USING gin (to_tsvector('chinese', content));

Realizar búsquedas de texto completo

Puedes utilizar la función to_tsquery junto con el operador @@ para ejecutar búsquedas de texto completo.
to_tsquery('chinese', 'tu consulta') convierte tu frase de búsqueda en un tipo tsquery usando la configuración chinese.
El operador @@ verifica si un tsvector coincide con un tsquery.

1. Ejecuta la consulta de búsqueda:
   Buscar los documentos que contienen “中文” y “分词”.

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', '中文 & 分词');

   El símbolo & indica AND lógico en tsquery.
   También puedes usar | para OR lógico, y ! para NOT lógico.

   Por ejemplo, para buscar documentos que contengan “ServBay” o “开发”:

   SELECT
       id,
       content
   FROM documents
   WHERE to_tsvector('chinese', content) @@ to_tsquery('chinese', 'ServBay | 开发');

Diccionarios personalizados

pg_jieba utiliza por defecto el diccionario provisto por la librería Jieba para segmentar palabras. En algunos escenarios, podrías querer agregar vocabulario personalizado (como terminología profesional, nombres de productos, etc.) para mejorar la precisión.

Puedes crear un archivo de diccionario personalizado y configurarlo en pg_jieba.

Añadir vocabulario personalizado

1. Crear un archivo de diccionario personalizado:
   Crea un archivo de texto en el directorio de configuración de ServBay, por ejemplo:

   /Applications/ServBay/etc/pg_jieba/custom_dict.txt

   Ten en cuenta que esta es una ruta sugerida; puedes elegir otra según la estructura real de tu instalación.

2. Agregar palabras personalizadas al archivo:
   Abre custom_dict.txt en un editor de texto. Escribe una palabra por línea. Opcionalmente, puedes añadir la frecuencia y la etiqueta gramatical separadas por espacios: palabra [frecuencia [etiqueta]]. Cuanto mayor la frecuencia, mayor la probabilidad de separar ese vocabulario del texto.

   自然语言处理 3 n
   ServBay 5 eng
   结巴分词库 3 n

   Por ejemplo, 3 n indica que “自然语言处理” tiene frecuencia 3 y es un sustantivo. 5 eng indica que “ServBay” debe ser segmentado como término en inglés y con frecuencia 5.

3. Configura pg_jieba para usar el diccionario personalizado:
   En la sesión de PostgreSQL, configura el parámetro pg_jieba.dict_path apuntando al directorio donde se encuentra tu diccionario personalizado.
   Nota: pg_jieba.dict_path suele ser un directorio, no un archivo concreto. Si tu archivo personalizado se encuentra en el mismo directorio que el diccionario principal o en el directorio indicado en la configuración de pg_jieba, puede que no sea necesario modificar el parámetro, dependiendo de cómo ServBay empaquete la extensión. Consulta la documentación de ServBay o realiza pruebas para determinar la configuración correcta.

   Si la configuración de pg_jieba en ServBay permite especificar un archivo directamente, o si ya está en el directorio por defecto escaneado por pg_jieba, este SET podría ser opcional o variar:

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/'; -- Suponiendo que el diccionario principal y custom_dict.txt están en este directorio

   O, si efectivamente puedes apuntar al archivo (comportamiento poco habitual, consulta la documentación de ServBay):

   SET pg_jieba.dict_path = '/Applications/ServBay/etc/pg_jieba/custom_dict.txt'; -- Usa con precaución, verifica qué acepta tu instalación

   Importante: El comando SET solo es válido para la sesión actual. Para que sea permanente, modifica postgresql.conf añadiendo el parámetro pg_jieba.dict_path con la ruta correspondiente.

Recargar el diccionario

Después de modificar el archivo de diccionario personalizado o cambiar la configuración de pg_jieba.dict_path, necesitas recargar el diccionario para que los cambios tengan efecto.

1. Recargar el diccionario:
   Ejecuta la siguiente función SQL:

   SELECT jieba_reload_dict();

   Tras la ejecución, las operaciones de segmentación utilizarán el diccionario actualizado.

Preguntas frecuentes (FAQ)

• P: Al ejecutar CREATE EXTENSION pg_jieba; aparece el error "extension "pg_jieba" is not available", ¿qué hago?
  R: Normalmente, esto significa que los archivos de la extensión no están instalados correctamente en el directorio de extensiones de PostgreSQL, o PostgreSQL no puede encontrarlos. En ServBay, pg_jieba debería venir preinstalado. Verifica que te estás conectando a la instancia de PostgreSQL de ServBay y que la instalación no esté dañada. Si el problema persiste, intenta reiniciar ServBay o revisa los archivos de registro de ServBay.

• P: Mi diccionario personalizado no funciona, ¿qué hago?
  R: Verifica lo siguiente:

  1. Que la ruta del archivo del diccionario es correcta y el usuario de PostgreSQL tiene permisos de lectura.
  2. Que el formato del archivo es correcto: una palabra por línea, frecuencia y etiqueta opcionales separados por espacios.
  3. Que has configurado correctamente el parámetro pg_jieba.dict_path. Recuerda que SET solo aplica a la sesión actual. Para hacerlo permanente, edita postgresql.conf.
  4. Que ejecutaste SELECT jieba_reload_dict(); para recargar el diccionario.
  5. Si modificaste postgresql.conf, reinicia el servidor PostgreSQL.

• P: ¿Por qué los resultados de la búsqueda de texto no son precisos?
  R: La precisión depende tanto de la calidad de la segmentación como de cómo construyes tus consultas.

  1. Verifica la segmentación usando la función ts_debug('chinese', 'Tu texto') para ver cómo la configuración chinese segmenta una muestra. Así podrás comprobar si el diccionario personalizado se está usando correctamente.
  2. Ajusta la configuración de segmentación cambiando los tipos de palabras en el comando ALTER TEXT SEARCH CONFIGURATION chinese ADD MAPPING FOR ... WITH simple;, por ejemplo, excluyendo partículas y signos de puntuación.
  3. Mejora tus consultas revisando los términos y operadores lógicos (&, |, !) utilizados con to_tsquery.

Resumen

pg_jieba es una poderosa herramienta para implementar búsqueda de texto completo en chino dentro de PostgreSQL. Gracias a la integración preconfigurada de pg_jieba en ServBay, cualquier desarrollador puede habilitar y configurar segmentación de texto en chino localmente de manera sencilla.
Siguiendo los pasos de esta guía, ya sabes cómo instalar, configurar y utilizar pg_jieba en ServBay, cómo crear y personalizar configuraciones de búsqueda de texto, ejecutar búsquedas básicas de texto completo y mejorar la segmentación con diccionarios personalizados. Incorporando estas técnicas en tus proyectos, mejorarás significativamente la capacidad de búsqueda sobre contenido en chino.