Accede a los datos de Elasticsearch desde AlloyDB Omni

Selecciona una versión de la documentación:

Puedes acceder a los datos almacenados en Elasticsearch y buscarlos creando un wrapper de datos externos (FDW) y una tabla externa en AlloyDB Omni.

Antes de comenzar

Antes de comenzar, completa lo siguiente:

Crea una cuenta de servicio

AlloyDB Omni requiere una cuenta de servicio con Google Cloud para autenticar y usar Secret Manager. AlloyDB Omni usa Secret Manager para almacenar tu clave de API de Elasticsearch.

Si aún no creaste una cuenta de servicio para AlloyDB Omni, crea una siguiendo estos pasos:

  1. Crea una cuenta de servicio con Google Cloud. Otorgas permisos a esta cuenta de servicio para acceder a Secret Manager en Configura AlloyDB AI.

  2. Crea una clave de cuenta de servicio y guárdala en formato JSON en el archivo private-key.json. Luego, descárgala.

  3. Copia la clave de la cuenta de servicio que creaste en KEY_PATH. La ruta de acceso de la clave debe ser una ruta de acceso en tu host a la que pueda acceder el usuario que ejecuta tu contenedor de AlloyDB Omni y que sea de su propiedad.

Almacena la clave de API de Elasticsearch en Secret Manager

AlloyDB Omni almacena y lee tu clave de API de Elasticsearch desde Secret Manager. Para obtener más información sobre cómo usar Secret Manager, consulta Crea un secreto y accede a él con Secret Manager.

Asegúrate de otorgar permiso a tu cuenta de servicio de AlloyDB Omni para leer el Secret. Para obtener más información, consulta Administra el acceso a los secretos.

Configura AlloyDB AI para AlloyDB Omni

Para configurar AlloyDB AI para AlloyDB Omni, consulta Configura AlloyDB AI para AlloyDB Omni y omite el primer paso.

Habilita y configura la extensión external_search_fdw

Para comenzar la integración en Elasticsearch, completa las siguientes instrucciones para habilitar y configurar la extensión external_search_fdw de AlloyDB Omni:

  1. Habilita la extensión external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Configura el acceso a tu clúster de Elasticsearch a través de un servidor de datos externo.

    CREATE SERVER ELASTICSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (server 'ELASTICSEARCH_SERVER_HOST_PORT',
         search_provider 'elastic',
         auth_mode 'secret_manager',
         auth_method 'AUTH_METHOD',
         secret_path 'SECRET_PATH',
         max_deadline_ms 'MAX_DEADLINE',
         pagination_num_results 'PAGINATION_NUM_RESULTS',
         pagination_context_timeout_ms 'PAGINATION_CONTEXT_TIMEOUT');

    Reemplaza las siguientes variables:

    • ELASTICSEARCH_SERVER_NAME: Es el nombre de tu servidor de datos externo. Por ejemplo, my-elasticsearch-server.

    • ELASTICSEARCH_SERVER_HOST_PORT: Es la URL pública de tu clúster de Elasticsearch. Por ejemplo, https://node1.elastic.test.com:9200.

    • AUTH_METHOD: Es el tipo de autenticación que se usará. Puedes elegir entre las siguientes opciones:

      • ApiKey: Es la clave de API de Elasticsearch personal o de usuario.

      • Basic: Es el nombre de usuario y la contraseña de Elasticsearch.

    • SECRET_PATH: Es la ruta de acceso de Secret Manager a tus credenciales de autenticación de Elasticsearch. Por ejemplo, projects/123456789012/secrets/apikey/versions/1. 123456789012 representa el ID del proyecto de Google Cloud .

    • MAX_DEADLINE (opcional): es la cantidad máxima de tiempo, en milisegundos, que AlloyDB Omni espera una respuesta de Elasticsearch. Establece este valor según las ubicaciones de tus instancias de AlloyDB Omni y Elasticsearch. El valor predeterminado es 10000.

    • PAGINATION_NUM_RESULTS (opcional): Es la cantidad máxima de resultados que se recuperan por lote de Elasticsearch. Si se solicitan más resultados, AlloyDB Omni los recupera en varios lotes de este tamaño. El valor predeterminado es 32.

    • PAGINATION_CONTEXT_TIMEOUT (opcional): Es la cantidad de tiempo, en milisegundos, que Elasticsearch mantiene activo el contexto de la solicitud de paginación. El valor predeterminado es 30000.

  3. Define la asignación de usuarios de PostgreSQL para el servidor de Elasticsearch. Ten en cuenta que los FDW de PostgreSQL requieren esta asignación de usuarios para funcionar. AlloyDB Omni se autentica con el encabezado de autorización de REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Configura el esquema para tus datos de Elasticsearch a través de una tabla de datos externa.

    CREATE FOREIGN TABLE ELASTICSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    ELASTICSEARCH_FIELDS)
       SERVER ELASTICSEARCH_SERVER_NAME
       OPTIONS(remote_table_name 'ELASTICSEARCH_INDEX_NAME');

    Reemplaza las siguientes variables nuevas:

    • ELASTICSEARCH_FD_TABLE: es el nombre de la tabla de datos externa que representa tu tabla de Elasticsearch. Por ejemplo, my-fd-elasticsearch-table

    • ELASTICSEARCH_FIELDS: es una lista separada por comas de definiciones de esquemas de campos de Elasticsearch en el siguiente formato: elasticsearch_field_name PG_DATA_TYPE. Por ejemplo, elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Estos campos deben coincidir con los nombres de los campos en Elasticsearch, a menos que se agregue la opción remote_field_name. Por ejemplo: elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Para obtener la lista de tipos de datos de Elasticsearch que se pueden definir para AlloyDB Omni, consulta Tipos de datos compatibles.

    • ELASTICSEARCH_INDEX_NAME: es el nombre de tu índice de Elasticsearch. Por ejemplo, my-elasticsearch-index

