Connecteur Amazon Athena OpenSearch - Amazon Athena
PrérequisConditionsParamètresConfiguration de bases de données et de tables dans AWS GlueExécution de requêtes SQLPerformanceRequêtes directesRessources supplémentaires

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Connecteur Amazon Athena OpenSearch

OpenSearch Service

Le OpenSearch connecteur Amazon Athena permet à Amazon Athena de communiquer avec OpenSearch vos instances afin que vous puissiez utiliser le SQL pour interroger vos données. OpenSearch

Note

En raison d'un problème connu, le OpenSearch connecteur ne peut pas être utilisé avec un VPC.

Si Lake Formation est activé sur votre compte, le rôle IAM de votre connecteur Lambda fédéré Athena que vous avez déployé dans AWS Serverless Application Repository le doit avoir un accès en lecture dans Lake Formation au. AWS Glue Data Catalog

Prérequis

Conditions

Les termes suivants concernent le OpenSearch connecteur.

  • Domaine : nom que ce connecteur associe au point de terminaison de votre OpenSearch instance. Le domaine est également utilisé comme nom de base de données. Pour les OpenSearch instances définies au sein d'Amazon OpenSearch Service, le domaine est détectable automatiquement. Pour les autres cas, vous devez fournir un mappage entre le nom de domaine et le point de terminaison.

  • Index — Table de base de données définie dans votre OpenSearch instance.

  • Mapping (Mappage) – Si un index est une table de base de données, le mappage est son schéma (c’est-à-dire les définitions de ses champs et attributs).

    Ce connecteur prend en charge à la fois la récupération des métadonnées depuis l' OpenSearch instance et depuis le AWS Glue Data Catalog. Si le connecteur trouve une AWS Glue base de données et une table qui correspondent à vos noms de OpenSearch domaine et d'index, il tente de les utiliser pour définir le schéma. Nous vous recommandons de créer votre AWS Glue table de manière à ce qu'elle soit un sur-ensemble de tous les champs de votre OpenSearch index.

  • Document – Un enregistrement au sein d’une table de base de données.

  • Flux de données – Données temporelles composées de plusieurs index de support. Pour plus d'informations, consultez les sections Flux de données dans la OpenSearch documentation et Getting started with data streams dans le Amazon OpenSearch Service Developer Guide.

    Note

    Les index de flux de données étant créés et gérés en interne par OpenSearch, le connecteur choisit le mappage de schéma à partir du premier index disponible. Pour cette raison, nous vous recommandons vivement de configurer une AWS Glue table comme source de métadonnées supplémentaire. Pour plus d’informations, consultez Configuration de bases de données et de tables dans AWS Glue.

Paramètres

