sp_describe_first_result_set (Transact-SQL)

適用対象: はいSQL Server (サポートされているすべてのバージョン) はいAzure SQL データベース はいAzure SQL Managed Instance はいAzure Synapse Analytics はいParallel Data Warehouse

バッチの最初の使用可能な結果セットのメタデータを返し Transact-SQL ます。 バッチが結果を返さない場合は、空の結果セットを返します。 では、 データベース エンジン 静的分析を実行することによって実行される最初のクエリのメタデータをが判別できない場合に、エラーが発生します。 )SQL (sys.dm_exec_describe_first_result_set動的管理ビューでは、同じ情報が返されます。

トピック リンク アイコン Transact-SQL 構文表記規則

構文

  
sp_describe_first_result_set [ @tsql = ] N'Transact-SQL_batch'   
    [ , [ @params = ] N'parameters' ]   
    [ , [ @browse_information_mode = ] <tinyint> ] ]  

引数

[ @tsql = ] 'Transact-SQL_batch' 1つ以上の Transact-SQL ステートメント。 Transact-sql SQL_batchnvarchar (n) または nvarchar (max) です。

[ @params = ] N'parameters'@params は、バッチのパラメーターの宣言文字列を提供し Transact-SQL ます。これは sp_executesql に似ています。 パラメーターには、 nvarchar (n) または nvarchar (max) を指定できます。

_Batch に埋め込まれているすべてのパラメーターの定義を含む1つの文字列を指定 Transact-SQL します。 この文字列は Unicode 定数または Unicode 変数にする必要があります。 各パラメーター定義は、パラメーター名とデータ型で構成されます。 n は、追加のパラメーター定義を示すプレースホルダーです。 ステートメントで指定するすべてのパラメーターは、params で定義する必要があり @ ます。 ステートメント Transact-SQL 内のステートメントまたはバッチにパラメーターが含まれていない場合、 @ params は必要ありません。 このパラメーターの既定値は NULL です。

[ @browse_information_mode = ] tinyint 追加のキー列とソーステーブル情報を返すかどうかを指定します。 1に設定すると、各クエリはクエリに FOR BROWSE オプションが含まれているかのように分析されます。 追加のキー列とソース テーブル情報が返されます。

  • 0に設定すると、情報は返されません。

  • 1に設定すると、各クエリはクエリに FOR BROWSE オプションが含まれているかのように分析されます。 ベースのテーブル名がソース列情報として返されます。

  • 2に設定すると、各クエリは、カーソルの準備または実行時に使用されるかのように分析されます。 ビュー名がソース列情報として返されます。

リターン コードの値

sp_describe_first_result_set は、成功した場合に常に0の状態を返します。 プロシージャがエラーをスローし、プロシージャが RPC として呼び出された場合、返される状態は、sys.dm_exec_describe_first_result_set の [error_type] 列に記述されているエラーの種類によって設定されます。 プロシージャがから呼び出された場合 Transact-SQL 、エラーが発生した場合でも、戻り値は常に0になります。

結果セット

この共通メタデータは、結果のメタデータの各列に対する 1 行の結果セットとして返されます。 各行には、列の種類と NULL 値の許容属性が次のセクションに示す形式で記述されます。 各コントロールのパスに最初のステートメントが存在しない場合は、0 行の結果セットが返されます。

列名 データ型 説明
is_hidden bit NOT NULL 列が参照情報のために追加された余分な列であり、実際には結果セットに表示されないことを示します。
column_ordinal int NOT NULL 結果セット内の列の位置を示す序数を格納します。 最初の列の位置は1として指定されます。
name sysname NULL 列の名前を確認できる場合は、その名前を格納します。 それ以外の場合、NULL が含まれます。
is_nullable bit NOT NULL 列で Null が許容される場合は値1が格納され、列が null を許容しない場合は0、null を許容するかどうかを判断できない場合は1が格納されます。
system_type_id int NOT NULL に指定されている列のデータ型の system_type_id が含まれています。型です。 CLR 型の場合は、system_type_name 列が NULL を返しても、この列は値 240 を返します。
system_type_name nvarchar (256) NULL 列のデータ型に指定されている名前と引数 (長さ、有効桁数、小数点以下桁数など) を格納します。 データ型がユーザー定義の別名型の場合は、基になるシステム型がここで指定されます。 CLR ユーザー定義型の場合は、この列には NULL が返されます。
max_length smallint NOT NULL 列の最大長 (バイト単位) です。

