sp_describe_first_result_set (Transact-SQL)

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) SQL analytics endpoint in Microsoft Fabric Warehouse in Microsoft Fabric

Retourne les métadonnées pour le premier jeu de résultats possible du lot Transact-SQL. Retourne un jeu de résultats vide si le lot ne retourne pas de résultats. Génère une erreur si le Moteur de base de données ne peut pas déterminer les métadonnées pour la première requête qui sera exécutée en effectuant une analyse statique. La vue de gestion dynamique sys.dm_exec_describe_first_result_set retourne les mêmes informations.

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Arguments

[ @tsql = ] 'tsql'

Une ou plusieurs instructions Transact-SQL. @tsql peut être nvarchar(n) ou nvarchar(max).

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

@params fournit une chaîne de déclaration pour les paramètres du lot Transact-SQL, qui est similaire à sp_executesql. Les paramètres peuvent être nvarchar(n) ou nvarchar(max).

Chaîne qui contient les définitions de tous les paramètres incorporés dans @tsql. Cette chaîne doit être une constante Unicode ou une variable Unicode. Chaque définition de paramètre se compose d'un nom de paramètre et d'un type de données. n correspond à un espace réservé pour d’autres définitions de paramètres. Chaque paramètre spécifié dans l’instruction doit être défini dans @params. Si l’instruction Transact-SQL ou le lot de l’instruction ne contient pas de paramètres, @params n’est pas obligatoire. NULL est la valeur par défaut de ce paramètre.

[ @browse_information_mode = ] tinyint

Spécifie si des colonnes clés supplémentaires et des informations de table source sont retournées. Si elle est définie 1sur , chaque requête est analysée comme si elle inclut une FOR BROWSE option sur la requête.

• Si la valeur est définie 0, aucune information n’est retournée.

• Si elle est définie 1sur , chaque requête est analysée comme si elle inclut une FOR BROWSE option sur la requête. Cela retourne les noms de table de base en tant qu’informations de colonne source.

• Si la valeur est définie 2, chaque requête est analysée comme si elle serait utilisée dans la préparation ou l’exécution d’un curseur. Cela retourne les noms d’affichage en tant qu’informations de colonne source.

Valeurs des codes de retour

sp_describe_first_result_set retourne toujours un état de zéro sur le succès. Si la procédure lève une erreur et que la procédure est appelée en tant que RPC, l’état de retour est rempli par le type d’erreur décrit dans la colonne error_type de sys.dm_exec_describe_first_result_set. Si la procédure est appelée à partir de Transact-SQL, la valeur de retour est toujours égale à zéro, même en cas d’erreur.

Jeu de résultats

Ces métadonnées communes sont retournées en tant que jeu de résultats avec une ligne pour chaque colonne dans les métadonnées de résultats. Chaque ligne décrit le type et la possibilité de valeur NULL de la colonne dans le format décrit dans la section suivante. Si la première instruction n’existe pas pour chaque chemin de contrôle, un jeu de résultats avec zéro ligne est retourné.

Notes

sp_describe_first_result_set garantit que si la procédure retourne les premières métadonnées du jeu de résultats pour (un hypothétique) lot A et si ce lot (A) est ensuite exécuté, le lot soit :

• déclenche une erreur d’optimisation au moment de l’optimisation
• déclenche une erreur d’exécution
• renvoie aucun jeu de résultats
• retourne un premier jeu de résultats avec les mêmes métadonnées décrites par sp_describe_first_result_set

Le nom, la possibilité de valeur NULL et le type de données peuvent différer. Si sp_describe_first_result_set elle retourne un jeu de résultats vide, la garantie est que l’exécution du lot retourne des jeux sans résultat.

Cette garantie suppose qu’aucune modification de schéma pertinente n’a lieu sur le serveur. Les modifications de schéma pertinentes sur le serveur n’incluent pas la création de tables temporaires ou de variables de table dans le lot A entre l’heure appelée sp_describe_first_result_set et l’heure à laquelle le jeu de résultats est retourné pendant l’exécution, y compris les modifications de schéma apportées par le lot B.

sp_describe_first_result_set retourne une erreur dans l’un des cas suivants :

• L’entrée @tsql n’est pas un lot Transact-SQL valide. La validité est déterminée en analysant le lot Transact-SQL. Les erreurs provoquées par le lot lors de l’optimisation de la requête ou pendant l’exécution ne sont pas prises en compte lors de la détermination de la validité du lot Transact-SQL.

• @params n’est pas NULL et contient une chaîne qui n’est pas une chaîne de déclaration valide de manière syntactique pour les paramètres, ou si elle contient une chaîne qui déclare un paramètre plusieurs fois.

• Le lot Transact-SQL d’entrée déclare une variable locale du même nom qu’un paramètre déclaré dans @params.

• L’instruction utilise une table temporaire.

• La requête inclut la création d'une table permanente qui est alors interrogée.

Si tous les autres contrôles réussissent, tous les chemins d'accès de flux de contrôle possibles à l'intérieur du lot d'entrée sont pris en compte. Cela prend en compte toutes les instructions de flux de contrôle (GOTO, IF/ELSE, WHILEet blocs Transact-SQL/TRYCATCH) ainsi que toutes les procédures, lots Transact-SQL dynamiques ou déclencheurs appelés à partir du lot d’entrée par une EXEC instruction, une instruction DDL qui provoque le déclenchement de déclencheurs DDL ou une instruction DML qui provoque le déclenchement de déclencheurs sur une table cible ou sur une table modifiée en raison d’une action en cascade sur une contrainte de clé étrangère. À un moment donné, comme avec de nombreux chemins de contrôle possibles, un algorithme s’arrête.

