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

  • Artigo

APLICA-SE A: NoSQL

O Azure Cosmos DB fornece uma execução transacional de linguagem integrada de JavaScript. Ao usar a API para NoSQL no Azure Cosmos DB, você pode escrever procedimentos armazenados, gatilhos e funções definidas pelo usuário (UDFs) 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 à linguagem JavaScript no Azure Cosmos DB ou o Azure Cosmos DB para SDKs de cliente NoSQL.

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

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

  • Lógica processual: JavaScript é uma linguagem de programação de alto nível que fornece uma interface rica 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 seja bem-sucedida.

  • Desempenho: Os dados JSON são intrinsecamente mapeados para o sistema de tipo de linguagem JavaScript. Esse mapeamento permite uma série de otimizações, como a materialização preguiçosa de documentos JSON no buffer pool 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:

    • Lotes: você pode agrupar operações como inserções e enviá-las em massa. Os custos de latência de tráfego de 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 invocação de procedimentos armazenados é rápida e tem um baixo espaço ocupado.

    • Sequenciamento: Às vezes, as operações precisam de um mecanismo de acionamento que pode executar uma ou atualizações adicionais nos dados. Além da Atomicidade, há também benefícios de desempenho ao executar no lado 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 em seu aplicativo. A abstração permite manter os dados seguros, simplificando o acesso a partir dos scripts.

Gorjeta

Os procedimentos armazenados são mais adequados para operações com muita gravação e que exigem uma transação através de um valor de chave de partição. Ao decidir se deseja usar procedimentos armazenados, otimize em torno do encapsulamento da quantidade máxima de gravações possível. De um modo geral, os procedimentos armazenados não são o meio mais eficiente para fazer um grande número de operações de leitura ou consulta, portanto, usar procedimentos armazenados para agrupar um grande número de leituras 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.

Nota

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

Transações

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 bem conhecido que significa: Atomicity, Consistency, I solation, e Durability.

  • A atomicidade garante que todas as operações realizadas dentro de uma transação são tratadas como uma única unidade, e todas elas estão comprometidas ou nenhuma delas está.

  • A consistência garante que os dados estejam sempre em um estado válido nas 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 esteja sempre presente.

No Azure Cosmos DB, o tempo de execução do JavaScript é hospedado dentro do mecanismo de banco de dados. Assim, as solicitações feitas dentro dos procedimentos armazenados e os gatilhos são executados 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, consulte o artigo como implementar transações .

Gorjeta

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

Âmbito 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 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 aos bancos de dados relacionais) estão implícitas no Azure Cosmos DB. Se houver exceções do script, o tempo de execução do JavaScript do Azure Cosmos DB reverterá toda a transação. Como tal, lançar uma exceção é efetivamente equivalente a uma 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 de procedimentos armazenados ofereçam forte consistência. As consultas usando 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 suportar gravações transacionais. Enquanto isso, a lógica somente leitura é melhor implementada como lógica do lado do aplicativo e consultas usando o Azure Cosmos DB para SDKs NoSQL, o que ajudará você a saturar a taxa de transferência do banco de dados.

Gorjeta

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

Execução vinculada

Todas as operações do Azure Cosmos DB devem ser concluídas dentro da duração de 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 prazo, a transação será revertida.

Você pode garantir que suas funções JavaScript terminem dentro do limite de tempo ou implementar um modelo baseado em continuação para a execução em lote/retomada. 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 booleano que representa se essa operação será concluída. Se esse valor for false, é 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 armazenamento não aceito têm garantia de conclusão se o procedimento armazenado for concluído a tempo e não enfileirar mais solicitações. Assim, 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 governados. 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 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 JavaScript podem potencialmente acabar usando um grande número de unidades de solicitação em um curto espaço de tempo e podem ser limitadas se o limite de capacidade de taxa de transferência provisionada for atingido. É importante observar que os scripts consomem 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 menos dispendiosas do que as mesmas operações executadas a partir do cliente.

Acionadores

O Azure Cosmos DB suporta dois tipos de acionadores:

Pré-acionadores

O Azure Cosmos DB fornece gatilhos que podem ser invocados executando uma operação em um item do Azure Cosmos DB. Por exemplo, pode especificar um pré-acionador quando cria um item. Neste caso, o pré-acionador será executado antes da criação do item. Os pré-acionadores 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 a partir da solicitação original. Quando os acionadores são registados, os utilizadores podem especificar as operações com as quais estes podem ser executados. Se um acionador tiver sido criado com TriggerOperation.Create, significa que não será permitido utilizar o acionador numa operação de substituição. Para obter exemplos, consulte o artigo Como escrever acionadores .

Pós-acionadores

Semelhante aos 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 que é enviada ao cliente. Para obter exemplos, consulte o artigo Como escrever acionadores .

Nota

Os gatilhos registrados não são executados automaticamente quando suas operações correspondentes (criar / excluir / substituir / atualizar) acontecem. Têm de ser chamados quando estas operações estiverem em execução. Para saber mais, consulte o artigo Como executar acionadores .

Funções definidas pelo utilizador

Funções definidas pelo usuário (UDFs) são usadas para estender a API para sintaxe de linguagem de consulta NoSQL e implementar lógica de negócios personalizada facilmente. Eles só podem ser chamados dentro de consultas. UDFs não têm acesso ao objeto de contexto e devem ser usados como JavaScript somente de computação. Portanto, UDFs podem ser executados em réplicas secundárias.

API de consulta integrada à linguagem JavaScript

Além de emitir consultas usando a sintaxe de consulta API for NoSQL, o SDK do lado do servidor permite que você execute consultas usando uma interface JavaScript sem qualquer conhecimento de SQL. A API de consulta JavaScript permite que você crie consultas programaticamente passando funções de predicado para uma sequência de chamadas de função. As consultas são analisadas pelo tempo de execução do JavaScript e executadas de forma eficiente no Azure Cosmos DB. Para saber mais sobre o suporte à API de consulta JavaScript, consulte o artigo Trabalhando com a API de consulta integrada à linguagem JavaScript. Para obter exemplos, consulte o artigo Como escrever procedimentos armazenados e gatilhos usando a API de consulta JavaScript.

Próximos passos

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 o planejamento de capacidade para uma migração para o Azure Cosmos DB? Você pode usar informações sobre seu cluster de banco de dados existente para planejamento de capacidade.