Procedimentos armazenados, gatilhos e funções definidas pelo usuário

  • Artigo

APLICA-SE A: NoSQL

O Azure Cosmos DB fornece execução transacional e integrada à linguagem de JavaScript. Ao usar a API para SQL no Azure Cosmos DB, você poderá escrever procedimentos armazenados, gatilhos e UDFs (funções definidas pelo usuário) na linguagem JavaScript. Escreva sua lógica em JavaScript que é executada dentro do mecanismo de banco de dados. É possível criar e executar gatilhos, procedimentos armazenados e UDFs usando o portal do Azure, a API de consulta integrada de linguagem JavaScript no Azure Cosmos DB ou os SDKs de cliente do Azure Cosmos DB for NoSQL.

Benefícios do uso da programação do servidor

A escrita de procedimentos armazenados, gatilhos e UDFs (funções definidas pelo usuário) em JavaScript permite que você crie aplicativos sofisticados e que eles tenham as seguintes vantagens:

  • Lógica de procedimento: o JavaScript é uma linguagem de programação de alto nível que oferece uma interface rica e já conhecida para expressar a lógica de negócios. Você pode executar uma sequência de operações complexas nos dados.

  • Transações atômicas: as operações de banco de dados do Azure Cosmos DB executadas em um procedimento armazenado ou um gatilho são atômicas. Essa funcionalidade atômica permite que um aplicativo combine operações relacionadas em um único lote, de modo que todas as operações ou nenhuma delas seja bem-sucedida.

  • Desempenho: os dados JSON são intrinsecamente mapeados para o sistema de tipos de linguagem JavaScript. Esse mapeamento permite uma série de otimizações, como a materialização lenta de documentos JSON no pool de buffers e sua disponibilização sob demanda para o código em execução. Há outros benefícios de desempenho associados à alternância da lógica de negócios para o banco de dados, que incluem:

    • Lote: você pode agrupar operações como inserções e enviá-las em massa. Os custos de latência do tráfego de rede e a sobrecarga de armazenamento para criar transações separadas são reduzidos significativamente.

    • Pré-compilação: os procedimentos armazenados, os gatilhos e as UDFs são pré-compilados implicitamente no formato de código de bytes, para evitar os custos de compilação no momento da invocação de cada script. Devido à pré-compilação, a invocação de procedimentos armazenados é rápida e tem um volume baixo.

    • Sequenciamento: às vezes, as operações precisam de um mecanismo de disparo que possa executar uma ou mais atualizações nos dados. Além da Atomicidade, também há benefícios de desempenho com a execução do servidor.

  • Encapsulamento: procedimentos armazenados podem ser usados para agrupar lógica em um só lugar. O encapsulamento adiciona uma camada de abstração aos dados, o que permite que você desenvolva seus aplicativos de maneira independente dos dados. Essa camada de abstração é útil quando os dados são sem esquema e você não precisa gerenciar a adição de lógica extra diretamente no aplicativo. A abstração permite manter os dados seguros simplificando o acesso pelos scripts.

Dica

Os procedimentos armazenados são mais adequados para operações que são de gravação pesada e exigem uma transação em um valor de chave de partição. Quando você decidir em que local usar procedimentos armazenados, otimize o encapsulamento da quantidade máxima possível de gravações. Em termos gerais, os procedimentos armazenados não são o meio mais eficaz para fazer grandes quantidades de operações de leitura ou consulta. Portanto, o uso de procedimentos armazenados para criar um lote de uma grande quantidade de leituras para retorná-las para o cliente não produzirá o benefício desejado. Para obter o melhor desempenho, essas operações de leitura pesada devem ser feitas no lado do cliente, usando o SDK do Azure Cosmos DB.

Observação

Os recursos javaScript do lado do servidor, incluindo procedimentos armazenados, gatilhos e funções definidas pelo usuário, não oferecem suporte à importação de módulos.

Transactions