Tipos de datos admitidos

AlloyDB Omni admite los siguientes tipos de datos de Elasticsearch:

Tipos de datos Tipo de PostgreSQL
alias Tipo de PostgreSQL para el campo al que hace referencia alias
binary bytea
boolean BOOLEAN

byte,

short

SMALLINT
date TIMESTAMPTZ

double,

scaled_float

DOUBLE PRECISION

float,

half_float

REAL
integer INTEGER
long BIGINT

object,

flattened

jsonb

text,

annotated_text,

keyword,

constant_keyword,

wildcard

TEXT
unsigned_long NUMERIC

Consulta tus datos de Elasticsearch

AlloyDB Omni toma las consultas en SQL y las convierte en consultas de la API de REST de Elasticsearch. Durante esta conversión, AlloyDB Omni intenta enviar la mayor cantidad posible de lógica de consulta sin cambiar la identidad de la consulta, incluida la LIMIT de la consulta en SQL. Sin embargo, hay casos en los que puedes especificar que no se envíen ciertos campos de Elasticsearch o en los que no se puede enviar la lógica de consulta. Por ejemplo, LIKE y otros operadores de coincidencia de texto no se pueden enviar hacia abajo. Para ver más ejemplos de lo que se puede y no se puede enviar, consulta Ejemplos de envío.

En situaciones en las que el LIMIT se establece en un valor superior a pagination_num_results o en las que no se especifica LIMIT o no se puede enviar, AlloyDB Omni usa la API de Scroll, que puede consumir muchos recursos.

Debido a que la API de Scroll puede consumir muchos recursos, te recomendamos que examines tus consultas con EXPLAIN VERBOSE para ver qué APIs se usan. Limitar el uso de la API de Scroll y usar LIMIT mejora el rendimiento.

Para consultar tus datos de Elasticsearch, tienes las siguientes opciones:

  • Consultas en SQL estándar
  • DSL de consulta
  • Búsquedas híbridas

Consultas en SQL estándar

Las consultas en SQL estándar se pueden escribir con la sintaxis de Lucene de Elasticsearch.

Para realizar una consulta en SQL estándar, consulta el siguiente ejemplo:

SELECT id, body
FROM ELASTICSEARCH_FD_TABLE
WHERE FILTER
ORDER BY metadata <@> 'QUERY';

Reemplaza las siguientes variables:

  • ELASTICSEARCH_FD_TABLE: es el nombre de la tabla de datos externa que representa tu tabla de Elasticsearch. Por ejemplo, my-fd-elasticsearch-table.

  • FILTER (opcional): Es el filtro que se aplicará a tu consulta de Elasticsearch. Por ejemplo, AND qubits < 105

  • QUERY: Es la consulta que se enviará a Elasticsearch. Para ver algunas consultas de ejemplo, consulta la siguiente lista:

    • body:quantum body:computing
    • body:(quantum computing)
    • body:(quantum AND computing)
    • body:"quantum computing"
    • body:"quantum computing" AND qubits:[* TO 105}

DSL de consulta

DSL de consulta es el lenguaje de consulta con estilo JSON y con todas las funciones de Elasticsearch, recomendado para casos de uso avanzados. El DSL de consulta te permite realizar búsquedas, filtrados y agregaciones complejos que no se pueden expresar en la sintaxis de consulta en SQL.

