sp_describe_first_result_set (Transact-SQL)

Gilt für:SQL ServerAzure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL Analytics-Endpunkt in Microsoft FabricWarehouse in Microsoft Fabric

Gibt die Metadaten für das erste mögliche Resultset des Transact-SQL-Batchs zurück. Gibt ein leeres Resultset zurück, wenn vom Batch keine Ergebnisse zurückgegeben werden. Löst einen Fehler aus, wenn die Datenbank-Engine die Metadaten für die erste Abfrage, die durch eine statische Analyse ausgeführt wird, nicht ermitteln kann. Die dynamische Verwaltungssicht sys.dm_exec_describe_first_result_set (Transact-SQL) gibt dieselben Informationen zurück.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

[ @tsql = ] 'Transact-SQL_batch' Mindestens eine Transact-SQL-Anweisung. Transact-SQL_batch kann nvarchar(n) oder nvarchar(max) sein.

[ @params = ] N'parameters': @params stellt eine Deklarationszeichenfolge für Parameter für den Transact-SQL-Batch bereit, ähnlich wie „sp_executesql“. Parameter können nvarchar(n) oder nvarchar(max) sein.

Eine Zeichenfolge, die die Definitionen aller in Transact-SQL_batch eingebetteten Parameter enthält. Die Zeichenfolge muss eine Unicode-Konstante oder eine Unicode-Variable sein. Jede Parameterdefinition besteht aus einem Parameternamen und einem Datentyp. n ist ein Platzhalter für zusätzlicher Parameterdefinitionen. Jeder in Parameter in der Anweisung muss in @params definiert werden. Wenn die Transact-SQL-Anweisung oder der Batch in der Anweisung keine Parameter enthält, ist @params nicht erforderlich. Der Standardwert für diesen Parameter ist NULL.

[ @browse_information_mode = ] tinyint: Gibt an, ob zusätzliche Schlüsselspalten und Quelltabelleninformationen zurückgegeben werden. Bei Festlegung auf 1 werden alle Abfragen so analysiert, als ob die FOR BROWSE-Option in der Abfrage enthalten wäre. Zusätzliche Schlüsselspalten und Quelltabelleninformationen werden zurückgegeben.

• Bei 0 werden keine Informationen zurückgegeben.

• Bei Festlegung auf 1 werden alle Abfragen so analysiert, als ob die FOR BROWSE-Option in der Abfrage enthalten wäre. Damit werden Basistabellennamen als Quellspalteninformationen zurückgegeben.

• Bei 2 wird jede Abfrage analysiert, als würde sie beim Vorbereiten oder Ausführen eines Cursors verwendet. Damit werden Sichtnamen als Quellspalteninformationen zurückgegeben.

Rückgabecodewerte

sp_describe_first_result_set gibt bei Erfolg immer den Status 0 zurück. Wenn die Prozedur einen Fehler auslöst und als RPC aufgerufen wird, wird der Rückgabestatus von dem Fehlertyp aufgefüllt, der in der Spalte „error_type“ von „sys.dm_exec_describe_first_result_set“ beschrieben ist. Wenn die Prozedur von Transact-SQL aufgerufen wird, ist der Rückgabewert immer 0, auch wenn ein Fehler vorliegt.

Resultsets

Diese allgemeinen Metadaten werden in den Ergebnismetadaten als Resultset mit einer Zeile für jede Spalte zurückgegeben. Jede Zeile beschreibt den Typ und die NULL-Zulässigkeit der Spalte in dem Format, das im folgenden Abschnitt beschriebenen wird. Wenn die erste Anweisung nicht für alle Steuerelementpfade vorhanden ist, wird ein Resultset mit 0 Zeilen zurückgegeben.

Bemerkungen

sp_describe_first_result_set stellt Folgendes sicher: Wenn die Prozedur die Metadaten für das erste Resultset eines (hypothetischen) Batchs A zurückgibt und dieser Batch (A) anschließend ausgeführt wird, wird vom Batch (1) ein Optimierungszeitfehler ausgelöst, (2) ein Laufzeitfehler ausgelöst, (3) kein Resultset zurückgegeben oder (4) ein erstes Resultset mit den Metadaten zurückgegeben, die von sp_describe_first_result_set beschrieben werden.

Der Name, die NULL-Zulässigkeit und der Datentyp können abweichen. Wenn sp_describe_first_result_set ein leeres Resultset zurückgibt, ist garantiert, dass die Batchausführung keine Resultsets zurückgibt.

