CRIAR SEQUÊNCIA (Transact-SQL)

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureBanco de dados SQL no Microsoft Fabric

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 das colunas de identidade, não estã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 dos valores de colunas de identidade gerados quando as linhas são inseridas, um aplicativo pode obter o próximo número de sequência sem inserir a linha chamando o VALOR NEXT 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 a função e a CREATE SEQUENCENEXT VALUE FOR função, 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 | usuário-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.

Constante START WITH <>

O primeiro valor retornado pelo objeto de sequência. O START valor deve ser um valor menor ou igual ao 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.

Incremento por <constante>

Valor usado para incrementar (ou diminuir se negativo) o valor do objeto de sequência para cada chamada à NEXT VALUE FOR função. Se o incremento for um valor negativo, o objeto de sequência estará decrescente; caso contrário, ele é crescente. O incremento não pode ser 0. O incremento padrão para um novo objeto de sequência é 1.

[ Constante< MINVALUE >| SEM 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.

[ Constante< MAXVALUE >| SEM 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 | SEM CICLO ]

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.

Observação

O ciclo de uma SEQUENCE reinicialização do valor mínimo ou máximo, não do valor inicial.

[ CACHE [ <constante> ] | SEM 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. Usa CACHE como padrão.

Por exemplo, se um tamanho de cache de 50 for escolhido, o SQL Server não manterá 50 valores individuais armazenados em cache. Ele armazena em cache apenas o valor atual e a quantidade 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.

Observação

Se a opção de cache estiver habilitada sem especificar um tamanho de cache, o Mecanismo de Banco de Dados selecionará um tamanho. No entanto, os usuários não devem depender da seleção ser consistente. A Microsoft pode alterar o método de cálculo do tamanho do cache sem aviso prévio.

Quando criado com a opção CACHE , um desligamento inesperado (como uma falha de energia) pode resultar na perda de números de sequência restantes no cache.

Observações

Os números de sequência são gerados fora do escopo da transação atual. Eles são consumidos se a transação que usa o número de sequência é 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 melhorar o CACHE desempenho, o SQL Server pré-aloca o número de números de sequência especificados pelo argumento.

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 último valor armazenado em cache (30) é 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 lacunas, mas garante que o mesmo valor nunca será emitido duas vezes para um único objeto de sequência, a menos que seja definido como CYCLE ou seja reiniciado manualmente.

O cache é mantido na memória rastreando o valor atual (o último valor emitido) e a quantidade 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.

Definindo o argumento de cache para NO CACHE gravar o valor da sequência atual nas tabelas do sistema sempre que uma sequência for usada. Isso pode prejudicar o desempenho ao aumentar o acesso ao disco, mas reduz a possibilidade de intervalos não intencionais. As lacunas ainda poderão ocorrer se os números forem solicitados usando as funções ou NEXT VALUE FOR as sp_sequence_get_range funções, mas os números não forem usados ou forem usados em transações não confirmadas.

Quando um objeto de sequência usa a opçãoCACHE, se você reiniciar o objeto de sequência ou alterar as INCREMENTpropriedades, CYCLEMINVALUEMAXVALUEou o tamanho do cache, isso fará com que o cache seja gravado nas tabelas do sistema antes que a alteração ocorra. Em seguida, o cache é recarregado começando com o 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 armazenados em cache estão disponíveis

O processo a seguir ocorre sempre que um objeto de sequência é solicitado a gerar o próximo valor para a opção CACHE se houver valores não utilizados 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 processo a seguir ocorre sempre que um objeto de sequência é solicitado a gerar o próximo valor para a opção CACHE se o cache estiver 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 evento estendido esgotado por cache é acionado para notificar o usuário sobre o novo valor persistente.

Opção NO CACHE

O processo a seguir ocorre sempre que um objeto de sequência é solicitado a 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

CREATE SEQUENCERequer , ALTERou CONTROL permissão na 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 objetos de sequência, fazendo com que eles gerem números.

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

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 usar um tipo de dados definido pelo usuário, o criador da sequência deverá ter REFERENCES permissão no tipo.

Audit

Para auditar CREATE SEQUENCE, monitore o SCHEMA_OBJECT_CHANGE_GROUP.

Exemplos

Para obter exemplos de como criar sequências e usar a NEXT VALUE FOR função para gerar números de sequência, consulte 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. Criar uma sequência que aumenta em 1

No exemplo a seguir, Thierry cria uma sequência chamada CountBy1 que aumenta uma vez que é usada.

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

B. Criar uma sequência que diminui em 1

O exemplo a seguir começa em 0 e conta em números negativos por um sempre que é usado.

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

C. Criar uma sequência que aumenta em 5

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

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

D. Criar uma sequência que comece com um número designado

Depois de importar uma tabela, Thierry percebe que o número de ID mais alto usado é 24.328. O Thierry precisa de uma sequência que gere números a partir de 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. Criar 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.

Saída	Valor padrão
start_value	-9223372036854775808
increment	1
minimum_value	-9223372036854775808
maximum_value	9223372036854775807
is_cycling	0
is_cached	1
current_value	-9223372036854775808

F. Criar 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. Criar uma sequência usando 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';

Conteúdo relacionado

• ALTER SEQUÊNCIA (Transact-SQL)
• SEQUÊNCIA DE QUEDA (Transact-SQL)
• PRÓXIMO VALOR PARA (Transact-SQL)
• Números de sequência