Condividi tramite

sp_describe_first_result_set (Transact-SQL)

  • Articolo

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure endpoint di analisi SQL di Azure Synapse Analytics Platform System (PDW) in Microsoft Fabric Warehouse 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 riesce a determinare i metadati per la prima query che verrà eseguita eseguendo un'analisi statica. La visualizzazione a gestione dinamica sys.dm_exec_describe_first_result_set restituisce le stesse informazioni.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

[ @tsql = ] 'tsql'

Una o più istruzioni Transact-SQL. @tsql potrebbe essere nvarchar(n) o nvarchar(max).

[ @params = ] N'params'

@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 che contiene le definizioni di tutti i parametri incorporati in @tsql. 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. NULL è il valore predefinito per questo parametro.

[ @browse_information_mode = ] tinyint

Specifica se vengono restituite colonne chiave aggiuntive e informazioni sulla tabella di origine. Se impostato su 1, ogni query viene analizzata come se includesse un'opzione FOR BROWSE nella query.

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

  • Se impostato su 1, ogni query viene analizzata come se includesse un'opzione FOR BROWSE nella query. In questo modo vengono restituiti i nomi delle tabelle di base come informazioni sulla colonna di origine.

  • Se impostato su 2, ogni query viene analizzata come se fosse usata per preparare o eseguire un cursore. In questo modo vengono restituiti i nomi delle visualizzazioni 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 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 Indica che la colonna è una colonna aggiuntiva aggiunta ai fini dell'esplorazione delle informazioni e che non viene effettivamente visualizzata nel set di risultati. Non ammette i valori NULL.
column_ordinal int Contiene la posizione ordinale della colonna nel set di risultati. La posizione della prima colonna viene specificata come 1. Non ammette i valori NULL.
name sysname Contiene il nome della colonna se è possibile determinare un nome. In caso contrario, contiene NULL. Ammette valori Null.
is_nullable bit Contiene il valore 1 se la colonna consente , 0 se la colonna non consente NULLNULLe 1 se non può essere determinata se la colonna consente NULL. Non ammette i valori NULL.
system_type_id int Contiene l'oggetto system_type_id del tipo di dati della colonna come specificato in sys.types. Per i tipi CLR, anche se la system_type_name colonna restituisce NULL, questa colonna restituisce il valore 240. Non ammette i valori NULL.
system_type_name nvarchar(256) 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 si tratta di un tipo CLR definito dall'utente, NULL viene restituito in questa colonna. Ammette valori Null.
max_length smallint 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 max_length valore è 16 o il valore impostato da sp_tableoption 'text in row'. Non ammette i valori NULL.
precision tinyint Precisione della colonna se basata su valori numerici. In caso contrario restituisce 0. Non ammette i valori NULL.
scale tinyint Scala della colonna se basata su valori numerici. In caso contrario restituisce 0. Non ammette i valori NULL.
collation_name sysname Nome delle regole di confronto della colonna se basata su caratteri. In caso contrario restituisce NULL. Ammette valori Null.
user_type_id int Per i tipi CLR e alias, contiene l'oggetto user_type_id del tipo di dati della colonna come specificato in sys.types. In caso contrario, è NULL. Ammette valori Null.
user_type_database sysname Per i tipi di alias e CLR, contiene il nome del database in cui è definito il tipo. In caso contrario, è NULL. Ammette valori Null.
user_type_schema sysname Per i tipi di alias e CLR, contiene il nome dello schema in cui è definito il tipo. In caso contrario, è NULL. Ammette valori Null.
user_type_name sysname Per i tipi di alias e CLR, contiene il nome del tipo. In caso contrario, è NULL. Ammette valori 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. Ammette valori Null.
xml_collection_id int Contiene l'oggetto 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 di XML Schema. Ammette valori Null.
xml_collection_database sysname 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 di XML Schema. Ammette valori Null.
xml_collection_schema sysname 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 di XML Schema. Ammette valori Null.
xml_collection_name sysname Contiene il nome della raccolta XML Schema associata a questo tipo. Questa colonna restituisce NULL se il tipo restituito non è associato a una raccolta di XML Schema. Ammette valori Null.
is_xml_document bit Restituisce 1 se il tipo di dati restituito è XML e tale tipo è garantito che sia un documento XML completo (incluso un nodo radice), anziché un frammento XML. In caso contrario restituisce 0. Non ammette i valori NULL.
is_case_sensitive bit Restituisce 1 se la colonna è un tipo stringa con distinzione tra maiuscole e minuscole e 0 in caso contrario. Non ammette i valori NULL.
is_fixed_length_clr_type bit Restituisce 1 se la colonna è un tipo CLR a lunghezza fissa e 0 in caso contrario. Non ammette i valori NULL.
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 il server in cui ha origine. Viene popolata solo se sono richieste informazioni di esplorazione. Ammette valori Null.
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. Ammette valori Null.
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. Ammette valori Null.
source_table sysname Nome della tabella di origine restituita dalla colonna in questo risultato. Restituisce NULL se la tabella non può essere determinata. Viene popolata solo se sono richieste informazioni di esplorazione. Ammette valori Null.
source_column sysname Nome della colonna di origine restituita dalla colonna del risultato. Restituisce NULL se la colonna non può essere determinata. Viene popolata solo se sono richieste informazioni di esplorazione. Ammette valori Null.
is_identity_column bit Restituisce 1 se la colonna è una colonna Identity e 0 in caso contrario. Restituisce NULL se non è possibile determinare che la colonna è una colonna Identity. Ammette valori Null.
is_part_of_unique_key bit Restituisce 1 se la colonna fa parte di un indice univoco (incluso vincolo univoco e primario) e 0 in caso contrario. Restituisce NULL se non è possibile determinare che la colonna fa parte di un indice univoco. Viene popolata solo se sono richieste informazioni di esplorazione. Ammette valori Null.
is_updateable bit Restituisce 1 se la colonna è aggiornabile e 0 in caso contrario. Restituisce NULL se non è possibile determinare che la colonna è aggiornabile. Ammette valori Null.
is_computed_column bit Restituisce 1 se la colonna è una colonna calcolata e 0 in caso contrario. Restituisce NULL se non è possibile determinare che la colonna è una colonna calcolata. Ammette valori Null.
is_sparse_column_set bit Restituisce 1 se la colonna è una colonna di tipo sparse e 0 in caso contrario. Restituisce NULL se non è possibile determinare che la colonna fa parte di un set di colonne di tipo sparse. Ammette valori Null.
ordinal_in_order_by_list smallint Posizione di questa colonna nell'elenco ORDER BY . Restituisce NULL se la colonna non viene visualizzata nell'elenco ORDER BY o se l'elenco ORDER BY non può essere determinato in modo univoco. Ammette valori Null.
order_by_list_length smallint Lunghezza dell'elenco ORDER BY . Restituisce NULL se non è presente alcun ORDER BY elenco o se l'elenco ORDER BY non può essere determinato in modo univoco. Questo valore è lo stesso per tutte le righe restituite da sp_describe_first_result_set. Ammette valori Null.
order_by_is_descending smallint ordinal_in_order_by_list Se non NULLè , la order_by_is_descending colonna indica la direzione della ORDER BY clausola per questa colonna. In caso contrario, segnala NULL. Ammette valori Null.
tds_type_id int Per uso interno. Non ammette i valori NULL.
tds_length int Per uso interno. Non ammette i valori NULL.
tds_collation_id int Per uso interno. Ammette valori Null.
tds_collation_sort_id tinyint Per uso interno. Ammette valori Null.

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 quindi eseguito, il batch:

  • genera un errore di tempo di ottimizzazione
  • genera un errore di run-time
  • non restituisce alcun set di risultati
  • 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 del batch restituisce set di risultati senza risultati.

