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.

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.

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.

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.

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)