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

Für AlloyDB Omni ist ein Dienstkonto mit Google Cloud erforderlich, um Secret Manager zu authentifizieren und zu verwenden. In AlloyDB Omni wird Secret Manager verwendet, um Ihren Elasticsearch-API-Schlüssel zu speichern.

Wenn Sie noch kein Dienstkonto für AlloyDB Omni erstellt haben, gehen Sie so vor:

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

  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. Kopieren Sie den von Ihnen erstellten Dienstkontoschlüssel nach KEY_PATH. Der Schlüsselpfad muss ein Pfad auf Ihrem Host sein, auf den der Nutzer, der Ihren AlloyDB Omni-Container ausführt, zugreifen kann und der ihm gehört.

Elasticsearch-API-Schlüssel in Secret Manager speichern

AlloyDB Omni speichert Ihren Elasticsearch-API-Schlüssel in Secret Manager und liest ihn daraus. 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.

AlloyDB AI für AlloyDB Omni konfigurieren

Informationen zum Konfigurieren von AlloyDB AI für AlloyDB Omni finden Sie unter AlloyDB AI für AlloyDB Omni konfigurieren. Überspringen Sie den ersten Schritt.

Die Erweiterung „external_search_fdw“ aktivieren und konfigurieren

Führen Sie die folgenden Schritte aus, um die external_search_fdw-Erweiterung für AlloyDB Omni zu aktivieren und zu konfigurieren:

  1. Aktivieren Sie die Erweiterung external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Konfigurieren Sie den Zugriff auf Ihren Elasticsearch-Cluster über einen Foreign Data Server.

    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 ausländischen 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:

    • SECRET_PATH: Secret Manager-Pfad zu Ihren Elasticsearch-Anmeldedaten. Beispiel: projects/123456789012/secrets/apikey/versions/1 123456789012 steht für Ihre Google Cloud -Projekt-ID.

    • (Optional) MAX_DEADLINE: 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, in dem 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. Die Authentifizierung in AlloyDB Omni erfolgt ü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: Eine 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, sofern nicht die Option remote_field_name angehängt wird. 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 nimmt SQL-Abfragen entgegen und wandelt sie in Elasticsearch REST API-Abfragen um. Bei 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 möglicherweise festlegen, dass bestimmte Elasticsearch-Felder nicht per Pushdown übertragen werden sollen, oder in denen die Abfragelogik nicht per Pushdown übertragen werden kann. Beispielsweise können LIKE und andere Operatoren für den Textabgleich nicht per Push übertragen werden. Weitere Beispiele dafür, was per Pushdown übertragen werden kann und was nicht, 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 Anfragen mit EXPLAIN VERBOSE zu untersuchen, um zu sehen, welche APIs verwendet werden. Wenn Sie die Verwendung der Scroll API einschränken und LIMIT verwenden, wird die Leistung verbessert.

Zum Abfragen Ihrer Elasticsearch-Daten haben Sie folgende Möglichkeiten:

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

Standard-SQL-Abfragen

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

Ein Beispiel für eine Standard-SQL-Abfrage finden Sie unten:

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 Abfrage. Hier 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 Abfrage-DSL ist die funktionsreiche Abfragesprache von Elasticsearch im JSON-Stil, die für erweiterte Anwendungsfälle empfohlen wird. Mit der Query DSL können Sie komplexe Suchvorgänge, Filterungen und Aggregationen durchführen, die in der SQL-Abfragesyntax nicht möglich sind.

Wenn Sie Abfragen mit der 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: die an Elasticsearch zu sendende Abfrage. 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 in Ihren 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 zum gesamten Reciprocal Rank Fusion (RRF). Beispiel: 0.5 Wenn Sie keine Gewichte angeben, werden sie gleichmäßig verteilt. Weitere Informationen finden Sie unter Parameter für die hybride Suche.

  • 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: die an Elasticsearch zu sendende Abfrage. Mit "elasticsearch_field_name:\"quantum computing\"" wird beispielsweise nach dem Begriff „Quantum Computing“ im Feld elasticsearch_field_name gesucht. Alle in Unterstützte Datentypen genannten Abfragetypen können in Ihrer Abfrage verwendet werden.

Weitere Informationen zu den für hybride Suchanfragen verfügbaren Parametern finden Sie unter Parameter für hybride Suchfunktionen.

Beispiele für Pushdown

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 Sortierungen
  • LIMIT

Beispielabfragen, die zeigen, welche Aspekte von AlloyDB Omni per Pushdown verarbeitet werden können und welche nicht, finden Sie in der folgenden Tabelle.

Abfragetyp Beispielabfrage Abfrageelemente nach unten verschoben
Ungefilterte Anfragen 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT Felder
  • ORDER BY ... DESC Sortieren
  • 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
Bewertungsfilterung 
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 Sortieren
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
Rohdatenabfragen 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT Felder
  • ORDER BY ... DESC Sortieren

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.
  • Zeitüberschreitungen bei Verbindungen: 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 Elasticsearch.

  • 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