sp_describe_first_result_set (Transact-SQL)

  • Artigo

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)Ponto de extremidade de SQL no Microsoft FabricWarehouse no Microsoft Fabric

Retorna os metadados para o primeiro conjunto possível de resultados do lote Transact-SQL. Retorna um conjunto de resultados vazio quando o lote não retorna resultados. Gera um erro quando o Mecanismo de Banco de Dados não pode determinar os metadados para a primeira consulta que será executada por meio de uma análise estática. E exibição de gerenciamento dinâmico sys.dm_exec_describe_first_result_set (Transact-SQL) retorna a mesma informação.

Convenções de sintaxe de Transact-SQL

Sintaxe

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

Argumentos

[ @tsql = ] 'Transact-SQL_batch' Uma ou mais instruções de Transact-SQL. Transact-SQL_batch pode ser nvarchar(n) ou nvarchar(max).

[ @params = ] N'parameters' @params fornece uma cadeia de declaração para os parâmetros do lote Transact-SQL, similar a sp_executesql. Os parâmetros podem ser nvarchar(n) ou nvarchar(max).

É uma cadeia de caracteres que contém as definições de todos os parâmetros inseridos na instrução Transact-SQL_batch. A cadeia de caracteres deve ser uma constante Unicode ou uma variável Unicode. Cada definição de parâmetro consiste em um nome de parâmetro e um tipo de dados. n é um espaço reservado que indica definições de parâmetro adicionais. Todo parâmetro especificado na instrução deve ser definido em @ params. Se a instrução Transact-SQL ou lote na instrução não contiverem parâmetros, @params não será necessário. O valor padrão para este parâmetro é NULL.

[ @browse_information_mode = ] tinyint Especifica se colunas de chave adicionais e informações de tabela de origem são retornadas. Se definido como 1, cada consulta será analisada como se incluísse uma opção FOR BROWSE na consulta. Colunas de chave adicionais e informações de tabela de origem são retornadas.

  • Se for definido como 0, nenhuma informação será retornada.

  • Se definido como 1, cada consulta será analisada como se incluísse uma opção FOR BROWSE na consulta. Isto retornará nomes de tabela base como as informações de coluna de origem.

  • Se for definido como 2, cada consulta será analisada como se fosse usada na preparação ou execução de um cursor. Isto retornará nomes de exibição como as informações de coluna de origem.

Valores do código de retorno

sp_describe_first_result_set sempre retorna um status de zero ao obter êxito. Se o procedimento lançar um erro e se for chamado como uma RPC, o status de retorno será preenchido pelo tipo de erro descrito na coluna error_type de sys.dm_exec_describe_first_result_set. Se o procedimento for chamado de Transact-SQL, o valor de retorno sempre será zero, até mesmo se houver erro.

Conjuntos de resultados

Estes metadados comuns são retornados como um conjunto de resultados com uma linha para cada coluna nos metadados de resultados. Cada linha descreve o tipo e a nulidade da coluna no formato descrito na seção a seguir. Se a primeira instrução não existir para todo caminho de controle, um conjunto de resultados com zero linhas será retornado.

Nome da coluna Tipo de dados Descrição
is_hidden bit NOT NULL Indica que a coluna é uma coluna extra adicionada para fins de informações de navegação e que ela não é exibida realmente no conjunto de resultados.
column_ordinal int NOT NULL Contém a posição ordinal da coluna no conjunto de resultados. A posição da primeira coluna será especificada como 1.
name sysname NULL Conterá o nome da coluna se um nome puder ser determinado. Caso contrário, conterá NULL.
is_nullable bit NOT NULL Conterá o valor 1 se a coluna permitir NULLs, 0 se a coluna não permitir NULLs e 1 caso não seja possível determinar se a coluna permite NULLs.
system_type_id int NOT NULL Contém o system_type_id do tipo de dados da coluna especificada em sys.types. Para tipos de CLR, embora a coluna system_type_name retorne NULL, essa coluna retornará o valor 240.
system_type_name nvarchar(256) NULL Contém o nome e argumentos (como comprimento, precisão, escala), especificados para o tipo de dados da coluna. Se o tipo de dados for um tipo de alias definido pelo usuário, o tipo de sistema subjacente será especificado aqui. Se for um tipo de CLR definido pelo usuário, NULL será retornado nessa coluna.
max_length smallint NOT NULL Comprimento máximo (em bytes) da coluna.

-1 = O tipo de dados de coluna é varchar(max), nvarchar(max), varbinary(max) ou xml.

