Procédures stockées, déclencheurs et fonctions définies par l’utilisateurStored procedures, triggers, and user-defined functions

Azure Cosmos DB offre une exécution transactionnelle, intégrée au langage, de JavaScript.Azure Cosmos DB provides language-integrated, transactional execution of JavaScript. Lorsque vous utilisez l’API SQL dans Azure Cosmos DB, vous pouvez écrire les procédures stockées, les déclencheurs et les fonctions définies par l’utilisateur dans le langage JavaScript.When using the SQL API in Azure Cosmos DB, you can write stored procedures, triggers, and user-defined functions (UDFs) in the JavaScript language. Vous pouvez écrire votre logique dans JavaScript et l’exécuter dans le moteur de base de données.You can write your logic in JavaScript that executed inside the database engine. Vous pouvez créer et exécuter des déclencheurs, des procédures stockées et des fonctions définies par l’utilisateur à l’aide du Portail Azure, de l’API de requête avec langage intégré JavaScript dans Azure Cosmos DB ou des Kits de développement logiciel (SDK) clients de l’API SQL Cosmos DB.You can create and execute triggers, stored procedures, and UDFs by using Azure portal, the JavaScript language integrated query API in Azure Cosmos DB or the Cosmos DB SQL API client SDKs.

Avantages de l’utilisation de la programmation côté serveurBenefits of using server-side programming

L’écriture de procédures stockées, déclencheurs et fonctions définies par l’utilisateur (UDF) dans JavaScript vous permet de créer des applications riches avec les avantages suivants :Writing stored procedures, triggers, and user-defined functions (UDFs) in JavaScript allows you to build rich applications and they have the following advantages:

  • Logique procédurale : JavaScript en tant que langage de programmation de haut niveau offre une interface riche et familière permettant d’exprimer la logique métier.Procedural logic: JavaScript as a high-level programming language that provides rich and familiar interface to express business logic. Vous pouvez effectuer une séquence d’opérations complexes sur les données.You can perform a sequence of complex operations on the data.

  • Transactions atomiques : Azure Cosmos DB garantit que les opérations de base de données effectuées dans un déclencheur ou une procédure stockée sont atomiques.Atomic transactions: Azure Cosmos DB guarantees that the database operations that are performed within a single stored procedure or a trigger are atomic. Cette fonctionnalité atomique permet à une application de combiner des applications connexes en un seul lot de façon à ce que toutes les opérations réussissent ou qu’aucune ne réussisse.This atomic functionality lets an application combine related operations into a single batch, so that either all of the operations succeed or none of them succeed.

  • Performances : Les données JSON sont mappées de manière intrinsèque au système de type de langage JavaScript.Performance: The JSON data is intrinsically mapped to the JavaScript language type system. Ce mappage permet plusieurs optimisations telles que la matérialisation différée de documents JSON dans le pool de tampons et leur disponibilité sur demande à l’exécution de code.This mapping allows for a number of optimizations like lazy materialization of JSON documents in the buffer pool and making them available on-demand to the executing code. Il existe d'autres avantages en matière de performances en lien avec l'expédition de la logique métier à la base de données, parmi lesquels :There are other performance benefits associated with shipping business logic to the database, which includes:

    • Traitement par lot : Vous pouvez regrouper les opérations telles que les insertions et les envoyer en bloc.Batching: You can group operations like inserts and submit them in bulk. Les coûts liés à la latence du trafic réseau et la surcharge en matière de stockage pour créer des transactions séparées sont considérablement réduits.The network traffic latency costs and the store overhead to create separate transactions are reduced significantly.

    • Précompilation : Les procédures stockées, les déclencheurs et les fonctions définies par l’utilisateur sont précompilés de façon implicite en format de code d’octet afin d’éviter les frais de compilation à chaque appel de script.Pre-compilation: Stored procedures, triggers, and UDFs are implicitly pre-compiled to the byte code format in order to avoid compilation cost at the time of each script invocation. La précompilation permet de s’assurer que les appels de procédures stockées sont rapides et présentent un encombrement réduit.Due to pre-compilation, the invocation of stored procedures is fast and has a low footprint.

    • Séquencement : Parfois, les opérations ont besoin d’un mécanisme de déclenchement qui peut exécuter une ou plusieurs mises à jour sur les données.Sequencing: Sometimes operations need a triggering mechanism that may perform one or additional updates to the data. En plus de l’atomicité, il existe également des avantages de performances lors de l’exécution côté serveur.In addition to Atomicity, there are also performance benefits when executing on the server side.

  • Encapsulation : Les procédures stockées peuvent être utilisées pour regrouper la logique à un endroit.Encapsulation: Stored procedures can be used to group logic in one place. L’encapsulation ajoute une couche d'abstraction aux données, ce qui vous permet de faire évoluer vos applications indépendamment des données.Encapsulation adds an abstraction layer on top of the data, which enables you to evolve your applications independently from the data. Cette couche d’abstraction est utile lorsque les données sont sans schéma et que vous n’êtes pas obligé de gérer l’ajout d’une logique supplémentaire directement dans votre application.This layer of abstraction is helpful when the data is schema-less and you don't have to manage adding additional logic directly into your application. L’abstraction vous permet d'assurer la sécurité de vos données en simplifiant l'accès à partir des scripts.The abstraction lets your keep the data secure by streamlining the access from the scripts.

