Compartilhar via

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

  • Aplica-se a: ✅ NoSQL

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

Benefícios de usar a programação do lado do servidor

A gravação de procedimentos armazenados, gatilhos e UDFs (funções definidas pelo usuário) no JavaScript permite que você crie aplicativos avançados e eles têm as seguintes vantagens:

  • Lógica de procedimento: O JavaScript é uma linguagem de programação de alto nível que fornece uma interface avançada e familiar 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 único procedimento armazenado ou em 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 sejam bem-sucedidas ou nenhuma delas tenha êxito.

  • Desempenho: Os dados JSON são mapeados intrinsecamente 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 disponibilizá-los sob demanda para o código em execução. Há outros benefícios de desempenho associados à mudança da lógica de negócios para o banco de dados, que incluem:

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

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

    • Seqüenciamento: Às vezes, as operações precisam de um mecanismo de gatilho que possa executar uma ou mais atualizações para os dados. Além da Atomicidade, também há benefícios de desempenho com a execução do servidor.

  • Encapsulamento: Os procedimentos armazenados podem ser usados para agrupar a lógica em um só lugar. O encapsulamento adiciona uma camada de abstração sobre os dados, o que permite que você evolua seus aplicativos independentemente dos dados. Essa camada de abstração é útil quando os dados não têm esquema e você não precisa gerenciar a adição de lógica adicional diretamente ao seu aplicativo. A abstração permite manter os dados seguros simplificando o acesso dos scripts.

Dica

Os procedimentos armazenados são mais adequados para operações que são intensivas em gravação e exigem uma transação envolvendo um valor de chave de partição. Ao decidir se deseja usar procedimentos armazenados, otimize em torno de encapsular a quantidade máxima de gravações possível. De modo geral, os procedimentos armazenados não são os meios mais eficientes para fazer um grande número de operações de leitura ou consulta, portanto, o uso de procedimentos armazenados para um grande número de leituras em lote para retornar ao 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.

O uso de procedimentos armazenados com consistência forte não é sugerido, pois as mutações são locais.

Observação

Os recursos JavaScript do lado do servidor, incluindo procedimentos armazenados, gatilhos e funções definidas pelo usuário, não dão 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 executadas 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.

  • Atomicidade Garante que todas as operações realizadas dentro de uma transação sejam tratadas como uma única unidade, e que ou todas sejam confirmadas ou que nenhuma seja.

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

  • O isolamento garante que nenhuma transação interfira uma com a outra– muitos sistemas comerciais fornecem vários níveis de isolamento que podem ser usados com base nas necessidades do aplicativo.

  • A durabilidade garante que qualquer alteração confirmada em um banco de dados sempre estará presente.

No Azure Cosmos DB, o runtime do JavaScript é hospedado dentro do mecanismo de banco de dados. Portanto, as solicitações feitas nos procedimentos armazenados e nos 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 de um gatilho. Para obter exemplos, veja como implementar o artigo de transações .

Dica

Para obter suporte a transações no Azure Cosmos DB para NoSQL, você também pode implementar um lote transacional usando o SDK do cliente preferencial. Para obter mais informações, consulte operações em lotes transacionais no Azure Cosmos DB para NoSQL.

Escopo de uma transação

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

Confirmação e reversão

As transações são integradas nativamente ao modelo de programação JavaScript do Azure Cosmos DB. Dentro de uma função JavaScript, todas as operações são automaticamente encapsuladas em uma única transação. Se a lógica 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 (familiares a bancos de dados relacionais) estã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

Procedimentos armazenados e gatilhos são sempre executados na réplica primária de um contêiner do Azure Cosmos DB. Esse recurso garante que as leituras de procedimentos armazenados ofereçam forte consistência. As consultas que usam funções definidas pelo usuário podem ser executadas na réplica primária ou 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 alterações em itens feitas pela mesma transação de script. Essa instrução se aplica tanto a consultas SQL, como getContent().getCollection().queryDocuments(), quanto a consultas de linguagem integradas, como getContext().getCollection().filter().

Execução delimitada

Todas as operações do Azure Cosmos DB devem ser concluídas dentro da duração do tempo limite especificada. Os procedimentos armazenados têm um limite de tempo limite de 5 segundos. Essa restrição se aplica a funções 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.

Você pode garantir que suas funções JavaScript terminem dentro do limite de tempo ou implementem um modelo baseado em continuação para executar em lote/retomar a execução. Para 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, criar, ler, atualizar e excluir itens) retornam um valor booliano que representa se essa operação será concluída. Se esse valor for falso, é uma indicação de que o procedimento deve encerrar a execução porque o script está consumindo mais tempo ou taxa de transferência provisionada do que o valor configurado. As operações enfileiradas antes da primeira operação de repositório não aceita têm a garantia de serem concluídas se o procedimento armazenado for concluído a tempo e não enfileirar mais nenhuma solicitação. Portanto, as operações devem ser enfileiradas uma de cada 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 lado do servidor, eles são estritamente controlados. 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 honrar os limites de execução.

As funções 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 largura de banda adicional além da já utilizada na execução de operações de banco de dados, entretanto, essas operações de banco de dados são um pouco mais baratas do que as mesmas operações executadas pelo cliente.

Triggers

O Azure Cosmos DB dá suporte a dois tipos de gatilhos:

Pré-gatilhos

O Azure Cosmos DB fornece gatilhos que podem ser invocados executando 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 de o item ser criado. Os 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 da 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, consulte o artigo Como escrever gatilhos .

Pós-disparadores

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, consulte o artigo Como escrever gatilhos .

Observação

Os gatilhos registrados não são executados automaticamente quando suas operações correspondentes (criar/excluir/substituir/atualizar) ocorrem. Eles precisam ser chamados explicitamente ao executar essas operações. Para saber mais, veja 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 NoSQL e implementar a lógica de negócios personalizada facilmente. Eles podem ser chamados somente em consultas. As UDFs não têm acesso ao objeto de contexto e devem ser usadas como JavaScript exclusivo para computação. Portanto, as UDFs podem ser executadas em réplicas secundárias.

API de consulta integrada à linguagem JavaScript

Além de emitir consultas usando a sintaxe de consulta API para NoSQL, o SDK do lado do servidor permite que você execute consultas usando uma interface JavaScript sem qualquer conhecimento do SQL. A API de consulta JavaScript permite criar consultas de forma programática, passando funções de predicado para uma cadeia de chamadas de funções. 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 JavaScript, consulte o artigo sobre como Trabalhar com a API de consulta integrada à linguagem JavaScript. Para obter exemplos, consulte Como gravar procedimentos armazenados e gatilhos usando o artigo da API de Consulta 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 seu cluster de banco de dados existente para planejamento de capacidade.

  • Last updated on