sp_describe_first_result_set (Transact-SQL)
Si applica a:
SQL Server database SQL di Azure Istanza gestita di SQL di Azure Azure Synapse Analytics AnalyticsPlatform System (PDW)SQL analytics endpoint in Microsoft FabricWarehouse in Microsoft Fabric
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 il motore di database non è in grado di determinare i metadati per la prima query che verrà eseguita eseguendo un'analisi statica. La vista a gestione dinamica sys.dm_exec_describe_first_result_set (Transact-SQL) restituisce le stesse informazioni.
Convenzioni di 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 per il batch Transact-SQL, simile a sp_executesql. I parametri possono essere nvarchar(n) o nvarchar(max).
Stringa contenente 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 parametri 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 Specifica se vengono restituite altre colonne chiave e informazioni sulla tabella di origine. 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 del codice restituito
sp_describe_first_result_set restituisce sempre lo stato zero in caso di esito positivo. Se la routine genera un errore e la routine viene chiamata rpc, lo stato restituito viene popolato dal tipo di errore descritto nella colonna error_type di sys.dm_exec_describe_first_result_set. Se la routine 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 verrà 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 la 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 = Il tipo di dati della colonna è varchar(max), nvarchar(max), varbinary(max)o xml. Per le colonne di testo , 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, viene restituito 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 assegnato come appare 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 il 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 primi metadati del set di risultati per (un ipotetico) batch A e se tale batch (A) viene successivamente eseguito, il batch genererà (1) un errore di tempo di ottimizzazione, (2) genera un errore di runtime, (3) non restituisce alcun set di risultati o (4) restituisce un primo set di risultati con gli stessi metadati descritti da sp_describe_first_result_set.
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, la garanzia è che l'esecuzione batch restituirà set di risultati senza risultati.
Questa garanzia presuppone che nel server non siano presenti modifiche dello schema rilevanti. Le modifiche dello schema rilevanti nel server non includono la creazione di tabelle temporanee o variabili di tabella nel batch A tra il tempo chiamato sp_describe_first_result_set e l'ora in cui il set di risultati viene restituito durante l'esecuzione, incluse le modifiche dello schema apportate dal batch B.
sp_describe_first_result_set restituisce un errore in uno dei casi seguenti.
Se il @tsql di input non è un batch Transact-SQL valido. La validità è determinata dall'analisi e dall'analisi del batch Transact-SQL. Eventuali errori causati dal batch durante l'ottimizzazione delle query o durante l'esecuzione non vengono considerati quando si determina se il batch Transact-SQL è valido.
Se @params non è NULL e contiene una stringa che non è una stringa di dichiarazione sintatticamente valida per i parametri o se contiene una stringa che dichiara un parametro più di una volta.
Se il batch Transact-SQL di input dichiara una variabile locale con 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. Questo tiene conto di tutte le istruzioni del flusso di controllo (GOTO, Blocchi IF/EL edizione Standard, WHILE e Transact-SQL TRY/CATCH) e qualsiasi routine, batch Transact-SQL dinamici o trigger richiamati dal batch di input da 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 a causa di un'azione a catena su una chiave esterna Vincolo. 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 viene 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:
da varchar(a) a varchar(a') dove a' > a.
da varchar(a) a varchar(max)
da nvarchar(a) a nvarchar(a') dove a' > a.
da nvarchar(a) a nvarchar(max)
varbinary(a) to varbinary(a') dove a' > a.
da varbinary(a) a varbinary(max)
sp_describe_first_result_set non supporta la ricorsione indiretta.
Autorizzazioni
È necessaria l'autorizzazione per eseguire l'argomento @tsql.
Esempi
Esempi tipici
R. 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;
Questo è il 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
Questo è il 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
Questo è il 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 |
C. Archiviazione dei risultati in una tabella
In alcuni scenari è necessario inserire i risultati della sp_describe_first_result_set procedura in una tabella in modo da poter elaborare ulteriormente lo schema.
Prima di tutto è necessario creare una tabella che corrisponda all'output della sp_describe_first_result_set procedura:
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
);
Quando si crea una tabella, è possibile archiviare lo schema di una query in tale tabella.
declare @tsql nvarchar(max) = 'select top 0 * from sys.credentials';
insert #frs
exec sys.sp_describe_first_result_set @tsql;
select * from #frs;
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 valore intNULL
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 valore intNULL
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 VALORE NULL INT
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 abbia 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: valore NULL int perché sia dbo.t1.a che s1.t1.a hanno un tipo int e null diversi.
Vedi anche
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)
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per