Utilisez les variables d'environnement Lambda de cette section pour configurer le OpenSearch connecteur.

  • spill_bucket – Spécifie le compartiment Amazon S3 pour les données qui dépassent les limites des fonctions Lambda.

  • spill_prefix – (Facultatif) Par défaut, il s’agit d’un sous-dossier dans le spill_bucket spécifié appelé athena-federation-spill. Nous vous recommandons de configurer un cycle de vie de stockage Amazon S3 à cet endroit pour supprimer les déversements supérieurs à un nombre de jours ou d’heures prédéterminé.

  • spill_put_request_headers – (Facultatif) Une carte codée au format JSON des en-têtes et des valeurs des demandes pour la demande putObject Amazon S3 utilisée pour le déversement (par exemple, {"x-amz-server-side-encryption" : "AES256"}). Pour les autres en-têtes possibles, consultez le PutObjectmanuel Amazon Simple Storage Service API Reference.

  • kms_key_id – (Facultatif) Par défaut, toutes les données déversées vers Amazon S3 sont chiffrées à l'aide du mode de chiffrement authentifié AES-GCM et d'une clé générée de manière aléatoire. Pour que votre fonction Lambda utilise des clés de chiffrement plus puissantes générées par KMS, comme a7e63k4b-8loc-40db-a2a1-4d0en2cd8331, vous pouvez spécifier l’ID d’une clé KMS.

  • disable_spill_encryption – (Facultatif) Lorsque la valeur est définie sur True, le chiffrement des déversements est désactivé. La valeur par défaut est False afin que les données déversées vers S3 soient chiffrées à l’aide d’AES-GCM, soit à l’aide d’une clé générée de manière aléatoire soit à l’aide de KMS pour générer des clés. La désactivation du chiffrement des déversements peut améliorer les performances, surtout si votre lieu de déversement utilise le chiffrement côté serveur.

  • disable_glue — (Facultatif) S'il est présent et défini sur true, le connecteur ne tente pas de récupérer des métadonnées supplémentaires à partir de. AWS Glue

  • query_timeout_cluster – Le délai d’expiration, en secondes, pour les requêtes d’intégrité du cluster utilisées dans la génération d’examens parallèles.

  • query_timeout_search – Le délai d’expiration, en secondes, des requêtes de recherche utilisées pour récupérer des documents à partir d’un index.

  • auto_discover_endpoint – Valeur booléenne. L’argument par défaut est true. Lorsque vous utilisez le OpenSearch service Amazon et que vous définissez ce paramètre sur true, le connecteur peut découvrir automatiquement vos domaines et points de terminaison en appelant les opérations d'API de description ou de liste appropriées sur le OpenSearch service. Pour tout autre type d' OpenSearch instance (par exemple, auto-hébergée), vous devez spécifier les points de terminaison de domaine associés dans la domain_mapping variable. Siauto_discover_endpoint=true, le connecteur utilise des AWS informations d'identification pour s'authentifier auprès du OpenSearch service. Dans le cas contraire, le connecteur récupère les informations d'identification du nom d'utilisateur et du mot de passe AWS Secrets Manager par le biais de la domain_mapping variable.

  • domain_mapping – Utilisé uniquement lorsque auto_discover_endpoint est défini sur false et définit le mappage entre les noms de domaine et leurs points de terminaison associés. La domain_mapping variable peut prendre en charge plusieurs OpenSearch points de terminaison au format suivant :

    domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...

    Aux fins de l'authentification auprès d'un OpenSearch point de terminaison, le connecteur prend en charge les chaînes de substitution injectées en utilisant le format dont le nom ${SecretName}: d'utilisateur et le mot de passe ont été extraits AWS Secrets Manager. Le signe deux-points (:) à la fin de l’expression sert de séparateur par rapport au reste du point de terminaison.

    Important

    Afin de vous aider à optimiser la sécurité, n'utilisez pas d'informations d'identification codées en dur dans vos variables d'environnement ou vos chaînes de connexion. Pour plus d'informations sur le transfert de vos secrets codés en dur vers AWS Secrets Manager, voir Déplacer les secrets codés en dur vers AWS Secrets Manager dans le Guide de l'AWS Secrets Manager utilisateur.

    L’exemple suivant utilise le secret opensearch-creds.

    movies=https://${opensearch-creds}:search-movies-ne...qu.us-east-1.es.amazonaws.com

    Au moment de l’exécution, ${opensearch-creds} est affiché sous la forme du nom d’utilisateur et du mot de passe, comme dans l’exemple suivant.

    movies=https://myusername@mypassword:search-movies-ne...qu.us-east-1.es.amazonaws.com

    Dans le paramètre domain_mapping, chaque paire domaine-point de terminaison peut utiliser un secret différent. Le secret lui-même doit être spécifié au format nom_utilisateur@mot de passe. Bien que le mot de passe puisse contenir des signes @ intégrés, le premier @ sert de séparateur denom_utilisateur.

    Il est également important de noter que la virgule (,) et le signe égal (=) sont utilisés par ce connecteur comme séparateurs pour les paires domaine-point de terminaison. Pour cette raison, vous ne devez les utiliser nulle part dans le secret stocké.

Configuration de bases de données et de tables dans AWS Glue

Le connecteur obtient des informations de métadonnées à l'aide de AWS Glue ou OpenSearch. Vous pouvez configurer une AWS Glue table comme source de définition de métadonnées supplémentaire. Pour activer cette fonctionnalité, définissez une AWS Glue base de données et une table correspondant au domaine et à l'index de la source que vous complétez. Le connecteur peut également tirer parti des définitions de métadonnées stockées dans l' OpenSearch instance en récupérant le mappage pour l'index spécifié.

Définition des métadonnées pour les tableaux dans OpenSearch

OpenSearch ne possède pas de type de données de tableau dédié. Chaque champ peut contenir zéro ou plusieurs valeurs, à condition qu’elles soient du même type de données. Si vous souhaitez l'utiliser OpenSearch comme source de définition de métadonnées, vous devez définir une _meta propriété pour tous les index utilisés avec Athena pour les champs qui doivent être considérés comme une liste ou un tableau. Si vous ne parvenez pas à effectuer cette étape, les requêtes renvoient uniquement le premier élément du champ de liste. Lorsque vous spécifiez la propriété _meta, les noms de champs doivent être entièrement qualifiés pour les structures JSON imbriquées (par exemple, address.street, où street est un champ imbriqué dans une structure address).