-1 = 列のデータ型は varchar (max),、 nvarchar (max),、 varbinary (max),、または xml です。

テキスト 列の場合、 max_length 値は16か sp_tableoption ' text in row ' によって設定された値になります。
有効桁数 (precision) tinyint NOT NULL 数値ベースの場合は、列の有効桁数です。 それ以外の場合は 0 を返します。
scale tinyint NOT NULL 数値ベースの場合は、列の小数点以下桁数です。 それ以外の場合は 0 を返します。
collation_name sysname NULL 文字ベースの場合は、列の照合順序の名前です。 それ以外の場合は NULL を返します。
user_type_id int NULL CLR 型と別名型の場合、sys.types で指定された列のデータ型の user_type_id を格納します。 それ以外の場合は NULL です。
user_type_database sysname NULL CLR 型と別名型の場合、その型が定義されたデータベースの名前を格納します。 それ以外の場合は NULL です。
user_type_schema sysname NULL CLR 型と別名型の場合、その型が定義されたスキーマの名前を格納します。 それ以外の場合は NULL です。
user_type_name sysname NULL CLR 型と別名型の場合、その型の名前を格納します。 それ以外の場合は NULL です。
assembly_qualified_type_name nvarchar (4000) CLR 型の場合、その型を定義するアセンブリの名前とクラスを返します。 それ以外の場合は NULL です。
xml_collection_id int NULL sys.columns で指定された列のデータ型の xml_collection_id を格納します。 この列は、返される型が XML スキーマ コレクションに関連付けられていない場合は NULL を返します。
xml_collection_database sysname NULL この型に関連付けられている XML スキーマ コレクションが定義されているデータベースを格納します。 この列は、返される型が XML スキーマ コレクションに関連付けられていない場合は NULL を返します。
xml_collection_schema sysname NULL この型に関連付けられている XML スキーマ コレクションが定義されているスキーマを格納します。 この列は、返される型が XML スキーマ コレクションに関連付けられていない場合は NULL を返します。
xml_collection_name sysname NULL この型に関連付けられている XML スキーマ コレクションの名前を格納します。 この列は、返される型が XML スキーマ コレクションに関連付けられていない場合は NULL を返します。
is_xml_document bit NOT NULL 返されたデータ型が XML で、その型が XML フラグメントではなく完全な XML ドキュメント (ルート ノードを含む) であると保証される場合、1 を返します。 それ以外の場合は 0 を返します。
is_case_sensitive bit NOT NULL 列が大文字と小文字を区別する文字列型の場合は1、それ以外の場合は0を返します。
is_fixed_length_clr_type bit NOT NULL 列が固定長の CLR 型の場合は1、それ以外の場合は0を返します。
source_server sysname この結果内の列によって返された元のサーバーの名前です (リモート サーバーから発生する場合)。 名前は、sys. サーバーに表示されるときに指定されます。 この列がローカル サーバー上で発生した場合、または元のサーバーを特定できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
source_database sysname この結果内の列によって返された元のデータベースの名前です。 データベースを特定できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
source_schema sysname この結果内の列によって返された元のスキーマの名前です。 スキーマを特定できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
source_table sysname この結果内の列によって返された元のテーブルの名前です。 テーブルを特定できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
source_column sysname 結果列から返された元の列の名前です。 列を特定できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
is_identity_column ビット NULL この列が ID 列の場合は 1、それ以外の場合は 0 を返します。 ID 列であることを確認できない場合は NULL を返します。
is_part_of_unique_key ビット NULL この列が一意インデックス (一意制約と主キー制約を含む) の一部である場合は 1、それ以外の場合は 0 を返します。 一意インデックスの一部であることを確認できない場合は NULL を返します。 参照情報が要求された場合にのみ設定されます。
is_updateable ビット NULL この列が更新可能である場合は 1、それ以外の場合は 0 を返します。 更新可能であることを確認できない場合は NULL を返します。
is_computed_column ビット NULL この列が計算列の場合は 1、それ以外の場合は 0 を返します。 計算列であることを確認できない場合は NULL を返します。
is_sparse_column_set ビット NULL この列がスパース列の場合は 1、それ以外の場合は 0 を返します。 列がスパース列セットの一部であることを判断できない場合は NULL を返します。
ordinal_in_order_by_list smallint NULL ORDER BY リストにおけるこの列の位置。 列が ORDER BY リストに表示されない場合、または ORDER BY リストを一意に特定できない場合は、NULL を返します。
order_by_list_length smallint NULL ORDER BY リストの長さを返します。 ORDER BY リストがない場合、または ORDER BY リストを一意に特定できない場合は NULL を返します。 この値は sp_describe_first_result_set によって返されるすべての行で同じであることに注意して ください。
order_by_is_descending smallint NULL ordinal_in_order_by_list が NULL でない場合、order_by_is_descending 列には、この列の ORDER BY 句の方向がレポートされます。 それ以外の場合は、NULL が報告されます。
tds_type_id int NOT NULL 内部使用です。
tds_length int NOT NULL 内部使用です。
tds_collation_id int NULL 内部使用です。
tds_collation_sort_id tinyint NULL 内部使用です。

