Accéder aux données Elasticsearch depuis AlloyDB pour PostgreSQL

Accédez aux données stockées dans Elasticsearch et recherchez-les en créant un wrapper de données externes (FDW) et une table externe dans AlloyDB pour PostgreSQL.

Avant de commencer

Avant de commencer, assurez-vous d'avoir effectué les opérations suivantes :

Stocker la clé API Elasticsearch dans Secret Manager

AlloyDB stocke et lit votre clé API Elasticsearch à partir de Secret Manager. Pour en savoir plus sur l'utilisation de Secret Manager, consultez Créer un secret et y accéder à l'aide de Secret Manager.

Assurez-vous d'accorder à votre compte de service AlloyDB l'autorisation de lire le secret. Pour en savoir plus, consultez Créer un secret et y accéder à l'aide de Secret Manager.

Activer et configurer l'extension external_search_fdw

Pour commencer l'intégration avec Elasticsearch, suivez les instructions ci-dessous pour activer et configurer l'extension AlloyDB external_search_fdw :

  1. Activez l'extension external_search_fdw.

    CREATE EXTENSION external_search_fdw;

  2. Configurez l'accès à votre cluster Elasticsearch via un serveur de données externe.

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

    Remplacez les variables suivantes :

    • ELASTICSEARCH_SERVER_NAME : nom de votre serveur de données externe. Exemple : my-elasticsearch-server.

    • ELASTICSEARCH_SERVER_HOST_PORT : URL publique de votre cluster Elasticsearch. Exemple : https://node1.elastic.test.com:9200.

    • AUTH_METHOD : type d'authentification à utiliser. Vous avez le choix entre les options suivantes :

    • SECRET_PATH : chemin d'accès Secret Manager à vos identifiants d'authentification Elasticsearch. Exemple : projects/123456789012/secrets/apikey/versions/1. 123456789012 représente l'ID de votre projet Google Cloud .

    • (Facultatif) MAX_DEADLINE : durée maximale, en millisecondes, pendant laquelle AlloyDB attend une réponse d'Elasticsearch. Vous devez définir cette valeur en fonction des emplacements de vos instances AlloyDB et Elasticsearch. La valeur par défaut est 10000.

    • (Facultatif) PAGINATION_NUM_RESULTS : nombre maximal de résultats récupérés par lot à partir d'Elasticsearch. Si d'autres résultats sont demandés, AlloyDB les récupère en plusieurs lots de cette taille. La valeur par défaut est 32.

    • (Facultatif) PAGINATION_CONTEXT_TIMEOUT : durée, en millisecondes, pendant laquelle Elasticsearch maintient actif le contexte de la requête de pagination. La valeur par défaut est 30000.

  3. Définissez le mappage des utilisateurs PostgreSQL pour le serveur Elasticsearch. Notez que les FDW PostgreSQL nécessitent ce mappage d'utilisateurs pour fonctionner. AlloyDB s'authentifie à l'aide de l'en-tête d'autorisation REST.

    CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;

  4. Configurez le schéma de vos données Elasticsearch via une table de données externe.

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

    Remplacez les nouvelles variables suivantes :

    • ELASTICSEARCH_FD_TABLE : nom de la table de données externe qui représente votre table Elasticsearch. Exemple :my-fd-elasticsearch-table

    • ELASTICSEARCH_FIELDS : liste de définitions de schéma de champ Elasticsearch séparées par une virgule, au format suivant : elasticsearch_field_name PG_DATA_TYPE. Exemple : elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISION. Ces champs doivent correspondre aux noms de champs dans Elasticsearch, sauf si l'option remote_field_name est ajoutée. Par exemple, elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO').

      Pour obtenir la liste des types de données Elasticsearch pouvant être définis pour AlloyDB, consultez Types de données compatibles.

    • ELASTICSEARCH_INDEX_NAME : nom de votre index Elasticsearch. Exemple :my-elasticsearch-index

Types de données acceptés

AlloyDB est compatible avec les types de données Elasticsearch suivants :

Type(s) de données Type PostgreSQL
alias Type PostgreSQL pour le champ auquel alias fait référence
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

Interroger vos données Elasticsearch

AlloyDB prend les requêtes SQL et les convertit en requêtes d'API REST Elasticsearch. Lors de cette conversion, AlloyDB tente de transférer autant de logique de requête que possible sans modifier l'identité de la requête, y compris le LIMIT de la requête SQL. Toutefois, dans certains cas, vous pouvez spécifier de ne pas appliquer certains champs Elasticsearch ou la logique de requête ne peut pas être appliquée. Par exemple, LIKE et d'autres opérateurs de correspondance de texte ne peuvent pas être transférés. Pour obtenir d'autres exemples d'opérations pouvant ou non être transmises, consultez Exemples de transmission.

Dans les scénarios où LIMIT est défini sur une valeur supérieure à pagination_num_results, ou lorsque LIMIT n'est pas spécifié ou ne peut pas être transmis, AlloyDB utilise l'API Scroll, qui peut consommer beaucoup de ressources.

L'API Scroll pouvant consommer beaucoup de ressources, nous vous recommandons d'examiner vos requêtes à l'aide de EXPLAIN VERBOSE pour voir quelles API sont utilisées. Limiter l'utilisation de l'API Scroll et utiliser LIMIT améliore les performances.

