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

Aperçu — FDW Elasticsearch

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Accédez aux données stockées dans Elasticsearch et effectuez des recherches dans ces données en créant un wrapper de données externes (FDW) et une table externe dans AlloyDB pour PostgreSQL.

Limites

Avant de connecter AlloyDB à Elasticsearch, prenez connaissance 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.

Avant de commencer

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

• Créez un cluster.

• Activez la connectivité sortante sur votre instance AlloyDB principale.

• Déployez et exécutez Elasticsearch en production.

• Créez une clé API personnelle/utilisateur en lecture seule qu'AlloyDB peut utiliser pour accéder à votre cluster Elasticsearch.

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'autoriser votre compte de service AlloyDB à 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 votre intégration à 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 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 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 extraits par lot depuis Elasticsearch. Si plus de 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 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 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, 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 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 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, 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 où LIMIT n'est pas spécifié ou ne peut pas être transféré, AlloyDB utilise l'API Scroll, qui peut être gourmande en 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 en 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.

Recherches hybrides

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.

• 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 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 illustrant les aspects qu'AlloyDB peut ou 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

Remarque : Elasticsearch est une marque d'Elastic NV et n'est pas affiliée à Google LLC.