解説

sp_describe_first_result_set は、プロシージャが (仮定の) バッチ a に対して最初の結果セットのメタデータを返す場合に、そのバッチ (a) が後で実行されると、バッチによって (1) 最適化時のエラーが発生することを保証します。 (2) 実行時エラーが発生します。 (3) は結果セットを返しません。または、(4) sp_describe_first_result_set によって記述されたものと同じメタデータを持つ最初の結果セットを返します。

名前、NULL 値の許容属性、およびデータ型が異なる可能性があります。 空 sp_describe_first_result_set 結果セットを返す場合、バッチ実行は結果セットを返しません。

この保証は、サーバーに関連するスキーマの変更がないと仮定します。 サーバー上の関連するスキーマの変更には 、sp_describe_first_result_set が呼び出された時刻から、バッチ B によって行われたスキーマ変更など、実行中に結果セットが返される時間までの間に、バッチ A に一時テーブルまたはテーブル変数を作成することはできません。

sp_describe_first_result_set、 次の場合にエラーが返されます。

  • 入力 @ tsql が有効なバッチでない Transact-SQL 場合。 有効性は、バッチの解析と分析によって決定 Transact-SQL されます。 クエリの最適化中または実行中にバッチによって発生したエラーは、バッチが有効かどうかを判断 Transact-SQL するときに考慮されません。

  • パラメーターが NULL ではなく、構文的に有効なパラメーターの宣言文字列ではない文字列が含まれている場合、またはパラメーターを複数宣言する文字列が含まれている場合は @ 。

  • 入力バッチが params で宣言されたパラメーターと同 Transact-SQL じ名前のローカル変数を @ 宣言する場合。

  • ステートメントが一時テーブルを使用する場合。

  • クエリには、クエリが実行される永続的なテーブルの作成が含まれます。

他のすべてのチェックが成功した場合、入力バッチ内で可能なすべての制御フロー パスが考慮されます。 これには、すべての制御フロー ステートメント (GOTO、IF/ELSE、WHILE、TRY/CATCH ブロック) と、EXEC ステートメントによって入力バッチから呼び出されるプロシージャ、動的バッチ、またはトリガー、DDL トリガーの起動を引き起こす DDL ステートメント、またはターゲット テーブルまたは外部キー制約に対するカスケード アクションが原因で変更されたテーブルに対してトリガーが起動される Transact-SQL DML ステートメントが考慮されます。 Transact-SQL 多くの制御パスが考えられる場合、ある時点でアルゴリズムが停止します。

制御フロー パスごとに、結果セットを返す最初のステートメント (指定されている場合) は、 によって決定 sp_describe_first_result_set。