Pour interroger vos données Elasticsearch, vous disposez des options suivantes :

  • Requêtes SQL standards
  • DSL de requête
  • Recherches hybrides

Requêtes SQL standards

Les requêtes SQL standards peuvent être écrites à l'aide de la syntaxe Lucene d'Elasticsearch.

Pour effectuer une requête SQL standard, consultez l'exemple de requête suivant :

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

Remplacez les variables suivantes :

  • ELASTICSEARCH_FD_TABLE : nom de la table de données externe qui représente votre table Elasticsearch. Exemple : my-fd-elasticsearch-table.

  • (Facultatif) FILTER : filtre à appliquer à votre requête Elasticsearch. Exemple :AND qubits < 105

  • QUERY : requête à envoyer à Elasticsearch. Voici quelques exemples de requêtes :

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

DSL de requête

Query DSL est le langage de requête complet de style JSON d'Elasticsearch, recommandé pour les cas d'utilisation avancés. Le DSL de requête vous permet d'effectuer des recherches, des filtrages et des agrégations complexes qui ne peuvent pas être exprimés dans la syntaxe de requête SQL.

Pour effectuer des requêtes à l'aide du langage DSL de requête, consultez l'exemple de requête suivant :

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;

Remplacez les variables suivantes :

  • ELASTICSEARCH_FD_TABLE : nom de la table de données externe qui représente votre table Elasticsearch. Exemple : my-fd-elasticsearch-table.

  • QUERY : requête à envoyer à Elasticsearch. Exemple : "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]".

Notez que pour Query DSL, vous ne devez propager que les expressions query, filter et sort.

Pour effectuer une recherche hybride sur vos données Elasticsearch, consultez l'exemple de recherche suivant :

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;

Remplacez les variables suivantes :

  • LIMIT : nombre de résultats à renvoyer. Exemple :3

  • WEIGHT : contribution de cette entrée de recherche à la Reciprocal Rank Fusion (RRF) globale.

  • ELASTICSEARCH_FD_TABLE : nom de la table de données externe qui représente votre table Elasticsearch. Exemple : my-fd-elasticsearch-table.

  • DOCUMENT_ID_COLUMN_NAME : nom de la colonne d'ID de document.

  • QUERY : requête à envoyer à Elasticsearch. Par exemple, "elasticsearch_field_name:\"quantum computing\"" recherche l'expression "informatique quantique" dans le champ elasticsearch_field_name. Tous les types de requêtes mentionnés dans la section Types de données compatibles peuvent être utilisés dans votre requête.

Pour en savoir plus sur les paramètres disponibles pour les recherches hybrides, consultez Paramètres de la fonction de recherche hybride.

Exemples de pushdown

Pour rendre les requêtes plus efficaces, AlloyDB tente de transférer les aspects suivants de la requête directement dans l'appel d'API effectué vers Elasticsearch :

  • SELECT champs
  • WHERE filtres
  • ORDER BY tri
  • LIMIT

Pour obtenir des exemples de requêtes illustrant les aspects qu'AlloyDB peut et ne peut pas transférer, consultez le tableau suivant.

Type de requête Exemple de requête Éléments de requête transférés
Requêtes non filtrées 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT champs
  • ORDER BY ... DESC tri
  • LIMIT
Correspondance exacte avec le texte 
SELECT id, body
FROM elasticsearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT champs
  • WHERE filtre
  • LIMIT
Expressions à champ unique 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT champs
  • WHERE filtre
Expressions constantes 
SELECT id, body
FROM elasticsearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT champs
  • WHERE filtre
  • LIMIT
Expressions avec des fonctions 
SELECT id, body
FROM elasticsearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT champs
Expressions multichamps 
SELECT id, body
FROM elasticsearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT champs
Filtrage des scores 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM elasticsearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT champs
  • ORDER BY ... DESC tri
LIKE et opérateurs similaires 
SELECT id, body
FROM elasticsearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT champs
  • WHERE id > 10 filtre
Requêtes brutes 
SELECT id, body
FROM elasticsearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT champs
  • ORDER BY ... DESC tri

Dépannage

Si vous rencontrez des problèmes d'authentification ou de connectivité lors de l'interrogation de votre cluster Elasticsearch, vérifiez les causes courantes suivantes :

  • Erreurs d'authentification HTTP 401 ou 403 : vérifiez que votre secret Elasticsearch dans Secret Manager contient des identifiants d'authentification valides pour votre auth_method (ApiKey ou Basic), et vérifiez que le compte de service utilisé par AlloyDB dispose de l'autorisation secretmanager.secretAccessor.
  • Délais avant expiration de la connexion : vérifiez que la connectivité IP publique sortante est activée sur votre instance AlloyDB principale et que votre pare-feu Elasticsearch autorise les connexions entrantes sur le port spécifié.

Limites

Avant de connecter AlloyDB à Elasticsearch, tenez compte des limites suivantes :

  • L'intégration d'Elasticsearch n'est disponible que sur la version majeure 17 de PostgreSQL et les versions ultérieures.

  • AlloyDB lit les données Elasticsearch, mais n'y écrit pas.

  • Vous êtes responsable de la synchronisation des données entre AlloyDB et Elasticsearch.

  • Les types Elasticsearch spécialisés, tels que geo_point, ne sont pas acceptés. Pour obtenir la liste complète des types de données acceptés, consultez Types de données acceptés.

Étapes suivantes