Conseil

Les procédures stockées conviennent parfaitement pour des opérations intenses en écriture et nécessitant une transaction sur une valeur de clé de partition.Stored procedures are best suited for operations that are write-heavy and require a transaction across a partition key value. Lorsque vous décidez d’utiliser des procédures stockées, optimisez en encapsulant la quantité maximale d’écritures possibles.When deciding whether to use stored procedures, optimize around encapsulating the maximum amount of writes possible. En règle générale, les procédures stockées ne sont pas le moyen le plus efficace pour effectuer un grand nombre d’opérations de lecture ou de requête. L’utilisation de procédures stockées pour traiter par lot un grand nombre de lectures à retourner au client n’offre donc pas l’avantage souhaité.Generally speaking, stored procedures are not the most efficient means for doing large numbers of read or query operations, so using stored procedures to batch large numbers of reads to return to the client will not yield the desired benefit. Pour des performances optimales, ces opérations intenses en lecture doivent être effectuées côté client à l’aide du Kit de développement logiciel (SDK) Cosmos.For best performance, these read-heavy operations should be done on the client-side, using the Cosmos SDK.

TransactionsTransactions

Une transaction dans une base de données classique peut être définie comme étant une séquence d'opérations effectuées en tant qu'unité de travail logique unique.Transaction in a typical database can be defined as a sequence of operations performed as a single logical unit of work. Chaque transaction offre des garanties de propriété ACID.Each transaction provides ACID property guarantees. ACID est un acronyme bien connu qui est l’abréviation de : Atomicity, Consistency, Isolation, Durability (Atomicité, cohérence, isolation et durabilité).ACID is a well-known acronym that stands for: Atomicity, Consistency, Isolation, and Durability.

  • L'atomicité permet de s'assurer que toutes les opérations effectuées au sein d'une transaction sont traitées en tant que simple unité validée dans son intégralité ou aucunement.Atomicity guarantees that all the operations done inside a transaction are treated as a single unit, and either all of them are committed or none of them are.

  • La cohérence permet de s'assurer que les données sont toujours dans un état valide d'une transaction à l'autre.Consistency makes sure that the data is always in a valid state across transactions.

  • L'isolation, quant à elle, permet de garantir qu'aucune transaction n'interfère avec les autres. De nombreux systèmes commerciaux fournissent plusieurs niveaux d'isolation pouvant être utilisés en fonction des besoins des applications.Isolation guarantees that no two transactions interfere with each other – many commercial systems provide multiple isolation levels that can be used based on the application needs.

  • La durabilité permet de s'assurer que toute modification validée dans une base de données sera toujours présente.Durability ensures that any change that is committed in a database will always be present.

