Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Interrogation avec des fonctions définies par l'utilisateur
Les fonctions définies par l'utilisateur (UDF) dans Amazon Athena vous permettent de créer des fonctions personnalisées pour traiter des registres ou des groupes de registres. Une UDF accepte les paramètres, effectue le travail, puis renvoie un résultat.
Pour utiliser une UDF dans Athena, vous écrivez une clause USING EXTERNAL FUNCTION
avant une instruction SELECT
dans une requête SQL. L'instruction SELECT
fait référence à l'UDF et définit les variables qui sont transmises à l'UDF lors de l'exécution de la requête. La requête SQL appelle une fonction Lambda en utilisant le moteur d'exécution Java lorsqu'elle invoque l'UDF. Les UDF sont définies dans la fonction Lambda en tant que méthodes dans un package de déploiement Java. Plusieurs UDF peuvent être définies dans le même package de déploiement Java pour une fonction Lambda. Vous spécifiez également le nom de la fonction Lambda dans la clause USING EXTERNAL FUNCTION
.
Vous disposez de deux options pour déployer une fonction Lambda pour les UDF Athena. Vous pouvez déployer la fonction directement en utilisant Lambda, ou vous pouvez utiliser le AWS Serverless Application Repository. Pour trouver les fonctions Lambda existantes pour les UDF, vous pouvez effectuer une recherche dans le référentiel public AWS Serverless Application Repository ou privé, puis les déployer sur Lambda. Vous pouvez également créer ou modifier le code source Java, le packager dans un fichier JAR et le déployer à l'aide de Lambda ou du AWS Serverless Application Repository. Pour des exemples de code source Java et de packages pour vous aider à démarrer, voir Création et déploiement d'une UDF à l'aide de Lambda. Pour plus d'informations sur Lambda, consultez le Guide du développeur AWS Lambda. Pour plus d'informations AWS Serverless Application Repository, consultez le guide du AWS Serverless Application Repository développeur.
Pour un exemple d'utilisation des UDF avec Athena pour traduire et analyser du texte, consultez l'article du AWS blog Machine Learning Translate and analysis text using SQL functions with Amazon Athena, Amazon Translate et Amazon Comprehend
Pour un exemple d'utilisation des UDF pour étendre les requêtes géospatiales dans Amazon Athena, consultez Étendre les requêtes géospatiales dans Amazon Athena avec des UDF et AWS Lambda
Considérations et restrictions
-
Fonctions Athena intégrées – Les fonctions intégrées dans Athena sont conçues pour être très performantes. Nous vous recommandons d'utiliser des fonctions intégrées plutôt que les UDF lorsque cela est possible. Pour de plus amples informations sur les fonctions intégrées, veuillez consulter Fonctions dans Amazon Athena.
-
UDF scalaires uniquement – Athena ne prend en charge que les UDF scalaires, qui traitent une ligne à la fois et renvoient une valeur de colonne unique. Athena transmet un lot de lignes, potentiellement en parallèle, à l'UDF chaque fois qu'il invoque Lambda. Lors de la conception des UDF et des requêtes, tenez compte de l'impact potentiel de ce traitement sur le trafic réseau.
-
Les fonctions du gestionnaire de UDF utilisent un format abrégé — Utilisez un format abrégé (pas le format complet), pour vos fonctions UDF (par exemple,
package.Class
et non depackage.Class::method
). -
Les méthodes UDF doivent être en minuscules — Les méthodes UDF doivent être en minuscules ; la casse chameau n'est pas autorisée.
-
Les méthodes UDF nécessitent des paramètres – Les méthodes UDF doivent avoir au moins un paramètre d'entrée. Toute tentative d'invocation d'une méthode UDF définie sans paramètres d'entrée entraîne une exception d'exécution. Les UDF sont destinés à exécuter des fonctions sur des enregistrements de données, mais un UDF sans arguments n'accepte aucune donnée, générant une exception.
-
Prise en charge de l'exécution Java – Actuellement, les UDF Athena prennent en charge les exécutions Java 8 et Java 11 pour Lambda. Pour plus d'informations, consultez la rubrique Création de fonctions Lambda avec Java du Guide du développeur AWS Lambda .
-
Autorisations IAM – Pour exécuter et créer des instructions de requête UDF dans Athena, le principal IAM qui exécute la requête doit être autorisé à effectuer des actions en plus des fonctions Athena. Pour plus d’informations, consultez Exemple de politiques d'autorisations IAM pour autoriser les fonctions définies par l'utilisateur (UDF) Amazon Athena.
-
Quotas Lambda – Les quotas Lambda s'appliquent aux UDF. Pour plus d'informations, consultez la section Quotas Lambda du Guide du développeur AWS Lambda .
-
Filtrage au niveau des lignes – Le filtrage au niveau des lignes de Lake Formation n'est pas pris en charge pour les UDF.
-
Views (Vues) : vous ne pouvez pas utiliser des vues avec des UDF.
-
Problèmes connus — Pour obtenir la up-to-date liste la plus complète des problèmes connus, voir Limitations et problèmes
dans la section awslabs/ aws-athena-query-federation de. GitHub
Vidéos
Regardez les vidéos suivantes pour en savoir plus sur l'utilisation des fonctions UDF dans Athena.
Vidéo : Présentation des fonctions définies par l'utilisateur (UDF) dans Amazon Athena
La vidéo suivante montre comment utiliser les fichiers UDF dans Amazon Athena pour effacer des informations sensibles.
Note
La syntaxe de cette vidéo est une version préliminaire, mais les concepts sont les mêmes. Utilisez Athena sans le groupe de travail AmazonAthenaPreviewFunctionality
.
Vidéo : Traduction, analyse et rédaction de champs de texte à l'aide de requêtes SQL dans Amazon Athena
La vidéo suivante montre comment vous pouvez utiliser les UDF dans Amazon Athena avec d'autres AWS services pour traduire et analyser du texte.
Note
La syntaxe de cette vidéo est une version préliminaire, mais les concepts sont les mêmes. Pour connaître la syntaxe correcte, consultez l'article de blog intitulé Traduction, rédaction et analyse de texte à l'aide de fonctions SQL avec Amazon Athena, Amazon Translate et Amazon Comprehend
Syntaxe de requête UDF
La clause USING EXTERNAL FUNCTION
spécifie une ou plusieurs UDF qui peuvent être référencées par une instruction SELECT
ultérieure dans la requête. Vous avez besoin du nom de la méthode de l'UDF et du nom de la fonction Lambda qui héberge l'UDF. À la place du nom de la fonction Lambda, vous pouvez utiliser l'ARN Lambda. Dans les scénarios entre comptes, l'ARN Lambda est requis.
Résumé
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
)] [...]
Paramètres
- USING EXTERNAL FUNCTION
UDF_name
(variable1
data_type
[,variable2
data_type
][,...]) -
UDF_name
spécifie le nom de l'UDF, qui doit correspondre à une méthode Java au sein de la fonction Lambda référencée. Chaque élémentdata_type variable
spécifie une variable nommée et son type de données correspondant que l'UDF accepte en entrée. Ledata_type
doit être l'un des types de données Athena pris en charge, répertoriés dans le tableau suivant, et être mappé sur le type de données Java correspondant.Type de données Athena Type de données Java TIMESTAMP
java.time. LocalDateTime (UTC)
DATE
java.time. LocalDate (UTC)
TINYINT
java.lang.Byte
SMALLINT
java.lang.Short
REAL
java.lang.Float
DOUBLE
java.lang.Double
DECIMAL (voir la note
RETURNS
)java.math. BigDecimal
BIGINT
java.lang.Long
INTEGER
java.lang.Int
VARCHAR
java.lang.String
VARBINARY
byte[]
BOOLEAN
java.lang.Boolean
ARRAY
java.util.List
ROW
java.util.Map<String, Object>
- RETURNS
type_données
-
data_type
spécifie le type de données SQL que l'UDF renvoie en sortie. Les types de données Athena répertoriés dans le tableau ci-dessus sont pris en charge. Pour le type de donnéesDECIMAL
, utilisez la syntaxeRETURNS DECIMAL(
où laprecision
,scale
)précision
et l'échelle
sont des entiers. - LAMBDA '
lambda_function
' -
lambda_function
spécifie le nom de la fonction Lambda à invoquer lors de l'exécution de l'UDF. - SELECT [...]
UDF_name
(expression
) [...] -
La requête
SELECT
qui transmet des valeurs à l'UDF et renvoie un résultat.UDF_name
spécifie l'UDF à utiliser, suivie d'uneexpression
qui est évaluée pour transmettre des valeurs. Les valeurs transmises et renvoyées doivent correspondre aux types de données correspondants spécifiés pour l'UDF dans la clauseUSING EXTERNAL FUNCTION
.
Exemples
Pour des exemples de requêtes basées sur le code AthenaUDFHandler.java
Création et déploiement d'une UDF à l'aide de Lambda
Pour créer une UDF personnalisée, vous créez une nouvelle classe Java en étendant la classe UserDefinedFunctionHandler
. Le code source du UserDefinedFunctionHandlerfichier .java
Les étapes de cette section illustrent l'écriture et la création d'un fichier Jar UDF personnalisé à l'aide d' Apache Maven
Étapes de création d'une UDF personnalisée pour Athena à l'aide de Maven
Cloner le kit SDK et préparer votre environnement de développement
Avant de commencer, assurez-vous que git est installé sur votre système en utilisant sudo
yum install git -y
.
Pour installer le SDK de fédération de AWS requêtes
-
Saisissez ce qui suit sur la ligne de commande pour cloner le référentiel SDK. Ce référentiel inclut le kit SDK, des exemples et une suite de connecteurs de source de données. Pour de plus amples informations sur les connecteurs de source de données, veuillez consulter Utilisation de la requête fédérée d’Amazon Athena.
git clone https://github.com/awslabs/aws-athena-query-federation.git
Pour installer les éléments requis pour cette procédure
Si vous travaillez sur une machine de développement sur laquelle Apache Maven, le AWS CLI, et l'outil de AWS Serverless Application Model compilation sont déjà installés, vous pouvez ignorer cette étape.
-
À partir de la racine du répertoire
aws-athena-query-federation
que vous avez créé lors du clonage, exécutez le script prepare_dev_env.shqui prépare votre environnement de développement. -
Mettez à jour votre shell pour obtenir les nouvelles variables créées par le processus d'installation ou redémarrez votre session de terminal.
source ~/.profile
Important
Si vous ignorez cette étape, vous recevrez ultérieurement des erreurs indiquant que l'outil AWS CLI ou l'outil de AWS SAM génération ne sera pas en mesure de publier votre fonction Lambda.
Créez votre projet Maven
Exécutez la commande suivante pour créer votre projet Maven. Remplacez GroupID
par l'identifiant unique de votre organisation et remplacez-le my-athena-udf
par le nom de votre application. Pour plus d'informations, consultez Comment créer mon premier projet Maven
mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=
groupId
\ -DartifactId=my-athena-udfs
Ajouter des dépendances et des plugins à votre projet Maven
Ajoutez les configurations suivantes au fichier pom.xml
du projet Maven. Pour un exemple, consultez le fichier pom.xml
<properties> <aws-athena-federation-sdk.version>2022.47.1</aws-athena-federation-sdk.version> </properties> <dependencies> <dependency> <groupId>com.amazonaws</groupId> <artifactId>aws-athena-federation-sdk</artifactId> <version>${aws-athena-federation-sdk.version}</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-shade-plugin</artifactId> <version>3.2.1</version> <configuration> <createDependencyReducedPom>false</createDependencyReducedPom> <filters> <filter> <artifact>*:*</artifact> <excludes> <exclude>META-INF/*.SF</exclude> <exclude>META-INF/*.DSA</exclude> <exclude>META-INF/*.RSA</exclude> </excludes> </filter> </filters> </configuration> <executions> <execution> <phase>package</phase> <goals> <goal>shade</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
Écrire du code Java pour les UDF
Créez une nouvelle classe en étendant le UserDefinedFunctionHandlerfichier .java.
Dans l'exemple suivant, deux méthodes Java pour les UDF, compress()
et decompress()
, sont créées à l'intérieur de la 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); } }
Construire le fichier JAR
Exécutez mvn clean install
pour construire votre projet. Une fois la construction terminée, un fichier JAR est créé dans le dossier target
de votre projet nommé
, où artifactId
-version
.jarartifactId
est le nom que vous avez fourni dans le projet Maven, par exemple, my-athena-udfs
.
Déployez le JAR sur AWS Lambda
Vous avez deux options pour déployer votre code sur Lambda :
-
Déployer à l'aide de AWS Serverless Application Repository (recommandé)
-
Création d'une fonction Lambda à partir du fichier JAR
Option 1 : déploiement vers le AWS Serverless Application Repository
Lorsque vous déployez votre fichier JAR sur le AWS Serverless Application Repository, vous créez un AWS SAM modèle de fichier YAML qui représente l'architecture de votre application. Vous spécifiez ensuite ce fichier YAML et un compartiment Simple Storage Service (Amazon S3) où les artefacts de votre application sont téléchargés et mis à disposition du AWS Serverless Application Repository. La procédure ci-dessous utilise le script publish.shathena-query-federation/tools
du kit Athena Query Federation SDK que vous avez cloné précédemment.
Pour plus d'informations et pour connaître les exigences, consultez les sections Publication d'applications dans le Guide du AWS Serverless Application Repository développeur, concepts de AWS SAM modèles dans le Guide du AWS Serverless Application Model développeur et Publication d'applications sans serveur à l'aide de la AWS SAM CLI.
L'exemple suivant illustre les paramètres d'un fichier YAML. Ajoutez des paramètres similaires à votre fichier YAML et enregistrez-le dans votre répertoire de projet. Voir athena-udf.yaml
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
Copiez le script publish.sh
dans le répertoire du projet dans lequel vous avez enregistré votre fichier YAML et exécutez la commande suivante :
./publish.sh
MyS3Location
MyYamlFile
Par exemple, si l'emplacement de votre compartiment est s3://DOC-EXAMPLE-BUCKET/mysarapps/athenaudf
et que votre fichier YAML a été enregistré sous la forme my-athena-udfs.yaml
:
./publish.sh DOC-EXAMPLE-BUCKET/mysarapps/athenaudf my-athena-udfs
Pour créer une fonction Lambda
-
Ouvrez la console Lambda à l'adresse https://console.aws.amazon.com/lambda/
, choisissez Create function (Créer une fonction), puis Browse serverless app repository (Parcourir le référentiel d'applications sans serveur) -
Choisissez Private applications (Applications privées), recherchez votre application dans la liste ou recherchez-la en utilisant des mots clés, puis sélectionnez-la.
-
Vérifiez et fournissez les détails de l'application, puis choisissez Déployer.
Vous pouvez maintenant utiliser les noms de méthode définis dans le fichier JAR de votre fonction Lambda comme des UDF dans Athena.
Option 2 : création directe d'une fonction Lambda
Vous pouvez également créer une fonction Lambda directement à l'aide de la console ou. AWS CLI L'exemple suivant illustre l'utilisation de la commande CLI create-function
Lambda.
aws lambda create-function \ --function-name
MyLambdaFunctionName
\ --runtime java8 \ --role arn:aws:iam::1234567890123:role/my_lambda_role
\ --handlercom.mycompany.athena.udfs.MyUserDefinedFunctions
\ --timeout 900 \ --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar