Stored procedure, trigger e funzioni definite dall'utente

  • Articolo

SI APPLICA A: NoSQL

Azure Cosmos DB offre l'esecuzione transazionale di JavaScript integrata nel linguaggio. Quando si usa l'API per NoSQL in Azure Cosmos DB, è possibile scrivere stored procedure, triggere funzioni definite dall'utente nel linguaggio JavaScript. È possibile scrivere la logica nel linguaggio JavaScript eseguito all'interno del motore di database. È possibile creare ed eseguire trigger, stored procedure e funzioni definite dall'utente usando il portale di Azure, l'API di query integrata del linguaggio JavaScript in Azure Cosmos DB o gli SDK client di Azure Cosmos DB for NoSQL.

Vantaggi dell'uso della programmazione lato server

La scrittura di stored procedure, trigger e funzioni definite dall'utente (UDF) in JavaScript consente di creare applicazioni avanzate con i vantaggi seguenti:

  • Logica procedurale: come linguaggio di programmazione di alto livello, JavaScript offre un'interfaccia completa e familiare per esprimere la logica di business. È possibile eseguire una sequenza di operazioni complesse sui dati.

  • Transazioni atomiche: le operazioni di database di Azure Cosmos DB eseguite all'interno di una singola stored procedure o un trigger sono atomiche. Questa funzionalità atomica consente a un'applicazione di combinare le operazioni correlate in un unico batch, in modo che o nessuna o tutte abbiano esito positivo.

  • Prestazioni: i dati JSON sono intrinsecamente mappati al sistema di tipi di linguaggio JavaScript. Questo mapping consente un numero di ottimizzazioni, ad esempio la materializzazione differita dei documenti JSON nel pool di buffer e la relativa disponibilità su richiesta per il codice di esecuzione. Vi sono altri vantaggi relativi alle prestazioni associati al passaggio della logica di business al database, tra cui:

    • Invio in batch: è possibile raggruppare operazioni come gli inserimenti e inviarle in blocco. Ciò comporta una drastica riduzione dei costi legati alla latenza del traffico di rete e dei costi generali di archiviazione per la creazione di transazioni separate.

    • Precompilazione: le stored procedure, i trigger e le UDF vengono precompilati implicitamente nel formato di codice byte per evitare costi di compilazione a ogni chiamata dello script. La precompilazione garantisce velocità elevata e footprint ridotto delle chiamate delle stored procedure.

    • Sequenza: a volte le operazioni necessitano di un meccanismo di attivazione che possa eseguire uno o più aggiornamenti per i dati. Oltre all'atomicità, esistono anche vantaggi per le prestazioni durante l'esecuzione sul lato server.

  • Incapsulamento: è possibile usare le stored procedure per raggruppare la logica in un solo posto. L'incapsulamento aggiunge un livello di astrazione al di sopra dei dati, consentendo l'evoluzione delle applicazioni indipendentemente dai dati. Questo livello di astrazione è utile quando i dati sono senza schema e non è necessario gestire l'aggiunta di altra logica direttamente nell'applicazione. Questa astrazione consente di proteggere i dati semplificando l'accesso dagli script.

Suggerimento

Le stored procedure sono più adatte per le operazioni che richiedono un utilizzo elevato di scrittura e richiedono una transazione in un valore di chiave di partizione. Quando si decide se usare le stored procedure, eseguire l'ottimizzazione incapsulando la quantità massima di possibili operazioni di scrittura. In generale, le stored procedure non sono il modo più efficiente per eseguire un numero elevato di operazioni di lettura o query. Pertanto, l'uso delle stored procedure per inviare in batch un numero elevato di operazioni di lettura da restituire al client non produrrà i vantaggi desiderati. Per ottenere prestazioni ottimali, è consigliabile eseguire queste operazioni di lettura sul lato client usando Azure Cosmos DB SDK.

Nota

Le funzionalità JavaScript lato server, inclusi stored procedure, trigger e funzioni definite dall'utente, non supportano l'importazione di moduli.

Transazioni

