Compartilhar via

sp_sequence_get_range (Transact-SQL)

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsBanco de Dados SQL no Microsoft Fabric

Retorna um intervalo de valores de sequência de um objeto de sequência. O objeto de sequência gera e emite o número de valores solicitado e fornece o aplicativo com metadados relacionados ao intervalo.

Para obter mais informações sobre números de sequência, consulte Números de sequência.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_sequence_get_range
    [ @sequence_name = ] N'sequence_name'
    , [ @range_size = ] range_size
    , [ @range_first_value = ] range_first_value OUTPUT
    [ , [ @range_last_value = ] range_last_value OUTPUT ]
    [ , [ @range_cycle_count = ] range_cycle_count OUTPUT ]
    [ , [ @sequence_increment = ] sequence_increment OUTPUT ]
    [ , [ @sequence_min_value = ] sequence_min_value OUTPUT ]
    [ , [ @sequence_max_value = ] sequence_max_value OUTPUT ]
[ ; ]

Argumentos

@sequence_name [ = ] N'sequence_name'

O nome do objeto de sequência. O esquema é opcional. @sequence_name é nvarchar(776), sem padrão.

@range_size [ = ] range_size

O número de valores a ser buscado da sequência. @range_size é bigint, sem padrão.

@range_first_value [ = ] range_first_value SAÍDA

O parâmetro de saída retorna o primeiro valor (mínimo ou máximo) do objeto de sequência usado para calcular o intervalo solicitado. @range_first_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@range_last_value [ = ] range_last_value SAÍDA

O parâmetro de saída opcional retorna o último valor do intervalo solicitado. @range_last_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@range_cycle_count [ = ] range_cycle_count SAÍDA

O parâmetro de saída opcional retorna o número de vezes que o objeto de sequência realizou um ciclo a fim de retornar o intervalo solicitado. @range_cycle_count é um parâmetro OUTPUT do tipo int.

@sequence_increment [ = ] sequence_increment SAÍDA

O parâmetro de saída opcional retorna o incremento do objeto de sequência usado para calcular o intervalo solicitado. @sequence_increment é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@sequence_min_value [ = ] sequence_min_value SAÍDA

O parâmetro de saída opcional retorna o valor mínimo do objeto de sequência. @sequence_min_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

@sequence_max_value [ = ] sequence_max_value SAÍDA

O parâmetro de saída opcional retorna o valor máximo do objeto de sequência. @sequence_max_value é um parâmetro OUTPUT do tipo sql_variant, com o mesmo tipo base que o objeto de sequência usado na solicitação.

Valores do código de retorno

0 (sucesso) ou 1 (falha).

Comentários

sp_sequence_get_range está no esquema e pode ser referenciado sys como sys.sp_sequence_get_range.

Sequências de ciclo

Se necessário, o objeto de sequência alterna o número apropriado de vezes para atender ao intervalo solicitado. O número de vezes que o ciclo é retornado ao chamador por meio do parâmetro @range_cycle_count .

Observação

Ao realizar o ciclo, um objeto de sequência reinicia a partir do valor mínimo para uma sequência ascendente e do valor máximo para uma sequência decrescente, não a partir do valor inicial do objeto de sequência.

Sequências não cíclicas

Se o número de valores no intervalo solicitado for maior do que os valores disponíveis restantes no objeto de sequência, o intervalo solicitado não será deduzido do objeto de sequência e o seguinte erro 11732 será retornado:

O intervalo solicitado para o objeto de sequência '%.*ls' excede o limite máximo ou mínimo. Tente novamente com um intervalo menor.

Permissões

Requer UPDATE permissão no objeto de sequência ou no esquema do objeto de sequência.

Exemplos

Os exemplos a seguir usam um objeto de sequência chamado Test.RangeSeq. Use a instrução a seguir para criar a Test.RangeSeq sequência.

CREATE SCHEMA Test;
GO

CREATE SEQUENCE Test.RangeSeq
    AS INT
    START WITH 1
    INCREMENT BY 1
    MINVALUE 1
    MAXVALUE 25
    CYCLE
    CACHE 10;

R. Recuperar um intervalo de valores de sequência

A instrução a seguir obtém quatro números de sequência do objeto de sequência Test.RangeSeq e retorna o primeiro dos números para o usuário.

DECLARE @range_first_value_output AS SQL_VARIANT;

EXECUTE sys.sp_sequence_get_range
    @sequence_name = N'Test.RangeSeq',
    @range_size = 4,
    @range_first_value = @range_first_value_output OUTPUT;

SELECT @range_first_value_output AS FirstNumber;

B. Retornar todos os parâmetros de saída

O exemplo a seguir retorna todos os valores de saída do sp_sequence_get_range procedimento.

DECLARE
    @FirstSeqNum AS SQL_VARIANT,
    @LastSeqNum AS SQL_VARIANT,
    @CycleCount AS INT,
    @SeqIncr AS SQL_VARIANT,
    @SeqMinVal AS SQL_VARIANT,
    @SeqMaxVal AS SQL_VARIANT;

EXECUTE sys.sp_sequence_get_range
    @sequence_name = N'Test.RangeSeq',
    @range_size = 5,
    @range_first_value = @FirstSeqNum OUTPUT,
    @range_last_value = @LastSeqNum OUTPUT,
    @range_cycle_count = @CycleCount OUTPUT,
    @sequence_increment = @SeqIncr OUTPUT,
    @sequence_min_value = @SeqMinVal OUTPUT,
    @sequence_max_value = @SeqMaxVal OUTPUT;

-- The following statement returns the output values
SELECT @FirstSeqNum AS FirstVal,
       @LastSeqNum AS LastVal,
       @CycleCount AS CycleCount,
       @SeqIncr AS SeqIncrement,
       @SeqMinVal AS MinSeq,
       @SeqMaxVal AS MaxSeq;

Alterar o argumento @range_size para um número grande, como 75 faz com que o objeto de sequência alterne. Verifique o argumento @range_cycle_count para determinar se e quantas vezes o objeto de sequência foi alternado.

C. Exemplo: usando ADO.NET

O exemplo a seguir obtém um intervalo do Test.RangeSeq usando ADO.NET.

SqlCommand cmd = new SqlCommand();
cmd.Connection = conn;
cmd.CommandType = CommandType.StoredProcedure;
cmd.CommandText = "sys.sp_sequence_get_range";
cmd.Parameters.AddWithValue("@sequence_name", "Test.RangeSeq");
cmd.Parameters.AddWithValue("@range_size", 10);

// Specify an output parameter to retrieve the first value of the generated range.
SqlParameter firstValueInRange = new SqlParameter("@range_first_value", SqlDbType.Variant);
firstValueInRange.Direction = ParameterDirection.Output;
cmd.Parameters.Add(firstValueInRange);

conn.Open();
cmd.ExecuteNonQuery();

// Output the first value of the generated range.
Console.WriteLine(firstValueInRange.Value);

Conteúdo relacionado

  • Last updated on