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.

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

Limitações

Termos

Parâmetros

Use os parâmetros nesta seção para configurar o conector do Oracle.

Glue connections (recommended)

Recomendamos que você configure um conector 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

• 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

Um conector Oracle criado usando conexões do Glue não é compatível com o uso de um manipulador de multiplexação.

Legacy connections

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 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 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 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.

• 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

Parameter	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=<HOST_NAME>)(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 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 ou um endpoint da VPC 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

Parameter	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.

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.

Performance

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:

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. 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 desse conector, e concorda com os termos das respectivas licenças de terceiros fornecidas no arquivo 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 do conector Oracle em GitHub.com.

Para obter mais informações sobre esse conector, visite o site correspondente em GitHub.com.