Auf Elasticsearch-Daten über AlloyDB Omni zugreifen

Wählen Sie eine Dokumentationsversion aus:

Sie können auf Daten zugreifen, die in Elasticsearch gespeichert sind, und darin suchen, indem Sie einen Foreign Data Wrapper (FDW) und eine externe Tabelle in AlloyDB Omni erstellen.

Hinweis

Führen Sie zuerst die folgenden Schritte aus:

Dienstkonto erstellen

AlloyDB Omni benötigt ein Dienstkonto mit Google Cloud , um sich zu authentifizieren und Secret Manager zu verwenden. AlloyDB Omni verwendet Secret Manager, um Ihren Elasticsearch-API-Schlüssel zu speichern.

Wenn Sie noch kein Dienstkonto für AlloyDB Omni erstellt haben, erstellen Sie eines mit den folgenden Schritten:

  1. Erstellen Sie ein Dienstkonto mitGoogle Cloud. Sie gewähren diesem Dienstkonto Berechtigungen für den Zugriff auf Secret Manager in Datenbankcluster mit AlloyDB AI erstellen.

  2. Erstellen Sie einen Dienstkontoschlüssel und speichern Sie ihn im JSON-Format in der Datei private-key.json. Laden Sie ihn dann herunter.

  3. Speichern Sie den Schlüssel an einem permanenten Speicherort in Ihrem Dateisystem. Es bleibt für die gesamte Lebensdauer Ihres AlloyDB Omni-Servers an diesem Speicherort.

    Notieren Sie sich den Speicherort im Dateisystem, da Sie ihn für die folgenden Schritte benötigen.

  4. Kubernetes-Secret mit dem Dienstkontoschlüssel erstellen

Elasticsearch-API-Schlüssel in Secret Manager speichern

AlloyDB Omni speichert und liest Ihren Elasticsearch API-Schlüssel aus Secret Manager. Weitere Informationen zur Verwendung von Secret Manager finden Sie unter Secret mit Secret Manager erstellen und darauf zugreifen.

Achten Sie darauf, dass Sie Ihrem AlloyDB Omni-Dienstkonto die Berechtigung zum Lesen des Secrets erteilen. Weitere Informationen finden Sie unter Zugriff auf Secrets verwalten.

Datenbankcluster mit AlloyDB AI erstellen

Informationen zum Erstellen eines Datenbankclusters mit AlloyDB AI finden Sie unter AlloyDB AI in AlloyDB Omni installieren. Wenn Sie mit Elasticsearch auf Daten zugreifen und diese abfragen möchten, müssen Sie die vertexAI*-Konfigurationen nicht angeben.

Erweiterung „external_search_fdw“ aktivieren und konfigurieren

Wenn Sie die Integration in Elasticsearch starten möchten, führen Sie die folgenden Schritte aus, um die AlloyDB Omni-Erweiterung external_search_fdw zu aktivieren und zu konfigurieren:

  1. Aktivieren Sie die Erweiterung external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Zugriff auf Ihren Elasticsearch-Cluster über einen Foreign Data Server konfigurieren

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

    Ersetzen Sie die folgenden Variablen:

    • ELASTICSEARCH_SERVER_NAME: Name für Ihren externen Datenserver. Beispiel: my-elasticsearch-server

    • ELASTICSEARCH_SERVER_HOST_PORT: Öffentlich zugängliche URL für Ihren Elasticsearch-Cluster. Beispiel: https://node1.elastic.test.com:9200

    • AUTH_METHOD: Der zu verwendende Authentifizierungstyp. Sie haben die Wahl zwischen den folgenden Optionen:

      • ApiKey: Elasticsearch-API-Schlüssel für persönliche/Nutzerkonten.

      • Basic: Elasticsearch-Nutzername und -Passwort.

    • SECRET_PATH: Secret Manager-Pfad zu Ihren Elasticsearch-Authentifizierungsdaten. Beispiel: projects/123456789012/secrets/apikey/versions/1 123456789012 stellt Ihre Google Cloud Projekt-ID dar.

    • (Optional) MAX_DEADLINE: Die maximale Zeit in Millisekunden, die AlloyDB Omni auf eine Antwort von Elasticsearch wartet. Legen Sie diesen Wert basierend auf den Standorten Ihrer AlloyDB Omni- und Elasticsearch-Instanzen fest. Der Standardwert ist 10000.

    • (Optional) PAGINATION_NUM_RESULTS: Maximale Anzahl der Ergebnisse, die pro Batch aus Elasticsearch abgerufen werden. Wenn mehr Ergebnisse angefordert werden, ruft AlloyDB Omni die Ergebnisse in mehreren Batches dieser Größe ab. Der Standardwert ist 32.

    • (Optional) PAGINATION_CONTEXT_TIMEOUT: Zeitraum in Millisekunden, für den Elasticsearch den Kontext der Paginierungsanfrage aktiv hält. Der Standardwert ist 30000.

  3. Definieren Sie die PostgreSQL-Nutzerzuordnung für den Elasticsearch-Server. Hinweis: Für PostgreSQL-FDWs ist diese Nutzerzuordnung erforderlich. AlloyDB Omni authentifiziert sich über den REST-Autorisierungsheader.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Konfigurieren Sie das Schema für Ihre Elasticsearch-Daten über eine externe Datentabelle.

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

    Ersetzen Sie die folgenden neuen Variablen:

    • ELASTICSEARCH_FD_TABLE: Name der externen Datentabelle, die Ihre Elasticsearch-Tabelle darstellt. Beispiel: my-fd-elasticsearch-table.

    • ELASTICSEARCH_FIELDS: durch Kommas getrennte Liste von Elasticsearch-Feldschemadefinitionen im folgenden Format: elasticsearch_field_name PG_DATA_TYPE. Beispiel: elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Diese Felder müssen mit den Feldnamen in Elasticsearch übereinstimmen, es sei denn, die Option remote_field_name wird angehängt. Beispiel: elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Eine Liste der Elasticsearch-Datentypen, die für AlloyDB Omni definiert werden können, finden Sie unter Unterstützte Datentypen.

    • ELASTICSEARCH_INDEX_NAME: Name Ihres Elasticsearch-Index. Beispiel: my-elasticsearch-index.