バッチ内で最初のステートメントが複数見つかった場合、その結果は列数、列名、null 値の許容値、およびデータ型が異なる場合があります。 これらの違いを処理する方法の詳細について、ここに記載します。

  • 列数が異なる場合は、エラーがスローされ、結果は返されません。

  • 列名が異なる場合、返される列名は NULL に設定されます。

  • null 値の許容が異なります。返される null 値の許容は NULL を許可します。

  • データ型が異なる場合は、次の場合を除き、エラーがスローされ、結果は返されません。

    • varchar(a) から varchar(a') まで。ここで、 は を>します。

    • varchar(a) から varchar(max)

    • nvarchar(a) から nvarchar(a') まで。a' は >します。

    • nvarchar(a) から nvarchar(max)

    • varbinary(a) から varbinary(a') まで。ここで、 は を>します。

    • varbinary(a) から varbinary(max)

sp_describe_first_result_set 間接再帰はサポートされていません。

アクセス許可

tsql 引数を実行するための @ アクセス許可が必要です。

一般的な例

A. 簡単な例

次の例では、1 つのクエリから返される結果セットについて説明します。

sp_describe_first_result_set @tsql = N'SELECT object_id, name, type_desc FROM sys.indexes'  

次の例は、 パラメーターを含む 1 つのクエリから返される結果セットを示しています。

sp_describe_first_result_set @tsql =   
N'SELECT object_id, name, type_desc   
FROM sys.indexes   
WHERE object_id = @id1'  
, @params = N'@id1 int'  

B. ブラウズ モードの使用例

次の 3 つの例では、異なるブラウズ情報モード間の主要な違いを示します。 クエリ結果には、関係する列だけが含まれています。

情報が返されませんを示す 0 を使用する例。

CREATE TABLE dbo.t (a int PRIMARY KEY, b1 int);  
GO  
CREATE VIEW dbo.v AS SELECT b1 AS b2 FROM dbo.t;  
GO  
EXEC sp_describe_first_result_set N'SELECT b2 AS b3 FROM dbo.v', null, 0;  

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

is_hidden column_ordinal name source_schema source_table source_column is_part_of_unique_key
0 1 b3 NULL NULL NULL NULL

クエリに FOR BROWSE オプションが含まれる場合と同様に情報を返す 1 を使用する例。

EXEC sp_describe_first_result_set N'SELECT b2 AS b3 FROM v', null, 1  
  

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

is_hidden column_ordinal name source_schema source_table source_column is_part_of_unique_key
0 1 b3 dbo t B1 0
1 2 a dbo t a 1

カーソルを準備している場合と同じ分析を示す 2 を使用する例。

EXEC sp_describe_first_result_set N'SELECT b2 AS b3 FROM v', null, 2  

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

is_hidden column_ordinal name source_schema source_table source_column is_part_of_unique_key
0 1 B3 dbo v B2 0
1 2 ROWSTAT NULL NULL NULL 0

C. 結果をテーブルに格納する

一部のシナリオでは、スキーマをさらに処理するために、プロシージャの結果を一部のテーブル sp_describe_first_result_set に置く必要があります。 まず、プロシージャの出力と一致するテーブルを作成する必要 sp_describe_first_result_set があります。

create table #frs (
    is_hidden bit not null,
    column_ordinal int not null,
    name sysname null,
    is_nullable bit not null,
    system_type_id int not null,
    system_type_name nvarchar(256) null,
    max_length smallint not null,
    precision tinyint not null,
    scale tinyint not null,
    collation_name sysname null,
    user_type_id int null,
    user_type_database sysname null,
    user_type_schema sysname null,
    user_type_name sysname null,
    assembly_qualified_type_name nvarchar(4000),
    xml_collection_id int null,
    xml_collection_database sysname null,
    xml_collection_schema sysname null,
    xml_collection_name sysname null,
    is_xml_document bit not null,
    is_case_sensitive bit not null,
    is_fixed_length_clr_type bit not null,
    source_server sysname null,
    source_database sysname null,
    source_schema sysname null,
    source_table sysname null,
    source_column sysname null,
    is_identity_column bit null,
    is_part_of_unique_key bit null,
    is_updateable bit null,
    is_computed_column bit null,
    is_sparse_column_set bit null,
    ordinal_in_order_by_list smallint null,
    order_by_list_length smallint null,
    order_by_is_descending smallint null,
    tds_type_id int not null,
    tds_length int not null,
    tds_collation_id int null,
    tds_collation_sort_id tinyint null
);

テーブルを作成するときに、そのテーブルにクエリのスキーマを格納できます。

declare @tsql nvarchar(max) = 'select top 0 * from sys.credentials';

insert #frs
exec sys.sp_describe_first_result_set @tsql;

select * from #frs;

問題の例

以下の例では、すべて 2 つのテーブルを使用します。 次のステートメントを実行して、これらのテーブルを作成します。

CREATE TABLE dbo.t1 (a int NULL, b varchar(10) NULL, c nvarchar(10) NULL);  
CREATE TABLE dbo.t2 (a smallint NOT NULL, d varchar(20) NOT NULL, e int NOT NULL);  

列の数の違いによるエラー

この例では、考えられる最初の結果セットの列数が異なります。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    SELECT a FROM t1;  
ELSE  
    SELECT a, b FROM t1;  
SELECT * FROM t; -- Ignored, not a possible first result set.'  
  

データ型の違いによるエラー

考えられる最初の結果セットの間で、列の型が異なります。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    SELECT a FROM t1;  
ELSE  
    SELECT a FROM t2;  

結果: エラー、型の不一致 (intsmallint)。

列名を決定できません

考えられる最初の結果セットの列は、同じ可変長型、null 値の許容、および列名の長さによって異なります。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    SELECT b FROM t1;  
ELSE  
    SELECT d FROM t2; '  

結果: <Unknown Column Name> varchar(20) NULL

別名を使用して列名を同一にすることを強制する

前の例と同じですが、列の別名を使用して列名を同じにしています。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    SELECT b FROM t1;  
ELSE  
    SELECT d AS b FROM t2;'  

結果: b varchar(20)NULL

列の型を一致できないことが原因でエラーが発生しました

列の型は、考えられる最初の結果セットによって異なります。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    SELECT b FROM t1;  
ELSE  
    SELECT c FROM t1;'  

結果: エラー、型の不一致 (varchar(10)nvarchar(10))。

結果セットからエラーが返される可能性があります

最初の結果セットは、エラーまたは結果セットです。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    RAISERROR(''Some Error'', 16, 1);  
  
ELSE  
    SELECT a FROM t1;  
SELECT e FROM t2; -- Ignored, not a possible first result set.;'  

結果: intNULL

一部のコード パスは結果を返す

最初の結果セットが null または結果セットです。

sp_describe_first_result_set @tsql =   
N'  
IF(1=1)  
    RETURN;  
SELECT a FROM t1;'  

結果: intNULL

動的なデータのSQL

最初の結果セットはSQLリテラル文字列なので検出可能な動的変数です。

sp_describe_first_result_set @tsql =   
N'EXEC(N''SELECT a FROM t1'');'  

結果: INT NULL

動的 SQL からの結果の失敗

動的 SQL のため、最初の結果セットが未定義となります。

sp_describe_first_result_set @tsql =   
N'  
DECLARE @SQL NVARCHAR(max);  
SET @SQL = N''SELECT a FROM t1 WHERE 1 = 1 '';  
IF(1=1)  
    SET @SQL += N'' AND e > 10 '';  
EXEC(@SQL); '  

結果: エラー。 動的な結果が検出SQL。

ユーザー指定の結果セット

最初の結果セットがユーザーにより手動で指定されています。

sp_describe_first_result_set @tsql =   
N'  
DECLARE @SQL NVARCHAR(max);  
SET @SQL = N''SELECT a FROM t1 WHERE 1 = 1 '';  
IF(1=1)  
    SET @SQL += N'' AND e > 10 '';  
EXEC(@SQL)  
    WITH RESULT SETS(  
        (Column1 BIGINT NOT NULL)  
    ); '  

結果: Column1 bigint NOT NULL

あいまいな結果セットによるエラー

この例では、user1 という名前の別のユーザーが、列 (int NOT NULL) を持つ既定のスキーマ s1 に t1 という名前のテーブル を持っている前提としています

sp_describe_first_result_set @tsql =   
N'  
    IF(@p > 0)  
    EXECUTE AS USER = ''user1'';  
    SELECT * FROM t1;'  
, @params = N'@p int'  

結果: エラー。 t1 には dbo.t1 または s1.t1 を指定できます。各列の数は異なります。

あいまいな結果セットを含む結果

前の例と同じ前提を使用します。

sp_describe_first_result_set @tsql =   
N'  
    IF(@p > 0)  
    EXECUTE AS USER = ''user1'';  
    SELECT a FROM t1;'  

結果: int NULL です 。dbo.t1.a と s1.t1.a の両方に int 型と null 値の許容値が異なっています。

参照

sp_describe_undeclared_parameters (Transact-SQL)
sys.dm_exec_describe_first_result_set (Transact-SQL)
sys.dm_exec_describe_first_result_set_for_object (Transact-SQL)