Acessar dados do Elasticsearch no AlloyDB para PostgreSQL

Acesse e pesquise dados armazenados no Elasticsearch criando um wrapper de dados externos (FDW) e uma tabela externa no AlloyDB para PostgreSQL.

Limitações

Antes de conectar o AlloyDB ao Elasticsearch, reconheça as seguintes limitações:

  • A integração do Elasticsearch está disponível apenas na versão principal 17 do PostgreSQL e em versões mais recentes.

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

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

  • Tipos especializados do Elasticsearch, como geo_point não são compatíveis. Para conferir a lista completa de tipos de dados compatíveis, consulte Tipos de dados compatíveis.

Antes de começar

Antes de começar, verifique se você concluiu o seguinte:

Armazenar a chave de API do Elasticsearch no Secret Manager

O AlloyDB 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ê concedeu à conta de serviço do AlloyDB permissão para ler o secret. Para mais informações, consulte Criar e acessar um secret usando o Secret Manager.

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:

  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 usada. 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 seu projeto do Google Cloud .

    • (Opcional) MAX_DEADLINE: tempo máximo, em milissegundos, que o AlloyDB aguarda uma resposta do Elasticsearch. Defina esse valor com base nos locais das instâncias do AlloyDB 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 os vai recuperar em vários lotes desse tamanho. O valor padrão é 32.

    • (Opcional) PAGINATION_CONTEXT_TIMEOUT: quantidade de tempo, em milissegundos, 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 Elasticsearch. As FDWs do PostgreSQL exigem esse mapeamento de usuário para funcionar. O AlloyDB 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 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, 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 é 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 dados do Elasticsearch

O AlloyDB recebe consultas SQL e as converte em consultas da API REST do Elasticsearch. Durante essa conversão, o AlloyDB tenta enviar o máximo possível de lógica de consulta sem mudar a identidade dela, incluindo o LIMIT da consulta SQL. No entanto, há casos em que você pode especificar para não fazer push down de determinados campos do Elasticsearch 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. 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 um valor maior que pagination_num_results ou em que LIMIT não é especificado ou não pode ser reduzido, o AlloyDB 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 a performance.

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

  • Consultas SQL padrão
  • Linguagem 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}

Linguagem DSL de consulta

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

Para fazer consultas usando a DSL de consulta, confira o exemplo de consulta 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, só é necessário propagar as expressões query, filter e sort.

Para fazer uma pesquisa híbrida nos seus 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 desta entrada de pesquisa para a fusão de classificação recíproca (RRF, na sigla em inglês) geral.

  • 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 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 ilustram quais aspectos o AlloyDB pode e não pode enviar por push, consulte a tabela a seguir.

Tipo de consulta Exemplo de consulta Elementos de consulta enviados para baixo
Consultas não filtradas 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC sort
  • 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 sort
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 sort