A transação em um banco de dados típico pode ser definida como uma sequência de operações realizadas como uma única unidade lógica de trabalho. Cada transação fornece garantias de propriedade ACID. ACID é um acrônimo bastante conhecido que indica: Atomicidade, Consistência, Isolamento e Durabilidade.

  • A atomicidade garante que todas as operações feitas dentro de uma transação sejam tratadas como uma unidade: ou todas elas são confirmadas, ou nenhuma o é.

  • A consistência assegura que os dados estejam sempre em um estado válido entre as transações.

  • O isolamento garante que duas transações não interfiram uma com a outra. Muitos sistemas comerciais fornecem vários níveis de isolamento que podem ser usados com base nas necessidades de cada aplicativo.

  • A durabilidade cuida para que qualquer alteração confirmada em um banco de dados esteja sempre presente.

No Azure Cosmos DB, o runtime do JavaScript é hospedado dentro do mecanismo de banco de dados. Portanto, as solicitações feitas dentro dos procedimentos armazenados e dos gatilhos são executadas no mesmo escopo da sessão do banco de dados. Esse recurso permite que o Azure Cosmos DB garanta propriedades ACID para todas as operações que fazem parte de um procedimento armazenado ou um gatilho. Para obter exemplos, confira o artigo Como implementar transações.

Dica

Para suporte a transações no Azure Cosmos DB for NoSQL, você também pode implementar um lote transacional usando seu SDK preferido do cliente. Para obter mais informações, consulte Operações de lotes transacionais no Azure Cosmos DB for NoSQL.

Escopo de uma transação

Os procedimentos armazenados são associados a um contêiner do Azure Cosmos DB, e a execução do procedimento armazenado tem como escopo uma chave de partição lógica. Os procedimentos armazenados precisam incluir um valor de chave de partição lógica durante a execução que define a partição lógica do escopo da transação. Para obter mais informações, confira o artigo Particionamento do Azure Cosmos DB.

Confirmação e reversão

As transações são nativamente integradas ao modelo de programação do JavaScript do Azure Cosmos DB. Dentro de uma função do JavaScript, todas as operações são encapsuladas automaticamente em uma única transação. Se a lógica do JavaScript em um procedimento armazenado for concluída sem exceções, todas as operações dentro da transação serão confirmadas no banco de dados. Instruções como BEGIN TRANSACTION e COMMIT TRANSACTION (conhecidas por bancos de dados relacionais) são implícitas no Azure Cosmos DB. Se houver exceções do script, o runtime do JavaScript do Azure Cosmos DB reverterá a transação inteira. Dessa forma, gerar uma exceção é efetivamente equivalente a um ROLLBACK TRANSACTION no Azure Cosmos DB.

Consistência de dados

Os procedimentos armazenados e os gatilhos são sempre executados na réplica primária de um contêiner do Azure Cosmos DB. Esse recurso garante que as leituras dos procedimentos armazenados ofereçam coerência forte. As consultas que usam funções definidas pelo usuário podem ser executadas na réplica primária ou em qualquer réplica secundária. Os procedimentos armazenados e os gatilhos destinam-se a dar suporte a gravações transacionais. Enquanto isso, a lógica somente leitura é melhor implementada como lógica do lado do aplicativo e consultas usando os SDKs do Azure Cosmos DB for NoSQL, o que ajudará você a saturar a taxa de transferência do banco de dados.

Dica

As consultas executadas em um procedimento armazenado ou gatilho podem não ver as alterações nos itens feitas pela mesma transação de script. Essa instrução se aplica a consultas SQL, como getContent().getCollection().queryDocuments(), além de consultas de linguagem integradas, como getContext().getCollection().filter().

Execução vinculada

Todas as operações do Azure Cosmos DB precisam ser concluídas dentro da duração de tempo limite especificada. Os procedimentos armazenados têm um tempo limite de 5 segundos. Esta restrição se aplica às funções do JavaScript: procedimentos armazenados, gatilhos e funções definidas pelo usuário. Se uma operação não for concluída dentro desse limite de tempo, a transação será revertida.

