Conector do Amazon Athena para o OpenSearch - Amazon Athena
Pré-requisitosTermosParâmetrosConfiguração de bancos de dados e tabelas no AWS GlueExecução de consultas de SQLPerformanceConsultas de passagemRecursos adicionais do

Conector do Amazon Athena para o OpenSearch

OpenSearch Service

O conector do OpenSearch no Amazon Athena permite que o Amazon Athena se comunique com suas instâncias do OpenSearch para que você possa usar o SQL para consultar os dados do OpenSearch.

nota

Devido a um problema conhecido, o conector do OpenSearch não pode ser usado com uma VPC.

Se você tiver o Lake Formation habilitado em sua conta, o perfil do IAM para seu conector Lambda federado para Athena que você implantou no AWS Serverless Application Repository deve ter acesso de leitura ao AWS Glue Data Catalog no Lake Formation.

Pré-requisitos

Termos

Os termos a seguir estão relacionados ao conector OpenSearch.

  • Domínio: um nome que esse conector associa ao endpoint da sua instância do OpenSearch. O domínio também é usado como nome do banco de dados. Para instâncias do OpenSearch definidas no Amazon OpenSearch Service, o domínio é detectável automaticamente. Para outras instâncias, você deve fornecer um mapeamento entre o nome de domínio e o endpoint.

  • Índice: uma tabela de banco de dados definida em sua instância do OpenSearch.

  • Mapeamento: se um índice for uma tabela de banco de dados, o mapeamento será seu esquema (ou seja, as definições de seus campos e atributos).

    Esse conector oferece suporte à recuperação de metadados da instância do OpenSearch e do AWS Glue Data Catalog. Se o conector encontrar um banco de dados e tabela do AWS Glue que correspondam aos nomes de domínio e índice do OpenSearch, o conector tentará usá-los para definição de esquema. Recomendamos que você crie sua tabela do AWS Glue para que seja um superconjunto de todos os campos em seu índice do OpenSearch.

  • Documento: um registro em uma tabela do banco de dados.

  • Fluxo de dados: dados baseados em tempo que são compostos por vários índices de apoio. Para obter mais informações, consulte Fluxos de dados na documentação do OpenSearch e Conceitos básicos de fluxos de dados no Guia do desenvolvedor do Amazon OpenSearch Service.

    nota

    Como os índices do fluxo de dados são criados e gerenciados internamente pelo OpenSearch, o conector escolhe o mapeamento do esquema com base no primeiro índice disponível. Por isso, é altamente recomendável configurar uma tabela do AWS Glue como fonte suplementar de metadados. Para ter mais informações, consulte Configuração de bancos de dados e tabelas no AWS Glue.

Parâmetros

Use as variáveis de ambiente do Lambda nesta seção para configurar o conector OpenSearch.

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

  • disable_glue: (opcional) se estiver presente e definido como verdadeiro, o conector não tentará recuperar metadados complementares do AWS Glue.

  • query_timeout_cluster: o tempo limite, em segundos, para consultas de integridade do cluster usadas na geração de verificações paralelas.

  • query_timeout_search: o tempo limite, em segundos, para consultas de pesquisa usadas na recuperação de documentos de um índice.

  • auto_discover_endpoint: booleano. O padrão é true. Quando você usar o Amazon OpenSearch Service e definir esse parâmetro como verdadeiro, o conector poderá descobrir automaticamente seus domínios e endpoints chamando as operações de API de descrição ou lista apropriadas no OpenSearch Service. Para qualquer outro tipo de instância do OpenSearch (por exemplo, auto-hospedada), você deverá especificar os endpoints de domínio associados na variável domain_mapping. Se auto_discover_endpoint=true, o conector usará credenciais da AWS para se autenticar no OpenSearch Service. Caso contrário, o conector recuperará as credenciais de nome de usuário e senha do AWS Secrets Manager por meio da variável domain_mapping.

  • domain_mapping: usado somente quando auto_discover_endpoint for definido como falso, e estabelece o mapeamento entre nomes de domínio e seus endpoints associados. A variável domain_mapping pode acomodar vários endpoints do OpenSearch no formato a seguir:

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

    Para fins de autenticação em um endpoint do OpenSearch, o conector oferece suporte a strings de substituição injetadas usando o formato ${SecretName}: com nome de usuário e senha recuperados do AWS Secrets Manager. Os dois pontos (:) no final da expressão servem como separador do resto do endpoint.

    Importante

    Como prática recomendada de segurança, não use credenciais codificadas 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.

    O exemplo a seguir usa o segredo opensearch-creds.

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

    Em runtime, ${opensearch-creds} será renderizado como nome de usuário e senha, como no exemplo a seguir.

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

    No parâmetro domain_mapping, cada par de domínio e endpoint pode usar um segredo diferente. O segredo em si deve ser especificado no formato nome_do_usuário@senha. Embora a senha possa conter sinais @ incorporados, o primeiro @ serve como um separador de nome_do_usuário.

    Também é importante observar que a vírgula (,) e o sinal de igual (=) são usados por esse conector como separadores para os pares de endpoints do domínio. Por esse motivo, você não deve usá-los em nenhum lugar do segredo armazenado.

