Requisitos previos Términos Parámetros Configuración de bases de datos y tablas en AWS Glue Ejecución de consultas SQL Rendimiento Consultas de acceso directo Recursos adicionales

Conector para OpenSearch de Amazon Athena

OpenSearch Service

El conector Amazon Athena OpenSearch permite a Amazon Athena comunicarse con sus instancias de OpenSearch para que pueda utilizar SQL para consultar los datos de OpenSearch.

Este conector no se puede registrar en el Catálogo de datos de Glue como catálogo federado. Este conector no es compatible con los controles de acceso a datos definidos en Lake Formation a nivel de catálogo, base de datos, tabla, columna, fila y etiqueta. Este conector utiliza Conexiones de Glue para centralizar las propiedades de configuración en Glue.

nota

Debido a un problema conocido, el conector OpenSearch no se puede utilizar con una VPC.

Si Lake Formation está habilitado en la cuenta, el rol de IAM del conector de Lambda federado de Athena que haya implementado en AWS Serverless Application Repository debe tener acceso de lectura en Lake Formation para AWS Glue Data Catalog.

Requisitos previos

Implemente el conector en su Cuenta de AWS mediante la consola de Athena o AWS Serverless Application Repository. Para obtener más información, consulte Cómo crear una conexión de origen de datos o Uso del AWS Serverless Application Repository para implementar un conector de origen de datos.

Términos

Los siguientes términos hacen referencia al conector de OpenSearch.

Dominio: un nombre que este conector asocia con el punto de conexión de la instancia de OpenSearch. El dominio también se usa como nombre de base de datos. Para las instancias de OpenSearch definidas en Amazon OpenSearch Service, el dominio se puede detectar automáticamente. Para otras instancias, debe proporcionar una asignación entre el nombre de dominio y el punto de conexión.
Índice: una tabla de base de datos definida en la instancia de OpenSearch.
Asignación: si un índice es una tabla de base de datos, la asignación es su esquema (es decir, la definición de sus campos y atributos).

Este conector admite tanto la recuperación de metadatos de la instancia de OpenSearch como de AWS Glue Data Catalog. Si el conector encuentra una base de datos y una tabla de AWS Glue que coincidan con los nombres de dominio e índice de OpenSearch, el conector intenta utilizarlos para la definición del esquema. Le recomendamos que cree su tabla de AWS Glue para que sea un superconjunto de todos los campos del índice de OpenSearch.
Documento: un registro dentro de una tabla de base de datos.
Flujo de datos: datos basados en el tiempo que se componen de varios índices de respaldo. Para obtener más información, consulte Flujos de datos en la documentación de OpenSearch y Introducción a los flujos de datos en la Guía para desarrolladores de Amazon OpenSearch Service.

nota
Como los índices de flujos de datos se crean y administran internamente mediante una búsqueda abierta, el conector elige la asignación de esquemas del primer índice disponible. Por este motivo, recomendamos encarecidamente configurar una tabla de AWS Glue como origen de metadatos complementario. Para obtener más información, consulte Configuración de bases de datos y tablas en AWS Glue.

Parámetros

Utilice los parámetros de esta sección para configurar el conector OpenSearch.

nota

Los conectores de orígenes de datos de Athena creados a partir del 3 de diciembre de 2024 utilizan conexiones de AWS Glue.

Los nombres y definiciones de los parámetros que se indican a continuación corresponden a conectores de orígenes de datos de Athena creados antes del 3 de diciembre de 2024. Estos pueden variar respecto a las propiedades de conexión de AWS Glue correspondientes. A partir del 3 de diciembre de 2024, utilice los parámetros que se indican a continuación únicamente al implementar manualmente una versión anterior de un conector de origen de datos de Athena.

