Índices de búsqueda de texto completo en tablas administradas del catálogo de Unity

Un índice de búsqueda de texto completo acelera las consultas en una o varias columnas de texto de una tabla administrada de Delta Lake o Iceberg. El índice admite la coincidencia de subcadenas y la coincidencia de palabras. Al consultar la tabla con las funciones de search o isearch, Azure Databricks usa el índice para omitir los archivos que se garantizan que no contengan filas coincidentes. Esto reduce significativamente la cantidad de datos examinados, especialmente para búsquedas selectivas.

Requirements

Los índices de búsqueda de texto completo tienen requisitos en cuanto al proceso de cómputo, los permisos sobre la tabla base y el esquema, y la configuración de la tabla base.

Compute

Los índices de búsqueda de texto completo solo están disponibles en Azure Databricks Runtime 18.2 y versiones posteriores, y debe habilitar esta característica Beta en la configuración del área de trabajo. Consulte Administrar versiones preliminares de Azure Databricks.

Permissions

Para crear un índice de búsqueda:

• Debe tener permiso MODIFY para la tabla a la que hace referencia el índice de búsqueda.
• Debe tener el CREATE TABLE permiso en el esquema primario. Un propietario o usuario de esquema con el privilegio MANAGE puede concederle CREATE TABLE privilegios en el esquema.

Configuración de tablas

Antes de crear un índice de búsqueda de texto completo, la tabla base debe satisfacer lo siguiente:

• Debe crear el índice en el mismo catálogo y esquema que la tabla base.
• La tabla es una tabla Delta Lake administrada o una tabla Iceberg administrada.
• El seguimiento de filas está habilitado (delta.enableRowTracking = true). Consulte Seguimiento de filas en Azure Databricks.
• Las columnas indizadas son de tipo STRING, VARIANT, STRUCTo ARRAY. STRING las columnas usan la intercalación UTF8_BINARY.
• Una columna STRUCT contiene al menos un campo terminal STRING, VARIANT o ARRAY a cualquier profundidad de anidamiento; se ignoran los demás campos terminales.
• La tabla no usa ninguna característica de la lista de limitaciones, como: OpenSharing, clonación superficial, controles de acceso basados en atributos, directivas de seguridad de nivel de fila y máscaras de columna. Consulte Limitaciones.

Para obtener información sobre los requisitos de protocolo de las tablas, que se aplican tanto a las tablas de Delta Lake como a las de Iceberg, consulte Compatibilidad de funciones y protocolos de Delta Lake.

Creación de un índice de búsqueda de texto completo

Puede crear hasta cuatro índices en una sola tabla, cada uno en una columna diferente.

Use CREATE SEARCH INDEX para crear un índice en una o varias columnas de texto. En el ejemplo siguiente se indexa dos columnas de texto de una tabla de registro existente:

CREATE SEARCH INDEX log_idx
ON logs (message, error_detail);

La sintaxis completa es:

CREATE SEARCH INDEX [IF NOT EXISTS] index_name
  ON table_name ( column_name [, column_name ...] )
  [OPTIONS ( option_key = option_value [, ... ] )]

index_name debe ser único dentro del esquema y no puede coincidir con un nombre de tabla existente.

Para controlar cómo se tokeniza el texto, consulte Opciones.

Opciones

La OPTIONS cláusula acepta las siguientes claves:

Para obtener información detallada sobre los errores de opciones no válidas, consulte la condición de error SEARCH_INDEX_INVALID_PARAMETERS.

Selección de un tokenizador para el caso de uso

Los índices de búsqueda tienen dos opciones de tokenizador disponibles, en función de su caso de uso:

Para crear un índice de n-gramas con un tamaño de n-gramas de 4:

CREATE SEARCH INDEX log_ngram_idx
  ON logs (message)
  OPTIONS (tokenizer = 'ngram', ngram_size = 4);

Para crear un split índice con una longitud mínima de token de 2:

CREATE SEARCH INDEX log_word_idx
  ON logs (message)
  OPTIONS (tokenizer = 'split', min_token_length = 2);

Consulta de datos mediante search y isearch

Azure Databricks tiene dos funciones SQL para probar si un patrón de búsqueda está presente en uno o varios destinos de texto:

• search: Distinguir mayúsculas de minúsculas.
• isearch: no distingue mayúsculas de minúsculas.

Seleccione search o isearch según si necesita distinguir entre mayúsculas y minúsculas. Cuando las columnas indexadas están cubiertas por un índice de búsqueda de texto completo, Azure Databricks usa el índice para omitir los archivos que con seguridad no contienen filas coincidentes. Los índices de búsqueda no afectan a los resultados.

Los índices aceleran las consultas más cuando el patrón de búsqueda aparece en una pequeña fracción de los archivos de la tabla.

search( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )
isearch( target [, target ... ] , 'pattern' [, mode => 'substring' | 'word' ] )

Argumentos

search y isearch aceptan los argumentos siguientes:

• target debe ser de tipo STRING, VARIANT, STRUCTo ARRAY, los mismos tipos que permite la indexación. Se eliminan los duplicados de los objetivos.
• pattern debe ser un literal de cadena que no sea NULL.
• mode especifica cómo pattern coincide con cada target:
  • substring (valor predeterminado): pattern coincide como una subcadena dentro de cada target.
  • word: pattern se divide en tokens de palabras utilizando la misma regla que el tokenizador split. La función devuelve true si cada palabra de pattern aparece en al menos un destino, independientemente del orden. Consulte Selección de un tokenizador para su caso de uso.

Devoluciones

search y isearch devuelven un BOOLEAN valor con lógica de tres valores:

• true si al menos un objetivo no nulo coincide.
• null si ningún destino no nulo coincide, pero al menos un destino es null.
• false si todos los objetivos son distintos de NULL y ninguno coincide.

Ejemplos

Los siguientes ejemplos muestran consultas comunes de search y isearch:

-- Case-insensitive substring search across one column.
SELECT * FROM logs
WHERE isearch(message, 'connection refused');

-- Case-sensitive substring search across multiple columns.
SELECT * FROM logs
WHERE search(message, error_detail, '550e8400-e29b-41d4-a716-446655440000');

-- Word search: matches rows containing all three words, in any order.
SELECT * FROM audit_logs
WHERE search(message, 'user admin login', mode => 'word');

Administración de índices

Use las siguientes operaciones para administrar índices de búsqueda de texto completo:

Describir o ver un índice

Para ver información sobre un índice:

DESCRIBE INDEX log_idx;

Actualizar un índice

Los índices de búsqueda de texto completo no se actualizan automáticamente cuando cambia la tabla base.

Para actualizar el índice, agregue entradas para nuevas filas:

REFRESH INDEX log_idx;

REFRESH INDEX es una operación incremental solo de anexión. Indexa nuevos datos, pero no quita entradas para las filas eliminadas.

Para actualizar el índice, tanto para añadir entradas para las filas nuevas como para eliminar las entradas de las filas eliminadas, use REFRESH INDEX ... FULL:

REFRESH INDEX log_idx FULL;

Una actualización completa requiere más recursos de proceso que una actualización incremental. Con el tiempo, las actualizaciones incrementales acumulan entradas obsoletas, lo que aumenta el tamaño del índice y afecta negativamente al rendimiento.

Eliminar un índice

Para quitar un índice, ejecute lo siguiente:

DROP INDEX log_idx;

Para evitar un error por la falta de índices, use:

DROP INDEX IF EXISTS log_idx;

Limitaciones

Los índices de búsqueda de texto completo tienen las siguientes limitaciones:

• No se admite cambiar el nombre de una columna indizada en la tabla base o cambiar su tipo de datos.
• No se admiten tablas con OpenSharing. Si agrega la tabla base como origen o destino de OpenSharing después de crear el índice, Azure Databricks omite el índice de búsqueda.
• No se admiten tablas con clones poco profundos. Si agrega la tabla base como un origen de clon superficial después de crear el índice, Azure Databricks omite el índice de búsqueda.
• No se admiten tablas con controles de acceso basados en atributos, máscaras de columna o directivas de seguridad de nivel de fila. Si agrega cualquiera de estos controles a una tabla con un índice de búsqueda, Azure Databricks omite el índice de búsqueda. Consulte Conceptos básicos para el control de acceso basado en atributos (ABAC).