Para as colunas text, o valor max_length será 16 ou o valor definido por sp_tableoption 'text in row'.
precisão tinyint NOT NULL Precisão da coluna, se tiver base numérica. Caso contrário, retorna 0.
scale tinyint NOT NULL Escala da coluna, se tiver base numérica. Caso contrário, retorna 0.
collation_name sysname NULL Nome da ordenação da coluna, se baseada em caracteres. Caso contrário, retorna NULL.
user_type_id int NULL Para tipos de CLR e alias, contém o user_type_id do tipo de dados da coluna como especificado em sys.types. Caso contrário, é NULL.
user_type_database sysname NULL Para tipos de CLR e de alias, contém o nome do banco de dados no qual o tipo é definido. Caso contrário, é NULL.
user_type_schema sysname NULL Para tipos de CLR e de alias, contém o nome do esquema no qual o tipo é definido. Caso contrário, é NULL.
user_type_name sysname NULL Para tipos de CLR e de alias, contém o nome do tipo. Caso contrário, é NULL.
assembly_qualified_type_name nvarchar(4000) Para tipos de CLR, retorna o nome do assembly e da classe que define o tipo. Caso contrário, é NULL.
xml_collection_id int NULL Contém o xml_collection_id do tipo de dados da coluna como especificado em sys.columns. Essa coluna retornará NULL se o tipo retornado não estiver associado a uma coleção de esquemas XML.
xml_collection_database sysname NULL Contém o banco de dados no qual a coleção de esquemas XML associada a esse tipo está definida. Essa coluna retornará NULL se o tipo retornado não estiver associado a uma coleção de esquemas XML.
xml_collection_schema sysname NULL Contém o esquema no qual a coleção de esquemas XML associada a esse tipo está definida. Essa coluna retornará NULL se o tipo retornado não estiver associado a uma coleção de esquemas XML.
xml_collection_name sysname NULL Contém o nome da coleção de esquemas XML associada a esse tipo. Essa coluna retornará NULL se o tipo retornado não estiver associado a uma coleção de esquemas XML.
is_xml_document bit NOT NULL Retornará 1 se o tipo de dados retornado for o XML e esse tipo for garantido de ser um documento XML completo (incluindo um nó raiz), em vez de um fragmento XML. Caso contrário, retorna 0.
is_case_sensitive bit NOT NULL Retornará 1 se a coluna for um tipo de cadeia de caracteres com diferenciação de maiúsculas e minúsculas; caso contrário, retornará 0.
is_fixed_length_clr_type bit NOT NULL Retornará 1 se a coluna for um tipo de CLR de comprimento fixo; caso contrário, retornará 0.
source_server sysname Nome do servidor de origem retornado pela coluna neste resultado (se a origem for um servidor remoto). O nome é atribuído quando exibido em sys.servers. Retornará NULL se a coluna tiver origem no servidor local ou caso não seja possível determinar o servidor de origem. Será populado somente se informações de navegação forem solicitadas.
source_database sysname Nome do banco de dados de origem retornado pela coluna neste resultado. Retornará NULL se o banco de dados não puder ser determinado. Será populado somente se informações de navegação forem solicitadas.
source_schema sysname Nome do esquema de origem retornado pela coluna neste resultado. Retornará NULL se o esquema não puder ser determinado. Será populado somente se informações de navegação forem solicitadas.
source_table sysname Nome da tabela de origem retornado pela coluna neste resultado. Retornará NULL se a tabela não puder ser determinada. Será populado somente se informações de navegação forem solicitadas.
source_column sysname Nome da coluna de origem retornado pela coluna de resultado. Retornará NULL se a coluna não puder ser determinada. Será populado somente se informações de navegação forem solicitadas.
is_identity_column bit NULL Retornará 1 se a coluna for uma coluna de identidade; caso contrário, retornará 0. Retornará NULL caso não seja possível determinar se a coluna é uma coluna de identidade.
is_part_of_unique_key bit NULL Retornará 1 se a coluna fizer parte de um índice exclusivo (incluindo restrição exclusiva e primária); caso contrário, retornará 0. Retornará NULL caso não seja possível determinar se a coluna faz parte de um índice exclusivo. Será populado somente se informações de navegação forem solicitadas.
is_updateable bit NULL Retornará 1 se a coluna for uma coluna atualizável; caso contrário, retornará 0. Retornará NULL caso não seja possível determinar se a coluna é atualizável.
is_computed_column bit NULL Retornará 1 se a coluna for uma coluna computada; caso contrário, retornará 0. Retornará NULL caso não seja possível determinar se a coluna é uma coluna computada.
is_sparse_column_set bit NULL Retornará 1 se a coluna for uma coluna esparsa; caso contrário, retornará 0. Retornará NULL caso não seja possível determinar se a coluna faz parte de um conjunto de colunas esparsas.
ordinal_in_order_by_list smallint NULL Posição desta coluna na lista ORDER BY. Retornará o NULL se a coluna não for exibida na lista ORDER BY ou se a lista ORDER BY não puder ser determinada exclusivamente.
order_by_list_length smallint NULL Comprimento da lista ORDER BY. Retornará NULL se não houver uma lista ORDER BY ou se a lista ORDER BY não puder ser determinada exclusivamente. Observe que este valor será o mesmo para todas as linhas retornadas por sp_describe_first_result_set.
order_by_is_descending smallint NULL Se o ordinal_in_order_by_list não for NULL, a coluna order_by_is_descending relatará a direção da cláusula ORDER BY para esta coluna. Caso contrário, relatará NULL.
tds_type_id int NOT NULL Para uso interno.
tds_length int NOT NULL Para uso interno.
tds_collation_id int NULL Para uso interno.
tds_collation_sort_id tinyint NULL Para uso interno.

