CREATE SEQUENCE (Transact-SQL)

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure

Cria um objeto de sequência e especifica suas propriedades. Uma sequência é um objeto associado a um esquema definido pelo usuário que gera uma sequência de valores numéricos de acordo com a especificação com a qual a sequência foi criada. A sequência de valores numéricos é gerada em ordem crescente ou decrescente em um intervalo definido e pode ser configurada para reiniciar (em um ciclo) quando se esgotar. As sequências, ao contrário de colunas de identidade, não são associadas a tabelas específicas. Os aplicativos fazem referência a um objeto de sequência para recuperar seu próximo valor. A relação entre sequências e tabelas é controlada pelo aplicativo. Os aplicativos de usuário podem referenciar um objeto de sequência e coordenar os valores nas várias linhas e tabelas.

Ao contrário de valores de colunas de identidade que são gerados quando as linhas são inseridas, um aplicativo pode obter o próximo número de sequência sem inserir a linha por meio da chamada da função NEXT VALUE FOR. Use sp_sequence_get_range para obter vários números de sequência de uma vez.

Para obter informações e cenários que usam CREATE SEQUENCE e a função NEXT VALUE FOR , consulte Números de sequência.

Convenções de sintaxe de Transact-SQL

Sintaxe

CREATE SEQUENCE [schema_name . ] sequence_name  
    [ AS [ built_in_integer_type | user-defined_integer_type ] ]  
    [ START WITH <constant> ]  
    [ INCREMENT BY <constant> ]  
    [ { MINVALUE [ <constant> ] } | { NO MINVALUE } ]  
    [ { MAXVALUE [ <constant> ] } | { NO MAXVALUE } ]  
    [ CYCLE | { NO CYCLE } ]  
    [ { CACHE [ <constant> ] } | { NO CACHE } ]  
    [ ; ]  

Argumentos

sequence_name
Especifica o nome exclusivo pelo qual a sequência é conhecida no banco de dados. O tipo é sysname.

