# Conector do Amazon Athena para Oracle O conector do Amazon Athena para Oracle permite que o Amazon Athena execute consultas SQL em dados armazenados no Oracle em execução on-premises, no Amazon EC2 ou no Amazon RDS. Você também pode usar o conector para consultar dados no [Oracle Exadata](https://www.oracle.com/engineered-systems/exadata/). Esse conector pode ser registrado como um catálogo federado no Glue Data Catalog. Ele é compatível com controles de acesso a dados definidos no Lake Formation nos níveis de catálogo, banco de dados, tabela, coluna, linha e tag. Esse conector usa o Glue Connections para centralizar as propriedades de configuração no Glue. ## Pré-requisitos + Implante o conector na sua Conta da AWS usando o console do Athena ou o AWS Serverless Application Repository. Para ter mais informações, consulte [Criar uma conexão de fonte de dados](connect-to-a-data-source.md) ou [Usar o AWS Serverless Application Repository para implantar um conector de fonte de dados](connect-data-source-serverless-app-repo.md). ## Limitações + Não há suporte para operações de gravação de DDL. + Em uma configuração de multiplexador, o prefixo e o bucket de derramamento são compartilhados em todas as instâncias do banco de dados. + Quaisquer limites relevantes do Lambda. Para obter mais informações, consulte [Cotas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html) no *Guia do desenvolvedor do AWS Lambda*. + Há suporte somente à versão 12.1.0.2 do Oracle Databases. + Se o conector do Oracle não usar uma conexão do Glue, os nomes do banco de dados, da tabela e da coluna serão convertidos em maiúsculas pelo conector. Se o conector do Oracle usar uma conexão do Glue, os nomes do banco de dados, da tabela e da coluna não serão convertidos em maiúsculas pelo conector. Para alterar esse comportamento de maiúsculas e minúsculas, altere o Lambda pela variável de ambiente `casing_mode` para `upper` ou `lower` conforme necessário. Um conector Oracle usando uma conexão do Glue não é compatível com o uso de um manipulador de multiplexação. + Quando o Oracle `NUMBER` for usado sem Precisão e Escala definidos, o Athena irá tratá-lo como `BIGINT`. Para obter as casas decimais necessárias no Athena, especifique `default_scale=<{{number of decimal places}}>` nas variáveis de ambiente da sua função do Lambda. ## Termos Os termos a seguir estão relacionados ao conector Oracle. + **Instância do banco de dados**: qualquer instância de um banco de dados implantado on-premises, no Amazon EC2 ou no Amazon RDS. + **Manipulador**: um manipulador Lambda que acessa sua instância de banco de dados. Um manipulador pode ser para metadados ou para registros de dados. + **Manipulador de metadados**: um manipulador Lambda que recupera metadados da sua instância de banco de dados. + **Manipulador de registros**: um manipulador Lambda que recupera registros de dados da sua instância de banco de dados. + **Manipulador composto**: um manipulador Lambda que recupera tanto metadados quanto registros de dados da sua instância de banco de dados. + **Propriedade ou parâmetro**: uma propriedade do banco de dados usada pelos manipuladores para extrair informações do banco de dados. Você configura essas propriedades como variáveis de ambiente do Lambda. + **String de conexão**: uma string de texto usada para estabelecer uma conexão com uma instância de banco de dados. + **Catálogo**: um catálogo não AWS Glue registrado no Athena que é um prefixo obrigatório para a propriedade `connection_string`. + **Manipulador de multiplexação**: um manipulador Lambda que pode aceitar e usar várias conexões de banco de dados. ## Parâmetros Use os parâmetros nesta seção para configurar o conector do Oracle. ### Conectores federados do AWS Glue Data Catalog Recomendamos que você configure um conector do Oracle usando um objeto de conexões do Glue. Para tal, defina a variável de ambiente `glue_connection` do Lambda do conector Oracle como o nome da conexão do Glue a ser usada. **Propriedades das conexões do Glue** Use o comando apresentado a seguir para obter o esquema de um objeto de conexão do Glue. Esse esquema contém todos os parâmetros que você pode usar para controlar a conexão. ``` aws glue describe-connection-type --connection-type ORACLE ``` **Propriedades do ambiente do Lambda** As propriedades do ambiente do Lambda a seguir se aplicam somente quando você usa o conector com uma função do Lambda em sua conta. + **glue\_connection**: especifica o nome da conexão do Glue associada ao conector federado. + **is\_fips\_enabled**: (opcional) defina como true quando o modo FIPS estiver habilitado. O padrão é falso. + **casing\_mode** (Opcional): especifica como lidar com maiúsculas e minúsculas para nomes de esquemas e tabelas. O parâmetro `casing_mode` usa os seguintes valores para especificar o comportamento do mapeamento de maiúsculas e minúsculas: + **lower**: converte para minúsculas todos os nomes de esquema e tabela fornecidos. Esse é o padrão para conectores que têm uma conexão do Glue associada. + **upper**: converte para maiúsculas todos os nomes de esquema e tabela fornecidos. Esse é o padrão para conectores que não têm uma conexão do Glue associada. + **case\_insensitive\_search**: executa pesquisas sem diferenciar maiúsculas de minúsculas em nomes de esquemas e tabelas no Oracle. Use esse valor se sua consulta contiver nomes de esquema ou tabela que não correspondam ao padrão de maiúsculas e minúsculas do seu conector. **nota** Todos os conectores que usam a conexão federada do AWS Glue Data Catalog devem usar o AWS Secrets Manager para armazenar as credenciais. O conector para Oracle criado por meio de uma conexão federada do AWS Glue Data Catalog não é compatível com o uso de um manipulador de multiplexação. O conector para Oracle criado por meio de uma conexão federada do AWS Glue Data Catalog é compatível apenas com `ConnectionSchemaVersion` 2. ### Conectores federados do catálogo de dados do Athena **nota** Os conectores de fonte de dados do Athena criados a partir de 3 de dezembro de 2024 usam conexões do AWS Glue. Os nomes dos parâmetros e suas definições listados abaixo referem-se a conectores de fonte de dados do Athena criados sem uma conexão do Glue associada. Os parâmetros apresentados abaixo devem ser usados somente quando você [implantar manualmente](connect-data-source-serverless-app-repo.md) uma versão anterior de um conector de fonte de dados do Athena ou quando a propriedade de ambiente `glue_connection` não for especificada. **Propriedades do ambiente do Lambda** + **default**: uma string de conexão JDBC a ser usada para conexão com a instância do banco de dados Oracle. Por exemplo, ., `oracle://${jdbc_connection_string}` + **catalog\_connection\_string**: usada pelo manipulador de multiplexação (não compatível com o uso de uma conexão do Glue). Uma string de conexão de instância de banco de dados. Prefixe a variável de ambiente com o nome do catálogo usado no Athena. Por exemplo, se o catálogo registrado no Athena for myoraclecatalog, então o nome da variável de ambiente será myoraclecatalog\_connection\_string. + **spill\_bucket**: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda. + **spill\_prefix**: (opcional) assume como padrão uma subpasta no `spill_bucket` especificado chamado `athena-federation-spill`. Recomendamos que você configure um [ciclo de vida de armazenamento](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) do Amazon S3 neste local para excluir derramamentos anteriores a um número predeterminado de dias ou horas. + **spill\_put\_request\_headers**: (opcional) um mapa codificado em JSON de cabeçalhos e valores de solicitações para a solicitação `putObject` do Amazon S3 usada para o derramamento (por exemplo, `{"x-amz-server-side-encryption" : "AES256"}`). Para outros cabeçalhos possíveis, consulte [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) na *Referência da API do Amazon Simple Storage Service*. + **kms\_key\_id**: (opcional) por padrão, todos os dados transmitidos para o Amazon S3 são criptografados usando o modo de criptografia autenticado AES-GCM e uma chave gerada aleatoriamente. Para que sua função do Lambda use chaves de criptografia mais fortes geradas pelo KMS, como `a7e63k4b-8loc-40db-a2a1-4d0en2cd8331`, é possível especificar um ID de chave do KMS. + **disable\_spill\_encryption**: (opcional) quando definido como `True`, desativa a criptografia do derramamento. É padronizado como `False`, para que os dados transmitidos para o S3 sejam criptografados usando o AES-GCM — usando uma chave gerada aleatoriamente ou o KMS para gerar chaves. Desativar a criptografia do derramamento pode melhorar a performance, especialmente se o local do derramamento usar [criptografia no lado do servidor](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). + **is\_fips\_enabled**: (opcional) defina como true quando o modo FIPS estiver habilitado. O padrão é falso. + **casing\_mode** (Opcional): especifica como lidar com maiúsculas e minúsculas para nomes de esquemas e tabelas. O parâmetro `casing_mode` usa os seguintes valores para especificar o comportamento do mapeamento de maiúsculas e minúsculas: + **lower**: converte para minúsculas todos os nomes de esquema e tabela fornecidos. Esse é o padrão para conectores que têm uma conexão do Glue associada. + **upper**: converte para maiúsculas todos os nomes de esquema e tabela fornecidos. Esse é o padrão para conectores que não têm uma conexão do Glue associada. + **case\_insensitive\_search**: executa pesquisas sem diferenciar maiúsculas de minúsculas em nomes de esquemas e tabelas no Oracle. Use esse valor se sua consulta contiver nomes de esquema ou tabela que não correspondam ao padrão de maiúsculas e minúsculas do seu conector. #### String de conexão Use uma string de conexão JDBC no seguinte formato para se conectar a uma instância de banco de dados. ``` oracle://${{{jdbc_connection_string}}} ``` **nota** Se sua senha contiver caracteres especiais (por exemplo, `some.password`), coloque-a entre aspas duplas quando passá-la para a string de conexão (por exemplo, `"some.password"`). Não fazê-lo pode resultar em um erro de URL inválido especificado. #### Uso de um único manipulador de conexão É possível usar os seguintes metadados de conexão única e manipuladores de registros para se conectar a uma única instância do Oracle. **** | Tipo de manipulador | Classe | | --- | --- | | Manipulador composto | OracleCompositeHandler | | Manipulador de metadados | OracleMetadataHandler | | Manipulador de registros | OracleRecordHandler | ##### Parâmetros do manipulador de conexão única **** | Parâmetro | Descrição | | --- | --- | | default | Obrigatório. A string de conexão padrão. | | IsFIPSEnabled | Opcional. Definido como true quando o modo FIPS estiver ativado. O padrão é false. | Os manipuladores de conexão únicos oferecem suporte a uma instância de banco de dados e devem fornecer um parâmetro de string de conexão `default`. Todas as outras strings de conexão são ignoradas. O conector oferece suporte a conexões baseadas em SSL a instâncias do Amazon RDS. O suporte é limitado ao protocolo Transport Layer Security (TLS) e à autenticação do servidor pelo cliente. Não há suporte para a autenticação mútua no Amazon RDS. A segunda linha na tabela abaixo mostra a sintaxe para o uso de SSL. O exemplo de propriedade a seguir é para uma única instância do Oracle com suporte em uma função do Lambda. **** | Propriedade | 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=))) | #### Fornecimento de credenciais Para fornecer um nome de usuário e uma senha para seu banco de dados na string de conexão JDBC, é possível usar as propriedades da string de conexão ou o AWS Secrets Manager. + **String de conexão**: um nome de usuário e uma senha podem ser especificados como propriedades na string de conexão do JDBC. **Importante** Como prática recomendada de segurança, não use credenciais com codificação rígida em suas variáveis de ambiente ou strings de conexão. Para obter informações sobre como mover seus segredos codificados para o AWS Secrets Manager, consulte [Mover segredos codificados para o AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/hardcoded.html) no *Guia do usuário do AWS Secrets Manager*. + **AWS Secrets Manager**: para usar o recurso Athena Federated Query com o AWS Secrets Manager, a VPC conectada à sua função do Lambda deve ter [acesso à Internet](https://aws.amazon.com/premiumsupport/knowledge-center/internet-access-lambda-function/) ou um [endpoint da VPC](https://docs.aws.amazon.com/secretsmanager/latest/userguide/vpc-endpoint-overview.html) para se conectar ao Secrets Manager. É possível colocar o nome de um segredo no AWS Secrets Manager na sua string de conexão JDBC. O conector substitui o nome secreto pelos valores de `username` e `password` do Secrets Manager. Para instâncias de banco de dados do Amazon RDS, esse suporte é totalmente integrado. Se você usa o Amazon RDS, é altamente recomendável usar o AWS Secrets Manager e rotação de credenciais. Se seu banco de dados não usar o Amazon RDS, armazene as credenciais em JSON no seguinte formato: ``` {"username": "${username}", "password": "${password}"} ``` **nota** Se sua senha contiver caracteres especiais (por exemplo, `some.password`), coloque-a entre aspas duplas quando armazená-la no Secrets Manager (por exemplo, `"some.password"`). Não fazê-lo pode resultar em um erro de URL inválido especificado. **Exemplo de string de conexão com nome secreto** A string a seguir tem o nome secreto `${Test/RDS/Oracle}`. ``` oracle://jdbc:oracle:thin:${Test/RDS/Oracle}@//hostname:port/servicename ``` O conector usa o nome secreto para recuperar segredos e fornecer o nome de usuário e a senha, como no exemplo a seguir. ``` oracle://jdbc:oracle:thin:username/password@//hostname:port/servicename ``` Atualmente, o conector Oracle reconhece as propriedades `UID` e `PWD` do JDBC. #### Uso de um manipulador de multiplexação É possível usar um multiplexador para se conectar a várias instâncias de banco de dados com uma única função do Lambda. As solicitações são encaminhadas por nome do catálogo. Use as seguintes classes no Lambda. **** | Manipulador | Classe | | --- | --- | | Manipulador composto | OracleMuxCompositeHandler | | Manipulador de metadados | OracleMuxMetadataHandler | | Manipulador de registros | OracleMuxRecordHandler | ##### Parâmetros do manipulador de multiplexação **** | Parâmetro | Descrição | | --- | --- | | ${{catalog}}\_connection\_string | Obrigatório. Uma string de conexão de instância de banco de dados. Prefixe a variável de ambiente com o nome do catálogo usado no Athena. Por exemplo, se o catálogo registrado no Athena for myoraclecatalog, então o nome da variável de ambiente será myoraclecatalog\_connection\_string. | | default | Obrigatório. A string de conexão padrão. Essa string é usada quando o catálogo for lambda:${{{AWS\_LAMBDA\_FUNCTION\_NAME}}}. | As propriedades de exemplo a seguir são para uma função do Lambda MUX do Oracle que ofereça suporte a duas instâncias de banco de dados: `oracle1` (o padrão) e `oracle2`. **** | Propriedade | 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 | ## Suporte ao tipo de dados A tabela a seguir mostra os correspondentes tipos de dados do JDBC, do Oracle e do Arrow. **** | JDBC | Oracle | Arrow | | --- | --- | --- | | Booleano | booleano | Bit | | Inteiro | N/D | Tiny | | Short | smallint | Smallint | | Inteiro | integer | Int | | Longo | bigint | Bigint | | flutuação | float4 | Float4 | | Duplo | float8 | Float8 | | Data | date | Data/Dia | | Timestamp | timestamp | Date Milli | | String | texto | Varchar | | Bytes | bytes | Varbinary | | BigDecimal | numeric(p,s) | Decimal | | ARRAY | N/D (ver nota) | Lista | ## Partições e divisões As partições são usadas para determinar como gerar divisões para o conector. O Athena constrói uma coluna sintética do tipo `varchar` que representa o esquema de particionamento da tabela para ajudar o conector a gerar divisões. O conector não modifica a definição real da tabela. ## desempenho O Oracle oferece suporte a partições nativas. O conector do Athena para o Oracle pode recuperar dados dessas partições em paralelo. Se você quiser consultar conjuntos de dados muito grandes com distribuição uniforme de partições, o particionamento nativo é altamente recomendado. A seleção de um subconjunto de colunas acelera o runtime da consulta e reduz os dados verificados de forma significativa. O conector Oracle é resiliente ao controle de utilização devido à simultaneidade. No entanto, os tempos de execução das consultas tendem a ser longos. O conector do Athena para Oracle realiza a passagem direta de predicados para diminuir os dados examinados pela consulta. Predicados simples e expressões complexas são passados diretamente ao conector para reduzir a quantidade de dados examinados e o runtime de execução da consulta. ### Predicados Um predicado é uma expressão na cláusula `WHERE` de uma consulta SQL, que avalia para um valor booleano e filtra as linhas com base em várias condições. O conector do Athena para o Oracle pode combinar essas expressões e passá-las diretamente ao Oracle para melhorar a funcionalidade e reduzir a quantidade de dados examinados. Os seguintes operadores do conector do Athena para o Oracle são compatíveis com a passagem de predicados: + **Booleanos:** E, OU, NÃO + **Igualdade: **EQUAL, NOT\_EQUAL, LESS\_THAN, LESS\_THAN\_OR\_EQUAL, GREATER\_THAN, GREATER\_THAN\_OR\_EQUAL, IS\_NULL + **Aritméticos:** ADICIONAR, SUBTRAIR, MULTIPLICAR, DIVIDIR,  NEGAR + **Outros:**LIKE\_PATTERN, IN ### Exemplo de passagem direta combinada Para ter recursos aprimorados de consulta, combine os tipos de passagem direta, como no seguinte exemplo: ``` 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 passagem O conector Oracle é compatível com [consultas de passagem](federated-query-passthrough.md). As consultas de passagem usam uma função de tabela para enviar sua consulta completa para execução na fonte de dados. Para usar consultas de passagem com o Oracle, você pode empregar a seguinte sintaxe: ``` SELECT * FROM TABLE( system.query( query => '{{query string}}' )) ``` O exemplo de consulta a seguir envia uma consulta para uma fonte de dados no Oracle. A consulta seleciona todas as colunas na tabela `customer`. ``` SELECT * FROM TABLE( system.query( query => 'SELECT * FROM customer' )) ``` ## Informações de licença Ao usar esse conector, você reconhece a inclusão de componentes de terceiros, cuja lista pode ser encontrada no arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) desse conector, e concorda com os termos das respectivas licenças de terceiros fornecidas no arquivo [LICENSE.txt](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/LICENSE.txt) em GitHub.com. ## Recursos adicionais Para obter as informações mais recentes sobre a versão do driver JDBC, consulte o arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-oracle/pom.xml) do conector Oracle em GitHub.com. Para obter mais informações sobre esse conector, visite [o site correspondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-oracle) em GitHub.com.