Dans Azure Cosmos DB, le runtime JavaScript est hébergé dans le moteur de base de données.In Azure Cosmos DB, JavaScript runtime is hosted inside the database engine. Par conséquent, les demandes effectuées au sein de procédures stockées et de déclencheurs s'exécutent dans la même étendue qu'une session de base de données.Hence, requests made within the stored procedures and the triggers execute in the same scope as the database session. Cette fonctionnalité permet à Azure Cosmos DB de garantir les propriétés ACID pour toutes les opérations qui font partie d’une procédure stockée ou d’un déclencheur.This feature enables Azure Cosmos DB to guarantee ACID properties for all operations that are part of a stored procedure or a trigger. Pour obtenir des exemples, consultez l’article Guide pratique pour implémenter des transactions.For examples, see how to implement transactions article.

Étendue d’une transactionScope of a transaction

Si une procédure stockée est associée à un conteneur Azure Cosmos, alors la procédure stockée est exécutée dans l’étendue de transaction d’une clé de partition logique.If a stored procedure is associated with an Azure Cosmos container, then the stored procedure is executed in the transaction scope of a logical partition key. Chaque exécution de procédure stockée doit inclure une valeur de clé de partition logique correspondant à l’étendue de la transaction.Each stored procedure execution must include a logical partition key value that corresponds to the scope of the transaction. Pour plus d’informations, consultez l’article Partitionnement dans Azure Cosmos DB.For more information, see Azure Cosmos DB partitioning article.

Validation et restaurationCommit and rollback

Les transactions sont intégrées de façon native dans le modèle de programmation JavaScript d’Azure Cosmos DB.Transactions are natively integrated into the Azure Cosmos DB JavaScript programming model. Dans une fonction JavaScript, toutes les opérations sont automatiquement encapsulées dans une transaction unique.Within a JavaScript function, all the operations are automatically wrapped under a single transaction. Si la logique JavaScript dans une procédure stockée se termine sans aucune exception, toutes les opérations au sein de la transaction sont validées dans la base de données.If the JavaScript logic in a stored procedure completes without any exceptions, all the operations within the transaction are committed to the database. Les instructions comme BEGIN TRANSACTION et COMMIT TRANSACTION (familières aux bases de données relationnelles) sont implicites dans Azure Cosmos DB.Statements like BEGIN TRANSACTION and COMMIT TRANSACTION (familiar to relational databases) are implicit in Azure Cosmos DB. En cas d’exceptions dans le script, le runtime JavaScript d’Azure Cosmos DB annule toute la transaction.If there are any exceptions from the script, the Azure Cosmos DB JavaScript runtime will roll back the entire transaction. Par conséquent, lever une exception équivaut en fait à un ROLLBACK TRANSACTION dans Azure Cosmos DB.As such, throwing an exception is effectively equivalent to a ROLLBACK TRANSACTION in Azure Cosmos DB.

Cohérence des donnéesData consistency

Les procédures stockées et les déclencheurs sont toujours exécutés dans le réplica principal d’un conteneur Azure Cosmos.Stored procedures and triggers are always executed on the primary replica of an Azure Cosmos container. Cette fonctionnalité permet de s'assurer que les lectures à partir des procédures stockées offrent une cohérence forte.This feature ensures that reads from stored procedures offer strong consistency. Les requêtes utilisant des fonctions définies par l’utilisateur peuvent être exécutées sur le réplica principal ou un réplica secondaire.Queries using user-defined functions can be executed on the primary or any secondary replica. Les procédures stockées et les déclencheurs sont destinés à soutenir les écritures transactionnelles. Pendant ce temps, la logique en lecture seule est mieux implémentée en tant que logique côté application et les requêtes utilisant les kits SDK d’API SQL Azure Cosmos DB vous aideront à saturer le débit de base de données.Stored procedures and triggers are intended to support transactional writes – meanwhile read-only logic is best implemented as application-side logic and queries using the Azure Cosmos DB SQL API SDKs, will help you saturate the database throughput.

Exécution limitéeBounded execution

Toutes les opérations Azure Cosmos DB doivent s’effectuer avant le délai d’expiration spécifié.All Azure Cosmos DB operations must complete within the specified timeout duration. Cette contrainte s’applique aux fonctions JavaScript (procédures stockées, déclencheurs et fonctions définies par l’utilisateur).This constraint applies to JavaScript functions - stored procedures, triggers, and user-defined functions. Si une opération n'est pas terminée dans ce délai imparti, la transaction est annulée.If an operation does not complete within that time limit, the transaction is rolled back.

