# 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. 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. **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 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). ## 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](https://opensearch.org/docs/latest/dashboards/im-dashboards/datastream/) na documentação do OpenSearch e [Conceitos básicos de fluxos de dados](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/data-streams.html#data-streams-example) 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 obter mais informações, consulte [Configuração de bancos de dados e tabelas no AWS Glue](#connectors-opensearch-setting-up-databases-and-tables-in-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](https://docs.aws.amazon.com/glue/latest/dg/connection-properties.html) correspondentes. A partir de 3 de dezembro de 2024, use os parâmetros abaixo somente ao [implantar manualmente](connect-data-source-serverless-app-repo.md) uma versão anterior de um conector de fonte de dados do Athena. ### Conexões do Glue (recomendação) Recomendamos que você configure um conector do OpenSearch usando um objeto de conexão do Glue. Para isso, defina a variável de ambiente `glue_connection` do Lambda do conector do OpenSearch 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 OPENSEARCH ``` **Propriedades do ambiente do Lambda** + **glue\$1connection**: especifica o nome da conexão do Glue associada ao conector federado. **nota** Todos os conectores que usam conexões do Glue devem usar o AWS Secrets Manager para armazenar credenciais. O conector do OpenSearch criado usando conexões do Glue não é compatível com o uso de um manipulador de multiplexação. O conector do OpenSearch criado usando conexões do Glue é compatível apenas com o `ConnectionSchemaVersion` 2. ### Conexões legadas + **spill\$1bucket**: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda. + **spill\$1prefix**: (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\$1put\$1request\$1headers**: (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\$1key\$1id**: (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\$1spill\$1encryption**: (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). + **disable\$1glue**: (opcional) se estiver presente e definido como verdadeiro, o conector não tentará recuperar metadados complementares do AWS Glue. + **query\$1timeout\$1cluster**: o tempo limite, em segundos, para consultas de integridade do cluster usadas na geração de verificações paralelas. + **query\$1timeout\$1search**: o tempo limite, em segundos, para consultas de pesquisa usadas na recuperação de documentos de um índice. + **auto\$1discover\$1endpoint**: 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\$1mapping**: 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. O segredo deve ser armazenado no seguinte formato JSON: ``` { "username": "your_username", "password": "your_password" } ``` O conector analisará automaticamente essa estrutura JSON para recuperar as credenciais. **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*. 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\$1do\$1usuário*@*senha*. Embora a senha possa conter sinais `@` incorporados, o primeiro `@` serve como um separador de *nome\$1do\$1usuá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\$1float | BIGINT | SCALED\$1FLOAT(...) | | integer | INT | int | | curto | SMALLINT | smallint | | byte | TINYINT | tinyint | | double | FLOAT8 | double | | float, half\$1float | FLOAT4 | flutuação | | booleano | BIT | booleano | | date, date\$1nanos | DATEMILLI | timestamp | | Estrutura JSON | STRUCT | STRUCT | | \$1meta (para obter mais informações, consulte a seção [Definição de metadados para matrizes no OpenSearch](#connectors-opensearch-defining-metadata-for-arrays-in-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\$1FLOAT(*fator\$1de\$1escala*). 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\$1da\$1funçã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 ``` ## desempenho 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](federated-query-passthrough.md) e usa a linguagem Query DSL. Para obter mais informações sobre consultas com o Query DSL, consulte [Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) na documentação do Elasticsearch ou [Query DSL](https://opensearch.org/docs/latest/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 + 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](https://aws.amazon.com/blogs/big-data/query-data-in-amazon-opensearch-service-using-sql-from-amazon-athena/) no *Blog de Big Data da AWS*. + Para obter mais informações sobre esse conector, visite [o site correspondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-elasticsearch) em GitHub.com.