Accéder aux données Elasticsearch depuis AlloyDB Omni

Sélectionnez une version de la documentation :

Vous pouvez accéder aux données stockées dans Elasticsearch et les rechercher en créant un wrapper de données externes (FDW) et une table externe dans AlloyDB Omni.

Avant de commencer

Avant de commencer, procédez comme suit :

Créer un compte de service

AlloyDB Omni nécessite un compte de service avec Google Cloud pour s'authentifier et utiliser Secret Manager. AlloyDB Omni utilise Secret Manager pour stocker votre clé API Elasticsearch.

Si vous n'avez pas encore créé de compte de service pour AlloyDB Omni, faites-le en suivant ces étapes :

  1. Créez un compte de service avecGoogle Cloud. Vous accordez à ce compte de service l'autorisation d'accéder à Secret Manager dans Configurer AlloyDB/AI.

  2. Créez une clé de compte de service et enregistrez-la au format JSON dans le fichier private-key.json, puis téléchargez-la.

  3. Copiez la clé de compte de service que vous avez créée dans KEY_PATH. Le chemin d'accès à la clé doit être un chemin d'accès sur votre hôte qui est accessible et appartient à l'utilisateur qui exécute votre conteneur AlloyDB Omni.

Stocker la clé API Elasticsearch dans Secret Manager

AlloyDB Omni 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'autoriser votre compte de service AlloyDB Omni à lire le secret. Pour en savoir plus, consultez Gérer l'accès aux secrets.

Configurer AlloyDB AI pour AlloyDB Omni

Pour configurer AlloyDB AI pour AlloyDB Omni, consultez Configurer AlloyDB AI pour AlloyDB Omni et ignorez la première étape.

Activer et configurer l'extension external_search_fdw

Pour commencer votre intégration à Elasticsearch, suivez les instructions ci-dessous pour activer et configurer l'extension AlloyDB Omni 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 externes. 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 :

      • ApiKey : clé API personnelle/utilisateur Elasticsearch.

      • Basic : nom d'utilisateur et mot de passe Elasticsearch.

    • 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 Omni attend une réponse d'Elasticsearch. Définissez cette valeur en fonction de l'emplacement de vos instances AlloyDB Omni et Elasticsearch. La valeur par défaut est 10000.

    • (Facultatif) PAGINATION_NUM_RESULTS : nombre maximal de résultats extraits par lot depuis Elasticsearch. Si davantage de résultats sont demandés, AlloyDB Omni les récupère par lots de cette taille. La valeur par défaut est 32.

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

  3. Définissez le mappage utilisateur PostgreSQL pour le serveur Elasticsearch. Notez que les FDW PostgreSQL nécessitent ce mappage utilisateur pour fonctionner. AlloyDB Omni 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 externes.

    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 Omni, consultez Types de données acceptés.

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

Types de données acceptés

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

Type(s) de données Type PostgreSQL
alias Type PostgreSQL du 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 Omni prend les requêtes SQL et les convertit en requêtes d'API REST Elasticsearch. Lors de cette conversion, AlloyDB Omni 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, il peut arriver que vous spécifiiez de ne pas transférer certains champs Elasticsearch ou que la logique de requête ne puisse pas être transféré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 de ce qui peut et ne peut pas être transféré, consultez Exemples de transfert.

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 Omni utilise l'API Scroll, qui peut consommer beaucoup de ressources.

Étant donné que l'API Scroll peut 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 en SQL standard
  • DSL de requête
  • Recherches hybrides

Requêtes en SQL standard

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

Pour exécuter 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

Le DSL de requête est le langage de requête complet de style JSON d'Elasticsearch, recommandé pour les cas d'utilisation avancés. Le langage 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 des requêtes SQL.

Pour effectuer des requêtes à l'aide du 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 le DSL de requête, 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 au Reciprocal Rank Fusion (RRF) global. Exemple : 0.5. Si vous ne fournissez pas de pondérations, elles sont réparties de manière égale. Pour en savoir plus, consultez Paramètres de la fonction de recherche hybride.

  • 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 Types de données acceptés 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 Omni tente de transmettre les aspects suivants de la requête directement à l'appel d'API effectué vers Elasticsearch :

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

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

Type de requête Exemple de requête Éléments de requête déplacés vers le bas
Requêtes non filtrées 
SELECT id, body
FROM elasticsearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT champs
  • Trier par ORDER BY ... DESC
  • 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 multifield 
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
  • Trier par ORDER BY ... DESC
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
  • Trier par ORDER BY ... DESC

Dépannage

Si vous rencontrez des problèmes d'authentification ou de connectivité lorsque vous interrogez votre cluster Elasticsearch, vérifiez les points suivants :

  • 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 votre compte de service dispose de l'autorisation secretmanager.secretAccessor.
  • Délai de connexion dépassé : vérifiez les règles réseau et la configuration du pare-feu entre AlloyDB Omni et votre point de terminaison Elasticsearch.

Limites

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

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

  • Les types Elasticsearch spécialisés, tels que geo_point, ne sont pas acceptés. Pour en savoir plus, consultez Types de données acceptés.

Étapes suivantes