Auf Elasticsearch-Daten aus AlloyDB for PostgreSQL zugreifen

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

Hinweis

Bevor Sie beginnen, müssen Sie Folgendes tun:

Elasticsearch-API-Schlüssel in Secret Manager speichern

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

Wenn Sie die Integration in Elasticsearch starten möchten, führen Sie die folgenden Schritte aus, um die AlloyDB-Erweiterung external_search_fdw 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 externen Datenserver.

    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: Öffentliche URL für Ihren Elasticsearch-Cluster. Beispiel: https://node1.elastic.test.com:9200

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

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

    • (Optional) MAX_DEADLINE: Die 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 von Ergebnissen, 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, 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. Beachten Sie, dass PostgreSQL-FDWs diese Nutzerzuordnung benötigen, um zu funktionieren. AlloyDB 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 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 wandelt SQL-Abfragen in Elasticsearch REST API-Abfragen um. Während 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 bestimmte Elasticsearch-Felder nicht per Push übertragen möchten oder in denen die Abfragelogik nicht per Push ü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 Push übertragen werden kann und was nicht, finden Sie unter Pushdown-Beispiele.

In Szenarien, in denen LIMIT höher als pagination_num_results ist oder in denen LIMIT nicht angegeben ist oder nicht per Push übertragen werden kann, verwendet AlloyDB 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: Abfrage, die an Elasticsearch gesendet werden soll. 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

Query DSL ist die umfassende, JSON-basierte Abfragesprache von Elasticsearch, die für erweiterte Anwendungsfälle empfohlen wird. Mit der Query DSL können Sie komplexe Suchvorgänge, Filterungen und Aggregationen durchführen, die sich nicht in der SQL-Abfragesyntax 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]"

Beachten Sie, dass Sie für Query DSL nur die Ausdrücke query, filter und sort weitergeben müssen.

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 zur 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: Abfrage, die an Elasticsearch gesendet werden soll. Mit "elasticsearch_field_name:\"quantum computing\"" wird beispielsweise im Feld elasticsearch_field_name nach der Wortgruppe „quantum computing“ gesucht. Alle unter Unterstützte Datentypen genannten Abfragetypen können in Ihrer Abfrage verwendet werden.

Weitere Informationen zu den für die Hybridsuche verfügbaren Parametern finden Sie unter Parameter für die Hybridsuchfunktion.

Pushdown-Beispiele

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

In der folgenden Tabelle finden Sie Beispielabfragen, die veranschaulichen, welche Aspekte AlloyDB per Push übertragen kann und welche nicht.

Abfragetyp Beispielabfrage Abfrageelemente per Push übertragen
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
Unbearbeitete Abfragen 
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 die folgenden häufigen Ursachen:

  • HTTP-401- oder 403-Authentifizierungsfehler: Prüfen Sie, ob Ihr Elasticsearch-Secret in Secret Manager gültige Authentifizierungsdaten für Ihre auth_method (ApiKey oder Basic) enthält und ob das von AlloyDB verwendete Dienstkonto die Berechtigung secretmanager.secretAccessor hat.
  • Verbindungszeitüberschreitungen: Prüfen Sie, ob die ausgehende öffentliche IP-Verbindung auf Ihrer primären AlloyDB-Instanz aktiviert ist und ob Ihre Elasticsearch-Firewall eingehende Verbindungen über den angegebenen Port zulässt.

Beschränkungen

Bevor Sie AlloyDB mit Elasticsearch verbinden, beachten Sie die folgenden Einschränkungen:

  • Die Elasticsearch-Integration ist nur für PostgreSQL-Hauptversionen ab 17 verfügbar.

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

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

  • Spezielle 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