Una transazione in un tipico database può essere definita come una sequenza di operazioni eseguite come singola unità di lavoro logica. Ogni transazione offre garanzie di proprietà ACID. ACID è un acronimo noto che riassume quattro proprietà: Atomicità, Coerenza, Isolamento e Durabilità.

  • L'atomicità garantisce che tutte le operazioni eseguite nell'ambito di una transazione siano trattate come unità singola e che venga eseguito il commit di tutte le operazioni o di nessuna di esse.

  • La coerenza garantisce che i dati siano sempre in uno stato valido in tutte le transazioni.

  • L'isolamento garantisce che non vi siano transazioni conflittuali. La maggior parte dei sistemi commerciali offre più livelli di isolamento utilizzabili in base alle esigenze dell'applicazione.

  • La durabilità assicura che qualsiasi modifica di cui sia stato eseguito il commit in un database sia sempre presente.

In Azure Cosmos DB il runtime di JavaScript è ospitato all'interno del motore di database. Di conseguenza, le richieste effettuate nelle stored procedure e nei trigger vengono eseguite nello stesso ambito di una sessione di database. Questa funzionalità consente ad Azure Cosmos DB di garantire proprietà ACID per tutte le operazioni che fanno parte di una stored procedure o di un singolo trigger. Per gli esempi, vedere l'articolo relativo a come implementare le transazioni.

Suggerimento

Per il supporto delle transazioni in Azure Cosmos DB for NoSQL, è anche possibile implementare un batch transazionale usando l'SDK client preferito. Per altre informazioni, vedere operazioni batch transazionali in Azure Cosmos DB for NoSQL.

Ambito di una transazione

Le stored procedure sono associate a un contenitore di Azure Cosmos DB e l'esecuzione di stored procedure ha come ambito una chiave di partizione logica. Le stored procedure devono includere un valore di chiave di partizione logica durante l'esecuzione che definisce la partizione logica per l'ambito della transazione. Per altre informazioni, vedere l'articolo Partizionamento di Azure Cosmos DB.

Commit e rollback

Le transazioni sono integrate in modo nativo nel modello di programmazione JavaScript di Azure Cosmos DB. All'interno di una funzione JavaScript, viene eseguito il wrapping di tutte le operazioni in un'unica transazione. Se la logica JavaScript in una stored procedure viene completata senza eccezioni, nel database viene eseguito il commit di tutte le operazioni all'interno della transazione. Istruzioni come BEGIN TRANSACTION e COMMIT TRANSACTION (familiari nei database relazionali) sono implicite in Azure Cosmos DB. Se si verifica un'eccezione dallo script, il runtime JavaScript di Cosmos DB esegue il rollback dell'intera transazione. Di per sé, generare un'eccezione equivale effettivamente a una ROLLBACK TRANSACTION in Azure Cosmos DB.

Coerenza dei dati

Le stored procedure e i trigger vengono sempre eseguiti nella replica primaria del contenitore di Azure Cosmos DB. Questa funzionalità garantisce la coerenza assoluta delle letture dalle stored procedure. Le query che usano funzioni definite dall'utente possono essere eseguite nella replica primaria o in qualsiasi replica secondaria. Le stored procedure e i trigger sono progettati per supportare scritture transazionali, mentre la logica di sola lettura viene implementata meglio come logica sul lato applicazione e le query che usano gli SDK di Azure Cosmos DB for NoSQL consentiranno di saturare la velocità effettiva del database.

Suggerimento

Le query eseguite all'interno di una stored procedure o di un trigger potrebbero non visualizzare modifiche agli elementi apportati dalla stessa transazione script. Questa istruzione si applica sia alle query SQL, ad esempio getContent().getCollection.queryDocuments(), sia alle query del linguaggio integrate, ad esempio getContext().getCollection().filter().

Esecuzione vincolata

