# Consulta con funciones definidas por el usuario Las funciones definidas por el usuario (UDF) en Amazon Athena le permiten crear funciones personalizadas para procesar registros o grupos de registros. Una UDF acepta parámetros, realiza el trabajo y, a continuación, devuelve un resultado. Para utilizar una UDF en Athena, escriba una cláusula `USING EXTERNAL FUNCTION` antes de una instrucción `SELECT` en una consulta SQL. La instrucción `SELECT` hace referencia a la UDF y define las variables que se pasan a la UDF cuando se ejecuta la consulta. La consulta SQL invoca una función de Lambda mediante el tiempo de ejecución de Java cuando llama a la UDF. Las UDF se definen dentro de la función de Lambda como métodos en un paquete de implementación de Java. Se pueden definir varias UDF en el mismo paquete de implementación de Java para una función de Lambda. También se especifica el nombre de la función de Lambda en la cláusula `USING EXTERNAL FUNCTION`. Tiene dos opciones para implementar una función de Lambda para UDF de Athena. Puede implementar la función directamente mediante Lambda, o puede usar AWS Serverless Application Repository. Para buscar funciones de Lambda existentes para UDF, puede buscar en el repositorio público AWS Serverless Application Repository o su repositorio privado y, a continuación, realizar la implementación en Lambda. También puede crear o modificar el código fuente Java, empaquetarlo en un archivo JAR e implementarlo mediante Lambda o AWS Serverless Application Repository. Para ver un ejemplo de código fuente Java y paquetes para empezar, consulte [Creación e implementación de una UDF mediante Lambda](udf-creating-and-deploying.md). Para obtener más información acerca de Lambda, consulte la [Guía para desarrolladores de AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/). Para obtener más información sobre AWS Serverless Application Repository, consulte la Guía para desarrolladores de [AWS Serverless Application Repository](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/). Para ver un ejemplo que utiliza UDF con Athena para traducir y analizar texto, consulte el artículo del blog de Machine Learning de AWS [Traducir y analizar texto mediante funciones SQL con Amazon Athena, Amazon Translate y Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/), o vea el [video](udf-videos.md#udf-videos-xlate). Para ver un ejemplo del uso de UDF a fin de ampliar las consultas geoespaciales en Amazon Athena, consulte [Extend geospatial queries in Amazon Athena with UDFs and AWS Lambda](https://aws.amazon.com/blogs/big-data/extend-geospatial-queries-in-amazon-athena-with-udfs-and-aws-lambda/) en el *Blog de macrodatos de AWS*. **Topics** + [Videos sobre las UDF en Athena](udf-videos.md) + [Consideraciones y limitaciones](udf-considerations-limitations.md) + [Consulta mediante la sintaxis de la consulta de UDF](udf-query-syntax.md) + [Creación e implementación de una UDF mediante Lambda](udf-creating-and-deploying.md) # Videos sobre las UDF en Athena Mire los siguientes videos para obtener más información acerca del uso de las UDF en Athena. **Video: presentación de las funciones definidas por el usuario (UDF) en Amazon Athena** En el siguiente video, se muestra cómo utilizar UDF en Amazon Athena para redactar información confidencial. **nota** La sintaxis de este video es una versión preliminar, pero los conceptos son los mismos. Utilice Athena sin el grupo de trabajo `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) **Video : Traducir, analizar y redactar campos de texto mediante consultas SQL en Amazon Athena** En el siguiente video, se muestra cómo utilizar UDF en Amazon Athena junto con otros Servicios de AWS para traducir y analizar texto. **nota** La sintaxis de este video es una versión preliminar, pero los conceptos son los mismos. Para obtener la sintaxis correcta, consulte la publicación del blog relacionada [Traducir, redactar y analizar texto mediante funciones SQL con Amazon Athena, Amazon Translate y Amazon Comprehend](https://aws.amazon.com/blogs/machine-learning/translate-and-analyze-text-using-sql-functions-with-amazon-athena-amazon-translate-and-amazon-comprehend/) en el *blog de Machine Learning de 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) # Consideraciones y limitaciones Tenga en cuenta los siguientes puntos cuando utilice la función definida por el usuario (UDF) en Athena. + **Funciones de Athena integradas**: las funciones integradas en Athena se han diseñado para tener un alto rendimiento. Se recomienda utilizar funciones prediseñadas sobre UDF cuando sea posible. Para obtener más información sobre funciones prediseñadas, consulte [Funciones en Amazon Athena](functions.md). + **Únicamente UDF escalares**: Athena solo admite UDF escalares, que procesan una fila a la vez y devuelven un único valor de columna. Athena pasa un lote de filas, potencialmente en paralelo, a la UDF cada vez que invoca Lambda. Al diseñar UDF y consultas, tenga en cuenta el impacto potencial en el tráfico de red de este procesamiento. + **Funciones del controlador de la FDU utilizan un formato abreviado**: utilice el formato abreviado (no formato completo), para las funciones de la FDU (por ejemplo, `package.Class` en lugar de `package.Class::method`). + **Los métodos de la FDU deben ir en minúscula**: los métodos de la FDU deben estar en minúsculas; no se permite la combinación entre mayúsculas y minúsculas. + **Los métodos de UDF requieren parámetros**: los métodos de UDF deben tener al menos un parámetro de entrada. Si se intenta invocar una UDF definida sin parámetros de entrada, se produce una excepción en el tiempo de ejecución. Las UDF se han diseñado para desarrollar funciones con registros de datos, pero una UDF sin argumentos no acepta datos, por lo que se produce una excepción. + **Soporte de tiempo de ejecución en Java**: actualmente, las UDF de Athena admiten los tiempos de ejecución de Java 8, Java 11 y Java 17 para Lambda. Para obtener más información, consulte [Creación de funciones de Lambda con Java](https://docs.aws.amazon.com/lambda/latest/dg/lambda-java.html) en la *Guía para desarrolladores de AWS Lambda*. **nota** Para Java 17, debe establecer el valor de la variable de entorno `JAVA_TOOL_OPTIONS` como `--add-opens=java.base/java.nio=ALL-UNNAMED` en su Lambda. + **Permisos de IAM**: para ejecutar y crear instrucciones de consulta UDF en Athena, la entidad principal de IAM que ejecuta la consulta debe tener permiso para realizar acciones además de las funciones de Athena. Para obtener más información, consulte [Permiso de acceso a las UDF de Athena: políticas de ejemplo](udf-iam-access.md). + **Cuotas de Lambda**: las cuotas de Lambda se aplican a las UDF. Para obtener más información, consulte [Cuotas de Lambda](https://docs.aws.amazon.com/lambda/latest/dg/limits.html) en la *Guía para desarrolladores de AWS Lambda*. + **Filtrado a nivel de fila**: el filtrado a nivel de fila de Lake Formation no es compatible con las UDF. + **Vistas**: no se pueden utilizar vistas con UDF. + **Problemas conocidos**: para obtener la lista más actualizada de problemas conocidos, consulte [Limitaciones y problemas](https://github.com/awslabs/aws-athena-query-federation/wiki/Limitations_And_Issues) en la sección awslabs/aws-athena-query-federation de GitHub. # Consulta mediante la sintaxis de la consulta de UDF La cláusula `USING EXTERNAL FUNCTION` especifica una UDF o varias UDF a las que se puede hacer referencia mediante una instrucción `SELECT` posterior en la consulta. Necesita el nombre del método para la UDF y el nombre de la función de Lambda que aloja la UDF. En lugar del nombre de la función de Lambda, puede utilizar el ARN de Lambda. En escenarios de varias cuentas, se requiere el ARN de Lambda. ## Sinopsis ``` 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)] [...] ``` ## Parameters **USING EXTERNAL FUNCTION *UDF\$1name*(*variable1* *data\$1type*[, *variable2* *data\$1type*][,...])** *UDF\$1name* especifica el nombre de la UDF, que debe corresponderse con un método Java dentro de la función de Lambda de referencia. Cada *variable data\$1type* especifica una variable con nombre con su tipo de datos correspondiente, que la UDF acepta como entrada. El *data\$1type* debe ser uno de los tipos de datos de Athena admitidos que aparecen en la siguiente tabla y asignarse al tipo de datos Java correspondiente. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/athena/latest/ug/udf-query-syntax.html) **RETURNS *data\$1type*** `data_type` especifica el tipo de datos SQL que la UDF devuelve a la consulta como salida. Los tipos de datos de Athena enumerados en la tabla anterior son compatibles. Para el tipo de datos `DECIMAL`, utilice la sintaxis `RETURNS DECIMAL(precision, scale)` donde *precision* y *scale* son enteros. **LAMBDA '*lambda\$1function*'** *lambda\$1function* especifica el nombre de la función de Lambda que se va a invocar cuando se ejecuta la UDF. **SELECT [...] *UDF\$1name*(*expression*) [...]** La consulta `SELECT` que pasa valores a la UDF y devuelve un resultado. *UDF\$1name* especifica la UDF que se va a utilizar, seguida de una *expression* (expresión) que se evalúa para pasar valores. Los valores que se pasan y se devuelven deben coincidir con los tipos de datos correspondientes especificados para la UDF en la cláusula `USING EXTERNAL FUNCTION`. ### Ejemplos Para ver ejemplos de consultas basadas en el 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) en GitHub, consulte la página [Conector UDF de Amazon Athena](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs). # Creación e implementación de una UDF mediante Lambda Para crear una UDF personalizada, cree una nueva clase Java mediante la extensión de la clase `UserDefinedFunctionHandler`. El código fuente de [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) en el SDK está disponible en GitHub en el [repositorio](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk) awslabs/aws-athena-query-federation/athena-federation-sdk, junto con [implementaciones de UDF de ejemplo](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-udfs) que puede examinar y modificar para crear una UDF personalizada. Los pasos de esta sección muestran cómo escribir y crear un archivo Jar de UDF personalizado mediante [Apache Maven](https://maven.apache.org/index.html) desde la línea de comandos y una implementación. Instrucciones para crear una UDF personalizada para Athena mediante Maven 1. [Clonación del SDK y preparación del entorno de desarrollo](#udf-create-install-sdk-prep-environment) 1. [Creación del proyecto de Maven](#create-maven-project) 1. [Adición de dependencias y complementos al proyecto de Maven](#udf-add-maven-dependencies) 1. [Escritura de código Java para las UDF](#udf-write-java) 1. [Creación del archivo JAR](#udf-create-package-jar) 1. [Implementación de JAR en AWS Lambda](#udf-create-deploy) ## Clonación del SDK y preparación del entorno de desarrollo Antes de comenzar, asegúrese de que git esté instalado en su sistema mediante `sudo yum install git -y`. **Para instalar el SDK de federación de consultas de AWS** + Escriba lo siguiente en la línea de comandos para clonar el repositorio de SDK. Este repositorio incluye el SDK, ejemplos y un conjunto de conectores de origen de datos. Para obtener más información sobre los conectores de origen de datos, consulte [Uso de consulta federada de Amazon Athena](federated-queries.md). ``` git clone https://github.com/awslabs/aws-athena-query-federation.git ``` **Para instalar los requisitos previos para este procedimiento, tenga en cuenta lo siguiente:** Si está trabajando en un equipo de desarrollo que ya tiene instalado Apache Maven, la AWS CLI y la herramienta de compilación de AWS Serverless Application Model, puede omitir este paso. 1. Desde la raíz del directorio `aws-athena-query-federation` que creó cuando realizó la clonación, ejecute el script [prepare\$1dev\$1env.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/prepare_dev_env.sh) que prepara el entorno de desarrollo. 1. Actualice el shell para generar nuevas variables creadas por el proceso de instalación o reinicie la sesión de terminal. ``` source ~/.profile ``` **importante** Si omite este paso, obtendrá errores más adelante acerca de que la herramienta de compilación de la AWS CLI o el AWS SAM no puede publicar su función de Lambda. ## Creación del proyecto de Maven Ejecute el siguiente comando para crear el proyecto de Maven. Reemplace *groupId* por el ID único de su organización y sustituya *my-athena-udf* por el nombre de su aplicación. Para obtener más información, consulte [¿Cómo realizo mi primer proyecto de Maven?](https://maven.apache.org/guides/getting-started/index.html#How_do_I_make_my_first_Maven_project) en la documentación de Apache Maven. ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=groupId \ -DartifactId=my-athena-udfs ``` ## Adición de dependencias y complementos al proyecto de Maven Agregue las siguientes configuraciones al archivo `pom.xml` del proyecto de Maven. Para ver un ejemplo, consulte el archivo [pom.xml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/pom.xml) en 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 ``` ## Escritura de código Java para las UDF Extienda [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) para crear una nueva clase. Escriba sus UDF dentro de la clase. En el siguiente ejemplo, se crean dos métodos Java para UDF `compress()` y `decompress()`, dentro de la clase `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); } } ``` ## Creación del archivo JAR Ejecute `mvn clean install` para crear su proyecto. Después de que se compile correctamente, se crea un archivo JAR en la carpeta `target` de su proyecto denominada `artifactId-version.jar`, donde *artifactId* es el nombre que proporcionó en el proyecto de Maven, por ejemplo, `my-athena-udfs`. ## Implementación de JAR en AWS Lambda Tiene dos opciones para implementar su código en Lambda: + Implementación mediante AWS Serverless Application Repository (recomendado) + Creación de una función de Lambda desde el archivo JAR ### Opción 1: implementación en el AWS Serverless Application Repository Al implementar el archivo JAR en AWS Serverless Application Repository, se crea un archivo YAML de plantilla AWS SAM que representa la arquitectura de la aplicación. A continuación, especifique este archivo YAML y un bucket de Amazon S3 donde los artefactos de su aplicación se carguen y estén disponibles para el AWS Serverless Application Repository. El siguiente procedimiento utiliza el script [publish.sh](https://github.com/awslabs/aws-athena-query-federation/blob/master/tools/publish.sh) ubicado en el directorio `athena-query-federation/tools` del SDK de Athena Query Federation que clonó anteriormente. Para obtener más información y requisitos, consulte [Publicación de aplicaciones](https://docs.aws.amazon.com/serverlessrepo/latest/devguide/serverlessrepo-publishing-applications.html) en la *Guía para desarrolladores de AWS Serverless Application Repository*, [Conceptos de plantillas de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-basics.html) en la *Guía para desarrolladores de AWS Serverless Application Model* y [Publicación de aplicaciones sin servidor mediante la CLI de AWS SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-template-publishing-applications.html). En el siguiente ejemplo se muestran los parámetros de un archivo YAML. Agregue parámetros similares a su archivo YAML y guárdelo en su directorio de proyecto. Consulte [athena-udf.yaml](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-udfs/athena-udfs.yaml) en GitHub para ver un ejemplo 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 el script `publish.sh` en el directorio del proyecto donde guardó el archivo YAML y ejecute el siguiente comando: ``` ./publish.sh MyS3Location MyYamlFile ``` Por ejemplo, si la ubicación del bucket es `s3://amzn-s3-demo-bucket/mysarapps/athenaudf` y el archivo YAML se guardó como `my-athena-udfs.yaml`: ``` ./publish.sh amzn-s3-demo-bucket/mysarapps/athenaudf my-athena-udfs ``` **Cómo crear una función de Lambda** 1. Abra la consola de Lambda en [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/), elija **Create function** (Crear función), y luego elija **Browse serverless app repository** (Explorar el repositorio de aplicaciones sin servidor). 1. Elija **Private applications** (Aplicaciones privadas) busque su aplicación en la lista o búsquela con palabras clave y selecciónela. 1. Revise y proporcione los detalles de la aplicación y, a continuación, elija **Deploy** (Implementar). Ahora puede utilizar los nombres de los métodos definidos en su archivo JAR de la función de Lambda como UDF en Athena. ### Opción 2: creación directa de una función de Lambda También puede crear una función de Lambda directamente mediante la consola o la AWS CLI. En el siguiente ejemplo, se muestra el uso del comando de la CLI `create-function` de 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 ```