sys.dm_sql_referenced_entities (Transact-SQL)
Retorna uma linha para cada entidade definida pelo usuário, referenciada por nome na definição da entidade de referência especificada. Uma dependência entre duas entidades é criada quando uma entidade definida pelo usuário, denominada entidade referenciada, aparece por nome em uma expressão SQL persistente de outra entidade definida pelo usuário, denominada entidade de referência. Por exemplo, se um procedimento armazenado for a entidade de referência especificada, essa função retornará todas as entidades definidas pelo usuário que são referenciadas no procedimento armazenado como tabelas, exibições, UDTs (Tipos Definidos pelo Usuário) ou outros procedimentos armazenados.
Você pode usar essa função de gerenciamento dinâmico para informar os seguintes tipos de entidades referenciadas pela entidade de referência especificada:
Entidades associadas a esquema
Entidades não associadas a esquema
Entidades entre banco de dados e entre servidores
Dependências no nível de coluna de entidades associadas e não associadas a esquema
Tipos definidos pelo usuário (alias e UDT CLR)
Coleções de esquema XML
Funções de partição
Sintaxe
sys.dm_sql_referenced_entities (
' [ schema_name. ] referencing_entity_name ' , ' <referencing_class> ' )
<referencing_class> ::=
{
OBJECT
| DATABASE_DDL_TRIGGER
| SERVER_DDL_TRIGGER
}
Argumentos
[ schema_name. ] referencing_entity_name
É o nome da entidade de referência. schema_name é requerido quando a classe de referência é OBJECT.schema_name.referencing_entity_name é nvarchar(517).
<referencing_class> ::= { OBJECT | DATABASE_DDL_TRIGGER | SERVER_DDL_TRIGGER }
É a classe da entidade de referência especificada. Apenas uma classe pode ser especificada por instrução.<referencing_class> é nvarchar(60).
Tabela retornada
Nome da coluna |
Tipo de dados |
Descrição |
|---|---|---|
referencing_minor_id |
int |
ID da coluna quando a entidade de referência for uma coluna; caso contrário, 0. Não permite valor nulo. |
referenced_server_name |
sysname |
Nome do servidor da entidade referenciada. Essa coluna é populada para dependências entre servidores que são feitas especificando um nome de quatro partes válido. Para obter informações sobre nomes de várias partes, consulte convenções de sintaxe Transact-SQL (Transact-SQL). NULL para dependências não associadas a esquema para as quais a entidade foi referenciada sem especificar um nome de quatro partes. NULL para entidades associadas por esquema porque elas devem estar no mesmo banco de dados e, portanto, só podem ser definidas com um nome de duas partes (schema.object). |
referenced_database_name |
sysname |
Nome do banco de dados da entidade referenciada. Essa coluna é populada para referências entre servidores e bancos de dados, que são feitas especificando um nome de três ou quatro partes válido. NULL para referências não associadas por esquema quando especificadas usando um nome de uma ou duas partes. NULL para entidades associadas por esquema porque elas devem estar no mesmo banco de dados e, portanto, só podem ser definidas com um nome de duas partes (schema.object). |
referenced_schema_name |
sysname |
Esquema ao qual a entidade referenciada pertence. NULL para referências não associadas a esquema para as quais a entidade foi referenciada sem especificar o nome do esquema. Nunca NULL para referências associadas a esquema. |
referenced_entity_name |
sysname |
Nome da entidade referenciada. Não é anulável. |
referenced_minor_name |
sysname |
Nome da coluna quando a entidade referenciada é uma coluna; caso contrário, NULL. Por exemplo, referenced_minor_name é NULL na linha que lista a própria entidade referenciada. Uma entidade referenciada é uma coluna quando uma coluna é identificada pelo nome na entidade de referência ou quando a entidade pai é usada em uma instrução SELECT *. |
referenced_id |
int |
ID da entidade referenciada. Quando referenced_minor_id não é 0, referenced_id é a entidade na qual a coluna é definida. Sempre NULL para referências entre servidores. NULL para referências entre bancos de dados quando a ID não pode ser determinada, porque o banco de dados está offline ou a entidade não pode ser associada. NULL para referências dentro do banco de dados, se não for possível determinar a ID. Para referências não associadas a esquema, a ID não pode ser resolvida nos seguintes casos:
Jamais NULL para referências associadas a esquema. |
referenced_minor_id |
int |
ID da coluna quando a entidade referenciada é uma coluna; caso contrário, 0. Por exemplo, referenced_minor_is é 0 na linha que lista a própria entidade referenciada. Para referências não associadas a esquema, as dependências de coluna são informadas somente quando todas as entidades referenciadas podem ser associadas. Se não for possível associar alguma entidade referenciada, nenhuma dependência no nível de coluna será informada e referenced_minor_id será 0. Consulte o exemplo D. |
referenced_class |
tinyint |
Classe da entidade referenciada. 1 = Objeto ou coluna 6 = Tipo 10 = Coleção de esquema XML 21 = Função de partição |
referenced_class_desc |
nvarchar(60) |
Descrição de classe da entidade referenciada. OBJECT_OR_COLUMN TYPE XML_SCHEMA_COLLECTION PARTITION_FUNCTION |
is_caller_dependent |
bit |
Indica que a associação de esquema para a entidade referenciada ocorre em tempo de execução; portanto, a resolução da ID da entidade depende do esquema do chamador. Isso ocorre quando a entidade referenciada é um procedimento armazenado, um procedimento armazenado estendido ou uma função definida pelo usuário chamada em uma instrução EXECUTE. 1 = A entidade referenciada depende do chamador e é resolvida em tempo de execução. Nesse caso, referenced_id é NULL. 0 = A ID da entidade referenciada não depende do chamador. Sempre 0 para referências associadas por esquema e entre bancos de dados e servidores que especificam explicitamente um nome de esquema. Por exemplo, uma referência para uma entidade no formato EXEC MyDatabase.MySchema.MyProc não é dependente do chamador. Porém, uma referência no formato EXEC MyDatabase..MyProc é dependente do chamador. |
is_ambiguous |
bit |
Indica que a referência é ambígua e pode ser resolvida em tempo de execução para uma função definida pelo usuário, um UDT (Tipo Definido pelo Usuário) ou uma referência xquery para uma coluna do tipo xml. Por exemplo, suponha que a instrução SELECT Sales.GetOrder() FROM Sales.MySales esteja definida em um procedimento armazenado. Até que o procedimento armazenado seja executado ele não será conhecido, quer Sales.GetOrder() seja uma função definida pelo usuário no esquema Sales quer seja uma coluna denominada Sales do tipo UDT com um método denominado GetOrder(). 1 = A referência a uma função definida pelo usuário ou a um método UDT (Tipo Definido pelo Usuário) de coluna é ambígua. 0 = A referência não é ambígua ou a entidade pode ser associada com êxito quando a função é chamada. Sempre 0 para referências associadas a esquema. |
Exceções
Retorna um conjunto de resultados vazio em qualquer uma das seguintes condições:
Um objeto de sistema é especificado.
A entidade especificada não existe no banco de dados atual.
A entidade especificada não faz referência a nenhuma entidade.
Um parâmetro inválido é passado.
Retorna um erro quando a entidade de referência especificada é um procedimento armazenado numerado.
Retorna o erro 2020 quando as dependências de coluna não podem ser resolvidas. Esse erro não evita que a consulta retorne dependências no nível do objeto. Para obter mais informações, consulte Solucionando problemas de dependências do SQL.
Comentários
Essa função pode ser executada no contexto de qualquer banco de dados para retornar as entidades que fazem referência a um gatilho DDL no nível do servidor.
A tabela a seguir lista os tipos de entidades para os quais as informações de dependência são criadas e mantidas. As informações de dependência não são criadas nem mantidas para regras, padrões, tabelas temporárias, procedimentos armazenados temporários ou objetos do sistema.
Tipo de entidade |
Entidade de referência |
Entidade referenciada |
|---|---|---|
Tabela |
Sim* |
Sim |
Exibição |
Sim |
Sim |
Procedimento armazenado Transact-SQL** |
Sim |
Sim |
Procedimento armazenado CLR |
Não |
Sim |
Função Transact-SQL definida pelo usuário |
Sim |
Sim |
Função CLR definida pelo usuário |
Não |
Sim |
Gatilho CLR (DML e DDL) |
Não |
Não |
Gatilho DML Transact-SQL |
Sim |
Não |
Gatilho DDL no nível do banco de dados Transact-SQL |
Sim |
Não |
Gatilho DDL no nível do servidor Transact-SQL |
Sim |
Não |
Procedimentos armazenados estendidos |
Não |
Sim |
Fila |
Não |
Sim |
Sinônimo |
Não |
Sim |
Tipo (tipo de alias e dados CLR definidos pelo usuário) |
Não |
Sim |
Coleção de esquemas XML |
Não |
Sim |
Função de partição |
Não |
Sim |
* Uma tabela é controlada como entidade de referência apenas quando se refere a um módulo Transact-SQL, tipo definido pelo usuário ou coleção de esquemas XML na definição de uma coluna computada, restrição CHECK ou restrição DEFAULT.
** Os procedimentos armazenados numerados com um valor inteiro maior que 1 não são controlados nem como entidade que faz referência nem como entidade referenciada.
Para obter mais informações, consulte Compreendendo dependências do SQL.
Permissões
Requer permissão SELECT em sys.dm_sql_referenced_entities e permissão VIEW DEFINITION na entidade de referência. Por padrão, a permissão SELECT é concedida como pública. Requer permissão VIEW DEFINITION no banco de dados ou permissão ALTER DATABASE DDL TRIGGER no banco de dados quando a entidade de referência é um gatilho DDL do banco de dados. Requer permissão de VIEW ANY DEFINITION no servidor quando a entidade de referência é um gatilho DDL de servidor.
Exemplos
A. Retornando entidades referenciadas por um gatilho DDL de banco de dados
O exemplo a seguir retorna as entidades (tabelas e colunas) referenciadas pelo gatilho DDL ddlDatabaseTriggerLog de banco de dados.
USE AdventureWorks;
GO
SELECT referenced_schema_name, referenced_entity_name, referenced_minor_name,
referenced_minor_id, referenced_class_desc
FROM sys.dm_sql_referenced_entities ('ddlDatabaseTriggerLog', 'DATABASE_DDL_TRIGGER');
GO
B. Retornando entidades referenciadas por um objeto
O exemplo seguinte retorna as entidades referenciadas pela função dbo.ufnGetContactInformation definida pelo usuário.
USE AdventureWorks;
GO
SELECT referenced_schema_name, referenced_entity_name, referenced_minor_name,
referenced_minor_id, referenced_class_desc, is_caller_dependent, is_ambiguous
FROM sys.dm_sql_referenced_entities ('dbo.ufnGetContactInformation', 'OBJECT');
GO
C. Retornando dependências de coluna
O exemplo seguinte cria a tabela Table1 com a coluna computada c definida como a soma de colunas a e b. A exibição sys.dm_sql_referenced_entities então é chamada. A exibição retorna duas linhas, um para cada coluna definida na coluna computada.
USE AdventureWorks;
GO
CREATE TABLE dbo.Table1 (a int, b int, c AS a + b);
GO
SELECT referenced_schema_name AS schema_name,
referenced_entity_name AS table_name,
referenced_minor_name AS referenced_column,
COALESCE(COL_NAME(OBJECT_ID(N'dbo.Table1'),referencing_minor_id), 'N/A') AS referencing_column_name
FROM sys.dm_sql_referenced_entities ('dbo.Table1', 'OBJECT');
GO
-- Remove the table.
DROP TABLE dbo.Table1;
GO
Conjunto de resultados.
schema_name table_name referenced_column referencing_column
----------- ---------- ----------------- ------------------
dbo Table1 a c
dbo Table1 b c
D. Retornando dependências de colunas não associadas a esquema
O exemplo a seguir cancela a Table1 e cria a Table2 e o procedimento armazenado Proc1. O procedimento referencia a Table2 e a tabela inexistente Table1. A exibição sys.dm_sql_referenced_entities é executada com o procedimento armazenado especificado como entidade de referência. O conjunto de resultados mostra uma linha da Table1 e da Table2. Como a Table1 não existe, as dependências de coluna não podem ser resolvidas e o erro 2020 é retornado.
USE AdventureWorks;
GO
IF OBJECT_ID ( 'dbo.Table1', 'U' ) IS NOT NULL
DROP TABLE dbo.Table1;
GO
CREATE TABLE dbo.Table2 (c1 int, c2 int);
GO
CREATE PROCEDURE dbo.Proc1 AS
SELECT a, b, c FROM Table1;
SELECT c1, c2 FROM Table2;
GO
SELECT referenced_id, referenced_entity_name AS table_name, referenced_minor_name AS referenced_column_name
FROM sys.dm_sql_referenced_entities ('dbo.Proc1', 'OBJECT');
GO
E. Demonstrando manutenção de dependência dinâmica
O exemplo a seguir estende o Exemplo D para mostrar que dependências são mantidas dinamicamente. O exemplo recria primeiro a Table1que foi cancelada no exemplo D. Depois sys.dm_sql_referenced_entities é executado novamente com o procedimento armazenado especificado como a entidade de referência. O conjunto de resultados mostra que as tabelas e suas colunas respectivas definidas no procedimento armazenado são retornadas.
USE AdventureWorks;
GO
CREATE TABLE Table1 (a int, b int, c AS a + b);
GO
SELECT referenced_id, referenced_entity_name AS table_name, referenced_minor_name as column_name
FROM sys.dm_sql_referenced_entities ('dbo.Proc1', 'OBJECT');
GO
DROP TABLE Table1, Table2;
DROP PROC Proc1;
GO
Conjunto de resultados.
referenced_id, table_name, column_name
------------- ----------- -----------
2139154566 Table1 NULL
2139154566 Table1 a
2139154566 Table1 b
2139154566 Table1 c
2707154552 Table2 NULL
2707154552 Table2 c1
2707154552 Table2 c2
Histórico de alterações
Conteúdo atualizado |
|---|
Removida a instrução "Dependências da coluna não controladas para funções CLR com valor de tabela" na seção Comentários. |
Corrigido o tipo de dados do parâmetro referencing_entity_name. |
Consulte também