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

Encontrar filas que contengan una palabra o subcadena específica, como un código de error en mensajes de registro, puede requerir escanear grandes cantidades de texto. 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. Cuando consultas la tabla con las funciones search o isearch, Azure Databricks usa el índice para saltarse archivos que no pueden contener filas coincidentes. Esto reduce significativamente la cantidad de datos examinados, especialmente para búsquedas selectivas.

Cuándo usar índices de búsqueda en texto completo

Crear un índice de búsqueda en texto completo cuando:

• Regularmente buscas en una o más columnas de texto de una tabla gestionada grande en busca de palabras o subcadenas.
• El patrón de búsqueda aparece en una pequeña fracción de los archivos de la tabla. Los índices aceleran más estas consultas selectivas.
• Puede escribir las consultas con las funciones search o isearch. Consulte Consultar datos con search e isearch.

No crees un índice en una tabla que use una característica listada en Limitaciones, como seguridad a nivel de fila o máscaras de columna. Azure Databricks no usa el índice en esas tablas.

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 en texto completo solo están disponibles en Databricks Runtime 18.3 y versiones posteriores, y debes habilitar esta función Beta en la configuración de tu espacio 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 en texto completo, la tabla base debe cumplir todos estos requisitos:

• 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.
• La optimización predictiva está habilitada. Consulte Habilitación de la optimización predictiva.
• 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 estas 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 estos argumentos:

• 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

En estos ejemplos se muestran consultas search e isearch habituales:

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

Actualización automática del índice

La optimización predictiva mantiene actualizados los índices de búsqueda en texto completo a medida que cambia la tabla base. Añade entradas para nuevas filas y elimina entradas para las filas eliminadas. Los refrescos se ejecutan en segundo plano, por lo que los datos escritos recientemente pueden tardar un tiempo en indexarse.

No puedes ejecutarlo REFRESH INDEX manualmente.

Si desactivas la optimización predictiva en la tabla base, sus índices dejan de actualizarse. Las consultas permanecen correctas, pero escanean los datos que el índice no cubre, así que se ralentizan a medida que cambia la tabla. Para reanudar las actualizaciones, vuelve a activar la optimización predictiva.

Las actualizaciones de índices se ejecutan como operaciones de optimización predictiva en computación serverless y se facturan a tu cuenta. Consulta Cómputo y facturación.

Para hacer un seguimiento de las actualizaciones del índice, consulte la tabla del sistema de optimización predictiva para el tipo de operación REFRESH_INDEX. Estas filas llevan el nombre del índice y el ID en table_name y table_id. Consulte Referencia de la tabla del sistema de optimización predictiva.

Administración de índices

Utiliza estas operaciones para gestionar índices de búsqueda en texto completo:

Describir o ver un índice

Para ver información sobre un índice:

DESCRIBE INDEX log_idx;

Eliminar un índice

Para eliminar un índice, ejecuta:

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 en texto completo tienen estas 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).