# Conector Oracle de Amazon Athena El conector de Oracle de Amazon Athena permite que Amazon Athena ejecute consultas de SQL en los datos almacenados en Oracle que se ejecutan en las instalaciones, en Amazon EC2 o en Amazon RDS. También puede utilizar el conector para consultar datos en [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/). Este conector se puede registrar en el Catálogo de datos de Glue como un catálogo federado. Admite los controles de acceso a los 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. ## 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](connect-to-a-data-source.md) o [Uso del AWS Serverless Application Repository para implementar un conector de origen de datos](connect-data-source-serverless-app-repo.md). ## Limitaciones + Las operaciones de escritura de DDL no son compatibles. + En una configuración de multiplexor, el bucket de vertido y el prefijo se comparten en todas las instancias de base de datos. + Cualquier límite de Lambda relevante. Para obtener más información, consulte [Cuotas de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) en la *Guía para desarrolladores de AWS Lambda*. + Solo se admiten las bases de datos Oracle de la versión 12.1.0.2. + Si el conector de Oracle no utiliza una conexión Glue, este escribirá en mayúsculas los nombres de la base de datos, la tabla y la columna de forma predeterminada. Si el conector de Oracle utiliza una conexión de Glue, los nombres de la base de datos, la tabla y la columna no se escribirán de forma predeterminada en mayúsculas por el conector. Para cambiar este comportamiento de mayúsculas y minúsculas, cambie la variable de entorno de Lambda `casing_mode` a `upper` o `lower` según sea necesario. Un conector Oracle que utilice una conexión Glue no admite el uso de un controlador de multiplexación. + Cuando utiliza el Oracle `NUMBER` sin precisión ni escala definidas, Athena lo trata como `BIGINT`. Para obtener los decimales necesarios en Athena, especifique `default_scale=<{{number of decimal places}}>` en las variables de entorno de Lambda. ## Términos Los siguientes términos hacen referencia al conector de Oracle. + **Instancia de base de datos**: cualquier instancia de base de datos implementada en las instalaciones, en Amazon EC2 o en Amazon RDS. + **Controlador**: un controlador de Lambda que accede a la instancia de base de datos. Un controlador puede ser para los metadatos o para los registros de datos. + **Controlador de metadatos**: un controlador de Lambda que recupera los metadatos de la instancia de base de datos. + **Controlador de registros**: un controlador de Lambda que recupera registros de datos de la instancia de base de datos. + **Controlador compuesto**: un controlador de Lambda que recupera tanto los metadatos como los registros de datos de la instancia de base de datos. + **Propiedad o parámetro**: una propiedad de base de datos que usan los controladores para extraer información de la base de datos. Estas propiedades se configuran como variables de entorno de Lambda. + **Cadena de conexión**: una cadena de texto que se usa para establecer una conexión con una instancia de base de datos. + **Catálogo**: un catálogo ajeno a AWS Glue registrado en Athena que es un prefijo obligatorio para la propiedad `connection_string`. + **Controlador de multiplexación**: un controlador de Lambda que puede aceptar y usar varias conexiones a bases de datos. ## Parameters Utilice los parámetros de esta sección para configurar el conector de Oracle. ### Conectores federados de AWS Glue Data Catalog Recomendamos configurar un conector de Oracle mediante un objeto de conexiones de Glue. Para ello, establezca la variable de entorno `glue_connection` de la función Lambda del conector Oracle con el nombre de la conexión de Glue que se va a utilizar. **Propiedades de las conexiones de Glue** Utilice el siguiente comando para obtener el esquema de un objeto de conexión de Glue. Este esquema contiene todos los parámetros que puede utilizar para controlar su conexión. ``` aws glue describe-connection-type --connection-type ORACLE ``` **Propiedades del entorno de Lambda** Las siguientes propiedades del entorno de Lambda se aplican solo cuando utiliza el conector con una función de Lambda en su cuenta. + **glue\_connection**: especifica el nombre de la conexión de Glue asociada al conector federado. + **is\_fips\_enabled**: (opcional) se establece en true cuando el modo FIPS está activado. El valor predeterminado es false. + **casing\_mode**: (opcional) especifica cómo manejar el uso de mayúsculas y minúsculas en los nombres de esquemas y tablas. El parámetro `casing_mode` utiliza los siguientes valores para especificar el comportamiento de las mayúsculas y minúsculas. + **lower**: convierte a minúsculas todos los nombres de esquemas y tablas proporcionados. Este es el valor predeterminado para los conectores que tienen una conexión de Glue asociada. + **upper**: convierte a mayúsculas todos los nombres de esquemas y tablas proporcionados. Este es el valor predeterminado para los conectores que no tienen una conexión de Glue asociada. + **case\_insensitive\_search**: realiza búsquedas sin distinguir mayúsculas y minúsculas en los nombres de esquemas y tablas en Oracle. Utilice este valor si la consulta contiene nombres de esquemas o tablas que no coinciden con el uso de mayúsculas y minúsculas predeterminado del conector. **nota** Todos los conectores que utilizan una conexión federada de AWS Glue Data Catalog deben utilizar AWS Secrets Manager para almacenar credenciales. El conector de Oracle creado por medio de una conexión federada de AWS Glue Data Catalog no admite el uso de un controlador de multiplexación. El conector de Oracle creado por medio de una conexión federada de AWS Glue Data Catalog solo es compatible con `ConnectionSchemaVersion` 2. ### Conectores federados del catálogo de datos de Athena **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 sin una conexión de Glue asociada. Utilice los siguientes parámetros solo cuando [implemente de forma manual](connect-data-source-serverless-app-repo.md) una versión anterior de un conector de origen de datos de Athena o cuando no se especifique la propiedad de entorno de `glue_connection`. **Propiedades del entorno de Lambda** + **default**: la cadena de conexión JDBC que se utilizará para conectarse a la instancia de base de datos de Oracle. Por ejemplo: ., `oracle://${jdbc_connection_string}` + **catalog\_connection\_string**: la utiliza el controlador de multiplexación (no se admite cuando se utiliza una conexión Glue). Una cadena de conexión de instancia de base de datos. Agregue el prefijo a la variable de entorno con el nombre del catálogo usado en Athena. Por ejemplo, si el catálogo registrado en Athena es myoraclecatalog, el nombre de la variable de entorno será myoraclecatalog\_connection\_string. + **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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **is\_fips\_enabled**: (opcional) se establece en true cuando el modo FIPS está activado. El valor predeterminado es false. + **casing\_mode**: (opcional) especifica cómo manejar el uso de mayúsculas y minúsculas en los nombres de esquemas y tablas. El parámetro `casing_mode` utiliza los siguientes valores para especificar el comportamiento de las mayúsculas y minúsculas. + **lower**: convierte a minúsculas todos los nombres de esquemas y tablas proporcionados. Este es el valor predeterminado para los conectores que tienen una conexión de Glue asociada. + **upper**: convierte a mayúsculas todos los nombres de esquemas y tablas proporcionados. Este es el valor predeterminado para los conectores que no tienen una conexión de Glue asociada. + **case\_insensitive\_search**: realiza búsquedas sin distinguir mayúsculas y minúsculas en los nombres de esquemas y tablas en Oracle. Utilice este valor si la consulta contiene nombres de esquemas o tablas que no coinciden con el uso de mayúsculas y minúsculas predeterminado del conector. #### Cadena de conexión Use una cadena de conexión JDBC con el siguiente formato para conectarse a una instancia de base de datos. ``` oracle://${{{jdbc_connection_string}}} ``` **nota** Si la contraseña contiene caracteres especiales (por ejemplo, `some.password`), escríbala entre comillas dobles cuando la pase a la cadena de conexión (por ejemplo, `"some.password"`). Si no lo hace, puede producirse un error de URL de Oracle especificada no válida. #### Uso de un controlador de conexión única Puede usar los siguientes controladores de registros y metadatos de conexión única para conectarse a una sola instancia de Oracle. **** | Tipo de controlador | Clase | | --- | --- | | Controlador compuesto | OracleCompositeHandler | | Controlador de metadatos | OracleMetadataHandler | | Controlador de registros | OracleRecordHandler | ##### Parámetros de controlador de conexión única **** | Parámetro | Descripción | | --- | --- | | default | Obligatorio. La cadena de conexión predeterminada. | | IsFIPSEnabled | Opcional. Se establece en true cuando el modo FIPS está habilitado. El valor predeterminado es false. | Los controladores de conexión única admiten una instancia de base de datos y deben proporcionar un parámetro de cadena de conexión `default`. Se omiten todas las demás cadenas de conexión. El conector admite conexiones basadas en SSL con instancias de Amazon RDS. La compatibilidad se limita al protocolo de seguridad de la capa de transporte (TLS) y a la autenticación del servidor por parte del cliente. La autenticación mutua no se admite en Amazon RDS. La segunda fila de la tabla siguiente muestra la sintaxis para usar SSL. La siguiente propiedad de ejemplo es para una sola instancia de Oracle compatible con una función de Lambda. **** | Propiedad | Valor | | --- | --- | | default | oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename | | | oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCPS) (HOST=)(PORT=))(CONNECT\_DATA=(SID=))(SECURITY=(SSL\_SERVER\_CERT\_DN=))) | #### Proporcionar credenciales Para proporcionar un nombre de usuario y una contraseña para la base de datos en la cadena de conexión JDBC, puede usar las propiedades de la cadena de conexión o AWS Secrets Manager. + **Cadena de conexión**: se pueden especificar un nombre de usuario y una contraseña como propiedades en la cadena de conexión JDBC. **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](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) en la *Guía del usuario de AWS Secrets Manager*. + **AWS Secrets Manager**: para utilizar la característica Consulta federada de Athena con AWS Secrets Manager, la VPC conectada a la función de Lambda debe tener [acceso a Internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) o un [punto de conexión de VPC](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) para conectarse a Secrets Manager. Puede poner el nombre de un secreto en AWS Secrets Manager, en la cadena de conexión JDBC. El conector reemplaza el nombre del secreto por los valores `username` y `password` de Secrets Manager. Para las instancias de bases de datos de Amazon RDS, esta compatibilidad está estrechamente integrada. Si usa Amazon RDS, le recomendamos encarecidamente que use AWS Secrets Manager y la rotación de credenciales. Si la base de datos no usa Amazon RDS, guarde las credenciales como archivos JSON con el siguiente formato: ``` {"username": "${username}", "password": "${password}"} ``` **nota** Si la contraseña contiene caracteres especiales (por ejemplo, `some.password`), escríbala entre comillas dobles cuando la guarde en Secrets Manager (por ejemplo, `"some.password"`). Si no lo hace, puede producirse un error de URL de Oracle especificada no válida. **Ejemplo de cadena de conexión con nombre secreto** La siguiente cadena tiene el nombre secreto `${Test/RDS/Oracle}`. ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` El conector usa el nombre secreto para recuperar los secretos y proporcionar el nombre de usuario y la contraseña, como en el siguiente ejemplo. ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` Actualmente, el conector de Oracle reconoce las propiedades `UID` y `PWD` de JDBC. #### Uso de un controlador de multiplexación Puede usar un multiplexor para conectarse a varias instancias de base de datos con una sola función de Lambda. Las solicitudes se enrutan por nombre de catálogo. Use las siguientes clases en Lambda. **** | Controlador | Clase | | --- | --- | | Controlador compuesto | OracleMuxCompositeHandler | | Controlador de metadatos | OracleMuxMetadataHandler | | Controlador de registros | OracleMuxRecordHandler | ##### Parámetros del controlador de multiplexación **** | Parámetro | Descripción | | --- | --- | | ${{catalog}}\_connection\_string | Obligatorio. Una cadena de conexión de instancia de base de datos. Agregue el prefijo a la variable de entorno con el nombre del catálogo usado en Athena. Por ejemplo, si el catálogo registrado en Athena es myoraclecatalog, el nombre de la variable de entorno será myoraclecatalog\_connection\_string. | | default | Obligatorio. La cadena de conexión predeterminada. Esta cadena se usa cuando el catálogo es lambda:${{{AWS\_LAMBDA\_FUNCTION\_NAME}}}. | Las siguientes propiedades de ejemplo son para una función de Lambda de Oracle MUX que admite dos instancias de base de datos: `oracle1` (la predeterminada) y `oracle2`. **** | Propiedad | Valor | | --- | --- | | default | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog1\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle1}@//oracle1.hostname:port/servicename | | oracle\_catalog2\_connection\_string | oracle://jdbc:oracle:thin:${Test/RDS/Oracle2}@//oracle2.hostname:port/servicename | ## Compatibilidad con tipos de datos En la siguiente tabla, se muestran los tipos de datos correspondientes para JDBC, Oracle y Arrow. **** | JDBC | Oracle | Arrow | | --- | --- | --- | | Booleano | booleano | Bit | | Entero | N/A | Pequeño | | Short | smallint | Smallint | | Entero | integer | Int | | Largo | bigint | Bigint | | float | float4 | Float4 | | Double | float8 | Float8 | | Date | date | DateDay | | Marca de tiempo | marca de tiempo | DateMilli | | Cadena | text | Varchar | | Bytes | bytes | Varbinary | | BigDecimal | numeric(p,s) | Decimal | | ARRAY | N/D (ver nota) | Enumeración | ## Particiones y divisiones Las particiones se usan para determinar cómo generar divisiones para el conector. Athena crea una columna sintética de tipo `varchar` que representa el esquema de partición de la tabla para ayudar al conector a generar divisiones. El conector no modifica la definición de la tabla real. ## Rendimiento Oracle admite particiones nativas. El conector Oracle de Athena puede recuperar datos de estas particiones en paralelo. Si quiere consultar conjuntos de datos muy grandes con una distribución uniforme de particiones, se recomienda encarecidamente la partición nativa. La selección de un subconjunto de columnas acelera significativamente el tiempo de ejecución de las consultas y reduce la cantidad de datos analizados. El conector Oracle resiste las limitaciones debidas a la simultaneidad. Sin embargo, los tiempos de ejecución de las consultas suelen ser prolongados. El conector Oracle de Athena inserta predicados para reducir los datos analizados en la consulta. Los predicados simples y las expresiones complejas se insertan en el conector para reducir la cantidad de datos analizados y disminuir el tiempo de ejecución de las consultas. ### Predicados Un predicado es una expresión de la cláusula `WHERE` de una consulta SQL que da como resultado un valor booleano y filtra las filas en función de varias condiciones. El conector Oracle de Athena puede combinar estas expresiones e insertarlas directamente en Oracle para mejorar la funcionalidad y reducir la cantidad de datos analizados. Los siguientes operadores del conector Oracle de Athena admiten la inserción de predicados: + **Booleano: **AND, OR, NOT. + **Igualdad:** EQUAL, NOT\_EQUAL, LESS\_THAN, LESS\_THAN\_OR\_EQUAL, GREATER\_THAN, GREATER\_THAN\_OR\_EQUAL, IS\_NULL. + **Aritmética: **ADD, SUBTRACT, MULTIPLY, DIVIDE, NEGATE. + **Otros: **LIKE\_PATTERN, IN. ### Ejemplo de inserción combinada Para mejorar las capacidades de consulta, combine los tipos de inserciones, como en el siguiente ejemplo: ``` SELECT * FROM my_table WHERE col_a > 10 AND ((col_a + col_b) > (col_c % col_d)) AND (col_e IN ('val1', 'val2', 'val3') OR col_f LIKE '%pattern%'); ``` ## Consultas de acceso directo El conector de Oracle admite [consultas de acceso directo](federated-query-passthrough.md). Las consultas de acceso directo utilizan una función de tabla para enviar la consulta completa al origen de datos para su ejecución. Para usar consultas de transferencia de datos con Oracle, puede utilizar la siguiente sintaxis: ``` SELECT * FROM TABLE( system.query( query => '{{query string}}' )) ``` El siguiente ejemplo de consulta envía una consulta a un origen de datos de Oracle. La consulta selecciona todas las columnas de la tabla `customer`. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## Información sobre licencias Al usar este conector, reconoce la inclusión de componentes de terceros, cuya lista se puede encontrar en el archivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) para este conector y acepta los términos de las licencias de terceros correspondientes que se proporcionan en el archivo [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) de GitHub.com. ## Recursos adicionales Para obtener la información más reciente sobre la versión del controlador JDBC, consulte el archivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) para el conector de Oracle en GitHub.com. Para obtener más información acerca de este conector, consulte [el sitio correspondiente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle) en GitHub.com.