sp_sequence_get_range (Transact-SQL)

適用対象: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics

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

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

Transact-SQL 構文表記規則

構文

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 パラメーターを介して呼び出し元に循環した回数が返されます。

循環しないシーケンス

要求された範囲内の値の数がシーケンス オブジェクトの残りの使用可能な値より大きい場合、要求された範囲はシーケンス オブジェクトから差し引かれず、次のエラー 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);

関連するコンテンツ

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