Configuração de bancos de dados e tabelas no AWS Glue

O conector obtém informações de metadados usando o AWS Glue ou o OpenSearch. É possível configurar uma tabela do AWS Glue como fonte de definição de metadados complementar. Para ativar esse recurso, defina um banco de dados do AWS Glue e uma tabela que correspondam ao domínio e ao índice da fonte que você está complementando. O conector também pode aproveitar as definições de metadados armazenadas na instância do OpenSearch recuperando o mapeamento para o índice especificado.

Definição de metadados para matrizes no OpenSearch

O OpenSearch não tem um tipo de dados de matriz dedicado. Qualquer campo pode conter zero ou mais valores, desde que sejam do mesmo tipo de dados. Se você quiser usar o OpenSearch como sua fonte de definição de metadados, você deve definir uma propriedade _meta para todos os índices usados com o Athena para os campos que devam ser considerados uma lista ou matriz. Se você não conseguir concluir essa etapa, as consultas retornarão somente o primeiro elemento no campo da lista. Quando você especificar a propriedade _meta, os nomes dos campos deverão ser totalmente qualificados para estruturas JSON aninhadas (por exemplo, address.street, em que street é um campo aninhado dentro de uma estrutura address).

O exemplo a seguir define as listas actor e genre na tabela movies.

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

Tipos de dados

O conector OpenSearch pode extrair definições de metadados do AWS Glue ou da instância do OpenSearch. O conector usa o mapeamento na tabela a seguir para converter as definições em tipos de dados do Apache Arrow, incluindo os pontos indicados na seção a seguir.

OpenSearch Apache Arrow AWS Glue
text, keyword, binary VARCHAR string
longo BIGINT bigint
scaled_float BIGINT SCALED_FLOAT(...)
inteiro INT int
curto SMALLINT smallint
byte TINYINT tinyint
double FLOAT8 double
float, half_float FLOAT4 float
boolean BIT boolean
date, date_nanos DATEMILLI timestamp
Estrutura JSON STRUCT STRUCT
_meta (para obter mais informações, consulte a seção Definição de metadados para matrizes no OpenSearch.) LIST ARRAY

Notas sobre tipos de dados

  • No momento, o conector oferece suporte somente os tipos de dados do OpenSearch e do AWS Glue listados na tabela anterior.

  • Um scaled_float é um número de ponto flutuante escalado por um fator fixo de escala dupla e representado como um BIGINT no Apache Arrow. Por exemplo, 0,756 com um fator de escala de 100 é arredondado para 76.

  • Para definir um scaled_float no AWS Glue, você deverá selecionar o tipo de coluna array e declarar o campo usando o formato SCALED_FLOAT(fator_de_escala).

    Os exemplos a seguir são válidos:

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

    Os exemplos a seguir não são válidos:

    SCALED_FLOAT(10.) 
SCALED_FLOAT(.5)

  • Ao converter de date_nanos para DATEMILLI, os nanossegundos serão arredondados para o milissegundo mais próximo. Valores válidos para date e date_nanos incluem, entre outros, os seguintes formatos:

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

  • Um binary do OpenSearch é uma representação de string de um valor binário codificado usando Base64, e é convertido em um VARCHAR.

Execução de consultas de SQL

Veja a seguir exemplos de consultas DDL que você pode usar com esse conector. Nos exemplos, nome_da_função corresponde ao nome da função do Lambda domínio é o nome do domínio que você deseja consultar e índice é o nome do seu índice.

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

Performance

O conector OpenSearch do Athena oferece suporte a verificações paralelas baseadas em fragmentos. O conector usa as informações de integridade do cluster recuperadas da instância do OpenSearch para gerar várias solicitações para uma consulta de pesquisa de documentos. As solicitações são divididas para cada fragmento e executadas simultaneamente.

O conector também reduz os predicados como parte de suas consultas de pesquisa de documentos. O exemplo de consulta e predicado a seguir mostra como o conector usa a redução de predicado.

Consulta

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 passagem

O conector OpenSearch é compatível com consultas de passagem e usa a linguagem Query DSL. Para obter mais informações sobre consultas com o Query DSL, consulte Query DSL na documentação do Elasticsearch ou Query DSL na documentação do OpenSearch.

Para usar as consultas de passagem com o conector OpenSearch, use a seguinte sintaxe:

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

O seguinte exemplo de consulta de passagem do OpenSearch filtra funcionários com status de emprego ativo no índice employee do esquema default.

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

Recursos adicionais do