spill_bucket: especifica el bucket de Amazon S3 para los datos que superen los límites de la función de Lambda.
spill_prefix: (opcional) de forma predeterminada, se establece una subcarpeta en la carpeta especificada spill_bucket llamada athena-federation-spill. Le recomendamos configurar un ciclo de vida de almacenamiento de Amazon S3 en esta ubicación para eliminar vertidos de más de un número predeterminado de días u horas.
spill_put_request_headers: (opcional) un mapa codificado en JSON de encabezados y valores de solicitudes para la solicitud putObject de Amazon S3 que se usa para el vertidos (por ejemplo, {"x-amz-server-side-encryption" : "AES256"}). Para ver otros encabezados posibles, consulte PutObject en la referencia de la API de Amazon Simple Storage Service.
kms_key_id: (opcional) de forma predeterminada, los datos que se vierten a Amazon S3 se cifran mediante el modo de cifrado autenticado AES-GCM y una clave generada aleatoriamente. Para que la función de Lambda use claves de cifrado más seguras generadas por KMS, como a7e63k4b-8loc-40db-a2a1-4d0en2cd8331, puede especificar un ID de clave de KMS.
disable_spill_encryption: (opcional) cuando se establece en True, desactiva el cifrado del vertido. El valor predeterminado es False, de modo que los datos que se vierten a S3 se cifran mediante AES-GCM, ya sea mediante una clave generada aleatoriamente o KMS para generar claves. La desactivación del cifrado de vertido puede mejorar el rendimiento, especialmente si su ubicación de vertido usa cifrado del servidor.
disable_glue: (opcional) si está presente y se establece en true (verdadero), el conector no intentará recuperar metadatos complementarios de AWS Glue.
query_timeout_cluster: el tiempo de espera, en segundos, para las consultas de estado del clúster utilizadas en la generación de análisis paralelos.
query_timeout_search: el tiempo de espera, en segundos, de las consultas de búsqueda utilizadas en la recuperación de documentos de un índice.
auto_discover_endpoint: booleano. El valor predeterminado es true. Cuando utiliza Amazon OpenSearch Service y establece este parámetro en true (verdadero), el conector puede detectar automáticamente los dominios y puntos de conexión al llamar a las operaciones de API de descripción o lista correspondientes en el servicio OpenSearch Service. Para cualquier otro tipo de instancia de OpenSearch (por ejemplo, autoalojada), debe especificar los puntos de conexión del dominio asociados en la variable domain_mapping. Si auto_discover_endpoint=true, el conector usa las credenciales de AWS para autenticarse en OpenSearch Service. De lo contrario, el conector recupera las credenciales del nombre de usuario y contraseña de AWS Secrets Manager a través de la variable domain_mapping.
domain_mapping: se usa solo cuando auto_discover_endpoint se establece en false (falso) y define la asignación entre los nombres de dominio y sus puntos de conexión asociados. La variable domain_mapping puede admitir varios puntos de conexión de OpenSearch con el siguiente formato:
```
domain1=endpoint1,domain2=endpoint2,domain3=endpoint3,...       
```
Con el fin de autenticarse en un punto de conexión de OpenSearch, el conector admite cadenas de sustitución inyectadas con el formato ${SecretName}: y con nombre de usuario y contraseña obtenidos de AWS Secrets Manager. Los dos puntos (:) al final de la expresión sirven como separador del resto del punto de conexión.

importante
Como práctica recomendada en materia de seguridad, no utilice credenciales codificadas en las variables de entorno ni en las cadenas de conexión. Para obtener información sobre cómo transferir los secretos codificados a AWS Secrets Manager, consulte Mover secretos codificados a AWS Secrets Manager en la Guía del usuario de AWS Secrets Manager.

En el siguiente ejemplo se usa el secreto opensearch-creds.
```
movies=https://${opensearch-creds}:search-movies-ne...qu---us-east-1---es.amazonaws.com     
```
En tiempo de ejecución, ${opensearch-creds} se representa como nombre de usuario y contraseña, como en el siguiente ejemplo.
```
movies=https://myusername@mypassword:search-movies-ne...qu---us-east-1---es.amazonaws.com
```
En el parámetro domain_mapping, cada par dominio-punto de conexión puede usar un secreto diferente. El secreto en sí se debe especificar en el formato user_name@password. Aunque la contraseña puede contener signos @ incrustados, la primera @ sirve como separador de user_name.

También es importante tener en cuenta que este conector utiliza la coma (,) y el signo igual (=) como separadores para los pares dominio-punto de conexión. Por este motivo, no debe utilizarlos en ningún lugar dentro del secreto almacenado.

Configuración de bases de datos y tablas en AWS Glue

El conector obtiene información de metadatos mediante AWS Glue u OpenSearch. Puede configurar una tabla de AWS Glue como origen de la definición de metadatos suplementaria. Para habilitar esta característica, defina una base de datos y una tabla de AWS Glue que coincidan con el dominio y el índice del origen que va a complementar. El conector también puede aprovechar las definiciones de metadatos almacenadas en la instancia de OpenSearch al recuperar la asignación para el índice especificado.

Definición de metadatos para matrices en OpenSearch

OpenSearch no tiene un tipo de datos de matrices dedicado. Cualquier campo puede contener cero o más valores siempre que sean del mismo tipo de datos. Si desea utilizar OpenSearch como origen de definición de metadatos, debe definir una propiedad _meta para todos los índices utilizados con Athena en los campos que se van a considerar una lista o matriz. Si no completa este paso, las consultas devuelven solo el primer elemento del campo de la lista. Al especificar la propiedad _meta, los nombres del campo deben estar totalmente cualificados para las estructuras JSON anidadas (por ejemplo, address.street, en la que street es un campo anidado dentro de una estructura de address).