L’exemple suivant définit les listes actor et genre dans la table movies.

PUT movies/_mapping 
{ 
  "_meta": { 
    "actor": "list", 
    "genre": "list" 
  } 
}

Types de données

Le OpenSearch connecteur peut extraire les définitions de métadonnées de l'instance AWS Glue ou de l' OpenSearch instance. Le connecteur utilise le mappage du tableau suivant pour convertir les définitions en types de données Apache Arrow, y compris les points notés dans la section suivante.

OpenSearch Apache AWS Glue
texte, mot clé, binaire VARCHAR chaîne
long BIGINT bigint
scaled_float BIGINT SCALED_FLOAT(...)
entier INT int
short SMALLINT smallint
 octet TINYINT tinyint
double FLOAT8 double
float, half_float FLOAT4 float
boolean BIT boolean
date, date_nanos DATEMILLI timestamp
Structure JSON STRUCT STRUCT
_meta (pour plus d’informations, consultez la section Définition des métadonnées pour les tableaux dans OpenSearch.) LIST ARRAY

Remarques sur les types de données

  • Actuellement, le connecteur ne prend en charge que les AWS Glue types de données OpenSearch et répertoriés dans le tableau précédent.

  • Unscaled_float est un nombre à virgule flottante mis à l’échelle par un facteur de mise à l’échelle double fixe et représenté en tant que BIGINT dans Apache Arrow. Par exemple, 0,756 avec un facteur d’échelle de 100 est arrondi à 76.

  • Pour définir un scaled_float in AWS Glue, vous devez sélectionner le type de array colonne et déclarer le champ au format SCALED_FLOAT (scaling_factor).

    Les exemples suivants sont valides :

    SCALED_FLOAT(10.51) 
SCALED_FLOAT(100) 
SCALED_FLOAT(100.0)

    Les exemples suivants ne sont pas valides :

    SCALED_FLOAT(10.) 
SCALED_FLOAT(.5)

  • Lors de la conversion de date_nanos vers DATEMILLI, les nanosecondes sont arrondies à la milliseconde la plus proche. Valeurs valides pour date et date_nanos incluent, sans s’y limiter, les formats suivants :

    "2020-05-18T10:15:30.123456789" 
"2020-05-15T06:50:01.123Z" 
"2020-05-15T06:49:30.123-05:00" 
1589525370001 (epoch milliseconds)

  • An OpenSearch binary est une représentation sous forme de chaîne d'une valeur binaire codée en utilisant Base64 et convertie en VARCHAR a.

Exécution de requêtes SQL

Vous trouverez ci-dessous des exemples de requêtes DDL que vous pouvez utiliser avec ce connecteur. Dans les exemples,function_name correspond au nom de votre fonction Lambda,domaine est le nom du domaine à interroger et index est le nom de votre index.

SHOW DATABASES in `lambda:function_name`
SHOW TABLES in `lambda:function_name`.domain
DESCRIBE `lambda:function_name`.domain.index

Performance

Le OpenSearch connecteur Athena prend en charge les scans parallèles basés sur des partitions. Le connecteur utilise les informations relatives à l'état du cluster extraites de l' OpenSearch instance pour générer plusieurs demandes de recherche de documents. Les demandes sont réparties pour chaque partition et exécutées simultanément.

Le connecteur transfère également des prédicats dans le cadre de ses requêtes de recherche de documents. L’exemple de requête et de prédicat suivant montre comment le connecteur utilise le prédicat poussé vers le bas.

Interrogation

SELECT * FROM "lambda:elasticsearch".movies.movies 
WHERE year >= 1955 AND year <= 1962 OR year = 1996

Prédicat

(_exists_:year) AND year:([1955 TO 1962] OR 1996)

Requêtes directes

Le OpenSearch connecteur prend en charge les requêtes directes et utilise le langage Query DSL. Pour plus d'informations sur les requêtes avec Query DSL, consultez Query DSL dans la documentation Elasticsearch ou Query DSL dans la documentation. OpenSearch

Pour utiliser des requêtes directes avec le OpenSearch connecteur, utilisez la syntaxe suivante :

SELECT * FROM TABLE(
        system.query(
            schema => 'schema_name',
            index => 'index_name',
            query => "{query_string}"
        ))

L' OpenSearch exemple de requête directe suivant filtre les employés dont le statut professionnel est actif dans l'employeeindex du default schéma.

SELECT * FROM TABLE(
        system.query(
            schema => 'default',
            index => 'employee',
            query => "{ ''bool'':{''filter'':{''term'':{''status'': ''active''}}}}"
        ))

Ressources supplémentaires