[ built_in_integer_type | user-defined_integer_type
Uma sequência pode ser definida como qualquer tipo de inteiro. Os seguintes tipos são permitidos:

• tinyint – intervalo de 0 a 255
• smallint – intervalo de -32.768 a 32.767
• int – intervalo de -2.147.483.648 a 2.147.483.647
• bigint – intervalo -9.223.372.036.854.775.808 a 9.223.372.036.854.775.807
• decimal e numeric com uma escala de 0.
• Qualquer tipo de dados definido pelo usuário (tipo de alias) que seja baseado em um dos tipos permitidos.

Se nenhum tipo de dados for fornecido, o tipo de dados bigint será usado como o padrão.

START WITH <constant>
O primeiro valor retornado pelo objeto de sequência. O valor START deve ser menor ou igual ao valor máximo e maior ou igual ao valor mínimo do objeto de sequência. O valor de início padrão para um novo objeto de sequência é o valor mínimo para um objeto de sequência e o valor máximo de um objeto de sequência decrescente.

INCREMENT BY <constant>
O valor usado para incrementar (ou decrementar, se negativo) o valor do objeto de sequência para cada chamada da função NEXT VALUE FOR. Se o incremento for um valor negativo, o objeto de sequência será decrescente, caso contrário, será crescente. O incremento não pode ser 0. O incremento padrão para um novo objeto de sequência é 1.

[ MINVALUE <constant> | NO MINVALUE ]
Especifica os limites do objeto de sequência. O valor mínimo padrão de um novo objeto de sequência é o valor mínimo do tipo de dados do objeto de sequência. É zero para o tipo de dados tinyint e um número negativo para todos os outros tipos de dados.

[ MAXVALUE <constant> | NO MAXVALUE
Especifica os limites do objeto de sequência. O valor máximo padrão para um novo objeto de sequência é o valor máximo do tipo de dados do objeto de sequência.

[ CYCLE | NO CYCLE ]
Propriedade que especifica se o objeto de sequência deve reiniciar do valor mínimo (ou máximo para objetos de sequência decrescente) ou deve lançar uma exceção quando seu valor mínimo ou máximo é excedido. A opção de ciclo padrão para novos objetos de sequência é NO CYCLE.

[ CACHE [<constant> ] | NO CACHE ]
Aumenta o desempenho de aplicativos que usam objetos de sequência por meio da minimização do número de E/S de disco necessárias para gerar números de sequência. Padrões para o CACHE.

Por exemplo, se um tamanho de cache de 50 for escolhido, o SQL Server não manterá 50 valores individuais em cache. Somente permanecem em cache o valor atual e o número de valores restantes no cache. Isso significa que a quantidade de memória necessária para armazenar o cache sempre é duas instâncias do tipo de dados do objeto de sequência.

Quando criado com a opção CACHE, um desligamento inesperado (uma falta de energia, por exemplo) pode acarretar a perda dos números de sequência restantes no cache.

Comentários gerais

Os números de sequência são gerados fora do escopo da transação atual. Eles serão consumidos se a transação que usa o número de sequência for confirmada ou revertida. A validação duplicada só ocorre quando o registro está totalmente preenchido. Isso pode resultar em alguns casos em que o mesmo número é usado para mais de um registro durante a criação, mas em seguida é identificado como uma duplicata. Se isso ocorrer e outros valores de numeração automática tiverem sido aplicados a registros subsequentes, o resultado poderá ser um intervalo entre os valores de numeração automática, um comportamento esperado.

Gerenciamento de cache

Para aprimorar o desempenho, o SQL Server pré-aloca o número de números de sequência especificado pelo argumento CACHE.

Por exemplo, uma nova sequência é criada com um valor inicial de 1 e um tamanho de cache de 15. Quando o primeiro valor é necessário, valores de 1 a 15 são disponibilizados da memória. O último valor em cache (15) é gravado nas tabelas do sistema no disco. Quando todos os 15 números são usados, a solicitação seguinte (pelo número 16) faz com que o cache seja alocado novamente. O novo valor colocado no cache por último (30) será gravado nas tabelas do sistema.

Se o Mecanismo de Banco de Dados for interrompido depois que você usar 22 números, o próximo número de sequência pretendido na memória (23) será gravado nas tabelas do sistema, substituindo o número armazenado antes.

Após a reinicialização do SQL Server e quando um número de sequência for necessário, o número inicial será lido nas tabelas do sistema (23). A quantidade de cache de 15 números (23-38) é alocada para a memória e o próximo número não de cache (39) é gravado nas tabelas do sistema.

Se o Mecanismo de Banco de Dados parar de modo anormal para um evento, como uma falha de energia, a sequência reiniciará com o número lido nas tabelas do sistema (39). Todos os números de sequência alocados à memória (mas nunca solicitados por um usuário ou aplicativo) são perdidos. Essa funcionalidade pode deixar intervalos, mas garante que o mesmo valor nunca seja emitido duas vezes para um único objeto de sequência, a menos que seja definido como CYCLE ou reiniciado manualmente.

O cache é mantido na memória por meio do acompanhamento do valor atual (o último valor emitido) e o número de valores restantes no cache. Portanto, a quantidade de memória usada pelo cache sempre é duas instâncias do tipo de dados do objeto de sequência.

A configuração do argumento de cache como NO CACHE grava o valor de sequência atual nas tabelas do sistema sempre que uma sequência é usada. Isso pode prejudicar o desempenho ao aumentar o acesso ao disco, mas reduz a possibilidade de intervalos não intencionais. Ainda poderão ocorrer intervalos se os números forem solicitados com o uso das funções NEXT VALUE FOR ou sp_sequence_get_range, mas, neste caso, os números não são usados ou são utilizados em transações não confirmadas.

Quando um objeto de sequência usa a opção CACHE, se você reiniciar esse objeto ou alterar INCREMENT, CYCLE, MINVALUE, MAXVALUE ou as propriedades de tamanho de cache, isso fará com que o cache seja gravado nas tabelas do sistema, antes da alteração. Em seguida, o cache é recarregado a partir do valor atual (ou seja, nenhum número é ignorado). A alteração do tamanho do cache entra em vigor imediatamente.

Opção CACHE quando os valores em cache estão disponíveis

O processo a seguir ocorre sempre que um objeto de sequência recebe uma solicitação para gerar o próximo valor para a opção CACHE, caso haja valores não usados disponíveis no cache na memória para o objeto de sequência.

1. O próximo valor para o objeto de sequência é calculado.

2. O novo valor atual para o objeto de sequência é atualizado na memória.

3. O valor calculado é retornado à instrução de chamada.

Opção CACHE quando o cache está esgotado

O seguinte processo ocorre sempre que um objeto de sequência recebe uma solicitação para gerar o próximo valor para a opção CACHE, quando o cache está esgotado:

1. O próximo valor para o objeto de sequência é calculado.

2. O último valor para o novo cache é calculado.

3. A linha da tabela do sistema para o objeto de sequência está bloqueada, e o valor calculado na etapa 2 (o último valor) é gravado na tabela do sistema. Um xevent de cache esgotado é disparado para notificar o usuário sobre o novo valor contínuo.

Opção NO CACHE

O processo a seguir ocorre sempre que um objeto de sequência recebe uma solicitação para gerar o próximo valor para a opção NO CACHE:

1. O próximo valor para o objeto de sequência é calculado.

2. O novo valor atual para o objeto de sequência é gravado na tabela do sistema.

3. O valor calculado é retornado à instrução de chamada.

Metadados

Para obter informações sobre sequências, consulte sys.sequences.

Segurança

Permissões

Requer a permissão CREATE SEQUENCE, ALTERou CONTROL no SCHEMA.

• Membros das funções de banco de dados fixas db_owner e db_ddladmin podem criar, alterar e remover objetos de sequência.

• Os membros das funções de banco de dados fixas db_owner e db_datawriter podem atualizar os objetos de sequência fazendo com que gerem números.

O exemplo a seguir concede ao usuário permissão AdventureWorks\Larry criar sequências no esquema de teste.

GRANT CREATE SEQUENCE ON SCHEMA::Test TO [AdventureWorks\Larry]  

A propriedade de um objeto de sequência pode ser transferida usando a instrução ALTER AUTHORIZATION.

Se uma sequência utilizar um tipo de dados definido pelo usuário, o autor da sequência deverá ter a permissão REFERENCES nesse tipo.

Audit

Para auditar CREATE SEQUENCE, monitore o SCHEMA_OBJECT_CHANGE_GROUP.

Exemplos

Para obter exemplos de como criar sequências e usar a função NEXT VALUE FOR para gerar números de sequência, veja Números de sequência.

A maioria dos exemplos a seguir cria objetos de sequência em um esquema denominado Teste.

Para criar o esquema de Teste, execute a instrução a seguir.

CREATE SCHEMA Test ;  
GO  

a. Criando uma sequência que aumenta em 1

No exemplo a seguir, Thierry cria uma sequência chamada CountBy1, que aumenta em incrementos de um cada vez que é utilizada.

CREATE SEQUENCE Test.CountBy1  
    START WITH 1  
    INCREMENT BY 1 ;  
GO  

B. Criando uma sequência que diminui em 1

O exemplo a seguir inicia em 0 e conta em decrementos negativos de um cada vez que é usada.

CREATE SEQUENCE Test.CountByNeg1  
    START WITH 0  
    INCREMENT BY -1 ;  
GO  

C. Criando uma sequência que aumenta em 5

O exemplo a seguir cria uma sequência que aumenta em incrementos de 5 cada vez que é utilizada.

CREATE SEQUENCE Test.CountBy1  
    START WITH 5  
    INCREMENT BY 5 ;  
GO  

D. Criando uma sequência que começa com um número designado

Depois de importar uma tabela, Thierry percebe que o número de ID mais alto usado é 24.328. Thierry precisa de uma sequência que gerará números que comecem em 24.329. O código a seguir cria uma sequência que inicia com 24.329 e incrementos de 1.

CREATE SEQUENCE Test.ID_Seq  
    START WITH 24329  
    INCREMENT BY 1 ;  
GO  

E. Criando uma sequência usando valores padrão

O exemplo a seguir cria uma sequência que usa os valores padrão.

CREATE SEQUENCE Test.TestSequence ;  

Execute a instrução a seguir para exibir as propriedades da sequência.

SELECT * FROM sys.sequences WHERE name = 'TestSequence' ;  

Uma lista parcial da saída demonstra os valores padrão.

F. Criando uma sequência com um tipo de dados específico

O exemplo a seguir cria uma sequência usando o tipo de dados smallint, com um intervalo de -32.768 a 32.767.

CREATE SEQUENCE SmallSeq 
    AS smallint ;  

G. Criando uma sequência com todos os argumentos

O exemplo a seguir cria uma sequência chamada DecSeq usando o tipo de dados decimal, com um intervalo de 0 a 255. A sequência começa com 125 e é incrementada em 25 sempre que um número é gerado. Como a sequência é configurada para executar um ciclo quando o valor excede o valor máximo de 200, a sequência é reiniciada no valor mínimo de 100.

CREATE SEQUENCE Test.DecSeq  
    AS decimal(3,0)   
    START WITH 125  
    INCREMENT BY 25  
    MINVALUE 100  
    MAXVALUE 200  
    CYCLE  
    CACHE 3  
;  

Execute a instrução a seguir para visualizar o primeiro valor; a opção START WITH de 125.

SELECT NEXT VALUE FOR Test.DecSeq;  

Execute a instrução mais três vezes para retornar 150, 175 e 200.

Execute a instrução novamente para saber como o valor inicial volta para a opção MINVALUE de 100.

Execute o código a seguir para confirmar o tamanho do cache e visualizar o valor atual.

SELECT cache_size, current_value   
FROM sys.sequences  
WHERE name = 'DecSeq' ;  

Consulte Também

ALTER SEQUENCE (Transact-SQL)
DROP SEQUENCE (Transact-SQL)
NEXT VALUE FOR (Transact-SQL)
Números de sequência