sys.dm_exec_describe_first_result_set (Transact-SQL)

發行項
08/21/2023

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體

此動態管理函式會採用 Transact-SQL 語句作為參數，並描述語句第一個結果集的中繼資料。

sys.dm_exec_describe_first_result_set 的結果集定義與 sys.dm_exec_describe_first_result_set_for_object （Transact-SQL）相同，且類似于 sp_describe_first_result_set （Transact-SQL）。

Transact-SQL 語法慣例

語法

  
sys.dm_exec_describe_first_result_set(@tsql, @params, @include_browse_information)

引數

@tsql
一或多個 Transact-SQL 語句。 Transact-SQL_batch 可能是 Nvarchar（ n ） 或 Nvarchar（max） 。

@params
@params提供 Transact-SQL 批次參數的宣告字串，類似于 sp_executesql。參數可以是 Nvarchar（n） 或 Nvarchar（max） 。

這是一個字串，其中包含已內嵌在 Transact-SQL 中之所有參數的定義_batch 。字串必須是 Unicode 常數或 Unicode 變數。每個參數定義都由參數名稱和資料類型組成。 n 是一個預留位置，表示其他參數定義。 stmt 中指定的每個參數都必須在 @params 中定義。如果語句中的 Transact-SQL 語句或批次不包含參數，則不需要@params。 Null 是此參數的預設值。

@include_browse_information
如果設定為 1，則會分析每個查詢，就像查詢上有 FOR BROWSE 選項一樣。傳回其他索引鍵資料行和來源資料表資訊。

傳回的資料表

這個常見的中繼資料會以結果集傳回。結果中繼資料中每個資料行的一個資料列描述下表所示格式的資料行類型和可為 Null 性。如果每個控制項路徑沒有第一個語句，則會傳回含有零個數據列的結果集。

資料行名稱	資料類型	描述
is_hidden	bit	指定資料行是針對流覽和資訊用途新增的額外資料行，實際上不會出現在結果集中。
column_ordinal	int	包含結果集中資料行的序數位置。第一個資料行的位置會指定為 1。
name	sysname	如果可以判斷名稱，則包含資料行的名稱。如果沒有，則會包含 Null。
is_nullable	bit	包含下列值：如果資料行允許 Null，則值為 1。如果資料行不允許 Null，則值為 0。如果無法判斷資料行允許 Null，則值為 1。
system_type_id	int	包含資料行資料類型的system_type_id，如 sys.types 中所指定。針對 CLR 類型，即使system_type_name資料行會傳回 Null，這個資料行也會傳回值 240。
system_type_name	nvarchar(256)	包含為數據行資料類型指定的名稱和引數（例如長度、有效位數、小數位數）。如果資料類型是使用者定義的別名類型，則會在這裡指定基礎系統類型。如果資料類型是 CLR 使用者定義型別，則會在此資料行中傳回 Null。
max_length	smallint	資料行的最大長度（以位元組為單位）。 -1 = 資料行資料類型為 Varchar（max）、 Nvarchar（max）、 Varbinary（max）或 xml 。針對文字資料行， max_length 值會是 16，或是sp_tableoption 「資料列中的文字」所設定的值。
有效位數	tinyint	如果以數值為基礎，則為數據行的有效位數。否則傳回 0。
scale	tinyint	如果以數值為基礎，則為數據行小數位數。否則傳回 0。
collation_name	sysname	如果以字元為基礎，則為數據行定序的名稱。否則會傳回 Null。
user_type_id	int	針對 CLR 和別名類型，包含資料行資料類型的user_type_id，如 sys.types 中所指定。否則為 Null。
user_type_database	sysname	針對 CLR 和別名類型，包含定義型別的資料庫名稱。否則為 Null。
user_type_schema	sysname	針對 CLR 和別名類型，包含定義型別的架構名稱。否則為 Null。
user_type_name	sysname	針對 CLR 和別名類型，包含類型的名稱。否則為 Null。
assembly_qualified_type_name	nvarchar(4000)	針對 CLR 類型，傳回定義型別的元件和類別名稱。否則為 Null。
xml_collection_id	int	包含資料行資料類型的xml_collection_id，如 sys.columns 中所指定。如果傳回的類型與 XML 架構集合無關，這個資料行會傳回 Null。
xml_collection_database	sysname	包含定義與這個類型相關聯之 XML 架構集合的資料庫。如果傳回的類型與 XML 架構集合無關，這個資料行會傳回 Null。
xml_collection_schema	sysname	包含定義與這個類型相關聯之 XML 架構集合的架構。如果傳回的類型與 XML 架構集合無關，這個資料行會傳回 Null。
xml_collection_name	sysname	包含與此類型相關聯的 XML 架構集合名稱。如果傳回的類型與 XML 架構集合無關，這個資料行會傳回 Null。
is_xml_document	bit	如果傳回的資料類型是 XML，而且該類型保證是完整的 XML 檔（包括根節點），而不是 XML 片段，則傳回 1。否則傳回 0。
is_case_sensitive	bit	如果資料行是區分大小寫的字串類型，則傳回 1。如果不是則傳回 0。
is_fixed_length_clr_type	bit	如果資料行是固定長度的 CLR 類型，則傳回 1。如果不是則傳回 0。
source_server	sysname	原始伺服器的名稱（如果它源自遠端伺服器）。名稱會在 sys.servers 中出現時提供。如果資料行源自本機伺服器，或無法判斷其來源的伺服器，則傳回 Null。只有在要求流覽資訊時才會填入。
source_database	sysname	此結果中資料行所傳回之原始資料庫的名稱。如果無法判斷資料庫，則傳回 Null。只有在要求流覽資訊時才會填入。
source_schema	sysname	此結果中資料行所傳回之原始架構的名稱。如果無法判斷架構，則傳回 Null。只有在要求流覽資訊時才會填入。
source_table	sysname	此結果中資料行所傳回之原始資料表的名稱。如果無法判斷資料表，則傳回 Null。只有在要求流覽資訊時才會填入。
source_column	sysname	結果資料行所傳回之原始資料行的名稱。如果無法判斷資料行，則傳回 Null。只有在要求流覽資訊時才會填入。
is_identity_column	bit	如果資料行是識別欄位，則傳回 1;如果不是，則傳回 0。如果無法判斷資料行是識別欄位，則傳回 Null。
is_part_of_unique_key	bit	如果資料行是唯一索引的一部分，則傳回 1（包括唯一和主要條件約束），如果不是，則傳回 0。如果無法判斷資料行是唯一索引的一部分，則傳回 Null。只有在要求流覽資訊時才會填入。
is_updateable	bit	如果資料行是可更新的，則傳回 1;如果不是，則傳回 0。如果無法判斷資料行可更新，則傳回 Null。
is_computed_column	bit	如果資料行是計算資料行，則傳回 1;如果不是，則傳回 0。如果無法判斷資料行是否為計算資料行，則傳回 Null。
is_sparse_column_set	bit	如果資料行是疏鬆資料行，則傳回 1;如果不是，則傳回 0。如果無法判斷資料行是疏鬆資料行集的一部分，則傳回 Null。
ordinal_in_order_by_list	smallint	此資料行的 ihe 位置位於 ORDER BY 清單中。如果資料行未出現在 ORDER BY 清單中，或無法唯一判斷 ORDER BY 清單，則傳回 Null。
order_by_list_length	smallint	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。
error_number	int	包含函式傳回的錯誤號碼。如果沒有發生錯誤，資料行將會包含 Null。
error_severity	int	包含函式所傳回的嚴重性。如果沒有發生錯誤，資料行將會包含 Null。
error_state	int	包含狀態訊息。函式所傳回。如果沒有發生錯誤，資料行將會包含 Null。
error_message	Nvarchar（4096）	包含函式所傳回的訊息。如果沒有發生錯誤，資料行將會包含 Null。
error_type	int	包含整數，表示要傳回的錯誤。對應至error_type_desc。請參閱備註底下的清單。
error_type_desc	nvarchar(60)	包含代表所傳回錯誤的簡短大寫字串。對應至error_type。請參閱備註底下的清單。

