# Consultar com funções definidas pelo usuário As funções definidas pelo usuário (UDFs) no Amazon Athena permitem criar funções personalizadas para processar registros ou grupos de registros. Uma UDF aceita parâmetros, executa o trabalho e retorna um resultado. Para usar uma UDF no Athena, escreva uma cláusula `USING EXTERNAL FUNCTION` antes de uma instrução `SELECT` em uma consulta SQL. A instrução `SELECT` faz referência à UDF e define as variáveis que são passadas para a UDF quando a consulta é executada. A consulta SQL invoca uma função do Lambda usando o runtime Java ao chamar a UDF. As UDFs são definidas dentro da função do Lambda como métodos em um pacote de implantação Java. É possível definir várias UDFs no mesmo pacote de implantação Java para uma função do Lambda. Você também especifica o nome da função do Lambda na cláusula `USING EXTERNAL FUNCTION`. Você tem duas opções para implantar uma função do Lambda para UDFs do Athena. É possível implantar a função diretamente no Lambda ou usar o AWS Serverless Application Repository. Para encontrar as funções do Lambda existentes para UDFs, pesquise no AWS Serverless Application Repository público ou em seu repositório privado e implante-as no Lambda. Você também pode criar ou modificar o código-fonte Java, empacotá-lo em um arquivo JAR e implantá-lo usando o Lambda ou o AWS Serverless Application Repository. Para ver exemplos de código-fonte e pacotes Java para você começar, consulte [Criar e implantar uma UDF com o Lambda](udf-creating-and-deploying.md). Para obter mais informações sobre o Lambda, consulte o [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). Consulte mais informações sobre o AWS Serverless Application Repository no [Guia do desenvolvedor do AWS Serverless Application Repository](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/). Para ver um exemplo que usa UDFs com o Athena para traduzir e analisar texto, consulte o artigo no blog do Machine Learning da AWS: [Traduzir e analisar texto usando funções SQL com Amazon Athena, Amazon Translate e Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) (em inglês) ou assista a [video](udf-videos.md#udf-videos-xlate). Para ver um exemplo de uso de UDFs para estender consultas geoespaciais no Amazon Athena, consulte [Estenda consultas geoespaciais no Amazon Athena com UDFs e AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) no *Blog de Big Data da AWS*. **Topics** + [Vídeos sobre UDFs no Athena](udf-videos.md) + [Considerações e limitações](udf-considerations-limitations.md) + [Consultar com uso da sintaxe de consulta de UDFs](udf-query-syntax.md) + [Criar e implantar uma UDF com o Lambda](udf-creating-and-deploying.md) # Vídeos sobre UDFs no Athena Assista aos vídeos a seguir para saber mais como usar as UDFs no Athena. **Vídeo: Apresentação das funções definidas pelo usuário (UDFs) no Amazon Athena** O vídeo a seguir mostra como você pode usar as UDFs no Amazon Athena para editar informações confidenciais. **nota** A sintaxe neste vídeo é pré-lançamento, mas os conceitos são os mesmos. Usar o Athena sem o grupo de trabalho `AmazonAthenaPreviewFunctionality`. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/AxJ6jP4Pfmo/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/AxJ6jP4Pfmo) **Vídeo: Traduzir, analisar e editar campos de texto usando consultas SQL no Amazon Athena** O vídeo a seguir mostra como você pode usar as UDFs no Amazon Athena junto com outros Serviços da AWS para traduzir e analisar texto. **nota** A sintaxe neste vídeo é pré-lançamento, mas os conceitos são os mesmos. Para obter a sintaxe correta, consulte a publicação relacionada no blog: [Traduzir, editar e analisar texto usando funções SQL com Amazon Athena, Amazon Translate e Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) (em inglês) no *blog do Machine Learning da AWS*. [![AWS Videos](http://img.youtube.com/vi/https://www.youtube.com/embed/Od7rXG-WMO4/0.jpg)](http://www.youtube.com/watch?v=https://www.youtube.com/embed/Od7rXG-WMO4) # Considerações e limitações Considere os seguintes pontos ao usar funções definidas pelo usuário (UDFs) no Athena. + **Funções integradas do Athena**: as funções integradas no Athena são desenvolvidas para ter alta performance. Recomendamos usar as funções integradas em lugar das UDFs quando possível. Para obter mais informações sobre funções integradas, consulte [Funções no Amazon Athena](functions.md). + **Somente UDFs escalares**: o Athena aceita somente UDFs escalares, que processam uma linha por vez e retornam um único valor de coluna. O Athena passa um lote de linhas, possivelmente em paralelo, para a UDF sempre que invoca o Lambda. Ao desenvolver UDFs e consultas, esteja ciente do possível impacto desse processamento no tráfego de rede. + **As funções do manipulador UDF usam o formato abreviado**: use o formato abreviado (não o formato completo), para suas funções UDF (por exemplo, `package.Class` em vez de `package.Class::method`). + **Os métodos UDF devem estar em letras minúsculas**: os métodos UDF devem estar em letras minúsculas. Não é permitida a combinação de maiúsculas e minúsculas. + **Os métodos UDF exigem parâmetros**: os métodos UDF devem ter pelo menos um parâmetro de entrada. A tentativa de invocar um UDF definido sem parâmetros de entrada causa uma exceção de runtime. Os UDFs são destinados a executar funções em registros de dados, mas um UDF sem argumentos não recebe dados, então ocorre uma exceção. + **Suporte ao runtime do Java**: atualmente, as UDFs do Athena são compatíveis com os runtimes do Java 8, Java 11 e Java 17 para o Lambda. Para obter mais informações, consulte [Construir funções do Lambda com Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) no *Guia do desenvolvedor do AWS Lambda*. **nota** Para o Java 17, você deve definir o valor da variável `JAVA_TOOL_OPTIONS` do ambiente como `--add-opens=java.base/java.nio=ALL-UNNAMED` em seu Lambda. + **Permissões do IAM**: para executar e criar instruções de consulta de UDF no Athena, o principal do IAM que executa a consulta deve ter permissão para executar ações além das funções do Athena. Para obter mais informações, consulte [Permitir acesso a UDFs do Athena: exemplos de políticas](udf-iam-access.md). + **Cotas do Lambda**: as cotas do Lambda se aplicam às UDFs. Para obter mais informações, consulte [Cotas do Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) no *Guia do desenvolvedor do AWS Lambda*. + **Filtragem em nível de linha** – A filtragem em nível de linha do Lake Formation não é compatível com UDFs. + **Visualizações**: não é possível usar visualizações com UDFs. + **Problemas conhecidos**: para acessar a lista mais recente de problemas conhecidos, consulte [Limitations and issues](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) (Limitações e problemas) na seção awslabs/aws-athena-query-federation do GitHub. # Consultar com uso da sintaxe de consulta de UDFs A cláusula `USING EXTERNAL FUNCTION` especifica uma UDF ou várias UDFs que podem ser referenciadas por uma instrução `SELECT` subsequente na consulta. Você precisa do nome do método da UDF e do nome da função do Lambda que hospeda a UDF. No lugar do nome da função do Lambda, você pode usar o ARN do Lambda. Em cenários entre contas, o ARN do Lambda é obrigatório. ## Resumo ``` USING EXTERNAL FUNCTION UDF_name(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN' [, EXTERNAL FUNCTION UDF_name2(variable1 data_type[, variable2 data_type][,...]) RETURNS data_type LAMBDA 'lambda_function_name_or_ARN'[,...]] SELECT [...] UDF_name(expression) [, UDF_name2(expression)] [...] ``` ## Parâmetros **USING EXTERNAL FUNCTION *UDF\$1name*(*variable1* *data\$1type*[, *variable2* *data\$1type*][,...])** *UDF\$1name* especifica o nome da UDF, que deve corresponder a um método Java com a função do Lambda referenciada. Cada *variable data\$1type* especifica uma variável nomeada e o tipo de dados correspondente que a UDF aceita como entrada. O *data\$1type* deve ser um dos tipos de dados do Athena permitidos listados na tabela a seguir e mapear para o tipo de dados Java correspondente. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/athena/latest/ug/udf-query-syntax.html) **RETURNS *tipo\$1dados*** `data_type`O especifica o tipo de dados SQL que a UDF retorna como saída. Os tipos de dados do Athena listados na tabela acima são permitidos. Para o tipo de dados `DECIMAL`, use a sintaxe `RETURNS DECIMAL(precision, scale)` em que *precision* e *scale* são inteiros. **LAMBDA '*lambda\$1function*'** *lambda\$1function* especifica o nome da função do Lambda que será invocada ao executar a UDF. **SELECT [...] *UDF\$1name*(*expression*) [...]** A consulta `SELECT` que passa os valores para a UDF e retorna um resultado. *UDF\$1name* especifica a UDF que será usada, seguida de uma *expressão* que é avaliado para passar os valores. Os valores que são passados e retornados devem coincidir com os tipos de dados correspondentes especificados para a UDF na cláusula `USING EXTERNAL FUNCTION`. ### Exemplos Para ver exemplos de consultas baseadas no código [AthenaUDFHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/src/main/java/com/amazonaws/athena/connectors/udfs/AthenaUDFHandler.java) no GitHub, consulte a página [Amazon Athena UDF Connector](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) (Conector de UDF do Amazon Athena). # Criar e implantar uma UDF com o Lambda Para criar uma UDF personalizada, crie uma nova classe Java ao estender a classe `UserDefinedFunctionHandler`. O código-fonte para [UserDefinedFunctionHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java) no SDK está disponível no GitHub no [repositório](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) awslabs/aws-athena-query-federation/athena-federation-sdk, junto com um [exemplo de implementações de UDF](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) que você pode analisar e modificar para criar uma UDF personalizada. As etapas nessa seção demonstram a criação e compilação de um arquivo Jar da UDF usando [Apache Maven](https://maven.apache.org/index.html) da linha de comando e uma implantação. Execute as etapas a seguir para criar uma UDF personalizada para o Athena usando o Maven 1. [Clonar o SDK e preparar o ambiente de desenvolvimento](#udf-create-install-sdk-prep-environment) 1. [Criar um projeto Maven](#create-maven-project) 1. [Adicionar dependências e plugins ao projeto Maven](#udf-add-maven-dependencies) 1. [Escrever código Java para UDFs](#udf-write-java) 1. [Compilar o arquivo JAR](#udf-create-package-jar) 1. [Implantar o JAR no AWS Lambda](#udf-create-deploy) ## Clonar o SDK e preparar o ambiente de desenvolvimento Antes de começar, certifique-se de que o git esteja instalado no sistema usando `sudo yum install git -y`. **Como instalar o Query Federation SDK da AWS** + Digite o seguinte na linha de comando para clonar o repositório do SDK. Este repositório inclui o SDK, exemplos e um conjunto de conectores de fonte de dados. Para obter mais informações sobre conectores de fonte de dados, consulte [Usar a consulta federada do Amazon Athena](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Como instalar pré-requisitos para este procedimento** Se você trabalha em uma máquina de desenvolvimento que já tem o Apache Maven, a AWS CLI e a ferramenta de compilação do AWS Serverless Application Model instalados, pode ignorar esta etapa. 1. Na raiz do diretório `aws-athena-query-federation` criado ao executar a clonagem, execute o script [prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh) que prepara o ambiente de desenvolvimento. 1. Atualize o shell para fornecer novas variáveis criadas pelo processo de instalação ou reinicie a sessão do terminal. ``` source ~/.profile ``` **Importante** Se você ignorar essa etapa, receberá erros posteriormente sobre a AWS CLI ou a ferramenta de compilação do AWS SAM não conseguir publicar a função do Lambda. ## Criar um projeto Maven Execute o seguinte comando para criar o projeto Maven. Substitua *groupId* pelo ID exclusivo da organização e substitua *my-athena-udf* pelo nome do aplicativo. Para obter mais informações, consulte [Como criar meu primeiro projeto Maven?](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project) na documentação Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Adicionar dependências e plugins ao projeto Maven Adicione as configurações a seguir ao arquivo `pom.xml` do projeto Maven. Para ver um exemplo, consulte o arquivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) no GitHub. ``` 2022.47.1 com.amazonaws aws-athena-federation-sdk ${aws-athena-federation-sdk.version} org.apache.maven.plugins maven-shade-plugin 3.2.1 false *:* META-INF/*.SF META-INF/*.DSA META-INF/*.RSA package shade ``` ## Escrever código Java para UDFs Crie uma nova classe ao estender [UserDefinedFunctionHandler.java](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-federation-sdk/src/main/java/com/amazonaws/athena/connector/lambda/handlers/UserDefinedFunctionHandler.java). Escreva as UDFs dentro da classe. No exemplo a seguir, dois métodos Java para UDFs, `compress()` e `decompress()`, são criados dentro da classe `MyUserDefinedFunctions`. ``` *package *com.mycompany.athena.udfs; public class MyUserDefinedFunctions extends UserDefinedFunctionHandler { private static final String SOURCE_TYPE = "MyCompany"; public MyUserDefinedFunctions() { super(SOURCE_TYPE); } /** * Compresses a valid UTF-8 String using the zlib compression library. * Encodes bytes with Base64 encoding scheme. * * @param input the String to be compressed * @return the compressed String */ public String compress(String input) { byte[] inputBytes = input.getBytes(StandardCharsets.UTF_8); // create compressor Deflater compressor = new Deflater(); compressor.setInput(inputBytes); compressor.finish(); // compress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); while (!compressor.finished()) { int bytes = compressor.deflate(buffer); byteArrayOutputStream.write(buffer, 0, bytes); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return encoded string byte[] compressedBytes = byteArrayOutputStream.toByteArray(); return Base64.getEncoder().encodeToString(compressedBytes); } /** * Decompresses a valid String that has been compressed using the zlib compression library. * Decodes bytes with Base64 decoding scheme. * * @param input the String to be decompressed * @return the decompressed String */ public String decompress(String input) { byte[] inputBytes = Base64.getDecoder().decode((input)); // create decompressor Inflater decompressor = new Inflater(); decompressor.setInput(inputBytes, 0, inputBytes.length); // decompress bytes to output stream byte[] buffer = new byte[4096]; ByteArrayOutputStream byteArrayOutputStream = new ByteArrayOutputStream(inputBytes.length); try { while (!decompressor.finished()) { int bytes = decompressor.inflate(buffer); if (bytes == 0 && decompressor.needsInput()) { throw new DataFormatException("Input is truncated"); } byteArrayOutputStream.write(buffer, 0, bytes); } } catch (DataFormatException e) { throw new RuntimeException("Failed to decompress string", e); } try { byteArrayOutputStream.close(); } catch (IOException e) { throw new RuntimeException("Failed to close ByteArrayOutputStream", e); } // return decoded string byte[] decompressedBytes = byteArrayOutputStream.toByteArray(); return new String(decompressedBytes, StandardCharsets.UTF_8); } } ``` ## Compilar o arquivo JAR Execute `mvn clean install` para compilar o projeto. Após a compilação com êxito, um arquivo JAR é criado na pasta `target` do projeto nomeado como `artifactId-version.jar`, no qual *artifactId* é o nome fornecido por você no projeto Maven, por exemplo, `my-athena-udfs`. ## Implantar o JAR no AWS Lambda Você tem duas opções para implantar o código no Lambda: + Implantar usando AWS Serverless Application Repository (recomendado) + Criar uma função do Lambda do arquivo JAR ### Opção 1: implantar no AWS Serverless Application Repository Ao implantar o arquivo JAR no AWS Serverless Application Repository, você cria um arquivo YAML de modelo do AWS SAM que representa a arquitetura do aplicativo. Em seguida, você especifica esse arquivo YAML e um bucket do Amazon S3 no qual os artefatos da aplicação são carregados e disponibilizados para o AWS Serverless Application Repository. O procedimento abaixo usa o script [publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh) localizado no diretório `athena-query-federation/tools` do Athena Query Federation SDK clonado anteriormente. Para obter mais informações e conhecer os requisitos, consulte [Publicar aplicações](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) no *Guia do desenvolvedor do AWS Serverless Application Repository*, [Conceitos de modelo do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) no *Guia do desenvolvedor do AWS Serverless Application Model* e [Publicar aplicações com tecnologia sem servidor usando a CLI do AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). O exemplo a seguir demonstra parâmetros em um arquivo YAML. Adicione parâmetros similares ao arquivo YAML e salve-o no diretório de projetos. Consulte [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) no GitHub para ver o exemplo completo. ``` Transform: 'AWS::Serverless-2016-10-31' Metadata: 'AWS::ServerlessRepo::Application': Name: MyApplicationName Description: 'The description I write for my application' Author: 'Author Name' Labels: - athena-federation SemanticVersion: 1.0.0 Parameters: LambdaFunctionName: Description: 'The name of the Lambda function that will contain your UDFs.' Type: String LambdaTimeout: Description: 'Maximum Lambda invocation runtime in seconds. (min 1 - 900 max)' Default: 900 Type: Number LambdaMemory: Description: 'Lambda memory in MB (min 128 - 3008 max).' Default: 3008 Type: Number Resources: ConnectorConfig: Type: 'AWS::Serverless::Function' Properties: FunctionName: !Ref LambdaFunctionName Handler: "full.path.to.your.handler. For example, com.amazonaws.athena.connectors.udfs.MyUDFHandler" CodeUri: "Relative path to your JAR file. For example, ./target/athena-udfs-1.0.jar" Description: "My description of the UDFs that this Lambda function enables." Runtime: java8 Timeout: !Ref LambdaTimeout MemorySize: !Ref LambdaMemory ``` Copie o script `publish.sh` para o diretório de projetos no qual você salvou o arquivo YAML e execute o comando: ``` ./publish.sh MyS3Location MyYamlFile ``` Por exemplo, se o local do bucket for `s3://amzn-s3-demo-bucket/mysarapps/athenaudf` e o arquivo YAML for salvo como `my-athena-udfs.yaml`: ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Como criar uma função do Lambda** 1. Abra o console do Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), escolha **Create function** (Criar função) e selecione **Browse serverless app repository** (Procurar repositório de aplicações sem servidor) 1. Selecione **Private applications (Aplicativos privados)**, localize o aplicativo na lista ou procure usando palavras-chave e selecione-o. 1. Verifique, forneça detalhes do aplicativo e selecione **Deploy (Implantar).** Agora você pode usar os nomes dos métodos definidos no arquivo JAR da função do Lambda como UDFs no Athena. ### Opção 2: criar uma função do Lambda diretamente Você também pode criar uma função do Lambda diretamente usando o console ou a AWS CLI. O exemplo a seguir demonstra o uso do comando da CLI `create-function` do Lambda. ``` aws lambda create-function \ --function-name MyLambdaFunctionName \ --runtime java8 \ --role arn:aws:iam::1234567890123:role/my_lambda_role \ --handler com.mycompany.athena.udfs.MyUserDefinedFunctions \ --timeout 900 \ --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar ```