Accedere ai dati di Elasticsearch da AlloyDB per PostgreSQL

Anteprima — Elasticsearch FDW

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

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

Limitazioni

Prima di connettere AlloyDB a Elasticsearch, accetta le seguenti limitazioni:

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

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

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

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

Prima di iniziare

Prima di iniziare, assicurati di aver completato le seguenti operazioni:

• Crea un cluster.

• Abilita la connettività in uscita sull'istanza AlloyDB principale.

• Esegui il deployment e avvia Elasticsearch in produzione.

• Crea una chiave API personale/utente di sola lettura che AlloyDB può utilizzare per accedere al tuo cluster Elasticsearch.

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 Creare e accedere a un secret utilizzando Secret Manager.

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

Attivare e configurare l'estensione external_search_fdw

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

1. Attiva l'estensione external_search_fdw.

   CREATE EXTENSION external_search_fdw;
   

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

   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 esterni. 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: tipo di autenticazione da utilizzare. Puoi scegliere tra le seguenti opzioni:

     • ApiKey: Elasticsearch Chiave API personale/utente.

     • Basic: nome utente e password di Elasticsearch.

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

   • (Facoltativo) MAX_DEADLINE: tempo massimo, in millisecondi, per cui AlloyDB attende una risposta da Elasticsearch. Devi impostare questo valore in base alle posizioni 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: periodo di tempo, in millisecondi, in cui Elasticsearch mantiene attivo il contesto della richiesta di paginazione. Il valore predefinito è 30000.

3. Definisci il mapping degli utenti PostgreSQL per il server Elasticsearch. Tieni presente che le FDW PostgreSQL richiedono questa mappatura utente 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 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 aggiunto il 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, vedi 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:

Tipo/i 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 Elasticsearch

AlloyDB prende le query SQL e le converte in query dell'API REST di Elasticsearch. Durante questa conversione, AlloyDB tenta di eseguire il push-down della maggior parte della logica di query possibile senza modificare l'identità della query, incluso il LIMIT della query SQL. Tuttavia, in alcuni casi potresti specificare di non eseguire il push down di determinati campi Elasticsearch o in cui la logica di query non può essere eseguita. Ad esempio, LIKE e altri operatori di corrispondenza del testo non possono essere inseriti. Per altri esempi di ciò che può e non può essere eseguito in push, vedi Esempi di pushdown.

Negli scenari in cui LIMIT è impostato su un valore superiore a pagination_num_results o in cui LIMIT non è specificato o non può essere eseguito il push verso il basso, AlloyDB utilizza l'API Scroll, che può richiedere molte risorse.

Poiché l'API Scroll può richiedere molte risorse, ti consigliamo di esaminare le 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 Elasticsearch, hai a disposizione 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: 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 in stile JSON completo di funzionalità di Elasticsearch consigliato per casi d'uso avanzati. Query DSL consente di eseguire ricerche, filtri e aggregazioni complessi che non possono essere espressi nella sintassi delle query SQL.

Per eseguire query utilizzando Query DSL, vedi 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: 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.

Ricerche ibride

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

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: 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: 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 inserire i seguenti aspetti della query direttamente nella chiamata API effettuata a Elasticsearch:

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

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

Tipo di query	Esempio di query	Elementi della query spostati in basso
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 al 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 del punteggio	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

Nota: Elasticsearch è un marchio di Elastic NV e non è affiliato a Google LLC.