備註

此函式會使用與 sp_describe_first_result_set 相同的演算法。如需詳細資訊，請參閱 sp_describe_first_result_set （Transact-SQL）。

下表列出錯誤類型及其描述

error_type	error_type	描述
1	雜項	未描述的所有錯誤。
2	語法	批次中發生語法錯誤。
3	CONFLICTING_RESULTS	無法判斷結果，因為兩個可能的第一個語句之間發生衝突。
4	DYNAMIC_SQL	無法判斷結果，因為可能會傳回第一個結果的動態 SQL。
5	CLR_PROCEDURE	無法判斷結果，因為 CLR 預存程式可能會傳回第一個結果。
6	CLR_TRIGGER	無法判斷結果，因為 CLR 觸發程式可能會傳回第一個結果。
7	EXTENDED_PROCEDURE	無法判斷結果，因為擴充預存程式可能會傳回第一個結果。
8	UNDECLARED_PARAMETER	無法判斷結果，因為一或多個結果集資料行的資料類型可能相依于未宣告的參數。
9	遞歸	無法判斷結果，因為批次包含遞迴語句。
10	TEMPORARY_TABLE	無法判斷結果，因為批次包含臨時表，sp_describe_first_result_set 不支援。
11	UNSUPPORTED_STATEMENT	無法判斷結果，因為批次包含sp_describe_first_result_set 不支援的語句（例如 FETCH、REVERT 等）。
12	OBJECT_TYPE_NOT_SUPPORTED	不支援傳遞至函式@object_id （亦即非預存程式）
13	OBJECT_DOES_NOT_EXIST	系統目錄中找不到傳遞至函式的@object_id。

權限

需要許可權才能執行@tsql引數。

範例

主題 sp_describe_first_result_set （Transact-SQL）中的其他範例可以調整為使用 sys.dm_exec_describe_first_result_set 。

A. 傳回單一 Transact-SQL 語句的相關資訊

下列程式碼會傳回 Transact-SQL 語句結果的相關資訊。

USE AdventureWorks2022;  
GO  
SELECT * FROM sys.dm_exec_describe_first_result_set  
(N'SELECT object_id, name, type_desc FROM sys.indexes', null, 0) ;

B. 傳回程序的相關資訊

下列範例會建立名為 pr_TestProc 的預存程式，以傳回兩個結果集。然後，此範例示範 sys.dm_exec_describe_first_result_set 傳回程序中第一個結果集的相關資訊。

USE AdventureWorks2022;  
GO  
  
CREATE PROC Production.TestProc  
AS  
SELECT Name, ProductID, Color FROM Production.Product ;  
SELECT Name, SafetyStockLevel, SellStartDate FROM Production.Product ;  
GO  
  
SELECT * FROM sys.dm_exec_describe_first_result_set  
('Production.TestProc', NULL, 0) ;

C. 從包含多個語句的批次傳回中繼資料

下列範例會評估包含兩個 Transact-SQL 語句的批次。結果集描述傳回的第一個結果集。

USE AdventureWorks2022;  
GO  
  
SELECT * FROM sys.dm_exec_describe_first_result_set(  
N'SELECT CustomerID, TerritoryID, AccountNumber FROM Sales.Customer WHERE CustomerID = @CustomerID;  
SELECT * FROM Sales.SalesOrderHeader;',  
N'@CustomerID int', 0) AS a;  
GO

另請參閱

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