Vous pouvez vous assurer que les fonctions JavaScript s’exécutent dans ce délai ou mettre en œuvre un modèle basé sur la continuation pour traiter par lots/reprendre l’exécution.You can either ensure that your JavaScript functions finish within the time limit or implement a continuation-based model to batch/resume execution. Afin de simplifier le développement de procédures stockées et de déclencheurs pour gérer les limites de temps, toutes les fonctions sous le conteneur Azure Cosmos (par exemple, création, lecture, remplacement et suppression d’éléments) retournent une valeur booléenne qui indique si l'opération arrivera à son terme.In order to simplify development of stored procedures and triggers to handle time limits, all functions under the Azure Cosmos container (for example, create, read, update, and delete of items) return a boolean value that represents whether that operation will complete. Si cette valeur est false, cela indique que la procédure doit clôturer l’exécution, car le script consomme plus de temps ou de débit provisionné que la valeur configurée.If this value is false, it is an indication that the procedure must wrap up execution because the script is consuming more time or provisioned throughput than the configured value. Les opérations mises en file d'attente avant la première opération de stockage non acceptée sont assurées de s'exécuter si la procédure stockée s'exécute à temps et ne place pas d'autres demandes dans la file d'attente.Operations queued prior to the first unaccepted store operation are guaranteed to complete if the stored procedure completes in time and does not queue any more requests. Par conséquent, les opérations doivent être mises en file d’attente une à la fois à l’aide de la convention de rappel de JavaScript pour gérer le flux de contrôle du script.Thus, operations should be queued one at a time by using JavaScript’s callback convention to manage the script’s control flow. Étant donné que les scripts sont exécutés dans un environnement côté serveur, ils sont strictement régis.Because scripts are executed in a server-side environment, they are strictly governed. Les scripts enfreignant de façon répétitive les limites de l’exécution peuvent être marqués comme inactifs et ne peuvent pas être exécutés. Ils doivent être recréés pour respecter les limites de l’exécution.Scripts that repeatedly violate execution boundaries may be marked inactive and can't be executed, and they should be recreated to honor the execution boundaries.

Les fonctions JavaScript sont également soumises à la capacité de débit provisionné.JavaScript functions are also subject to provisioned throughput capacity. Les fonctions JavaScript peuvent potentiellement finir par utiliser un grand nombre d’unités de demande en peu de temps et leur débit peut être limité si la limite de capacité de débit provisionné est atteinte.JavaScript functions could potentially end up using a large number of request units within a short time and may be rate-limited if the provisioned throughput capacity limit is reached. Il est important de noter que les scripts consomment un débit supplémentaire en plus du débit consacré à l’exécution des opérations de base de données, bien que celles-ci soient légèrement moins coûteuses que l’exécution des mêmes opérations à partir du client.It is important to note that scripts consume additional throughput in addition to the throughput spent executing database operations, although these database operations are slightly less expensive than executing the same operations from the client.

DéclencheursTriggers

Azure Cosmos DB prend en charge deux types de déclencheurs :Azure Cosmos DB supports two types of triggers:

PrédéclencheursPre-triggers

Azure Cosmos DB fournit des déclencheurs qui peuvent être appelés par l’exécution d’une opération sur un élément Azure Cosmos.Azure Cosmos DB provides triggers that can be invoked by performing an operation on an Azure Cosmos item. Par exemple, vous pouvez spécifier un prédéclencheur lorsque vous créez un élément.For example, you can specify a pre-trigger when you are creating an item. Dans ce cas, le prédéclencheur sera exécuté avant la création de l’élément.In this case, the pre-trigger will run before the item is created. Les pré-déclencheurs ne peuvent pas avoir de paramètres en entrée.Pre-triggers cannot have any input parameters. Si nécessaire, l’objet de la demande peut être utilisé pour mettre à jour le corps du document à partir de la demande d’origine.If necessary, the request object can be used to update the document body from original request. Lorsque les déclencheurs sont enregistrés, les utilisateurs peuvent spécifier les opérations avec lesquelles il peut s'exécuter.When triggers are registered, users can specify the operations that it can run with. Si un déclencheur a été créé avec TriggerOperation.Create, cela signifie que l’utilisation du déclencheur dans une opération de remplacement n’est pas autorisée.If a trigger was created with TriggerOperation.Create, this means using the trigger in a replace operation will not be permitted. Pour obtenir des exemples, consultez l’article Guide pratique pour écrire des déclencheurs.For examples, see How to write triggers article.

