Accedere ai dati di Elasticsearch da AlloyDB per PostgreSQL

Accedi ai dati archiviati in Elasticsearch ed eseguine ricerche creando un wrapper di dati esterni (FDW) e una tabella esterna in AlloyDB per PostgreSQL.

Prima di iniziare

Prima di iniziare, assicurati di aver completato quanto segue:

Archivia la chiave API Elasticsearch in Secret Manager

AlloyDB archivia e legge la chiave API Elasticsearch da Secret Manager. Per saperne di più su come utilizzare Secret Manager, consulta Crea e accedi a un secret utilizzando Secret Manager.

Assicurati di concedere al account di servizio AlloyDB l'autorizzazione per leggere il secret. Per saperne di più, consulta Crea e accedi a un secret utilizzando Secret Manager.

Attiva e configura l'estensione external_search_fdw

Per avviare l'integrazione con Elasticsearch, completa le seguenti istruzioni per abilitare e configurare l'estensione AlloyDB external_search_fdw:

  1. Attiva l'estensione external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Configura l'accesso al tuo cluster Elasticsearch tramite un server di dati esterno.

    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');

    Sostituisci le seguenti variabili:

    • ELASTICSEARCH_SERVER_NAME: il nome del server di dati esterno. Ad esempio, my-elasticsearch-server.

    • ELASTICSEARCH_SERVER_HOST_PORT: URL pubblico del tuo cluster Elasticsearch. Ad esempio, https://node1.elastic.test.com:9200.

    • AUTH_METHOD: il tipo di autenticazione da utilizzare. Puoi scegliere tra le seguenti opzioni:

    • SECRET_PATH: il percorso di Secret Manager per le tue credenziali di autenticazione Elasticsearch. Ad esempio, projects/123456789012/secrets/apikey/versions/1. 123456789012 rappresenta l'ID progetto Google Cloud .

    • (Facoltativo) MAX_DEADLINE: tempo massimo, in millisecondi, che AlloyDB attende per una risposta da Elasticsearch. Devi impostare questo valore in base alle località delle tue istanze AlloyDB ed Elasticsearch. Il valore predefinito è 10000.

    • (Facoltativo) PAGINATION_NUM_RESULTS: numero massimo di risultati recuperati per batch da Elasticsearch. Se vengono richiesti più risultati, AlloyDB li recupera in più batch di queste dimensioni. Il valore predefinito è 32.

    • (Facoltativo) PAGINATION_CONTEXT_TIMEOUT: il periodo di tempo, in millisecondi, in cui Elasticsearch mantiene attivo il contesto della richiesta di impaginazione. Il valore predefinito è 30000.

  3. Definisci la mappatura degli utenti PostgreSQL per il server Elasticsearch. Tieni presente che i FDW PostgreSQL richiedono questa mappatura degli utenti per funzionare. AlloyDB esegue l'autenticazione utilizzando l'intestazione di autorizzazione REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Configura lo schema per i dati Elasticsearch tramite una tabella di dati esterni.

    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');

    Sostituisci le seguenti nuove variabili:

    • ELASTICSEARCH_FD_TABLE: il nome della tabella di dati esterni che rappresenta la tabella Elasticsearch. Ad esempio, my-fd-elasticsearch-table.

    • ELASTICSEARCH_FIELDS: un elenco separato da virgole di definizioni dello schema dei campi di Elasticsearch nel seguente formato: elasticsearch_field_name PG_DATA_TYPE. Ad esempio elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Questi campi devono corrispondere ai nomi dei campi in Elasticsearch, a meno che non venga aggiunta l'opzione remote_field_name. Ad esempio, elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Per l'elenco dei tipi di dati Elasticsearch che possono essere definiti per AlloyDB, consulta Tipi di dati supportati.

    • ELASTICSEARCH_INDEX_NAME: il nome dell'indice Elasticsearch. Ad esempio, my-elasticsearch-index.

Tipi di dati supportati

AlloyDB supporta i seguenti tipi di dati Elasticsearch:

Tipi di dati Tipo PostgreSQL
alias Tipo PostgreSQL per il campo a cui fa riferimento 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

Esegui query sui dati di Elasticsearch

AlloyDB prende le query SQL e le converte in query API REST di Elasticsearch. Durante questa conversione, AlloyDB tenta di eseguire il push down della logica di query il più possibile senza modificare l'identità della query, incluso il LIMIT della query SQL. Tuttavia, in alcuni casi potresti specificare di non eseguire il pushdown di determinati campi Elasticsearch o la logica di query non può essere sottoposta a pushdown. Ad esempio, LIKE e altri operatori di corrispondenza del testo non possono essere sottoposti a pushdown. Per altri esempi di ciò che può e non può essere sottoposto a pushdown, consulta Esempi di pushdown.

In scenari in cui LIMIT è impostato su un valore superiore a pagination_num_results o in cui LIMIT non è specificato o non può essere sottoposto a pushdown, AlloyDB utilizza l'API Scroll, che può richiedere un utilizzo intensivo delle risorse.

