sp_describe_first_result_set (Transact-SQL)

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) SQL Analytics-Endpunkt in Microsoft Fabric Warehouse 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 der Datenbank-Engine die Metadaten für die erste Abfrage nicht ermitteln kann, die durch Ausführen einer statischen Analyse ausgeführt wird. Die dynamische Verwaltungsansicht sys.dm_exec_describe_first_result_set dieselben Informationen zurückgibt.

Transact-SQL-Syntaxkonventionen

Syntax

sp_describe_first_result_set [ @tsql = ] N'tsql'
    [ , [ @params = ] N'@parameter_name data_type [ , ... n ]' ]
    [ , [ @browse_information_mode = ] <tinyint> ]
[ ; ]

Argumente

[ @tsql = ] 'tsql'

Mindestens eine Transact-SQL-Anweisung. @tsql kann nvarchar(n) oder nvarchar(max)sein.

[ @params = ] N'@parameter_name data_type [ , ... n ]'

@params stellt eine Deklarationszeichenfolge für Parameter für den Transact-SQL-Batch bereit, der ähnlich sp_executesqlist. Parameter können nvarchar(n) oder nvarchar(max)sein.

Eine Zeichenfolge, die die Definitionen aller Parameter enthält, die in @tsql eingebettet sind. 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 der Anweisung angegebene Parameter muss in @params definiert werden. Wenn die Transact-SQL-Anweisung oder der Batch in der Anweisung keine Parameter enthält, ist @params nicht erforderlich. NULL ist der Standardwert für diesen Parameter.

[ @browse_information_mode = ] tinyint

Gibt an, ob zusätzliche Schlüsselspalten und Quelltabelleninformationen zurückgegeben werden. Bei Festlegung auf 1, wird jede Abfrage so analysiert, als ob sie eine FOR BROWSE Option für die Abfrage enthält.

• Bei Festlegung auf 0, werden keine Informationen zurückgegeben.

• Bei Festlegung auf 1, wird jede Abfrage so analysiert, als ob sie eine FOR BROWSE Option für die Abfrage enthält. Dadurch werden Basistabellennamen als Quellspalteninformationen zurückgegeben.

• Bei Festlegung auf 2, wird jede Abfrage so analysiert, als würde sie beim Vorbereiten oder Ausführen eines Cursors verwendet werden. Dadurch werden Ansichtsnamen als Quellspalteninformationen zurückgegeben.

Rückgabecodewerte

sp_describe_first_result_set gibt immer den Status Null bei Erfolg zurück. Wenn die Prozedur einen Fehler auslöst und die Prozedur als RPC aufgerufen wird, wird der Rückgabestatus durch den Typ des in der spalte error_type beschriebenen sys.dm_exec_describe_first_result_setFehlers aufgefüllt. Wenn die Prozedur von Transact-SQL aufgerufen wird, ist der Rückgabewert immer null, auch wenn ein Fehler auftritt.

Resultset

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 für jeden Steuerelementpfad nicht vorhanden ist, wird ein Resultset mit null Zeilen zurückgegeben.

Hinweise

sp_describe_first_result_set garantiert, dass, wenn die Prozedur die ersten Resultsetmetadaten für (einen hypothetischen) Batch A zurückgibt und wenn dieser Batch (A) dann ausgeführt wird, entweder:

• löst einen Optimierungszeitfehler aus.
• löst einen Laufzeitfehler aus.
• gibt kein Resultset zurück.
• gibt ein erstes Resultset mit denselben Metadaten zurück, die von sp_describe_first_result_set

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

Dabei wird vorausgesetzt, dass keine relevanten Schemaänderungen auf dem Server vorgenommen wurden. Relevante Schemaänderungen auf dem Server enthalten nicht das Erstellen temporärer Tabellen oder Tabellenvariablen im Batch A zwischen dem Aufruf sp_describe_first_result_set und dem Zeitpunkt, zu dem das Resultset während der Ausführung zurückgegeben wird, einschließlich Schemaänderungen, die von Batch B vorgenommen wurden.

sp_describe_first_result_set gibt in einem der folgenden Fälle einen Fehler zurück:

• Die Eingabe @tsql ist kein gültiger Transact-SQL-Batch. Die Gültigkeit wird durch Parsen und Analysieren des Transact-SQL-Batchs bestimmt. Alle Fehler, die während der Abfrageoptimierung oder während der Ausführung durch den Batch verursacht werden, werden nicht berücksichtigt, wenn ermittelt wird, ob der Transact-SQL-Batch gültig ist.

