sp_sequence_get_range (Transact-SQL)

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics

シーケンス オブジェクトからシーケンス値の範囲を返します。 シーケンス オブジェクトは、要求された値の数を生成して発行し、範囲に関連するメタデータをアプリケーションに提供します。

シーケンス番号の詳細については、「 シーケンス番号」を参照してください。

Transact-SQL 構文表記規則

構文

  
sp_sequence_get_range [ @sequence_name = ] N'<sequence>'   
     , [ @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 ]  
    [ ; ]  

引数

[ @sequence_name = ] N'sequence' シーケンス オブジェクトの名前。 スキーマは省略可能です。 sequence_namenvarchar(776)です

[ @range_size = ] range_size シーケンスからフェッチする値の数。 @range_sizebigint です

[ @range_first_value = ] range_first_value 出力パラメーターは、要求された範囲の計算に使用されるシーケンス オブジェクトの最初の (最小値または最大値) の値を返します。 @range_first_valueは、要求で使用されるシーケンス オブジェクトと同じ基本型でsql_variantされます。

[ @range_last_value = ] range_last_value 省略可能な出力パラメーターは、要求された範囲の最後の値を返します。 @range_last_valueは、要求で使用されるシーケンス オブジェクトと同じ基本型でsql_variantされます。

[ @range_cycle_count = ] range_cycle_count オプションの出力パラメーターは、要求された範囲を返すためにシーケンス オブジェクトが循環した回数を返します。 @range_cycle_countint です

[ @sequence_increment = ] sequence_increment 省略可能な出力パラメーターは、要求された範囲の計算に使用されるシーケンス オブジェクトの増分を返します。 @sequence_incrementは、要求で使用されるシーケンス オブジェクトと同じ基本型でsql_variantされます。

[ @sequence_min_value = ] sequence_min_value オプションの出力パラメーターは、シーケンス オブジェクトの最小値を返します。 @sequence_min_valueは、要求で使用されるシーケンス オブジェクトと同じ基本型でsql_variantされます。

[ @sequence_max_value = ] sequence_max_value オプションの出力パラメーターは、シーケンス オブジェクトの最大値を返します。 @sequence_max_valueは、要求で使用されるシーケンス オブジェクトと同じ基本型でsql_variantされます。

リターン コードの値

0 (成功) または 1 (失敗)

解説

sys にsp_sequence_get_rangeisします。 スキーマ と は、sys.sp_sequence_get_rangeとして参照できます。

循環シーケンス

必要に応じて、シーケンス オブジェクトは、要求された範囲にサービスを提供するために適切な回数を循環します。 循環した回数は、@range_cycle_count パラメーターを通じて、呼び出し元に返されます。

注意

循環すると、シーケンス オブジェクトは、シーケンス オブジェクトの開始値ではなく、昇順シーケンスの最小値と降順シーケンスの最大値から再起動します。

循環しないシーケンス

要求された範囲内の値の数がシーケンス オブジェクトの残りの使用可能な値より大きい場合、要求された範囲はシーケンス オブジェクトから差し引かれず、次のエラー 11732 が返されます。

The requested range for sequence object '%.*ls' exceeds the maximum or minimum limit. Retry with a smaller range.

アクセス許可

シーケンス オブジェクトまたはシーケンス オブジェクトのスキーマに対する UPDATE 権限が必要です。

次の例では、Test.RangeSeq という名前のシーケンス オブジェクトを使用します。 Test.RangeSeq シーケンスを作成するには、次のステートメントを使用します。

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

A. シーケンス値の範囲を取得する

次のステートメントは、Test.RangeSeq シーケンス オブジェクトから 4 つのシーケンス番号を取得し、最初の番号をユーザーに返します。

DECLARE @range_first_value_output sql_variant ;  
  
EXEC 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. すべての出力パラメーターを返す

次の例では、sp_sequence_get_range プロシージャからすべての出力値を返します。

DECLARE    
  @FirstSeqNum sql_variant  
, @LastSeqNum sql_variant  
, @CycleCount int  
, @SeqIncr sql_variant  
, @SeqMinVal sql_variant  
, @SeqMaxVal sql_variant ;  
  
EXEC 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 ;  
  

引数 @range_size を 75 などの大きな数に変更すると、シーケンス オブジェクトを循環します。 シーケンス オブジェクトを循環したかどうか、およびその回数を調べるには、引数 @range_cycle_count をチェックします。

C. ADO.NET の使用例

次の例では、ADO.NET を使用して Test.RangeSeq から範囲を取得します。

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);  
  

参照

CREATE SEQUENCE (Transact-SQL)
ALTER SEQUENCE (Transact-SQL)
DROP SEQUENCE (Transact-SQL)
NEXT VALUE FOR (Transact-SQL)
シーケンス番号