THROW (Transact-SQL)

  • [アーティクル]

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)Microsoft Fabric の SQL 分析エンドポイントMicrosoft Fabric のウェアハウス

例外を発生させ、TRY...CATCH 構造の CATCH ブロックに例外を転送します。

Transact-SQL 構文表記規則

構文

THROW [ { error_number | @local_variable },  
        { message | @local_variable },  
        { state | @local_variable } ]   
[ ; ]

Note

SQL Server 2014 (12.x) 以前のバージョンの Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。

引数

error_number
例外を表す定数または変数です。 error_number は int で、50000 以上、2147483647 以下にする必要があります。

message
例外を説明する文字列または変数です。 message は nvarchar(2048) です。

状態
メッセージに関連付けられる状態を示す、0 から 255 の範囲の定数または変数です。 state は tinyint です。

解説

THROW ステートメントの前のステートメントの後に、セミコロン (;) ステートメント ターミネータが続く必要があります。

TRY...CATCH 構造を使用できない場合は、ステートメント バッチが終了します。 例外が発生する行番号およびプロシージャが設定されます。 重大度は 16 に設定されます。

パラメーターを使用せずに THROW ステートメントを指定する場合は、ステートメントが CATCH ブロック内に存在する必要があります。 これによりキャッチされた例外が発生します。 THROW ステートメント内でエラーが発生すると、ステートメント バッチが終了します。

% は THROW ステートメントのメッセージ テキストに予約された文字で、エスケープする必要があります。 文字 % を二重にすると、% をメッセージ テキストの一部として返します (例: "増加が元の値の 15% を超えました。")。

RAISERROR と THROW の違い

次の表に、RAISERROR と THROW のステートメントの違いを示します。

RAISERROR ステートメント THROW ステートメント
msg_id が RAISERROR に渡される場合、ID は sys.messages で定義する必要があります。 error_number パラメーターを sys.messages で定義する必要はありません。
msg_str パラメーターには printf 書式スタイルを含めることができます。 message パラメーターでは printf 書式スタイルは受け入れられません。
severity パラメーターでは例外の重大度を指定します。 severity パラメーターはありません。 例外を開始するために THROW を使用する場合、重大度は常に 16 に設定されます。 ただし、THROW を使用して既存の例外を再スローする場合、重大度はその例外の重大度レベルに設定されます。
SET XACT_ABORT を優先しないでください。 SET XACT_ABORT が ON の場合、トランザクションはロールバック "されます"。

例

A. THROW を使用して例外を発生させる

次の例では、THROW ステートメントを使用して例外を発生させる方法を示します。

THROW 51000, 'The record does not exist.', 1;

結果セットは次のようになります。

Msg 51000, Level 16, State 1, Line 1  
 
The record does not exist.

B. THROW を使用して例外を再度発生させる

次の例では、THROW ステートメントを使用して最後にスローされた例外を再度発生させる方法を示します。

USE tempdb;  
GO  
CREATE TABLE dbo.TestRethrow  
(    ID INT PRIMARY KEY  
);  
BEGIN TRY  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
--  Force error 2627, Violation of PRIMARY KEY constraint to be raised.  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
END TRY  
BEGIN CATCH  
  
    PRINT 'In catch block.';  
    THROW;  
END CATCH;

結果セットは次のようになります。

In catch block. 
Msg 2627, Level 14, State 1, Line 1  
Violation of PRIMARY KEY constraint 'PK__TestReth__3214EC272E3BD7D3'. Cannot insert duplicate key in object 'dbo.TestRethrow'.  
The statement has been terminated.

C. FORMATMESSAGE を THROW と共に使用する

次の例では、FORMATMESSAGE 関数を THROW と共に使用して、カスタマイズされたエラー メッセージをスローする方法を示します。 この例では、まず、sp_addmessage を使用して、ユーザー定義のエラー メッセージを作成します。 THROW ステートメントでは、RAISERROR のように、message パラメーターで書式引数が許可されないため、エラー メッセージ 60000 で想定される 3 つのパラメーター値を渡すために FORMATMESSAGE 関数が使用されます。

EXEC sys.sp_addmessage  
     @msgnum   = 60000  
    ,@severity = 16  
    ,@msgtext  = N'This is a test message with one numeric parameter (%d), one string parameter (%s), and another string parameter (%s).'  
    ,@lang = 'us_english';   
GO  
  
DECLARE @msg NVARCHAR(2048) = FORMATMESSAGE(60000, 500, N'First string', N'second string');   
  
THROW 60000, @msg, 1;

結果セットは次のようになります。

Msg 60000, Level 16, State 1, Line 2  
This is a test message with one numeric parameter (500), one string parameter (First string), and another string parameter (second string).

次のステップ

関連する概念の詳細については、次の記事を参照してください。