Para realizar consultas con DSL de consulta, consulta el siguiente ejemplo:

SELECT id, body
FROM ELASTICSEARCH_FD_TABLE
ORDER BY
  metadata <@> $${
    "query": {
      "bool": {
        "must": [
          {
            "query_string": {
              "query" : "QUERY"
            }
          }
        ],
        "filter": [
          {
            "range": { 
              "id": { 
                "lt": "10"
              }
            }
          }
        ]
      }
    },
    "sort": [
      {
        "id": {
          "order": "desc"
        }
      }
    ]
  }$$
LIMIT 1;

Reemplaza las siguientes variables:

  • ELASTICSEARCH_FD_TABLE: es el nombre de la tabla de datos externa que representa tu tabla de Elasticsearch. Por ejemplo, my-fd-elasticsearch-table.

  • QUERY: Es la consulta que se enviará a Elasticsearch. Por ejemplo, "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

Ten en cuenta que, para el DSL de consulta, solo se espera que propagues las expresiones query, filter y sort.

Para realizar una búsqueda híbrida en tus datos de Elasticsearch, consulta el siguiente ejemplo de búsqueda:

SELECT *
FROM
  ai.hybrid_search(
    ARRAY[
      '{"limit": LIMIT,
        "data_type": "external_search_fdw",
        "weight": WEIGHT,
        "table_name": "ELASTICSEARCH_FD_TABLE",
        "key_column": "DOCUMENT_ID_COLUMN_NAME",
        "query_text_input": QUERY}'::jsonb],
    NULL::TEXT,
    'RRF',
    FALSE)
ORDER BY score DESC;

Reemplaza las siguientes variables:

  • LIMIT: Es la cantidad de resultados que se devolverán. Por ejemplo, 3

  • WEIGHT: Es la contribución de esta entrada de búsqueda a la fusión por clasificación recíproca (RRF) general. Por ejemplo, 0.5. Si no proporcionas pesos, se distribuyen de manera uniforme. Para obtener más información, consulta Parámetros de la función de búsqueda híbrida.

  • ELASTICSEARCH_FD_TABLE: es el nombre de la tabla de datos externa que representa tu tabla de Elasticsearch. Por ejemplo, my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME: Es el nombre de la columna de ID del documento.

  • QUERY: Es la consulta que se enviará a Elasticsearch. Por ejemplo, "elasticsearch_field_name:\"quantum computing\"" busca la frase "computación cuántica" en el campo elasticsearch_field_name. Todos los tipos de consultas mencionados en Tipos de datos admitidos se pueden usar en tu consulta.

Para obtener más información sobre los parámetros disponibles para las búsquedas híbridas, consulta Parámetros de la función de búsqueda híbrida.

Ejemplos de anuncios pushdown

Para que las consultas sean más eficientes, AlloyDB Omni intenta enviar los siguientes aspectos de la consulta directamente a la llamada a la API realizada a Elasticsearch:

  • SELECT campos
  • WHERE filtros
  • ORDER BY ordenamiento
  • LIMIT

Para ver ejemplos de consultas que muestran qué aspectos AlloyDB Omni puede y no puede enviar, consulta la siguiente tabla.

Tipo de consulta Ejemplo de consulta Elementos de consulta enviados
Consultas sin filtrar 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC orden
  • LIMIT
Coincidencia exacta de texto 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expresiones de campo único 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
Expresiones constantes 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expresiones con funciones 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT campos
Expresiones de varios campos 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT campos
Filtrado de puntuaciones 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC orden
LIKE y operadores similares 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT campos
  • WHERE id > 10 filtro
Consultas sin procesar 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC orden

Soluciona problemas

Si tienes problemas de autenticación o conectividad cuando consultas tu clúster de Elasticsearch, verifica lo siguiente:

  • Errores de autenticación HTTP 401 o 403: Verifica que tu secreto de Elasticsearch en Secret Manager contenga credenciales de autenticación válidas para tu auth_method (ApiKey o Basic) y verifica que tu cuenta de servicio tenga el permiso secretmanager.secretAccessor.
  • Tiempos de espera de conexión: Verifica las reglas de red y la configuración del firewall entre AlloyDB Omni y tu extremo de Elasticsearch.

Limitaciones

  • AlloyDB Omni lee, pero no escribe, datos de Elasticsearch.

  • Eres responsable de sincronizar los datos entre AlloyDB Omni y Elasticsearch.

  • No se admiten los tipos especializados de Elasticsearch, como geo_point. Para obtener más información, consulta Tipos de datos compatibles.

¿Qué sigue?