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.
Esse conector não pode ser registrado como um catálogo federado no Glue Data Catalog. Esse conector não é 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.
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
Implante o conector na sua Conta da AWS usando o console do Athena ou o AWS Serverless Application Repository. Para obter mais informações, consulte Criar uma conexão de fonte de dados ou Usar o AWS Serverless Application Repository para implantar um conector de fonte de dados.
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 os parâmetros nesta seção para configurar o conector do OpenSearch.
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 e definições dos parâmetros listados abaixo são para conectores de fonte de dados do Athena criados antes de 3 de dezembro de 2024. Eles podem diferir de suas propriedades de conexão do AWS Glue correspondentes. A partir de 3 de dezembro de 2024, use os parâmetros abaixo somente ao implantar manualmente uma versão anterior de um conector de fonte de dados do Athena.
-
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 chamadoathena-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 comoFalse
, 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áveldomain_mapping
. Seauto_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áveldomain_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áveldomain_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 formatonome_do_usuário
@senha
. Embora a senha possa conter sinais@
incorporados, o primeiro@
serve como um separador denome_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 umBIGINT
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 colunaarray
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
paraDATEMILLI
, os nanossegundos serão arredondados para o milissegundo mais próximo. Valores válidos paradate
edate_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 usandoBase64
, e é convertido em umVARCHAR
.
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
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
-
Para ver um artigo sobre o uso do conector Amazon Athena OpenSearch para consultar dados no Amazon OpenSearch Service e no Amazon S3 em uma única consulta, consulte Consulte dados no Amazon OpenSearch Service usando SQL do Amazon Athena
no AWSBlog de Big Data. Para obter mais informações sobre esse conector, visite o site correspondente
em GitHub.com.