• @params ist nicht NULL und enthält eine Zeichenfolge, die keine syntaktisch gültige Deklarationszeichenfolge für Parameter ist, oder wenn sie eine Zeichenfolge enthält, die einen Parameter mehr als einmal 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. Dies berücksichtigt alle Steuerungsflussanweisungen (GOTO, IF/ELSE, WHILEund Transact-SQL-BlöckeCATCHTRY/) sowie alle Prozeduren, dynamischen Transact-SQL-Batches oder Trigger, die aus dem Eingabebatch durch eine EXEC Anweisung aufgerufen werden, eine DDL-Anweisung, die bewirkt, dass DDL-Trigger ausgelöst werden, oder eine DML-Anweisung, die Trigger für eine Zieltabelle oder eine Tabelle auslöst, die aufgrund einer Cascading-Aktion für eine Fremdschlüsseleinschränkung geändert wird. Irgendwann stoppt ein Algorithmus, wie viele mögliche Kontrollpfade.

Für jeden Ablaufpfad des Steuerelements wird die erste Anweisung (falls vorhanden) bestimmt sp_describe_first_result_set, die ein Resultset zurückgibt.

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 sich der Spaltenname unterscheidet, wird der zurückgegebene Spaltenname auf NULL.

• Wenn sich die Nullbarkeit unterscheidet, lässt NULLdie zurückgegebene Nullbarkeit zu.

• Wenn sich der Datentyp unterscheidet, wird ein Fehler ausgelöst, und es wird kein Ergebnis zurückgegeben, mit Ausnahme der folgenden Fälle:

  • 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 zum Ausführen des @tsql Arguments.

Beispiele

Typische Beispiele

A. Einfaches Beispiel

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

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

EXEC 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. Beispiele für den Suchmodus

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

Beispiel für die Verwendung , 0die 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;

Dies ist ein Auszug aus dem 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;

Dies ist ein Auszug aus dem Resultset.

Beispiel mit 2, das analysiert wird, als ob Sie einen Cursor vorbereiten.

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

Hier sehen Sie das Ergebnis.

C. Speichern von Ergebnissen in einer Tabelle

In einigen Szenarien müssen Sie die Ergebnisse der sp_describe_first_result_set Prozedur in eine Tabelle einfügen, damit Sie das Schema weiter verarbeiten 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 INTO #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.

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

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

Dies führt zu einem Fehler bei nicht übereinstimmenden Typen (int vs. 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:

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

Dies ist ein Auszug aus dem Resultset.

Spaltenname mit durch Aliasing erzwungenem identischem Spaltennamen

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

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

Dies ist ein Auszug aus dem Resultset.

Fehler, da Spaltentypen nicht abgeglichen werden können

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

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

Dies führt zu einem Fehler bei nicht übereinstimmenden Typen (varchar(10) vs. nvarchar(10)).

Resultset kann einen Fehler zurückgeben

Das erste Resultset ist Fehler oder Resultset.

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

Dies ist ein Auszug aus dem Resultset.

Einige Codepfade geben keine Ergebnisse zurück

Der erste Resultset ist NULL oder ein Resultset.

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

Dies ist ein Auszug aus dem Resultset.

Ergebnis von dynamischem SQL

First result set is dynamic SQL that is discoverable because it's a literal string.

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

Dies ist ein Auszug aus dem Resultset.

Ergebnisfehler von dynamischem SQL

Das erste Resultset ist aufgrund von dynamischem SQL nicht definiert.

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

Dies führt zu einem Fehler. Das Ergebnis ist aufgrund der dynamischen SQL-Datei nicht auffindbar.

Vom Benutzer angegebenes Resultset

Das erste Resultset wird manuell vom Benutzer angegeben.

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

Dies ist ein Auszug aus dem Resultset.

Fehler aufgrund eines mehrdeutigen Resultsets

In diesem Beispiel wird davon ausgegangen, dass ein anderer benannter user1 Benutzer über eine Tabelle im Standardschema s1 mit Spalten (a int NOT NULL) verfügtt1.

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

Dieser Code führt zu einem Invalid object name Fehler. t1 kann entweder dbo.t1 oder s1.t1, jeweils mit einer anderen Anzahl von Spalten, sein.

Ergebnis auch bei mehrdeutigem Resultset

Verwenden Sie die gleichen Annahmen wie im vorherigen Beispiel.

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

Dies ist ein Auszug aus dem Resultset.

Sowohl typ dbo.t1.a s1.t1.a int als auch unterschiedliche Nullwerte.

Zugehöriger Inhalt

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