Poiché l'API Scroll può richiedere un utilizzo intensivo delle risorse, ti consigliamo di esaminare le tue query utilizzando EXPLAIN VERBOSE per vedere quali API vengono utilizzate. Limitare l'utilizzo dell'API Scroll e utilizzare LIMIT migliora le prestazioni.

Per eseguire query sui dati di Elasticsearch, hai le seguenti opzioni:

  • Query SQL standard
  • Query DSL
  • Ricerche ibride

Query SQL standard

Le query SQL standard possono essere scritte utilizzando la sintassi Lucene di Elasticsearch.

Per eseguire una query SQL standard, consulta la seguente query di esempio:

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

Sostituisci le seguenti variabili:

  • ELASTICSEARCH_FD_TABLE: il nome della tabella di dati esterni che rappresenta la tabella Elasticsearch. Ad esempio, my-fd-elasticsearch-table.

  • (Facoltativo) FILTER: filtro da applicare alla query Elasticsearch. Ad esempio, AND qubits < 105.

  • QUERY: la query da inviare a Elasticsearch. Per alcuni esempi di query, consulta il seguente elenco:

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

Query DSL

Query DSL è il linguaggio di query completo in stile JSON di Elasticsearch, consigliato per casi d'uso avanzati. Query DSL ti consente di eseguire ricerche, filtri e aggregazioni complessi che non possono essere espressi nella sintassi delle query SQL.

Per eseguire query utilizzando Query DSL, consulta la seguente query di esempio:

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;

Sostituisci le seguenti variabili:

  • ELASTICSEARCH_FD_TABLE: il nome della tabella di dati esterni che rappresenta la tabella Elasticsearch. Ad esempio, my-fd-elasticsearch-table.

  • QUERY: la query da inviare a Elasticsearch. Ad esempio, "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

Tieni presente che per Query DSL devi propagare solo le espressioni query, filter e sort.

Per eseguire una ricerca ibrida sui dati di Elasticsearch, consulta la seguente ricerca di esempio:

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;

Sostituisci le seguenti variabili:

  • LIMIT: il numero di risultati da restituire. Ad esempio, 3.

  • WEIGHT: il contributo di questa voce di ricerca al Reciprocal Rank Fusion (RRF) complessivo.

  • ELASTICSEARCH_FD_TABLE: il nome della tabella di dati esterni che rappresenta la tabella Elasticsearch. Ad esempio, my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME: il nome della colonna ID documento.

  • QUERY: la query da inviare a Elasticsearch. Ad esempio, "elasticsearch_field_name:\"quantum computing\"" cerca la frase "quantum computing" nel campo elasticsearch_field_name. Tutti i tipi di query menzionati in Tipi di dati supportati possono essere utilizzati nella query.

Per ulteriori informazioni sui parametri disponibili per le ricerche ibride, consulta Parametri della funzione di ricerca ibrida.

Esempi di pushdown

Per rendere le query più efficienti, AlloyDB tenta di eseguire il push down dei seguenti aspetti della query direttamente nella chiamata API effettuata a Elasticsearch:

  • SELECT campi
  • WHERE filtri
  • ORDER BY ordinamento
  • LIMIT

Per query di esempio che illustrano quali aspetti AlloyDB è in grado di eseguire il pushdown e quali no, consulta la tabella seguente.

Tipo di query Esempio di query Elementi della query spostati verso il basso
Query non filtrate 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT campi
  • Ordinamento ORDER BY ... DESC
  • LIMIT
Corrispondenza esatta del testo 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT campi
  • WHERE filtro
  • LIMIT
Espressioni a campo singolo 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT campi
  • WHERE filtro
Espressioni costanti 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT campi
  • WHERE filtro
  • LIMIT
Espressioni con funzioni 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT campi
Espressioni con più campi 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT campi
Filtro dei punteggi 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT campi
  • Ordinamento ORDER BY ... DESC
LIKE e operatori simili 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT campi
  • WHERE id > 10 filtro
Query non elaborate 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT campi
  • Ordinamento ORDER BY ... DESC

Risoluzione dei problemi

Se riscontri problemi di autenticazione o connettività durante l'esecuzione di query sul tuo cluster Elasticsearch, controlla le seguenti cause comuni:

  • Errori di autenticazione HTTP 401 o 403: verifica che il secret Elasticsearch in Secret Manager contenga credenziali di autenticazione valide per auth_method (ApiKey o Basic) e verifica che il account di servizio utilizzato da AlloyDB disponga dell'autorizzazione secretmanager.secretAccessor.
  • Timeout della connessione: verifica che la connettività IP pubblica in uscita sia abilitata nell'istanza AlloyDB principale e che il firewall Elasticsearch consenta le connessioni in entrata sulla porta specificata.

Limitazioni

Prima di connettere AlloyDB a Elasticsearch, tieni presente le seguenti limitazioni:

  • L'integrazione di Elasticsearch è disponibile solo per la versione principale di PostgreSQL 17 e successive.

  • AlloyDB legge, ma non scrive, i dati di Elasticsearch.

  • Sei responsabile della sincronizzazione dei dati tra AlloyDB ed Elasticsearch.

  • I tipi Elasticsearch specializzati, come geo_point, non sono supportati. Per l'elenco completo dei tipi di dati supportati, consulta Tipi di dati supportati.

Passaggi successivi