Comentários

sp_describe_first_result_set garante que, se o procedimento retornar os metadados do primeiro conjunto de resultados para um lote A (hipotético) e se esse lote A for subsequentemente executado, o lote (1) gerará um erro de tempo de otimização, (2) gerará um erro em tempo de execução, (3) não retornará nenhum conjunto de resultados ou (4) retornará um primeiro conjunto de resultados com os mesmos metadados descritos por sp_describe_first_result_set.

O nome, a nulidade e o tipo de dados podem diferir. Se sp_describe_first_result_set retornar um conjunto de resultados vazio, a garantia será que a execução do lote retornará conjuntos sem resultados.

Essa garantia presume que não há alterações de esquema relevantes no servidor. Alterações de esquema relevantes no servidor não incluem a criação de tabelas temporárias ou de variáveis de tabela no lote A entre a hora em que sp_describe_first_result_set é chamado e a hora em que o conjunto de resultados é retornado durante a execução, inclusive alterações de esquema feitas pelo lote B.

sp_describe_first_result_set retorna um erro em um dos casos as seguir.

  • Se a entrada @tsql não for um lote  válido do Transact-SQL. A validade é determinada pela análise do lote do Transact-SQL. Os erros causados pelo lote durante a otimização ou execução da consulta não serão considerados para determinar se o lote do Transact-SQL é válido.

  • Se @params não for NULL e se contiver uma cadeia de caracteres que não seja uma cadeia de caracteres de declaração sintaticamente válida para parâmetros ou se contiver uma cadeia de caracteres que declare qualquer parâmetro mais de uma vez.

  • Se o lote de entrada do Transact-SQL declarar uma variável local com o mesmo nome de um parâmetro declarado em @params.

  • Se a instrução usar uma tabela temporária.

  • A consulta inclui a criação de uma tabela permanente que é então consultada.

Se todas as outras verificações forem bem-sucedidas, serão considerados todos os caminhos de fluxo de controle possíveis dentro do lote de entrada. Isso leva em conta todas as instruções de fluxo de controle (blocos GOTO, IF/ELSE, WHILE e TRY/CATCH do Transact-SQL), como também quaisquer procedimentos, lotes Transact-SQL dinâmicos ou gatilhos invocados a partir do lote de entrada por uma instrução EXEC, uma instrução DDL que causa o disparo de gatilhos DDL ou uma instrução DML que causa o disparo de gatilhos em uma tabela de destino ou em uma tabela que é modificada por causa de ação em cascata em uma restrição de chave estrangeira. No caso de muitos possíveis caminhos de controle, em algum ponto, um algoritmo para.

Para cada caminho de fluxo de controle, a primeira instrução (se houver) que retorna um conjunto de resultados é determinada porsp_describe_first_result_set.