Dabei wird vorausgesetzt, dass keine relevanten Schemaänderungen auf dem Server vorgenommen wurden. Das Erstellen von temporären Tabellen oder Tabellenvariablen in Batch A zwischen dem Zeitpunkt, an dem sp_describe_first_result_set aufgerufen wird, und dem Zeitpunkt, an dem das Resultset bei der Ausführung zurückgegeben wird, zählt ebenso wie Schemaänderungen durch Batch B nicht zu den relevanten Schemaänderungen auf dem Server.

sp_describe_first_result_set gibt in allen folgenden Fällen einen Fehler zurück.

• Die @tsql-Eingabe ist kein gültiger Transact-SQL-Batch. Die Gültigkeit wird durch Parsen und Analysieren des Transact-SQL-Batchs bestimmt. Fehler, die vom Batch im Rahmen der Abfrageoptimierung oder -ausführung ausgelöst werden, bleiben unberücksichtigt, wenn die Gültigkeit des Transact-SQL-Batchs überprüft wird.

• @params ist nicht NULL und enthält eine Zeichenfolge, die keine syntaktisch gültige Deklarationszeichenfolge für Parameter darstellt, oder eine Zeichenfolge, die einen Parameter mehrmals deklariert.

• Der Transact-SQL-Eingabebatch deklariert eine lokale Variable mit demselben Namen wie ein in @params deklarierter Parameter.

• Die Anweisung verwendet eine temporäre Tabelle.

• Die Abfrage umfasst die Erstellung einer dauerhaften Tabelle, die dann abgefragt wird.

Wenn alle anderen Überprüfungen erfolgreich sind, werden alle möglichen Ablaufsteuerungspfade im Eingabebatch berücksichtigt. Berücksichtigt werden hier alle Ablaufsteuerungsanweisungen (GOTO, IF/ELSE, WHILE und TRY-/CATCH-Blöcke in Transact-SQL) sowie Prozeduren, dynamische Transact-SQL-Batches oder Trigger, die vom Eingabebatch durch eine EXEC-Anweisung aufgerufen werden, DDL-Anweisungen, die DDL-Trigger auslösen, oder DML-Anweisungen, die Trigger für Zieltabellen oder Tabellen auslösen, die aufgrund einer kaskadierenden Aktion für eine Fremdschlüsseleinschränkung geändert werden. Bei einer Vielzahl möglicher Steuerelementpfade wird der Algorithmus irgendwann beendet.

Die erste Anweisung, die ggf. ein Resultset zurückgibt, wird für jeden Ablaufsteuerungspfad von sp_describe_first_result_set bestimmt.

Bei mehreren möglichen ersten Anweisungen in einem Batch kann sich das jeweilige Ergebnis im Hinblick auf die Anzahl der Spalten, die Spaltennamen, die NULL-Zulässigkeit und den Datentyp unterscheiden. Im Folgenden wird ausführlicher erläutert, wie diese Unterschiede gehandhabt werden:

• Wenn sich die Anzahl der Spalten unterscheidet, wird ein Fehler ausgelöst, und es wird kein Ergebnis zurückgegeben.

• Wenn der Spaltenname abweicht, wird der zurückgegebene Spaltenname auf NULL festgelegt.

• Wenn die NULL-Zulässigkeit abweicht, sind NULL-Werte in der zurückgegebenen NULL-Zulässigkeit zulässig.

