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, ou regardez le. video

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 sur le blog AWS Big Data.

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 de package.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 sur le blog AWS Machine Learning.

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ément data_type variable spécifie une variable nommée et son type de données correspondant que l'UDF accepte en entrée. Le data_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ées DECIMAL, utilisez la syntaxe RETURNS DECIMAL(precision, scale) où la 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'une expression 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 clause USING EXTERNAL FUNCTION.

Exemples

Pour des exemples de requêtes basées sur le code AthenaUDFHandler.java activé GitHub, consultez la page du GitHub connecteur Amazon Athena UDF.

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 dans le SDK est disponible GitHub dans le athena-federation-sdk référentiel awslabs/aws-athena-query-federation/, ainsi que des exemples d'implémentations UDF que vous pouvez examiner et modifier pour créer un UDF personnalisé.

Les étapes de cette section illustrent l'écriture et la création d'un fichier Jar UDF personnalisé à l'aide d' Apache Maven à partir de la ligne de commande, ainsi qu'un déploiement.

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.

1. À 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.sh qui prépare votre environnement de développement.

2. 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-udfpar le nom de votre application. Pour plus d'informations, consultez Comment créer mon premier projet Maven ? dans la documentation d'Apache 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 dans GitHub.

<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. Écrivez vos UDF à l'intérieur de la classe.

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é artifactId-version.jar, où artifactId 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.sh situé dans le répertoire athena-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 pour un exemple complet. GitHub

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

1. 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)

2. 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.

3. 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 \
 --handler com.mycompany.athena.udfs.MyUserDefinedFunctions \
 --timeout 900 \
 --zip-file fileb://./target/my-athena-udfs-1.0-SNAPSHOT.jar