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, na sigla em inglês) 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 requer 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 criou uma conta de serviço para o AlloyDB Omni, siga estas etapas:

  1. Crie uma conta de serviço com Google Cloud. Conceda a essa conta de serviço permissões para acessar o Secret Manager em Configurar a IA do AlloyDB.

  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. Copie a chave da conta de serviço que você criou para KEY_PATH. O caminho da chave precisa ser um caminho no host que seja acessível e de propriedade do usuário que executa o contêiner do AlloyDB Omni.

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.

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

Configurar a IA do AlloyDB para o AlloyDB Omni

Para configurar a IA do AlloyDB para o AlloyDB Omni, consulte Configurar a IA do AlloyDB para o AlloyDB Omni e pule a primeira etapa.

Ativar e configurar a extensão external_search_fdw

Para iniciar a integração com o Elasticsearch, siga as instruções abaixo 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 por 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 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 do 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 no 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: tempo, em milissegundos, que o Elasticsearch mantém o contexto da 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. Os 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 dados do Elasticsearch usando uma tabela de dados externos.

    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 novas:

    • 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 ver 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 í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 que alias está referenciando
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 que determinados campos do Elasticsearch não sejam enviados por push-down ou em que a lógica de consulta não pode ser enviada por push-down. 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, consulte Exemplos de pushdown.

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

Como a API Scroll pode consumir muitos recursos, recomendamos que você examine 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 Lucene do Elasticsearch.

Para realizar uma consulta SQL padrão, confira 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 à consulta do Elasticsearch. Por exemplo, AND qubits < 105.

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

    • 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 do Elasticsearch no estilo JSON, 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 de maneira uniforme. 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 ver exemplos de consultas que mostram quais aspectos o AlloyDB Omni pode e não pode enviar, 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 de classificação

Solução de problemas

Se você tiver problemas de autenticação ou conectividade ao consultar o 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