Tutte le operazioni di Azure Cosmos DB devono essere completate entro la scadenza specificata. Le stored procedure hanno un limite di timeout di 5 secondi. Questo vincolo si applica anche alle funzioni JavaScript (stored procedure, trigger e funzioni definite dall'utente). Se un'operazione non viene completata entro questo limite di tempo, viene eseguito il rollback della transazione.

È possibile verificare che le funzioni JavaScript terminino entro il tempo limite oppure implementare un modello basato sulla continuazione in modo da riprendere l'esecuzione o eseguirla in batch. Per semplificare lo sviluppo delle stored procedure e dei trigger per la gestione dei limiti di tempo, tutte le funzioni nel contenitore di Azure Cosmos DB (ad esempio per creare, leggere, aggiornare ed eliminare gli elementi) restituiscono un valore booleano che indica se l'operazione verrà completata. Se questo valore è false, è un'indicazione che la procedura deve eseguire il wrapping dell'esecuzione perché lo script usa più tempo o velocità effettiva con provisioning rispetto al valore configurato. Il completamento delle operazioni inserite in coda precedentemente alla prima operazione di archiviazione non accettata è garantito se la stored procedure viene completata in tempo e non vengono inserite in coda altre richieste. Di conseguenza, le operazioni devono essere accodate una alla volta usando convenzioni di callback di JavaScript per gestire il flusso di controllo dello script. Poiché gli script vengono eseguiti in un ambiente lato server, sono strettamente regolati. Gli script che violano ripetutamente i limiti di esecuzione possono essere contrassegnati come inattivi e non possono essere eseguiti. Devono essere ricreati per rispettare i limiti di esecuzione.

Le funzioni JavaScript sono anche soggette alla capacità di velocità effettiva con provisioning. È possibile che le funzioni JavaScript finiscano per usare un numero elevato di unità richiesta entro un breve periodo di tempo e siano soggette a velocità limitata se viene raggiunto il limite di capacità di velocità effettiva con provisioning. È importante notare che gli script usano velocità effettiva aggiuntiva oltre a quella usata per l'esecuzione delle operazioni di database, anche se queste operazioni di database sono leggermente meno costose rispetto all'esecuzione delle stesse operazioni a partire dal client.

Trigger

Azure Cosmos DB supporta due tipi di trigger:

Pre-trigger

Azure Cosmos DB include trigger che possono essere richiamati eseguendo un'operazione su un elemento di Azure Cosmos DB. È ad esempio possibile specificare un pre-trigger durante la creazione di un elemento. In questo caso, il pre-trigger verrà eseguito prima della creazione dell'elemento. I pre-trigger non possono avere parametri di input. Se necessario, l'oggetto richiesta è utilizzabile per aggiornare il corpo del documento della richiesta originale. Quando i trigger vengono registrati, gli utenti possono specificare le operazioni con le quali è possibile eseguirli. Se un trigger è stato creato con TriggerOperation.Create, non sarà consentito usarlo in un'operazione di sostituzione. Per gli esempi, vedere Come scrivere i trigger.

Post-trigger

Analogamente ai pre-trigger, anche i post-trigger sono associati a un'operazione su un elemento di Azure Cosmos DB e non richiedono parametri di input. Vengono eseguiti dopo il completamento dell'operazione e hanno accesso al messaggio di risposta inviato al client. Per gli esempi, vedere Come scrivere i trigger.

Nota

I trigger registrati non vengono eseguiti automaticamente quando si verificano le operazioni corrispondenti (creazione/eliminazione/sostituzione/aggiornamento). Devono essere chiamati in modo esplicito durante l'esecuzione di queste operazioni. Per altre informazioni, vedere l'articolo Come eseguire trigger.

Funzioni definite dall'utente

Le funzioni definite dall'utente, o UDF, consentono di estendere la sintassi del linguaggio di query dell'API per NoSQL e implementare facilmente la logica di business. Possono essere chiamate solo all'interno di query. Non hanno accesso all'oggetto contesto e vanno usate come JavaScript di solo calcolo. È quindi possibile eseguire le funzioni definite dall'utente su repliche secondarie.

API di query integrate nel linguaggio JavaScript

Oltre a eseguire una query utilizzando la sintassi delle query dell'API per NoSQL, l'SDK sul lato server consente di eseguire query tramite un'interfaccia JavaScript senza alcuna conoscenza di SQL. L'API di query JavaScript consente di creare query a livello di codice passando funzioni predicato nella sequenza delle chiamate di funzione. Le query vengono analizzate dal runtime JavaScript ed eseguite in modo efficiente usando Azure Cosmos DB. Per altre informazioni sul supporto delle API di query JavaScript, vedere l'articolo Utilizzo dell'API di query integrata nel linguaggio JavaScript. Per gli esempi, vedere l'articolo Come scrivere stored procedure e trigger in Azure Cosmos DB usando l'API di query di JavaScript.

Passaggi successivi

È possibile ottenere informazioni su come usare stored procedure, trigger e funzioni definite dall'utente in Azure Cosmos DB facendo riferimento ai seguenti articoli:

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.