Accedere ai dati di Elasticsearch da AlloyDB Omni

Seleziona una versione della documentazione:

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

Limitazioni

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

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

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

Prima di iniziare

Prima di iniziare, completa le seguenti operazioni:

Crea un account di servizio

AlloyDB Omni richiede un account di servizio con Google Cloud per autenticarsi 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 con Google Cloud. Concedi a questo account di servizio le autorizzazioni per accedere a Secret Manager in Crea un cluster di database con AlloyDB AI.

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

  3. Archivia la chiave in una posizione permanente del file system. Si trova in questa posizione per l'intera durata del server AlloyDB Omni.

    Prendi nota della sua posizione nel file system, perché ti servirà per i passaggi successivi.

  4. Crea un secret Kubernetes utilizzando la account di servizio account.

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 Creare e accedere 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ù, vedi Gestire l'accesso ai secret.

Crea un cluster di database con AlloyDB AI

Per creare un cluster di database con AlloyDB AI, consulta Installare AlloyDB AI in AlloyDB Omni. Per accedere ai dati ed eseguire query con Elasticsearch, non è necessario specificare le configurazioni vertexAI*.

Attivare e configurare l'estensione external_search_fdw

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

  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:

    • 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 Omni attende una risposta da Elasticsearch. Imposta questo valore in base alle posizioni 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 recupera i risultati 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 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 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 Omni, vedi 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:

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 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 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 verso il basso 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 inserito, AlloyDB Omni 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.

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 più efficienti le query, AlloyDB Omni tenta di inserire i 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 il push verso il basso 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