Unterstützte Datentypen

AlloyDB Omni unterstützt die folgenden Elasticsearch-Datentypen:

Datentyp(en) PostgreSQL-Typ
alias PostgreSQL-Typ für das Feld, auf das alias verweist
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

Elasticsearch-Daten abfragen

AlloyDB Omni wandelt SQL-Abfragen in Elasticsearch REST API-Abfragen um. Während dieser Konvertierung versucht AlloyDB Omni, so viel Abfragelogik wie möglich zu übertragen, ohne die Identität der Abfrage zu ändern, einschließlich der LIMIT der SQL-Abfrage. Es gibt jedoch Fälle, in denen Sie bestimmte Elasticsearch-Felder nicht per Push-Down übertragen möchten oder in denen die Abfragelogik nicht per Push-Down übertragen werden kann. Beispielsweise können LIKE und andere Operatoren für den Textabgleich nicht per Push übertragen werden. Weitere Beispiele dafür, was nicht und was doch per Pushdown übertragen werden kann, finden Sie unter Pushdown-Beispiele.

In Szenarien, in denen LIMIT höher als pagination_num_results festgelegt ist oder in denen LIMIT nicht angegeben ist oder nicht reduziert werden kann, verwendet AlloyDB Omni die Scroll API, die ressourcenintensiv sein kann.

Da die Scroll API ressourcenintensiv sein kann, empfehlen wir, Ihre Abfragen mit EXPLAIN VERBOSE zu prüfen, um zu sehen, welche APIs verwendet werden. Wenn Sie die Verwendung der Scroll API einschränken und LIMIT verwenden, wird die Leistung verbessert.

Sie haben die folgenden Möglichkeiten, Ihre Elasticsearch-Daten abzufragen:

  • Standard-SQL-Abfragen
  • Abfrage-DSL
  • Hybridsuchen

Standard-SQL-Abfragen

Standard-SQL-Abfragen können mit der Lucene-Syntax von Elasticsearch geschrieben werden.

Eine Standard-SQL-Abfrage finden Sie im folgenden Beispiel:

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

Ersetzen Sie die folgenden Variablen:

  • ELASTICSEARCH_FD_TABLE: Name der externen Datentabelle, die Ihre Elasticsearch-Tabelle darstellt. Beispiel: my-fd-elasticsearch-table.

  • (Optional) FILTER: Filter, der auf Ihre Elasticsearch-Abfrage angewendet werden soll. Beispiel: AND qubits < 105.

  • QUERY: Die an Elasticsearch zu sendende Anfrage. In der folgenden Liste finden Sie einige Beispielabfragen:

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

Abfrage-DSL

Die Abfragesprache (DSL) ist die funktionsreiche Abfragesprache von Elasticsearch im JSON-Stil, die für erweiterte Anwendungsfälle empfohlen wird. Mit Query DSL können Sie komplexe Suchvorgänge, Filterungen und Aggregationen durchführen, die sich in der SQL-Abfragesyntax nicht ausdrücken lassen.