En el siguiente ejemplo, se definen las listas actor y genre en la tabla movies.


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

Tipos de datos

El conector de OpenSearch puede extraer definiciones de metadatos de AWS Glue o de la instancia de OpenSearch. El conector utiliza la asignación de la siguiente tabla para convertir las definiciones en tipos de datos de Apache Arrow, incluidos los puntos que se indican en la sección siguiente.

OpenSearch	Apache Arrow	AWS Glue
text, keyword, binary	VARCHAR	cadena
long	BIGINT	bigint
scaled_float	BIGINT	SCALED_FLOAT(...)
integer	INT	int
short	SMALLINT	smallint
byte	TINYINT	tinyint
double	FLOAT8	double
float, half_float	FLOAT4	float
boolean	BIT	boolean
date, date_nanos	DATEMILLI	marca de tiempo
Estructura JSON	STRUCT	STRUCT
_meta (para obtener información, consulte la sección Definición de metadatos para matrices en OpenSearch).	LIST	ARRAY

Notas sobre los tipos de datos

Actualmente, el conector solo admite OpenSearch y los tipos de datos de AWS Glue incluidos en la tabla anterior.
scaled_float es un número de coma flotante escalado por un factor de escala doble fijo y representado como BIGINT en Apache Arrow. Por ejemplo, 0,756 con un factor de escala de 100 se redondea a 76.
Para definir un scaled_float en AWS Glue, debe seleccionar la columna de array y declarar el campo con el formato SCALED_FLOAT (scaling_factor).

Los ejemplos siguientes son válidos:
```
SCALED_FLOAT(10.51) 
SCALED_FLOAT(100) 
SCALED_FLOAT(100.0)
```
Los ejemplos siguientes no son válidos:
```
SCALED_FLOAT(10.) 
SCALED_FLOAT(.5)
```
Al hacer la conversión de date_nanos a DATEMILLI, los nanosegundos se redondean al milisegundo más próximo. Los valores válidos de date y date_nanos incluyen los siguientes formatos, entre otros:
```
"2020-05-18T10:15:30.123456789" 
"2020-05-15T06:50:01.123Z" 
"2020-05-15T06:49:30.123-05:00" 
1589525370001 (epoch milliseconds)
```
Un elemento binary de OpenSearch es una representación de cadena de un valor binario codificado mediante Base64 y se convierte a VARCHAR.

Ejecución de consultas SQL

Los siguientes son ejemplos de consultas DDL que puede usar con este conector. En los ejemplos, function_name corresponde al nombre de la función de Lambda, domain es el nombre del dominio que se desea consultar e index es el nombre del índice.


SHOW DATABASES in `lambda:function_name`


SHOW TABLES in `lambda:function_name`.domain


DESCRIBE `lambda:function_name`.domain.index

Rendimiento

El conector de OpenSearch de Athena admite análisis paralelos basados en particiones. El conector utiliza la información de estado del clúster recuperada de la instancia de OpenSearch para generar varias solicitudes de consulta de búsqueda de documentos. Las solicitudes se dividen para cada partición y se ejecutan de forma simultánea.

El conector también inserta los predicados como parte de sus consultas de búsqueda de documentos. El siguiente ejemplo de consulta y predicado muestra cómo utiliza el conector la inserción de predicados.

Query


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

Predicado


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

Consultas de acceso directo

El conector OpenSearch admite consultas de acceso directo y utiliza el lenguaje Query DSL. Para obtener más información sobre las consultas con Query DSL, consulte Query DSL en la documentación de Elasticsearch o Query DSL en la documentación de OpenSearch.

Para utilizar consultas de acceso directo con el conector OpenSearch, utilice la siguiente sintaxis:


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

En el siguiente ejemplo de OpenSearch, se filtran las consultas de acceso directo para los empleados con un estado laboral activo en el índice employee del esquema default.


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

Recursos adicionales

Para obtener información sobre cómo usar el conector OpenSearch de Amazon Athena para consultar datos en Amazon OpenSearch Service y Amazon S3 en una sola consulta, consulte el artículo Consulta de datos en Amazon OpenSearch Service mediante SQL desde Amazon Athena en el Blog de macrodatos de AWS.
Para obtener más información acerca de este conector, consulte el sitio correspondiente en GitHub.com.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Neptune

Oracle

Conector para OpenSearch de Amazon Athena

nota

Requisitos previos

Términos

nota

Parámetros

nota

importante

Configuración de bases de datos y tablas en AWS Glue

Definición de metadatos para matrices en OpenSearch

Tipos de datos

Notas sobre los tipos de datos

Ejecución de consultas SQL

Rendimiento

Consultas de acceso directo

Recursos adicionales