sp_describe_first_result_set (Transact-SQL)

Restituisce i metadati per il primo set di risultati possibile del batch Transact-SQL. Restituisce un set di risultati vuoto se il batch non restituisce risultati. Genera un errore se tramite il Motore di database non è possibile determinare i metadati per la prima query che verrà eseguita tramite un'analisi statica. Nella DMV sys.dm_exec_describe_first_result_set (Transact-SQL) vengono restituite le stesse informazioni.

Convenzioni della sintassi Transact-SQL

Sintassi

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

Argomenti

• [ @tsql = ] 'Transact-SQL_batch'
  Una o più istruzioni Transact-SQL. Transact-SQL_batch  può essere nvarchar(n) o nvarchar(max).

• [ @params = ] N'parameters'
  @params fornisce una stringa di dichiarazione per i parametri del batch Transact-SQL simile a sp_executesql. I parametri possono essere nvarchar(n) o nvarchar(max).

  Stringa che contiene le definizioni di tutti i parametri incorporati in Transact-SQL_batch. La stringa deve essere una costante o una variabile Unicode. Ogni definizione di parametro è costituita da un nome del parametro e da un tipo di dati. n è un segnaposto che indica definizioni di parametro aggiuntive. Ogni parametro specificato nell'istruzione deve essere definito in @params. Se l'istruzione Transact-SQL o il batch nell'istruzione non contiene parametri, @params non è necessario. Il valore predefinito per questo parametro è NULL.

• [ @browse_information_mode = ] tinyint
  Viene specificato se vengono restituite informazioni aggiuntive sulla tabella di origine e sulle colonne chiave. Se impostato su 1, ogni query viene analizzata come se per essa fosse stata specificata un'opzione FOR BROWSE. Vengono restituite informazioni aggiuntive sulla tabella di origine e sulle colonne chiave.

  • Se impostato su 0, non viene restituita alcuna informazione.

  • Se impostato su 1, ogni query viene analizzata come se per essa fosse stata specificata un'opzione FOR BROWSE. Verranno restituiti nomi della tabella di base come informazioni sulla colonna di origine.

  • Se impostato su 2, ogni query viene analizzata come se venisse utilizzata per la preparazione o l'esecuzione di un cursore. Verranno restituiti nomi della vista come informazioni sulla colonna di origine.

Valori di codice restituiti

sp_describe_first_result_set restituisce sempre uno stato pari a zero in caso di esito positivo. Se la procedura viene chiamata come RPC e viene generato un errore, lo stato restituito viene popolato dal tipo di errore, come descritto nella colonna error_type di sys.dm_exec_describe_first_result_set. Se la procedura viene chiamata da Transact-SQL, il valore restituito è sempre zero, anche quando si verifica un errore.

Set di risultati

Questi metadati comuni vengono restituiti come set di risultati con una riga per ogni colonna nei metadati dei risultati. Ogni riga descrive il tipo e l'ammissione di valori Null della colonna nel formato descritto nella sezione seguente. Se la prima istruzione non esiste per ogni percorso di controllo, viene restituito un set di risultati con zero righe.

Nome colonna	Tipo di dati	Descrizione
is_hidden	bit NOT NULL	Indica che la colonna è una colonna aggiuntiva aggiunta per informazioni di esplorazione che non compare effettivamente nel set di risultati.
column_ordinal	int NOT NULL	Contiene la posizione ordinale della colonna nel set di risultati. La posizione della prima colonna viene specificata come 1.
name	sysname NULL	Contiene il nome della colonna se è possibile determinare un nome. In caso contrario, contiene NULL.
is_nullable	bit NOT NULL	Contiene il valore 1 se la colonna ammette valori Null, 0 se la colonna non ammette valori Null e 1 se non è possibile determinare se la colonna ammette valori Null.
system_type_id	int NOT NULL	Contiene il system_type_id del tipo di dati della colonna come specificato in sys.types. Per i tipi CLR, anche se la colonna system_type_name restituisce NULL, in questa colonna viene restituito il valore 240.
system_type_name	nvarchar(256) NULL	Contiene il nome e gli argomenti, ad esempio lunghezza, precisione e scala, specificati per il tipo di dati della colonna. Se il tipo di dati è un tipo di alias definito dall'utente, il tipo di sistema sottostante viene specificato qui. Se è un tipo CLR definito dall'utente, in questa colonna viene restituito NULL.
max_length	smallint NOT NULL	Lunghezza massima in byte della colonna. -1 = La colonna è di tipo varchar(max), nvarchar(max), varbinary(max) o xml. Per le colonne di tipo text, il valore max_length sarà 16 o il valore impostato da sp_tableoption 'text in row'.
precision	tinyint NOT NULL	Precisione della colonna se basata su valori numerici. In caso contrario, restituisce 0.
scale	tinyint NOT NULL	Scala della colonna se basata su valori numerici. In caso contrario, restituisce 0.
collation_name	sysname NULL	Nome delle regole di confronto della colonna se basata su caratteri. In caso contrario, restituisce NULL.
user_type_id	int NULL	Per i tipi di alias e CLR, contiene il valore user_type_id del tipo di dati della colonna come specificato in sys.types. In caso contrario, è NULL.
user_type_database	sysname NULL	Per i tipi di alias e CLR, contiene il nome del database in cui è definito il tipo. In caso contrario, è NULL.
user_type_schema	sysname NULL	Per i tipi di alias e CLR, contiene il nome dello schema in cui è definito il tipo. In caso contrario, è NULL.
user_type_name	sysname NULL	Per i tipi di alias e CLR, contiene il nome del tipo. In caso contrario, è NULL.
assembly_qualified_type_name	nvarchar(4000)	Per i tipi CLR, restituisce il nome dell'assembly e la classe che definisce il tipo. In caso contrario, è NULL.
xml_collection_id	int NULL	Contiene il valore xml_collection_id del tipo di dati della colonna, come specificato in sys.columns. Questa colonna restituisce NULL se il tipo restituito non è associato a una raccolta XML Schema.
xml_collection_database	sysname NULL	Contiene il database in cui viene definita la raccolta XML Schema associata a questo tipo. Questa colonna restituisce NULL se il tipo restituito non è associato a una raccolta XML Schema.
xml_collection_schema	sysname NULL	Contiene lo schema in cui viene definita la raccolta XML Schema associata a questo tipo. Questa colonna restituisce NULL se il tipo restituito non è associato a una raccolta XML Schema.
xml_collection_name	sysname NULL	Contiene il nome della raccolta XML Schema associata a questo tipo. Questa colonna restituisce NULL se il tipo restituito non è associato a una raccolta XML Schema.
is_xml_document	bit NOT NULL	Restituisce 1 se il tipo di dati restituito è XML ed è garantito che questo tipo sia un documento XML completo (incluso un nodo radice), contrariamente a un frammento XML. In caso contrario, restituisce 0.
is_case_sensitive	bit NOT NULL	Restituisce 1 se la colonna è di un tipo stringa che fa distinzione tra maiuscole e minuscole e 0 in caso contrario.
is_fixed_length_clr_type	bit NOT NULL	Restituisce 1 se la colonna è di un tipo CLR a lunghezza fissa e 0 in caso contrario.
source_server	sysname	Nome del server di origine restituito dalla colonna in questo risultato (se ha origine in un server remoto). Il nome viene specificato come viene visualizzato in sys.servers. Restituisce NULL se la colonna ha origine nel server locale o se non è possibile determinare in quale server ha origine. Viene popolata solo se sono richieste informazioni di esplorazione.
source_database	sysname	Nome del database di origine restituito dalla colonna in questo risultato. Restituisce NULL se non è possibile determinare il database. Viene popolata solo se sono richieste informazioni di esplorazione.
source_schema	sysname	Nome dello schema di origine restituito dalla colonna in questo risultato. Restituisce NULL se non è possibile determinare lo schema. Viene popolata solo se sono richieste informazioni di esplorazione.
source_table	sysname	Nome della tabella di origine restituita dalla colonna in questo risultato. Restituisce NULL se non è possibile determinare la tabella. Viene popolata solo se sono richieste informazioni di esplorazione.
source_column	sysname	Nome della colonna di origine restituita dalla colonna del risultato. Restituisce NULL se non è possibile determinare la colonna. Viene popolata solo se sono richieste informazioni di esplorazione.
is_identity_column	bit NULL	Restituisce 1 se la colonna è una colonna Identity e 0 in caso contrario. Restituisce NULL se non è possibile determinare se la colonna è una colonna Identity.
is_part_of_unique_key	bit NULL	Restituisce 1 se la colonna fa parte di un indice univoco (inclusi vincoli univoci e primari) e 0 in caso contrario. Restituisce NULL se non è possibile determinare se la colonna fa parte di un indice univoco. Viene popolata solo se sono richieste informazioni di esplorazione.
is_updateable	bit NULL	Restituisce 1 se la colonna può essere aggiornata e 0 in caso contrario. Restituisce NULL se non è possibile determinare se la colonna può essere aggiornata.
is_computed_column	bit NULL	Restituisce 1 se la colonna è una colonna calcolata e 0 in caso contrario. Restituisce NULL se non è possibile determinare se la colonna è una colonna calcolata.
is_sparse_column_set	bit NULL	Restituisce 1 se la colonna è una colonna di tipo sparse e 0 in caso contrario. Restituisce NULL se non è possibile determinare se la colonna fa parte di un set di colonne di tipo sparse.
ordinal_in_order_by_list	smallint NULL	Posizione della colonna nell'elenco ORDER BY. Restituisce NULL se la colonna non compare nell'elenco ORDER BY o se l'elenco ORDER BY non può essere determinato in modo univoco.
order_by_list_length	smallint NULL	Lunghezza dell'elenco ORDER BY. Restituisce NULL se non è presente alcun elenco ORDER BY o se l'elenco ORDER BY non può essere determinato in modo univoco. Si noti che questo valore sarà lo stesso per tutte le righe restituite da sp_describe_first_result_set.
order_by_is_descending	smallint NULL	Se ordinal_in_order_by_list non è NULL, la colonna order_by_is_descending indica la direzione della clausola ORDER BY per questa colonna. In caso contrario, viene restituito NULL.
tds_type_id	int NOT NULL	Per uso interno.
tds_length	int NOT NULL	Per uso interno.
tds_collation_id	int NULL	Per uso interno.
tds_collation_sort_id	tinyint NULL	Per uso interno.

