Accedere ai dati di Elasticsearch da AlloyDB Omni

Seleziona una versione della documentazione:

Puoi accedere ai dati archiviati in Elasticsearch ed eseguirne ricerche creando un wrapper di dati esterni (FDW) e una tabella esterna in AlloyDB Omni.

Prima di iniziare

Prima di iniziare, completa i seguenti passaggi:

Crea un account di servizio

AlloyDB Omni richiede un account di servizio con Google Cloud per autenticare e utilizzare Secret Manager. AlloyDB Omni utilizza Secret Manager per archiviare la chiave API Elasticsearch.

Se non hai ancora creato un account di servizio per AlloyDB Omni, creane uno seguendo questi passaggi:

  1. Crea un service account conGoogle Cloud. Concedi a questo account di servizio le autorizzazioni per accedere a Secret Manager in Configura AlloyDB AI.

  2. Crea una account di servizio account e salvala in formato JSON nel file private-key.json, quindi scaricala.

  3. Copia la chiave del account di servizio che hai creato in KEY_PATH. Il percorso della chiave deve essere un percorso sul tuo host accessibile e di proprietà dell'utente che esegue il container AlloyDB Omni.

Archivia la chiave API Elasticsearch in Secret Manager

AlloyDB Omni 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 Omni l'autorizzazione per leggere il secret. Per saperne di più, consulta Gestisci l'accesso ai secret.

Configura AlloyDB AI per AlloyDB Omni

Per configurare AlloyDB AI per AlloyDB Omni, consulta Configura AlloyDB AI per AlloyDB Omni e salta il primo passaggio.

Abilita e configura l'estensione external_search_fdw

Per avviare l'integrazione con Elasticsearch, completa le seguenti istruzioni per attivare e configurare l'estensione AlloyDB Omni 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 Omni attende per una risposta da Elasticsearch. Imposta questo valore in base alle località delle tue istanze AlloyDB Omni 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 Omni li recupera in più batch di queste dimensioni. Il valore predefinito è 32.

    • (Facoltativo) PAGINATION_CONTEXT_TIMEOUT: il periodo di tempo, in millisecondi, per 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 Omni 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 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 Omni, consulta Tipi di dati supportati.

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

Tipi di dati supportati

AlloyDB Omni 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 Omni prende le query SQL e le converte in query dell'API REST di Elasticsearch. Durante questa conversione, AlloyDB Omni tenta di eseguire il push-down della logica di query il più possibile senza modificare l'identità della query, inclusa la LIMIT della query SQL. Tuttavia, in alcuni casi potresti specificare di non eseguire il push-down di determinati campi Elasticsearch o la logica di query non può essere sottoposta a push-down. Ad esempio, LIKE e altri operatori di corrispondenza del testo non possono essere sottoposti a push-down. 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 push-down, AlloyDB Omni 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 l'esempio di ricerca seguente:

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. Ad esempio, 0.5. Se non fornisci i pesi, questi vengono distribuiti in modo uniforme. Per saperne di più, consulta Parametri della funzione di ricerca ibrida.

  • 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. Nella query puoi utilizzare tutti i tipi di query menzionati in Tipi di dati supportati.

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 Omni tenta di eseguire il push-down dei seguenti aspetti della query direttamente nella chiamata API effettuata a Elasticsearch:

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

Per esempi di query che mostrano quali aspetti AlloyDB Omni è in grado di eseguire in push-down e quali no, consulta la tabella seguente.

Tipo di query Esempio di query Elementi della query con push-down
Query non filtrate 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT campi
  • ORDER BY ... DESC ordinamento
  • 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
  • ORDER BY ... DESC ordinamento
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
  • ORDER BY ... DESC ordinamento

Risoluzione dei problemi

Se riscontri problemi di autenticazione o connettività durante l'esecuzione di query sul tuo cluster Elasticsearch, controlla quanto segue:

  • 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 tuo account di servizio disponga dell'autorizzazione secretmanager.secretAccessor.
  • Timeout della connessione: verifica le regole di rete e la configurazione del firewall tra AlloyDB Omni e l'endpoint Elasticsearch.

Limitazioni

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

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

  • I tipi Elasticsearch specializzati, come geo_point, non sono supportati. Per maggiori informazioni, vedi Tipi di dati supportati.

Passaggi successivi