Post-déclencheursPost-triggers

Comme pour les prédéclencheurs, les post-déclencheurs sont également associés à une opération sur un élément Azure Cosmos et ils ne nécessitent aucun paramètre d’entrée.Similar to pre-triggers, post-triggers, are also associated with an operation on an Azure Cosmos item and they don’t require any input parameters. Ils sont exécutés après la fin de l’opération et ont accès au message de réponse qui est envoyé au client.They run after the operation has completed and have access to the response message that is sent to the client. Pour obtenir des exemples, consultez l’article Guide pratique pour écrire des déclencheurs.For examples, see How to write triggers article.

Notes

Les déclencheurs inscrits ne s’exécutent pas automatiquement lorsque leurs opérations correspondantes (créer / supprimer / remplacer / mettre à jour) sont effectuées.Registered triggers don't run automatically when their corresponding operations (create / delete / replace / update) happen. Ils doivent être appelés explicitement lors de l’exécution de ces opérations.They have to be explicitly called when executing these operations. Pour plus d’informations, consultez l’article Comment exécuter des déclencheurs.To learn more, see how to run triggers article.

Fonctions définies par l’utilisateurUser-defined functions

Les fonctions définies par l'utilisateur permettent d'étendre la syntaxe du langage de requête API SQL et de mettre en œuvre facilement une logique métier personnalisée.User-defined functions (UDFs) are used to extend the SQL API query language syntax and implement custom business logic easily. Elles ne peuvent être appelées que dans les requêtes.They can be called only within queries. Les fonctions définies par l’utilisateur n'ont pas accès à l'objet de contexte et sont destinées à être utilisées en tant que JavaScript en calcul seul.UDFs do not have access to the context object and are meant to be used as compute only JavaScript. Par conséquent, elles peuvent être exécutées sur des réplicas secondaires.Therefore, UDFs can be run on secondary replicas. Pour obtenir des exemples, consultez l’article Guide pratique pour écrire des fonctions définies par l’utilisateur.For examples, see How to write user-defined functions article.

API de requête intégrée au langage JavaScriptJavaScript language-integrated query API

En plus de l’émission de requêtes à l’aide de la syntaxe de requête API SQL, le kit SDK côté serveur vous permet d’effectuer des requêtes à l’aide d’une interface JavaScript sans aucune connaissance de SQL.In addition to issuing queries using SQL API query syntax, the server-side SDK allows you to perform queries by using a JavaScript interface without any knowledge of SQL. L’API de requête JavaScript permet de créer programmatiquement des requêtes en passant des fonctions de prédicat dans une séquence d’appels de fonctions.The JavaScript query API allows you to programmatically build queries by passing predicate functions into sequence of function calls. Les requêtes sont analysées par le runtime JavaScript et exécutées efficacement dans Azure Cosmos DB.Queries are parsed by the JavaScript runtime and are executed efficiently within Azure Cosmos DB. Pour en savoir plus sur la prise en charge de l’API de requête JavaScript, consultez l’article Utilisation de l’API de requête intégrée au langage JavaScript.To learn about JavaScript query API support, see Working with JavaScript language integrated query API article. Pour obtenir des exemples, consultez l’article Guide pratique pour écrire des procédures stockées et des déclencheurs dans Azure Cosmos DB à l’aide de l’API de requête JavaScript.For examples, see How to write stored procedures and triggers using Javascript Query API article.

Étapes suivantesNext steps

Consultez les articles suivants pour découvrir comment écrire et utiliser des procédures stockées, des déclencheurs et des fonctions définies par l’utilisateur dans Azure Cosmos DB :Learn how to write and use stored procedures, triggers, and user-defined functions in Azure Cosmos DB with the following articles: