sp_describe_first_result_set (Transact-SQL)

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. A exibição de gerenciamento dinâmico sys.dm_exec_describe_first_result_set (Transact-SQL) retorna as mesmas informações.

Convenções de sintaxe 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 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 contiver 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 de código de retorno

sp_describe_first_result_set sempre retorna o status zero ao obter êxito. Se o procedimento lançar um erro e 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'.
precision	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 do agrupamento 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 esse 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 existem 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 Transact-SQL válido. A validade é determinada pela análise do lote Transact-SQL. Os erros causados pelo lote durante a otimização ou execução da consulta não são considerados para determinar se o lote 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 Transact-SQL de entrada 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 de 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 por sp_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) para varchar(a'), onde a' é > a.

  • varchar(a) to varchar(max)

  • nvarchar(a) para nvarchar(a'), onde a' é > a.

  • nvarchar(a) to nvarchar(max)

  • varbinary(a) para varbinary(a'), onde a' é > a.

  • varbinary(a) to varbinary(max)

O sp_describe_first_result_set não dá suporte a 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;

Aqui está o conjunto de resultados.

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

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

Aqui está 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	a	dbo	t	a	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

Aqui está 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	NULL	NULL	NULL	0

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: a int NULL

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: a int NULL

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: a 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: Error. 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íguo

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: Error. 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: a int NULL, porque dbo.t1.a e s1.t1.a têm o tipo int e nulidade diferente.

Consulte também

Referência

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)