Wenn Sie Abfragen mit Query DSL ausführen möchten, sehen Sie sich die folgende Beispielabfrage an:

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;

Ersetzen Sie die folgenden Variablen:

  • ELASTICSEARCH_FD_TABLE: Name der externen Datentabelle, die Ihre Elasticsearch-Tabelle darstellt. Beispiel: my-fd-elasticsearch-table.

  • QUERY: Abfrage, die an Elasticsearch gesendet werden soll. Beispiel: "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]"

Bei der Query DSL müssen Sie nur die Ausdrücke query, filter und sort weitergeben.

Wenn Sie eine hybride Suche für Ihre Elasticsearch-Daten durchführen möchten, sehen Sie sich das folgende Beispiel an:

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;

Ersetzen Sie die folgenden Variablen:

  • LIMIT: Anzahl der zurückzugebenden Ergebnisse. Beispiel: 3.

  • WEIGHT: Beitrag dieses Sucheintrags zur gesamten Reciprocal Rank Fusion (RRF). Beispiel: 0.5 Wenn Sie keine Gewichtungen angeben, werden sie gleichmäßig verteilt. Weitere Informationen finden Sie unter Parameter für die hybride Suchfunktion.

  • ELASTICSEARCH_FD_TABLE: Name der externen Datentabelle, die Ihre Elasticsearch-Tabelle darstellt. Beispiel: my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME: Name der Spalte mit der Dokument-ID.

  • QUERY: Abfrage, die an Elasticsearch gesendet werden soll. Mit "elasticsearch_field_name:\"quantum computing\"" wird beispielsweise im Feld elasticsearch_field_name nach dem Begriff „Quantencomputer“ gesucht. Alle in Unterstützte Datentypen genannten Abfragetypen können in Ihrer Abfrage verwendet werden.

Weitere Informationen zu den für Hybridsuchen verfügbaren Parametern finden Sie unter Parameter für Hybridsuchfunktionen.

Pushdown-Beispiele

Um Abfragen effizienter zu gestalten, versucht AlloyDB Omni, die folgenden Aspekte der Abfrage direkt in den API-Aufruf an Elasticsearch zu übertragen:

  • SELECT Felder
  • WHERE Filter
  • ORDER BY Sortierung
  • LIMIT

Beispielabfragen, die zeigen, welche Aspekte AlloyDB Omni per Push-down übertragen kann und welche nicht, finden Sie in der folgenden Tabelle.

Abfragetyp Beispielabfrage Abfrageelemente nach unten verschoben
Ungefilterte Abfragen 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT Felder
  • ORDER BY ... DESC Sortierung
  • LIMIT
Genaue Textübereinstimmung 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT Felder
  • WHERE Filter
  • LIMIT
Einzelfeldausdrücke 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT Felder
  • WHERE Filter
Konstante Ausdrücke 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT Felder
  • WHERE Filter
  • LIMIT
Ausdrücke mit Funktionen 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT Felder
Ausdrücke mit mehreren Feldern 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT Felder
Score-Filterung 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT Felder
  • ORDER BY ... DESC Sortierung
LIKE und ähnliche Operatoren 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT Felder
  • WHERE id > 10 Filter
Rohabfragen 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT Felder
  • ORDER BY ... DESC Sortierung

Fehlerbehebung

Wenn beim Abfragen Ihres Elasticsearch-Clusters Authentifizierungs- oder Verbindungsprobleme auftreten, prüfen Sie Folgendes:

  • HTTP-Authentifizierungsfehler 401 oder 403: Prüfen Sie, ob Ihr Elasticsearch-Secret in Secret Manager gültige Anmeldedaten für die Authentifizierung für Ihre auth_method (ApiKey oder Basic) enthält und ob Ihr Dienstkonto die Berechtigung secretmanager.secretAccessor hat.
  • Verbindungszeitüberschreitungen: Prüfen Sie die Netzwerkregeln und die Firewallkonfiguration zwischen AlloyDB Omni und Ihrem Elasticsearch-Endpunkt.

Beschränkungen

  • AlloyDB Omni liest Elasticsearch-Daten, schreibt aber nicht in diese.

  • Sie sind für die Synchronisierung von Daten zwischen AlloyDB Omni und Elasticsearch verantwortlich.

  • Spezielle Elasticsearch-Typen wie geo_point werden nicht unterstützt. Weitere Informationen finden Sie unter Unterstützte Datentypen.

Nächste Schritte