Acessar dados do Elasticsearch no AlloyDB Omni

Selecione uma versão da documentação:

É possível acessar e pesquisar dados armazenados no Elasticsearch criando um wrapper de dados externos (FDW) e uma tabela externa no AlloyDB Omni.

Antes de começar

Antes de começar, faça o seguinte:

Criar uma conta de serviço

O AlloyDB Omni exige uma conta de serviço com Google Cloud para autenticar e usar o Secret Manager. O AlloyDB Omni usa o Secret Manager para armazenar sua chave de API do Elasticsearch.

Se você ainda não tiver criado uma conta de serviço para o AlloyDB Omni, siga estas etapas:

  1. Crie uma conta de serviço com Google Cloud. Você concede a essa conta de serviço permissões para acessar o Secret Manager em Criar um cluster de banco de dados com o AlloyDB AI.

  2. Crie uma chave de conta de serviço e salve-a no formato JSON no arquivo private-key.json. Em seguida, faça o download dela.

  3. Armazene a chave em um local permanente no sistema de arquivos. Ele fica nesse local durante todo o ciclo de vida do servidor do AlloyDB Omni.

    Anote o local no sistema de arquivos, porque você vai precisar dele nas próximas etapas.

  4. Crie um secret do Kubernetes usando a chave da conta de serviço.

Armazenar a chave de API do Elasticsearch no Secret Manager

O AlloyDB Omni armazena e lê sua chave de API do Elasticsearch no Secret Manager. Para mais informações sobre como usar o Secret Manager, consulte Criar e acessar um secret usando o Secret Manager.

Confira se você deu à conta de serviço do AlloyDB Omni permissão para ler o secret. Para mais informações, consulte Gerenciar o acesso a secrets.

Criar um cluster de banco de dados com a IA do AlloyDB

Para criar um cluster de banco de dados com o AlloyDB AI, consulte Instalar o AlloyDB AI no AlloyDB Omni. Para acessar e consultar dados com o Elasticsearch, não é necessário especificar as configurações de vertexAI*.

Ativar e configurar a extensão external_search_fdw

Para iniciar a integração com o Elasticsearch, siga estas instruções para ativar e configurar a extensão external_search_fdw do AlloyDB Omni:

  1. Ative a extensão external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Configure o acesso ao cluster do Elasticsearch usando um servidor de dados 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');

    Substitua as seguintes variáveis:

    • ELASTICSEARCH_SERVER_NAME: nome do servidor de dados externo. Por exemplo, my-elasticsearch-server.

    • ELASTICSEARCH_SERVER_HOST_PORT: URL público do seu cluster do Elasticsearch. Por exemplo, https://node1.elastic.test.com:9200.

    • AUTH_METHOD: tipo de autenticação a ser usado. Você pode escolher entre as seguintes opções:

    • SECRET_PATH: caminho do Secret Manager para suas credenciais de autenticação do Elasticsearch. Por exemplo, projects/123456789012/secrets/apikey/versions/1. 123456789012 representa o ID do projeto Google Cloud .

    • (Opcional) MAX_DEADLINE: tempo máximo, em milissegundos, que o AlloyDB Omni aguarda uma resposta do Elasticsearch. Defina esse valor com base nos locais das instâncias do AlloyDB Omni e do Elasticsearch. O valor padrão é 10000.

    • (Opcional) PAGINATION_NUM_RESULTS: número máximo de resultados buscados por lote do Elasticsearch. Se mais resultados forem solicitados, o AlloyDB Omni vai recuperar os resultados em vários lotes desse tamanho. O valor padrão é 32.

    • (Opcional) PAGINATION_CONTEXT_TIMEOUT: período, em milissegundos, em que o Elasticsearch mantém o contexto de solicitação de paginação ativo. O valor padrão é 30000.

  3. Defina o mapeamento de usuários do PostgreSQL para o servidor do Elasticsearch. As FDWs do PostgreSQL exigem esse mapeamento de usuário para funcionar. O AlloyDB Omni faz a autenticação usando o cabeçalho de autorização REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Configure o esquema dos seus dados do Elasticsearch usando uma tabela de dados 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');

    Substitua as seguintes variáveis:

    • ELASTICSEARCH_FD_TABLE: nome da tabela de dados externa que representa sua tabela do Elasticsearch. Por exemplo, my-fd-elasticsearch-table.

    • ELASTICSEARCH_FIELDS: lista separada por vírgulas de definições de esquema de campo do Elasticsearch no seguinte formato: elasticsearch_field_name PG_DATA_TYPE. Por exemplo, elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Esses campos precisam corresponder aos nomes de campo no Elasticsearch, a menos que a opção remote_field_name seja anexada. Por exemplo, elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Para conferir a lista de tipos de dados do Elasticsearch que podem ser definidos para o AlloyDB Omni, consulte Tipos de dados compatíveis.

    • ELASTICSEARCH_INDEX_NAME: nome do seu índice do Elasticsearch. Por exemplo, my-elasticsearch-index.

Tipos de dados compatíveis

O AlloyDB Omni é compatível com os seguintes tipos de dados do Elasticsearch:

Tipos de dados Tipo do PostgreSQL
alias Tipo do PostgreSQL para o campo a que alias está fazendo referência
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

Consultar os dados do Elasticsearch

