sp_sequence_get_range (Transact-SQL)
適用対象: 
SQL Server Azure SQL データベース Azure SQL Managed Instance Azure Synapse Analytics
シーケンス オブジェクトからシーケンス値の範囲を返します。 シーケンス オブジェクトは、要求された値の数を生成して発行し、範囲に関連するメタデータをアプリケーションに提供します。
シーケンス番号の詳細については、「 シーケンス番号」を参照してください。
構文
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 ]
[ ; ]
引数
[ @sequence_name = ] N'sequence_name'
シーケンス オブジェクトの名前。 スキーマは省略可能です。 @sequence_name は nvarchar(776)で、既定値はありません。
[ @range_size = ] range_size
シーケンスからフェッチする値の数。 @range_size は bigint で、既定値はありません。
[ @range_first_value = ] range_first_value OUTPUT
出力パラメーターは、要求された範囲の計算に使用されるシーケンス オブジェクトの最初の (最小値または最大値) の値を返します。 @range_first_value は、要求で使用されるシーケンス オブジェクトと同じ基本型を持つ、 sql_variant型の OUTPUT パラメーターです。
[ @range_last_value = ] range_last_value OUTPUT
省略可能な出力パラメーターは、要求された範囲の最後の値を返します。 @range_last_value は、要求で使用されるシーケンス オブジェクトと同じ基本型を持つ、 sql_variant型の OUTPUT パラメーターです。
[ @range_cycle_count = ] range_cycle_count OUTPUT
オプションの出力パラメーターは、要求された範囲を返すためにシーケンス オブジェクトが循環した回数を返します。 @range_cycle_count は、 int 型の OUTPUT パラメーターです。
[ @sequence_increment = ] sequence_increment OUTPUT
省略可能な出力パラメーター。要求された範囲の計算に使用するシーケンス オブジェクトの増分を返します。 @sequence_increment は、要求で使用されるシーケンス オブジェクトと同じ基本型を持つ、 sql_variant型の OUTPUT パラメーターです。
[ @sequence_min_value = ] sequence_min_value OUTPUT
オプションの出力パラメーターは、シーケンス オブジェクトの最小値を返します。 @sequence_min_value は、要求で使用されるシーケンス オブジェクトと同じ基本型を持つ、 sql_variant型の OUTPUT パラメーターです。
[ @sequence_max_value = ] sequence_max_value OUTPUT
オプションの出力パラメーターは、シーケンス オブジェクトの最大値を返します。 @sequence_max_value は、要求で使用されるシーケンス オブジェクトと同じ基本型を持つ、 sql_variant型の OUTPUT パラメーターです。
リターン コードの値
0 (成功) または 1 (失敗)。
解説
sp_sequence_get_range は sys スキーマ内にあり、 sys.sp_sequence_get_rangeとして参照できます。
循環シーケンス
必要に応じて、シーケンス オブジェクトは、要求された範囲にサービスを提供する適切な回数を循環します。 @range_cycle_count パラメーターを介して呼び出し元に循環した回数が返されます。
Note
循環すると、シーケンス オブジェクトは、シーケンス オブジェクトの開始値ではなく、昇順シーケンスの最小値と降順シーケンスの最大値から再起動します。
循環しないシーケンス
要求された範囲内の値の数がシーケンス オブジェクトの残りの使用可能な値より大きい場合、要求された範囲はシーケンス オブジェクトから差し引かれず、次のエラー 11732 が返されます。
シーケンス オブジェクト '%.*ls' に対して要求された範囲が、上限または最小値を超えています。 より小さい範囲で再試行してください。
アクセス許可
シーケンス オブジェクトまたはシーケンス オブジェクトのスキーマに対する 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);