Questa garanzia presuppone che nel server non siano presenti modifiche dello schema rilevanti. Le modifiche dello schema pertinenti nel server non includono la creazione di tabelle temporanee o variabili di tabella nel batch A tra il tempo sp_describe_first_result_set chiamato 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:

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

  • @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.

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

  • L'istruzione usa 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. In questo modo vengono prese in considerazione tutte le istruzioni del flusso di controllo (GOTO, IF/ELSE, WHILEe i blocchi Transact-SQL/TRYCATCH) e tutte le procedure, i batch Transact-SQL dinamici o i 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 un vincolo di chiave esterna. A un certo punto, con il maggior numero possibile di percorsi di controllo, un algoritmo si arresta.

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 viene impostato su NULL.

  • Se il valore Nullbility è diverso, il valore Nullbility restituito consente NULL.

  • Se il tipo di dati è diverso, viene generato un errore e non viene restituito alcun risultato ad eccezione dei 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 di base

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

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

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

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

Esempio che usa 0, che indica che non vengono restituite informazioni.

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;

Di seguito è riportato un set di risultati parziale.

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;

Di seguito è riportato un set di risultati parziale.

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

Esempio che usa 2 che indica l'analisi come se si preparasse 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. Archiviare i 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 INTO #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.

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

Errore perché i tipi di dati sono diversi

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

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

In questo modo si verifica un errore di 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:

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name Nome colonna sconosciuto
system_type_name varchar
max_length 20
is_nullable 1

Nome della colonna forzato a essere identico tramite aliasing

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

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name b
system_type_name varchar
max_length 20
is_nullable 1

Errore perché i tipi di colonna non possono essere confrontati

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

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

Ciò genera un errore di 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.

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name a
system_type_name int
is_nullable 1

Alcuni percorsi di codice non restituiscono risultati

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

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name a
system_type_name int
is_nullable 1

Risultato da SQL dinamico

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

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name a
system_type_name int
is_nullable 1

Errore di risultato da SQL dinamico

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

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

In questo modo si verifica un 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.

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name Column1
system_type_name bigint
is_nullable 0

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 s1 predefinito con colonne (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';

Questo codice genera un Invalid object name 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.

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

Di seguito è riportato un set di risultati parziale.

Colonna Valore
name a
system_type_name int
is_nullable 1

Sia dbo.t1.a che s1.t1.a hanno un tipo int e un valore Nullbility diverso.

Contenuto correlato