sp_addextendedproperty (Transact-SQL)

Adiciona uma nova propriedade estendida a um objeto de banco de dados.

Convenções de sintaxe Transact-SQL

Sintaxe

        sp_addextendedproperty
    [ @name= ] { 'property_name' }
    [ , [ @value= ] { 'value' } 
        [ , [ @level0type= ] { 'level0_object_type' } 
          , [ @level0name= ] { 'level0_object_name' } 
                [ , [ @level1type= ] { 'level1_object_type' } 
                  , [ @level1name= ] { 'level1_object_name' } 
                        [ , [ @level2type= ] { 'level2_object_type' } 
                          , [ @level2name= ] { 'level2_object_name' } 
                        ] 
                ]
        ] 
    ] 
[;]

Argumentos

• [ @name ] = { 'property_name' }
  É o nome da propriedade a ser adicionada. property_name é sysname e não pode ser NULL. Os nomes também podem incluir espaço em branco ou cadeias de caracteres não alfanuméricos e valores binários.

• [ @value= ] { 'value'}
  É o valor a ser associado à propriedade. value é sql_variant, com um padrão NULL. O tamanho de value não pode ser maior que 7.500 bytes.

• [ @level0type= ] { 'level0_object_type' }
  É o tipo de objeto de nível 0. level0_object_type é varchar(128), com um padrão NULL.

  As entradas válidas são ASSEMBLY, CONTRACT, EVENT NOTIFICATION, FILEGROUP, MESSAGE TYPE, PARTITION FUNCTION, PARTITION SCHEME, REMOTE SERVICE BINDING, ROUTE, SCHEMA, SERVICE, USER, TRIGGER, TYPE e NULL.

  Importante

  A capacidade de especificar USER como um tipo de nível 0 em uma propriedade estendida de um objeto de tipo nível 1 será removida em uma versão futura do SQL Server. Em vez disso use SCHEMA como o nível 0. Por exemplo, ao definir uma propriedade estendida em uma tabela, especifique o esquema da tabela em vez de um nome de usuário. A capacidade de especificar TYPE como um tipo de nível 0 será removida em uma versão futura do SQL Server. Para TYPE, use SCHEMA como o tipo de nível 0 e TYPE como o tipo de nível 1.

• [ @level0name= ] { 'level0_object_name' }
  É o nome do tipo de objeto de nível 0 especificado. level0_object_name é sysname com um padrão NULL.

• [ @level1type= ] { 'level1_object_type' }
  É o tipo de objeto de nível 1. level1_object_type é varchar(128), com um padrão NULL. As entradas válidas são AGGREGATE, DEFAULT, FUNCTION, LOGICAL FILE NAME, PROCEDURE, QUEUE, RULE, SYNONYM, TABLE, TABLE_TYPE, TYPE, VIEW, XML SCHEMA COLLECTION e NULL.

• [ @level1name= ] { 'level1_object_name' }
  É o nome do tipo de objeto de nível 1 especificado. level1_object_name é sysname, com um padrão NULL.

• [ @level2type= ] { 'level2_object_type' }
  É o tipo de objeto de nível 2. level2_object_type é varchar(128), com um padrão NULL. As entradas válidas são COLUMN, CONSTRAINT, EVENT NOTIFICATION, INDEX, PARAMETER, TRIGGER e NULL.

• [ @level2name= ] { 'level2_object_name' }
  É o nome do tipo de objeto de nível 2 especificado. level2_object_name é sysname, com um padrão NULL.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Comentários

Para especificar as propriedades estendidas, os objetos em um banco de dados do SQL Server são classificados em três níveis: 0, 1 e 2. O nível 0 é o nível mais alto e está definido como objetos que estão contidos no escopo do banco de dados. Os objetos de nível 1 estão contidos em um esquema ou escopo de usuário e os objetos de nível 2 estão contidos pelos objetos de nível 1. As propriedades estendidas podem ser definidas para os objetos em qualquer um desses níveis.

As referências a um objeto de um nível precisam ser qualificadas com os nomes dos objetos de nível superior que as possua ou contenha. Por exemplo, ao adicionar uma propriedade estendida à coluna de uma tabela (nível 2), é necessário também especificar o nome da tabela (nível 1) que contém a coluna e o esquema (nível 0) que contém a tabela.

Para obter uma lista completa de objetos e seus tipos válidos de nível 0, 1 e 2, consulte Usando propriedades estendidas em objetos de banco de dados.

Se todos os tipos e nomes de objeto forem nulos, a propriedade pertencerá ao próprio banco de dados atual.

Propriedades estendidas não são permitidas em objetos de sistema, objetos fora do escopo de um banco de dados definido pelo usuário ou objetos não listados em Argumentos como entradas válidas.

Replicando propriedades estendidas

As propriedades estendidas são replicadas apenas na sincronização inicial entre o Editor e o Assinante. Se você adicionar ou modificar uma propriedade estendida depois da sincronização inicial, a alteração não será replicada. Para obter mais informações sobre como replicar objetos de banco de dados, consulte Publicando dados e objetos de banco de dados.

Esquema versus usuário