Quando houver várias e possíveis primeiras instruções em um lote, seus resultados podem diferir no número de colunas, no nome da coluna, na nulidade e no tipo de dados. Veja aqui mais detalhadamente como essas diferenças são tratadas:

  • Se o número de colunas diferir, um erro será gerado e nenhum resultado será retornado.

  • Se o nome da coluna diferir, o nome da coluna retornado será definido como NULL.

  • Se a nulidade diferir, a nulidade retornada permitirá NULLs.

  • Se o tipo de dados diferir, um erro será gerado e nenhum resultado será retornado, exceto nos seguintes casos:

    • varchar(a) to varchar(a') where a' > a.

    • varchar(a) to varchar(max)

    • nvarchar(a) to nvarchar(a') where a' > a.

    • nvarchar(a) to nvarchar(max)

    • varbinary(a) to varbinary(a') where a' > a.

    • varbinary(a) to varbinary(max)

sp_describe_first_result_set não dá suporte à recursão indireta.

Permissões

Exige permissão para executar o argumento @tsql.

Exemplos

Exemplos típicos

a. Exemplo simples

O exemplo a seguir descreve o conjunto de resultados retornado de uma única consulta.

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

O exemplo a seguir mostra o conjunto de resultados retornado de uma única consulta que contém um parâmetro.

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. Exemplos do modo de procura

Os três exemplos a seguir ilustram a principal diferença entre os modos de procurar informações. Somente as colunas relevantes foram incluídas nos resultados da consulta.

Exemplo que usa 0 indicando que nenhuma informação foi retornada.

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;

Este é o conjunto de resultados.

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

Exemplo que usa 1 indicando que retorna informações como se incluísse uma opção FOR BROWSE na consulta.

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

Este é o conjunto de resultados.

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 um dbo t um 1

Exemplo que usa 2 indicando que foi analisado como se você estivesse preparando um cursor.

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

Este é o conjunto de resultados.

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 NULO NULO NULO 0

C. Armazenar resultados em uma tabela

Em alguns cenários, você precisaria colocar os resultados do procedimento sp_describe_first_result_set em alguma tabela para que você possa processar ainda mais o esquema. Primeiro, você precisa criar uma tabela que corresponda à saída do procedimento 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
);

Ao criar uma tabela, você poderá armazenar o esquema de alguma consulta nessa tabela.

declare @tsql nvarchar(max) = 'select top 0 * from sys.credentials';

insert #frs
exec sys.sp_describe_first_result_set @tsql;

select * from #frs;

Exemplos de problemas

Os exemplos a seguir usam duas tabelas para todos os exemplos. Execute as seguintes instruções para criar as tabelas de exemplo.

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

Erro porque o número de colunas difere

O número de colunas nos possíveis primeiros conjuntos de resultados difere neste exemplo.

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

Erro porque os tipos de dados diferem

Os tipos de colunas diferem nos primeiros possíveis conjuntos de resultados diferentes.

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

Resultado: erro, tipos incompatíveis (int vs. smallint).

O nome da coluna não pode ser determinado

As colunas nos primeiros possíveis conjuntos de resultados diferem no comprimento para o mesmo tipo de comprimento variável, nulidade e nomes de coluna:

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

Resultado: <Nome da Coluna Desconhecido>varchar(20) NULL

Nome de coluna forçado a ser idêntico via alias

Igual ao anterior, mas as colunas têm o mesmo nome via alias de coluna.

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

Resultado: b varchar(20)NULL

Erro porque os tipos de coluna não podem ser correspondidos

Os tipos de coluna diferem nos primeiros possíveis conjuntos de resultados diferentes.

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

Resultado: erro, tipos incompatíveis (varchar(10) vs. nvarchar(10)).

O conjunto de resultados pode retornar um erro

O primeiro conjunto de resultados é erro ou conjunto de resultados.

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

Resultado: um intNULL

Alguns caminhos de código não retornam resultados

O primeiro conjunto de resultados é nulo ou um conjunto de resultados.

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

Resultado: um intNULL

Resultado do SQL dinâmico

O primeiro conjunto de resultados é SQL dinâmico, detectável porque é cadeia de caracteres literal.

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

Resultado: um INT NULL

Falha no resultado do SQL dinâmico

O primeiro conjunto de resultados é indefinido devido ao SQL dinâmico.

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

Resultado: Erro. O resultado não é detectável devido ao SQL dinâmico.

Conjunto de resultados especificado por usuário

O primeiro conjunto de resultados é especificado manualmente pelo usuário.

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

Resultado: Column1 bigint NOT NULL

Erro causado por um conjunto de resultados ambíguos

Este exemplo presume que outro usuário nomeado usuário1 tem uma tabela nomeada t1 no esquema padrão s1 com colunas (um int NOT NULL).

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

Resultado: Erro. t1 pode ser dbo.t1 ou s1.t1, cada um com um número diferente de colunas.

Resulta até mesmo com um conjunto de resultados ambíguo

Use as mesmas suposições do exemplo anterior.

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

Resultado: um int NULL porque dbo.t1.a e s1.t1.a têm o tipo int e nulidade diferente.

Consulte Também

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)