Auf Elasticsearch-Daten aus AlloyDB for PostgreSQL zugreifen

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

Hinweis

Führen Sie zuerst die folgenden Schritte aus:

Elasticsearch-API-Schlüssel in Secret Manager speichern

AlloyDB 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-Dienstkonto die Berechtigung zum Lesen des Secrets erteilen. Weitere Informationen finden Sie unter Secret mit Secret Manager erstellen und darauf zugreifen.

external_search_fdw-Erweiterung aktivieren und konfigurieren

Führen Sie die folgenden Schritte aus, um die external_search_fdw-AlloyDB-Erweiterung 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 auf eine Antwort von Elasticsearch wartet. Sie sollten diesen Wert basierend auf den Standorten Ihrer AlloyDB- und Elasticsearch-Instanzen festlegen. 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 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. AlloyDB authentifiziert sich mit dem 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 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 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 nimmt SQL-Abfragen entgegen und wandelt sie in Elasticsearch REST API-Abfragen um. Bei dieser Konvertierung versucht AlloyDB, 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 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).

  • 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, die folgenden Aspekte der Abfrage direkt in den API-Aufruf an Elasticsearch zu übertragen:

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

Beispielabfragen, die veranschaulichen, welche Aspekte AlloyDB auslagern kann 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 bei der Abfrage Ihres Elasticsearch-Clusters Authentifizierungs- oder Verbindungsprobleme auftreten, prüfen Sie die folgenden häufigen Ursachen:

  • 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 das von AlloyDB verwendete Dienstkonto die Berechtigung secretmanager.secretAccessor hat.
  • Zeitüberschreitungen bei Verbindungen:Prüfen Sie, ob die öffentliche IP-Verbindung für ausgehende Verbindungen in Ihrer primären AlloyDB-Instanz aktiviert ist und ob Ihre Elasticsearch-Firewall eingehende Verbindungen über den angegebenen Port zulässt.

Beschränkungen

Beachten Sie vor dem Herstellen einer Verbindung zwischen AlloyDB und Elasticsearch die folgenden Einschränkungen:

  • Die Elasticsearch-Integration ist nur für PostgreSQL-Hauptversion 17 und höher verfügbar.

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

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

  • Spezialisierte Elasticsearch-Typen wie geo_point werden nicht unterstützt. Eine vollständige Liste der unterstützten Datentypen finden Sie unter Unterstützte Datentypen.

Nächste Schritte