Acessar dados do OpenSearch no AlloyDB

É possível acessar e pesquisar dados armazenados no OpenSearch usando a integração de pesquisa externa no AlloyDB. Com essa integração, é possível unir índices do OpenSearch a tabelas relacionais no AlloyDB sem mover ou copiar dados.

Antes de começar

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

Armazenar credenciais do OpenSearch no Secret Manager

O AlloyDB armazena e lê suas credenciais do OpenSearch 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 a conta de serviço do AlloyDB tem o papel Acessador de secrets do Secret Manager (roles/secretmanager.secretAccessor) para ler o secret do Secret Manager. Para mais informações, consulte Criar e acessar um secret usando o Secret Manager.

Ativar e configurar a extensão external_search_fdw

Para começar a integração com o OpenSearch, configure o acesso ao cluster do OpenSearch usando um servidor de dados externo.

  1. Ative a extensão external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Crie um servidor para o cluster do OpenSearch.

    CREATE SERVER OPENSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (
  server 'OPENSEARCH_SERVER_HOST_PORT',
  search_provider 'opensearch',
  auth_mode 'secret_manager',
  auth_method 'Basic',
  secret_path 'SECRET_PATH'
);

    Substitua as seguintes variáveis:

    • OPENSEARCH_SERVER_NAME: nome do servidor de dados externos. Por exemplo, opensearch.

    • OPENSEARCH_SERVER_HOST_PORT: URL público (endpoint) do cluster do OpenSearch.

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

  3. Defina o mapeamento de usuários do PostgreSQL para o servidor OpenSearch. 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 OPENSEARCH_SERVER_NAME;

  4. Mapeie o esquema do seu índice do OpenSearch para uma tabela externa do PostgreSQL.

    CREATE FOREIGN TABLE OPENSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    OPENSEARCH_FIELDS)
       SERVER OPENSEARCH_SERVER_NAME
       OPTIONS(
            remote_table_name 'OPENSEARCH_INDEX_NAME'
       );

    Substitua as seguintes variáveis:

    • OPENSEARCH_FD_TABLE: o nome da tabela de dados externa que representa sua tabela do OpenSearch. Por exemplo, my-fd-opensearch-table.

    • OPENSEARCH_FIELDS: uma lista separada por vírgulas em que cada entrada usa o formato opensearch_field_name PG_DATA_TYPE. Para uma lista dos tipos de dados do OpenSearch compatíveis e os tipos correspondentes do PostgreSQL, consulte Tipos de dados compatíveis.

    • OPENSEARCH_INDEX_NAME: o nome do seu índice do OpenSearch. Por exemplo, my-opensearch-index.

Tipos de dados compatíveis

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

Tipos de dados Tipo do AlloyDB
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,

keyword,

constant_keyword,

wildcard

TEXT
unsigned_long NUMERIC

Consultar seus dados do OpenSearch

O AlloyDB recebe consultas SQL e as converte em consultas da API REST do OpenSearch.

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

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

Consultas SQL padrão

Você pode usar o SQL padrão com a sintaxe do Lucene para a expressão de pesquisa.

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

Substitua as seguintes variáveis:

  • OPENSEARCH_FD_TABLE: o nome da tabela de dados externa que representa sua tabela do OpenSearch. Por exemplo, my-fd-opensearch-table.

  • (Opcional) FILTER: o filtro a ser aplicado à sua consulta do OpenSearch. Por exemplo, a = 10 AND b < 105.

  • QUERY: a consulta a ser enviada ao OpenSearch. Por exemplo, body:database.

Linguagem DSL de consulta

Para casos de uso avançados, use a linguagem de consulta DSL no estilo JSON do OpenSearch.

SELECT id, title
FROM OPENSEARCH_FD_TABLE
ORDER BY metadata <@> $${
  "query": {
    "bool": {
      "must": { "match": { "title": "opensearch" } },
      "filter": { "term": { "category": "software" } }
    }
  },
  "sort": [
    { "price": { "order": "desc" } }
  ]
}$$
LIMIT 1;

Substitua OPENSEARCH_FD_TABLE pelo nome da tabela de dados externa que representa sua tabela do OpenSearch. Por exemplo, my-fd-opensearch-table.

Para realizar uma pesquisa híbrida nos seus dados do OpenSearch, combine os resultados da pesquisa de tokens do OpenSearch com os resultados da pesquisa vetorial do AlloyDB.

SELECT *
FROM ai.hybrid_search(
  ARRAY[
    '{"limit": LIMIT,
      "weight": WEIGHT,
      "table_name": OPENSEARCH_FD_TABLE,
      "key_column": "id",
      "query_text_input": "QUERY"}'::jsonb
  ])
ORDER BY score DESC;

Substitua as seguintes variáveis:

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

  • WEIGHT: contribuição desta entrada de pesquisa para a fusão de classificação recíproca (RRF, na sigla em inglês) geral. Por exemplo, 0.5.

  • OPENSEARCH_FD_TABLE: nome da tabela de dados externa que representa sua tabela do OpenSearch. Por exemplo, my-fd-opensearch-table.

  • QUERY: consulta a ser enviada ao OpenSearch. Por exemplo, "opensearch_field_name:\"cloud databases\"" pesquisa a frase "bancos de dados na nuvem" no campo opensearch_field_name.

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

  • 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 opensearch_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 opensearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expressões de campo único 
SELECT id, body
FROM opensearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT campos
  • WHERE filtro
Expressões constantes 
SELECT id, body
FROM opensearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT campos
  • WHERE filtro
  • LIMIT
Expressões com funções 
SELECT id, body
FROM opensearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT campos
Expressões de vários campos 
SELECT id, body
FROM opensearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT campos
Filtragem de pontuação 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM opensearch_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 opensearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT campos
  • WHERE id > 10 filtro
Consultas brutas 
SELECT id, body
FROM opensearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT campos
  • ORDER BY ... DESC sort

Solução de problemas

Se você encontrar problemas de autenticação ou conectividade ao consultar seu cluster do OpenSearch, verifique as seguintes causas comuns:

  • Erros de autenticação HTTP 401 ou 403:verifique se o secret do OpenSearch no Secret Manager contém uma string formatada como username:password e se a conta de serviço do AlloyDB tem a função de acessador de secret do Secret Manager (roles/secretmanager.secretAccessor).
  • Tempo limite de conexão:verifique se a conectividade de IP público de saída está ativada na sua instância principal do AlloyDB e se o firewall do OpenSearch permite conexões de entrada na porta especificada.

Limitações

Antes de conectar o AlloyDB ao OpenSearch, entenda as seguintes limitações:

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

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

  • O AlloyDB não indexa automaticamente os dados do banco de dados no OpenSearch. Você é responsável por preencher os índices do OpenSearch e manter a consistência entre os dados no AlloyDB e os dados indexados no OpenSearch.

  • O AlloyDB não sincroniza automaticamente esquemas com o OpenSearch. Se o esquema do índice do OpenSearch mudar, atualize manualmente o esquema da tabela externa correspondente do PostgreSQL.

  • Tipos especializados do OpenSearch, 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.

  • Use a autenticação básica (nome de usuário e senha) configurada no cluster do OpenSearch.

A seguir