Garanta que as funções do JavaScript sejam concluídas dentro do limite de tempo ou implemente um modelo baseado em continuação para criar um lote/retomar a execução. A fim de simplificar o desenvolvimento de procedimentos armazenados e gatilhos para lidar com limites de tempo, todas as funções no contêiner do Azure Cosmos DB (por exemplo, criação, leitura, atualização e excluir itens) retornam um valor booliano que informa se a operação será concluída. Se esse valor for falso, ele será uma indicação de que o procedimento precisará encapsular a execução porque o script está consumindo mais tempo ou uma taxa de transferência provisionada maior do que o valor configurado. Operações colocadas em fila antes da primeira operação de armazenamento não aceita serão concluídas com certeza se o procedimento armazenado for concluído dentro do tempo e não colocar nenhuma outra solicitação em fila. Portanto, as operações devem ser colocadas na fila uma por vez usando a convenção de retorno de chamada do JavaScript para gerenciar o fluxo de controle do script. Como os scripts são executados em um ambiente do servidor, eles são estritamente controlados. Os scripts que violam repetidamente os limites de execução podem ser marcados como inativos e não podem ser executados e devem ser recriados para respeitar os limites de execução.

As funções do JavaScript também estão sujeitas à capacidade de taxa de transferência provisionada. As funções do JavaScript podem acabar usando um grande número de unidades de solicitação em um curto período e podem ter a taxa limitada se o limite da capacidade de taxa de transferência provisionada é atingido. É importante observar que os scripts consomem uma taxa de transferência adicional, além da taxa de transferência gasta executando operações de banco de dados, embora essas operações de banco de dados sejam um pouco mais baratas do que as mesmas operações executadas no cliente.

Gatilhos

O Azure Cosmos DB é compatível com dois tipos de gatilho:

Pré-gatilhos

O Azure Cosmos DB fornece gatilhos que podem ser invocados com a execução de uma operação em um item do Azure Cosmos DB. Por exemplo, você pode especificar um pré-gatilho ao criar um item. Nesse caso, o pré-gatilho será executado antes da criação do item. Pré-gatilhos não podem ter parâmetros de entrada. Se necessário, o objeto de solicitação pode ser usado para atualizar o corpo do documento na solicitação original. Quando os gatilhos são registrados, os usuários podem especificar as operações com as quais eles podem ser executados. Se um gatilho foi criado com TriggerOperation.Create, isso significa que o uso do gatilho em uma operação de substituição não será permitido. Para obter exemplos, confira o artigo Como escrever gatilhos.

Pós-gatilhos

Assim como os pré-gatilhos, os pós-gatilhos também estão associados a uma operação em um item do Azure Cosmos DB e não exigem nenhum parâmetro de entrada. Eles são executados após a conclusão da operação e têm acesso à mensagem de resposta enviada ao cliente. Para obter exemplos, confira o artigo Como escrever gatilhos.

Observação

Os gatilhos registrados não são executados automaticamente quando as operações correspondentes (criar/excluir/substituir/atualizar) acontecem. Eles precisam ser chamados explicitamente ao executar essas operações. Para saber mais, confira o artigo como executar gatilhos.

Funções definidas pelo usuário

As UDFs (funções definidas pelo usuário) são usadas para estender a sintaxe da linguagem de consulta da API para NoSQL e implementar uma lógica de negócios personalizada com facilidade. Elas podem ser chamadas somente em consultas. As UDFs não têm acesso ao objeto de contexto e devem ser usadas como JavaScript somente para cálculo. Portanto, as UDFs podem ser executadas em réplicas secundárias.

API de consulta integrada da linguagem JavaScript

Além de emitir consultas usando a sintaxe de consulta da API para SQL, o SDK do servidor permite que você execute consultas usando uma interface JavaScript sem nenhum conhecimento de SQL. A API de consulta do JavaScript permite que você crie consultas de forma programática passando funções de predicado em uma sequência de chamadas de função. As consultas são analisadas pelo runtime do JavaScript e são executadas com eficiência no Azure Cosmos DB. Para saber mais sobre o suporte à API de consulta do JavaScript, confira o artigo Trabalhando com a API de consulta integrada à linguagem do JavaScript. Para obter exemplos, confira o artigo Como escrever procedimentos armazenados e gatilhos usando a API de Consulta do JavaScript.

Próximas etapas

Saiba como escrever e usar procedimentos armazenados, gatilhos e funções definidas pelo usuário no Azure Cosmos DB com os seguintes artigos:

Tentando fazer um planejamento de capacidade para uma migração para o Microsoft Azure Cosmos DB? Você pode usar informações sobre o cluster de banco de dados existente para fazer isso.