Pour chaque chemin de flux de contrôle, la première instruction (le cas échéant) qui retourne un jeu de résultats est déterminée par sp_describe_first_result_set.

Lorsque plusieurs premières instructions possibles sont trouvées dans un lot, leurs résultats peuvent différer selon le nombre de colonnes, le nom de colonne, la possibilité de valeur NULL et le type de données. La gestion de ces différences fait l'objet d'une description plus détaillée dans cette rubrique :

• Si le nombre de colonnes diffère, une erreur est générée et aucun résultat n'est retourné.

• Si le nom de colonne diffère, le nom de colonne retourné est défini sur NULL.

• Si la valeur Nullability diffère, la valeur Nullability retournée autorise NULL.

• Si le type de données diffère, une erreur est levée et aucun résultat n’est retourné à l’exception des cas suivants :

  • varchar(a) à varchar(a’), où a’ > a.
  • varchar(a) à varchar(max)
  • nvarchar(a) à nvarchar(a’), où a’ > a.
  • nvarchar(a) à nvarchar(max)
  • varbinary(a) à varbinary(a’), où a’ > a.
  • varbinary(a) à varbinary(max)

sp_describe_first_result_set ne prend pas en charge la récursivité indirecte.

autorisations

Nécessite l’autorisation d’exécuter l’argument @tsql.

Exemples

Exemples typiques

A. Exemple de base

L'exemple suivant décrit le jeu de résultats retourné par une requête unique.

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

L'exemple suivant affiche le jeu de résultats retourné par une requête unique qui contient un paramètre.

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. Exemples de mode Parcourir

Les trois exemples suivants illustrent la principale différence entre les différents modes de navigation. Seules les colonnes pertinentes sont incluses dans les résultats de la requête.

Exemple utilisant 0, indiquant qu’aucune information n’est retournée.

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;

Voici un jeu de résultats partiel.

L'exemple qui utilise 1 indique qu'il retourne les informations comme s'il incluait une option FOR BROWSE sur la requête.

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

Voici un jeu de résultats partiel.

Exemple utilisant 2 indiquant l’analyse comme si vous préparez un curseur.

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

Voici le jeu de résultats obtenu.

C. Stocker des résultats dans une table

Dans certains scénarios, vous devez placer les résultats de la sp_describe_first_result_set procédure dans une table pour que vous puissiez continuer à traiter le schéma.

Tout d’abord, vous devez créer une table qui correspond à la sortie de la procédure 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
);

Lorsque vous créez une table, vous pouvez stocker le schéma d’une requête dans cette table.

DECLARE @tsql NVARCHAR(MAX) = 'select top 0 * from sys.credentials';

INSERT INTO #frs
EXEC sys.sp_describe_first_result_set @tsql;

SELECT * FROM #frs;

Exemples de problèmes

Les exemples suivants utilisent deux tables pour tous les exemples. Exécutez les instructions suivantes pour créer les tables d'exemples.

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

Erreur car le nombre de colonnes diffère

Le nombre de colonnes dans les premiers jeux de résultats possibles diffère dans cet exemple.

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

Erreur car les types de données diffèrent

Les types de colonnes diffèrent dans les premiers jeux de résultats possibles.

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

Cela entraîne une erreur de non-correspondance des types (int et smallint).

Impossible de déterminer le nom de colonne

Les colonnes dans les premiers jeux de résultats possibles diffèrent de par la longueur pour le même type de longueur variable, la possibilité de valeur NULL et les noms de colonne :

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

Voici un jeu de résultats partiel.

Nom de colonne forcé à être identique par crénelage

Identique à l'exemple précédent, mais les colonnes ont le même nom via le crénelage de colonne.

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

Voici un jeu de résultats partiel.

Erreur, car les types de colonnes ne peuvent pas être mis en correspondance

Les types de colonnes diffèrent dans les premiers jeux de résultats possibles.

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

Cela entraîne une erreur de incompatibilité des types (varchar(10) et nvarchar(10)).

Le jeu de résultats peut retourner une erreur

Le premier jeu de résultats est soit une erreur, soit un jeu de résultats.

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

Voici un jeu de résultats partiel.

Certains chemins de code ne retournent pas de résultats

Le premier jeu de résultats est soit Null, soit un jeu de résultats.

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

Voici un jeu de résultats partiel.

Résultat du SQL dynamique

Le premier jeu de résultats est sql dynamique détectable, car il s’agit d’une chaîne littérale.

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

Voici un jeu de résultats partiel.

Échec du résultat du SQL dynamique

Le premier jeu de résultats est indéfini en raison du SQL dynamique.

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

Cela entraîne une erreur. Le résultat n’est pas détectable en raison du sql dynamique.

Jeu de résultats spécifié par l'utilisateur

Le premier jeu de résultats est spécifié manuellement par l'utilisateur.

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

Voici un jeu de résultats partiel.

Erreur provoquée par un jeu de résultats ambigu

Cet exemple suppose qu’un autre utilisateur nommé a une table nommée user1 t1 dans le schéma s1 par défaut avec des colonnes (a int NOT NULL).

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

Ce code génère une Invalid object name erreur. t1 peut être soit dbo.t1 soit , s1.t1chacun avec un nombre différent de colonnes.

Résultat même avec un jeu de résultats ambigu

Utilisez les mêmes hypothèses que l'exemple précédent.

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

Voici un jeu de résultats partiel.

Les deux dbo.t1.a types sont s1.t1.a int et ont une valeur nullabilité différente.

Contenu connexe

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