O AlloyDB Omni recebe consultas SQL e as converte em consultas da API REST do Elasticsearch. Durante essa conversão, o AlloyDB Omni tenta enviar o máximo possível de lógica de consulta sem alterar a identidade da consulta, incluindo o LIMIT da consulta SQL. No entanto, há casos em que você pode especificar para não enviar por push determinados campos do Elasticsearch ou em que a lógica de consulta não pode ser enviada por push. Por exemplo, LIKE e outros operadores de correspondência de texto não podem ser enviados por push-down. Para mais exemplos do que pode e não pode ser enviado por push, consulte Exemplos de pushdown.

Em cenários em que LIMIT é definido como maior que pagination_num_results ou em que LIMIT não é especificado ou não pode ser reduzido, o AlloyDB Omni usa a API Scroll, que pode consumir muitos recursos.

Como a API Scroll pode consumir muitos recursos, recomendamos examinar suas consultas usando EXPLAIN VERBOSE para ver quais APIs são usadas. Limitar o uso da API Scroll e usar LIMIT melhora o desempenho.

Para consultar seus dados do Elasticsearch, você tem as seguintes opções:

  • Consultas SQL padrão
  • DSL de consulta
  • Pesquisas híbridas

Consultas SQL padrão

As consultas SQL padrão podem ser escritas usando a sintaxe do Lucene do Elasticsearch.

Para fazer uma consulta SQL padrão, consulte o exemplo a seguir:

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

Substitua as seguintes variáveis:

  • ELASTICSEARCH_FD_TABLE: nome da tabela de dados externa que representa sua tabela do Elasticsearch. Por exemplo, my-fd-elasticsearch-table.

  • (Opcional) FILTER: filtro a ser aplicado à sua consulta do Elasticsearch. Por exemplo, AND qubits < 105.

  • QUERY: consulta a ser enviada ao Elasticsearch. Confira alguns exemplos de consultas:

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

DSL de consulta

A DSL de consulta é a linguagem de consulta completa no estilo JSON do Elasticsearch recomendada para casos de uso avançados. Com a DSL de consulta, é possível realizar pesquisas, filtragens e agregações complexas que não podem ser expressas na sintaxe de consulta SQL.

Para realizar consultas usando a DSL de consulta, confira o exemplo a seguir:

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;

Substitua as seguintes variáveis:

  • ELASTICSEARCH_FD_TABLE: nome da tabela de dados externa que representa sua tabela do Elasticsearch. Por exemplo, my-fd-elasticsearch-table.

  • QUERY: consulta a ser enviada ao Elasticsearch. Por exemplo, "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

Para a DSL de consulta, você só precisa propagar as expressões query, filter e sort.

Para realizar uma pesquisa híbrida nos dados do Elasticsearch, consulte o exemplo de pesquisa a seguir:

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;

Substitua as seguintes variáveis:

  • LIMIT: número de resultados a serem retornados. Por exemplo, 3.

  • WEIGHT: contribuição dessa entrada de pesquisa para a Reciprocal Rank Fusion (RRF) geral. Por exemplo, 0.5. Se você não fornecer pesos, eles serão distribuídos uniformemente. Para mais informações, consulte Parâmetros da função de pesquisa híbrida.

  • ELASTICSEARCH_FD_TABLE: nome da tabela de dados externa que representa sua tabela do Elasticsearch. Por exemplo, my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME: nome da coluna de ID do documento.

  • QUERY: consulta a ser enviada ao Elasticsearch. Por exemplo, "elasticsearch_field_name:\"quantum computing\"" pesquisa a frase "computação quântica" no campo elasticsearch_field_name. Todos os tipos de consulta mencionados em Tipos de dados compatíveis podem ser usados na sua consulta.

Para mais informações sobre os parâmetros disponíveis para pesquisas híbridas, consulte Parâmetros da função de pesquisa híbrida.

Exemplos de pushdown

Para tornar as consultas mais eficientes, o AlloyDB Omni tenta enviar os seguintes aspectos da consulta diretamente para a chamada de API feita ao Elasticsearch:

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

Para exemplos de consultas que mostram quais aspectos o AlloyDB Omni pode e não pode enviar por push, consulte a tabela a seguir.

Tipo de consulta Exemplo de consulta Elementos de consulta enviados por push-down
Consultas não filtradas 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC de classificação
  • LIMIT
Correspondência exata de texto 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expressões de campo único 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
Expressões constantes 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expressões com funções 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT campos
Expressões de vários campos 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT campos
Filtragem de pontuação 
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 de classificação
LIKE e operadores semelhantes 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT campos
  • WHERE id > 10 filtro
Consultas brutas 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC classificação

Solução de problemas

Se você tiver problemas de autenticação ou conectividade ao consultar seu cluster do Elasticsearch, verifique o seguinte:

  • Erros de autenticação HTTP 401 ou 403: verifique se o secret do Elasticsearch no Secret Manager contém credenciais de autenticação válidas para seu auth_method (ApiKey ou Basic) e se sua conta de serviço tem a permissão secretmanager.secretAccessor.
  • Tempo limite de conexão: verifique as regras de rede e a configuração do firewall entre o AlloyDB Omni e o endpoint do Elasticsearch.

Limitações

  • O AlloyDB Omni lê, mas não grava, dados do Elasticsearch.

  • Você é responsável por sincronizar dados entre o AlloyDB Omni e o Elasticsearch.

  • Tipos especializados do Elasticsearch, como geo_point, não são compatíveis. Para mais informações, consulte Tipos de dados compatíveis.

A seguir