• Wenn der Datentyp abweicht, wird ein Fehler ausgelöst, und nur in folgenden Fällen wird ein Ergebnis zurückgegeben:

  • varchar(a) zu varchar(a') mit a' > a.

  • varchar(a) zu varchar(max)

  • nvarchar(a) zu nvarchar(a') mit a' > a.

  • nvarchar(a) zu nvarchar(max)

  • varbinary(a) zu varbinary(a') mit a' > a.

  • varbinary(a) zu varbinary(max)

sp_describe_first_result_set unterstützt keine indirekte Rekursion.

Berechtigungen

Erfordert die Berechtigung zur Ausführung des @tsql-Arguments.

Beispiele

Typische Beispiele

A. Einfaches Beispiel

Im folgenden Beispiel wird das von einer einzelnen Abfrage zurückgegebene Resultset beschrieben.

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

Im folgenden Beispiel wird das von einer einzelnen Abfrage mit einem Parameter zurückgegebene Resultset veranschaulicht.

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. Beispielen für Durchsuchenmodi

In den folgenden drei Beispielen wird der Hauptunterschied zwischen den unterschiedlichen Modi für die Informationssuche veranschaulicht. In den Abfrageergebnissen waren nur die relevanten Spalten enthalten.

Beispiel mit dem Wert 0, der angibt, dass keine Informationen zurückgegeben werden.

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;  

Hier ist das Resultset.

Beispiel mit dem Wert 1, der angibt, dass Informationen so zurückgegeben werden, als ob in der Abfrage eine FOR BROWSE-Option eingeschlossen wäre.

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

Hier ist das Resultset.

Beispiel mit dem Wert 2, der angibt, dass die Analyse erfolgt, als ob Sie einen Cursor vorbereiteten.

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

Hier ist das Resultset.

C. Speichern von Ergebnissen in einer Tabelle

In einigen Szenarien müssen Sie die Ergebnisse der Prozedur sp_describe_first_result_set in einer Tabelle speichern, um das Schema weiter verarbeiten zu können. Zunächst müssen Sie eine Tabelle erstellen, die der Ausgabe der Prozedur sp_describe_first_result_set entspricht:

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
);

Wenn Sie eine Tabelle erstellen, können Sie das Schema einer Abfrage in dieser Tabelle speichern.

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

insert #frs
exec sys.sp_describe_first_result_set @tsql;

select * from #frs;

Beispiele für Probleme

In den folgenden Beispielen werden zwei Tabellen für alle Beispiele verwendet. Führen Sie die folgenden Anweisungen aus, um die Beispieltabellen zu erstellen.

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);  

Fehler aufgrund unterschiedlicher Spaltenanzahl

Die Anzahl der Spalten in möglichen ersten Resultsets weicht in diesem Beispiel ab.

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.'  
  

Fehler aufgrund abweichender Datentypen

Die Spaltentypen unterscheiden sich in verschiedenen möglichen ersten Resultsets.

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

Ergebnis: Fehler, nicht übereinstimmende Typen (int im Gegensatz zu smallint).

Spaltenname kann nicht bestimmt werden

Die Spalten in möglichen ersten Resultsets unterscheiden sich hinsichtlich der Länge für identische Typen mit variabler Länge, NULL-Zulässigkeiten und Spaltennamen:

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

Ergebnis: <Unbekannter Spaltenname>varchar(20) NULL

Spaltenname mit durch Aliasing erzwungenem identischem Spaltennamen

Analog zum vorherigen, die Namen der Spalten sind jedoch aufgrund von Spaltenaliasing identisch.

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

Ergebnis: b varchar(20)NULL

Fehler aufgrund nicht zuzuordnender Spaltentypen

Die Spaltentypen unterscheiden sich in verschiedenen möglichen ersten Resultsets.

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

Ergebnis: Fehler, nicht übereinstimmende Typen (varchar(10) im Gegensatz zu nvarchar(10)).

Resultset kann einen Fehler zurückgeben

Das erste Resultset ist Fehler oder Resultset.

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.;'  

Ergebnis : intNULL

Einige Codepfade geben keine Ergebnisse zurück

Der erste Resultset ist NULL oder ein Resultset.

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

Ergebnis : intNULL

Ergebnis von dynamischem SQL

Das erste Resultset ist dynamisches SQL, das ermittelt werden kann, da es sich um eine Literalzeichenfolge handelt.

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

Ergebnis: INT NULL

Ergebnisfehler von dynamischem SQL

Das erste Resultset ist aufgrund von dynamischem SQL nicht definiert.

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); '  

Ergebnis: Fehler. Das Ergebnis kann aufgrund von dynamischem SQL nicht ermittelt werden.

Vom Benutzer angegebenes Resultset

Das erste Resultset wird manuell vom Benutzer angegeben.

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)  
    ); '  

Ergebnis: Column1 bigint NOT NULL

Fehler aufgrund eines mehrdeutigen Resultsets

In diesem Beispiel wird davon ausgegangen, dass ein anderer Benutzer oder eine andere Benutzerin mit dem Namen „user1“ über eine Tabelle mit dem Namen „t1“ im Standardschema „s1“ mit Spalten (int NOT NULL) verfügt.

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

Ergebnis: Fehler. „t1“ kann „dbo.t1“ oder „s1.t1“ mit einer jeweils unterschiedlichen Spaltenanzahl sein.

Ergebnis auch bei mehrdeutigem Resultset

Verwenden Sie die gleichen Annahmen wie im vorherigen Beispiel.

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

Ergebnis: int NULL, da „dbo.t1.a“ und „s1.t1.a“ den Typ int, aber eine unterschiedliche NULL-Zulässigkeit aufweisen.

Weitere Informationen

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)