Não recomendamos a especificação de USER como um tipo de nível 0 ao aplicar uma propriedade estendida a um objeto de banco de dados, pois isso poderá criar ambiguidade na resolução de nome. Por exemplo, suponha que a usuária Mary seja proprietária de dois esquemas (Mary e MySchema) e que esses dois esquemas contenham uma tabela chamada MyTable. Se Mary adicionar uma propriedade estendida à tabela MyTable e especificar @level0type = N'USER', @level0name = Mary, não ficará claro a tabela à qual a propriedade estendida é aplicada. Para manter a compatibilidade com versões anteriores, o SQL Server aplicará a propriedade à tabela contida no esquema Mary. Para obter mais informações sobre usuários e esquemas, consulte Separação do esquema de usuário.

Permissões

Os membros das funções de banco de dados fixas db_owner e db_ddladmin podem adicionar propriedades estendidas a qualquer objeto com a seguinte exceção: o db_ddladmin não pode adicionar propriedades ao próprio banco de dados, a usuários ou a funções.

Os usuários podem adicionar propriedades estendidas a objetos que possuam ou para os quais tenham permissões ALTER ou CONTROL. Para obter uma lista completa das permissões necessárias, consulte Usando propriedades estendidas em objetos de banco de dados.

Exemplos

A. Adicionando uma propriedade estendida a um banco de dados

O exemplo a seguir adiciona o nome da propriedade 'Caption' com um valor de 'AdventureWorks2008R2 Sample OLTP Database' ao banco de dados de exemplo AdventureWorks2008R2.

USE AdventureWorks2008R2;
GO
--Add a caption to the AdventureWorks2008R2 Database object itself.
EXEC sp_addextendedproperty 
@name = N'Caption', 
@value = 'AdventureWorks2008R2 Sample OLTP Database';

B. Adicionando uma propriedade estendida a uma coluna em uma tabela

O exemplo a seguir adiciona uma propriedade de legenda à coluna PostalCode na tabela Address.

USE AdventureWorks2008R2;
GO
EXEC sp_addextendedproperty 
@name = N'Caption', 
@value = 'Postal code is a required column.',
@level0type = N'Schema', @level0name = 'Person',
@level1type = N'Table',  @level1name = 'Address',
@level2type = N'Column', @level2name = 'PostalCode';
GO

C. Adicionando uma propriedade de máscara de entrada a uma coluna

O exemplo a seguir adiciona uma propriedade de máscara de entrada '99999 or 99999-9999 or #### ###' à coluna PostalCode na tabela Address.

USE AdventureWorks2008R2;
GO
EXEC sp_addextendedproperty 
@name = N'Input Mask ', @value = '99999 or 99999-9999 or #### ###',
@level0type = N'Schema', @level0name = 'Person',
@level1type = N'Table', @level1name = 'Address', 
@level2type = N'Column',@level2name = 'PostalCode';
GO

D. Adicionando uma propriedade estendida a um grupo de arquivos

O exemplo a seguir adiciona uma propriedade estendida ao grupo de arquivos PRIMARY.

USE AdventureWorks2008R2;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Primary filegroup for the AdventureWorks2008R2 sample database.', 
@level0type = N'FILEGROUP', @level0name = 'PRIMARY';
GO

E. Adicionando uma propriedade estendida a um esquema

O exemplo a seguir adiciona uma propriedade estendida ao esquema HumanResources.

USE AdventureWorks2008R2;
GO
EXECUTE sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample',
@value = N'Contains objects related to employees and departments.',
@level0type = N'SCHEMA', 
@level0name = 'HumanResources';

F. Adicionando uma propriedade estendida a uma tabela

O exemplo a seguir adiciona uma propriedade estendida é adicionada à tabela Address no esquema Person.

USE AdventureWorks2008R2;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Street address information for customers, employees, and vendors.', 
@level0type = N'SCHEMA', @level0name = 'Person',
@level1type = N'TABLE',  @level1name = 'Address';
GO

G. Adicionando uma propriedade estendida a uma função

O exemplo a seguir cria uma função de aplicativo e adiciona uma propriedade estendida à função.

USE AdventureWorks2008R2; 
GO
CREATE APPLICATION ROLE Buyers
WITH Password = '987G^bv876sPY)Y5m23'; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'Application Role for the Purchasing Department.',
@level0type = N'USER',
@level0name = 'Buyers';

H. Adicionando uma propriedade estendida a um tipo

O exemplo a seguir adiciona uma propriedade estendida a um tipo.

USE AdventureWorks2008R2; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'Data type (alias) to use for any column that represents an order number. For example a sales order number or purchase order number.', 
@level0type = N'SCHEMA', 
@level0name = N'dbo', 
@level1type = N'TYPE', 
@level1name = N'OrderNumber';

I. Adicionando uma propriedade estendida a um usuário

O exemplo a seguir cria um usuário e adiciona uma propriedade estendida a ele.

USE AdventureWorks2008R2; 
GO
CREATE USER CustomApp WITHOUT LOGIN ; 
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_Description', 
@value = N'User for an application.', 
@level0type = N'USER', 
@level0name = N'CustomApp';

Consulte também

Referência

Procedimentos armazenados do Mecanismo de Banco de Dados (Transact-SQL)

fn_listextendedproperty (Transact-SQL)

sp_dropextendedproperty (Transact-SQL)

sp_updateextendedproperty (Transact-SQL)

Conceitos

Usando propriedades estendidas em objetos de banco de dados

Exibindo propriedades estendidas