Osservazioni

sp_describe_first_result_set garantisce che se la procedura restituisce i metadati del primo set di risultati per un ipotetico batch A e se il batch (A) viene eseguito in seguito, verrà generato un errore in fase di ottimizzazione (1), verrà generato un errore di run-time (2), non verrà restituito alcun set di risultati (3) oppure verrà restituito un primo set di risultati con gli stessi metadati descritti da sp_describe_first_result_set (4).

Il nome, l'ammissione di valori Null e il tipo di dati possono variare. Se sp_describe_first_result_set restituisce un set di risultati vuoto, è garantito che l'esecuzione del batch non restituirà alcun set di risultati.

Questa garanzia presuppone che non vengano apportate modifiche allo schema nel server. Le modifiche allo schema rilevanti nel server non includono la creazione di tabelle temporanee o variabili di tabella nel batch A tra la chiamata a sp_describe_first_result_set e la restituzione del set di risultati durante l'esecuzione, incluse le modifiche apportate allo schema dal batch B.

sp_describe_first_result_set restituisce un errore nei casi seguenti.

• Il batch @tsql di input non è un batch Transact-SQL valido. La validità viene determinata tramite l'analisi del batch Transact-SQL. Qualsiasi errore causato dal batch durante l'ottimizzazione della query o durante l'esecuzione viene ignorato durante la determinazione della validità del batch Transact-SQL.

• @params non è NULL e contiene una stringa che non è una stringa di dichiarazione sintatticamente valida per i parametri oppure contiene una stringa che dichiara qualsiasi parametro più di una volta.

• Il batch Transact-SQL di input dichiara una variabile locale avente lo stesso nome di un parametro dichiarato in @params.

• L'istruzione utilizza una tabella temporanea.

• La query include la creazione di una tabella permanente sulla quale viene eseguita una query.

Se tutti gli altri controlli hanno esito positivo, vengono presi in considerazione tutti i possibili percorsi del flusso di controllo nel batch di input. Vengono quindi prese in considerazione tutte le istruzioni del flusso di controllo (GOTO, IF/ELSE, WHILE e blocchi TRY/CATCH Transact-SQL), nonché le procedure, i batch Transact-SQL dinamici o i trigger richiamati dal batch di input tramite un'istruzione EXEC, un'istruzione DDL che causa l'attivazione di trigger DDL o un'istruzione DML che causa l'attivazione di trigger in una tabella di destinazione o in una tabella modificata in seguito a un'azione di propagazione in un vincolo di chiave esterna. Qualora siano possibili più percorsi di controllo, a un certo punto si verifica l'arresto di un algoritmo.

Per ogni percorso del flusso di controllo, la prima istruzione (se presente) che restituisce un set di risultati è determinata da sp_describe_first_result_set.

Se in un batch vengono trovate più prime istruzioni possibili, i relativi risultati possono variare nel numero di colonne, nel nome della colonna, nell'ammissione di valori Null e nel tipo di dati. La gestione delle differenze viene descritta più dettagliatamente qui di seguito:

• Se il numero di colonne è diverso, viene generato un errore e non viene restituito alcun risultato.

• Se il nome della colonna è diverso, il nome della colonna restituito è impostato su NULL.

• Se l'ammissione di valori NULL è diversa, l'impostazione restituita ammette valori NULL.

• Se il tipo di dati è diverso, viene generato un errore e non viene restituito alcun risultato se non nei casi seguenti:

  • varchar(a) in varchar(a') dove a' > a.

  • varchar(a) per varchar(max)

  • nvarchar(a) in nvarchar(a') dove a' > a.

  • nvarchar(a) per nvarchar(max)

  • varbinary(a) in varbinary(a') dove a' > a.

  • varbinary(a) per varbinary(max)

sp_describe_first_result_set non supporta la ricorsione indiretta.

Autorizzazioni

Richiede l'autorizzazione per eseguire l'istruzione @tsql.

Esempi

Esempi tipici

A.Esempio semplice

Nell'esempio seguente viene descritto il set di risultati restituito da una singola query.

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

Nell'esempio seguente viene mostrato il set di risultati restituito da una singola query contenente un parametro.

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.Esempi di modalità browse

Nei tre esempi seguenti viene illustrata la differenza principale tra le diverse modalità di informazioni di esplorazione. Nei risultati delle query sono state incluse solo le colonne attinenti.

Nell'esempio in cui viene utilizzato 0 non viene restituita alcuna informazione.

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;

Set di risultati:

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

Nell'esempio in cui viene utilizzato 1 vengono restituite informazioni come se nella query fosse stata specificata un'opzione FOR BROWSE.

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

Set di risultati:

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

Nell'esempio in cui viene utilizzato 2 viene indicata l'esecuzione di un'analisi come se si stesse effettuando la preparazione di un cursore.

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

Set di risultati:

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

Esempi di problemi

Negli esempi seguenti vengono utilizzate due tabelle per tutti gli esempi. Eseguire le istruzioni seguenti per creare tabelle di esempio.

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

Errore perché il numero di colonne è diverso

Il numero di colonne nei primi set di risultati possibili è diverso in questo esempio.

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

Errore perché i tipi di dati sono diversi

I tipi delle colonne sono diversi nei vari primi set di risultati possibili.

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

Risultato: errore, tipi non corrispondenti (int e smallint).

Non è possibile determinare il nome della colonna

Le colonne nei primi set di risultati possibili variano nella lunghezza per lo stesso tipo di lunghezza variabile, ammissione di valori NULL e nomi delle colonne:

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

Risultato: <Nome colonna sconosciuto> varchar(20) NULL

Nome della colonna forzato a essere identico tramite aliasing

Come in precedenza, ma le colonne hanno lo stesso nome tramite l'aliasing delle colonne.

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

Risultato: b varchar(20) NULL

Errore perché non è possibile trovare tipi di colonna corrispondenti

I tipi di colonne sono diversi nei vari primi set di risultati possibili.

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

Risultato: errore, tipi non corrispondenti (varchar(10) e nvarchar(10)).

Il set di risultati può restituire un errore

Il primo set di risultati è errore o set di risultati.

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

Risultato: un int NULL

Alcuni percorsi di codice non restituiscono risultati

Il primo set di risultati è Null o un set di risultati.

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

Risultato: un int NULL

Risultato da SQL dinamico

Il primo set di risultati è SQL dinamico individuabile perché si tratta di una stringa letterale.

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

Risultato: un INT NULL

Errore di risultato da SQL dinamico

Il primo set di risultati non è definito a causa di SQL dinamico.

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

Risultato: Errore. Il risultato non è individuabile a causa di SQL dinamico.

Set di risultati specificato dall'utente

Il primo set di risultati viene specificato manualmente dall'utente.

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

Risultato: Column1 bigint NOT NULL

Errore causato da un set di risultati ambiguo

In questo esempio si presuppone che un altro utente denominato user1 disponga di una tabella denominata t1 nello schema predefinito s1 con colonne (int NOT NULL).

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

Risultato: Errore. t1 può essere dbo.t1 o s1.t1, ognuno con un numero diverso di colonne.

Risultato anche con set di risultati ambiguo

Utilizzare le stesse ipotesi dell'esempio precedente.

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

Risultato: un int NULL perché sia dbo.t1.a sia s1.t1.a presentano il tipo int e un'ammissione di valori NULL diversa.

Vedere anche

Riferimento

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)