sp_addextendedproperty (Transact-SQL)

Добавляет к объекту базы данных новое расширенное свойство.

Синтаксические обозначения в Transact-SQL

Синтаксис

        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' } 
                        ] 
                ]
        ] 
    ] 
[;]

Аргументы

• [ @name ] = { 'property_name' }
  Имя добавляемого свойства. Аргумент property_name имеет тип sysname, который не может принимать значение NULL. Имена могут также включать пустые или не являющиеся алфавитно-цифровыми строки символов, а также двоичные значения.

• [ @value= ] { 'value'}
  Значение, связанное со свойством. Аргумент value имеет тип sql_variant и значение по умолчанию NULL. Размер аргумента value не может превышать 7 500 байт.

• [ @level0type= ] { 'level0_object_type' }
  Это объект типа уровня 0. Аргумент level0_object_type имеет тип varchar(128) и значение по умолчанию NULL.

  Допустимые входные данные: ASSEMBLY, CONTRACT, EVENT NOTIFICATION, FILEGROUP, MESSAGE TYPE, PARTITION FUNCTION, PARTITION SCHEME, REMOTE SERVICE BINDING, ROUTE, SCHEMA, SERVICE, USER, TRIGGER, TYPE и NULL.

  Важно!

  Возможность указывать USER как тип уровня 0 в расширенном свойстве объекта типа уровня 1 будет удалена в следующей версии SQL Server. Используйте вместо этого в качестве типа уровня 0 схему (SCHEMA). Например, при определении расширенного свойства для таблицы задается схема таблицы вместо имени пользователя. Возможность указывать TYPE как тип уровня 0 будет удалена в следующей версии SQL Server. В значении аргумента TYPE следует указывать тип SCHEMA в качестве типа уровня 0 и TYPE в качестве типа уровня 1.

• [ @level0name= ] { 'level0_object_name' }
  Это имя указанного объекта типа уровня 0. Аргумент level0_object_name имеет тип sysname и значение по умолчанию NULL.

• [ @level1type= ] { 'level1_object_type' }
  Это объект типа уровня 1. Аргумент level1_object_type имеет тип varchar(128) и значение по умолчанию NULL. Допустимые входные данные: AGGREGATE, DEFAULT, FUNCTION, LOGICAL FILE NAME, PROCEDURE, QUEUE, RULE, SYNONYM, TABLE, TABLE_TYPE, TYPE, VIEW, XML SCHEMA COLLECTION и NULL.

• [ @level1name= ] { 'level1_object_name' }
  Это имя указанного объекта типа уровня 1. Аргумент level1_object_name имеет тип sysname и значение по умолчанию NULL.

• [ @level2type= ] { 'level2_object_type' }
  Это объект типа уровня 2. Аргумент level2_object_type имеет тип varchar(128) и значение по умолчанию NULL. Допустимые входные данные: COLUMN, CONSTRAINT, EVENT NOTIFICATION, INDEX, PARAMETER, TRIGGER и NULL.

• [ @level2name= ] { 'level2_object_name' }
  Это имя указанного объекта типа уровня 2. Аргумент level2_object_name имеет тип sysname и значение по умолчанию NULL.

Значения кода возврата

0 (успешное завершение) или 1 (неуспешное завершение)

Замечания

Чтобы указывать расширенные свойства, объекты в базе данных SQL Server классифицируются по трем уровням: 0, 1 и 2. Уровень 0 является самым высоким и определен как «объекты, содержащиеся в области базы данных». Объекты уровня 1 содержатся в схеме или в пользовательской области, а объекты уровня 2 содержатся в объектах уровня 1. Расширенные свойства могут быть определены для объектов на любом из этих уровней.

Ссылки на объект определенного уровня должны быть уточнены именами объектов более высокого уровня, в которых они содержатся или которым они принадлежат. Например, при добавлении расширенного свойства к столбцу таблицы (уровень 2) необходимо также задать имя таблицы (уровень 1), содержащей этот столбец, а также схему (уровень 0), содержащую таблицу.

Полный список объектов и их допустимых типов уровня 0, 1 и 2 см. в разделе Использование расширенных свойств с объектами базы данных.

Если значения всех типов и имен объектов равны NULL, свойство считается принадлежащим собственно текущей базе данных.

Для системных объектов, объектов вне области пользовательской базы данных, а также для объектов, не перечисленных в качестве допустимых входных параметров в списке аргументов, расширенные свойства недоступны.

Репликация расширенных свойств

Репликация расширенных свойств производится только в процессе первоначальной синхронизации между издателем и подписчиком. Если расширенное свойство добавляется или изменяется после этого, то эти изменения реплицированы не будут. Дополнительные сведения о репликации объектов базы данных см. в разделе Публикация данных и объектов базы данных.

Схемы и пользователи

Не рекомендуется указывать тип USER в качестве типа уровня 0 при применении расширенного свойства к объекту базы данных, так как это может вызвать неоднозначность при разрешении имен. Например, предположим, что пользователь Mary владеет двумя схемами (Mary и MySchema) и в обеих схемах содержится таблица с именем MyTable. Если пользователь Mary добавляет расширенное свойство к таблице MyTable и задает @level0type = N'USER', @level0name = Mary, то неясно, к какой таблице применяется это расширенное свойство. Чтобы обеспечить обратную совместимость, SQL Server применит свойство к таблице, содержащейся в схеме Mary. Дополнительные сведения о пользователях и схемах см. в разделе Отделение пользователей от схем.

Разрешения

Члены предопределенных ролей db_owner и db_ddladmin базы данных могут добавлять расширенные свойства к любым объектам со следующим исключением: db_ddladmin не может добавлять свойства к самой базе данных, пользователям или ролям.

Пользователи могут добавлять расширенные свойства к объектам, которыми они владеют или на которые у них есть разрешения ALTER или CONTROL. Полный список необходимых разрешений см. в разделе Использование расширенных свойств с объектами базы данных.

Примеры

И. Добавление расширенного свойства к пользователю

В следующем примере к образцу базы данных AdventureWorks2008R2 добавляется свойство с именем 'Caption' и значением 'AdventureWorks2008R2 Sample OLTP Database'.

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

Б. Добавление расширенного свойства к столбцу в таблице

В следующем примере свойство Caption добавляется к столбцу PostalCode в таблице 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

В. Добавление свойства маски ввода к столбцу

В следующем примере к столбцу PostalCode в таблице Address добавляется свойство маски ввода '99999 or 99999-9999 or #### ###'.

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

Г. Добавление расширенного свойства к файловой группе

В следующем примере расширенное свойство добавляется к файловой группе 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

Д. Добавление расширенного свойства к схеме

В следующем примере расширенное свойство добавляется к схеме 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';

Е. Добавление расширенного свойства к таблице

В следующем примере расширенное свойство добавляется к таблице Address, относящейся к схеме 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

Ж. Добавление расширенного свойства к роли

В следующем примере создается роль приложения, к которой добавляется расширенное свойство.

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

З. Добавление расширенного свойства к типу

В следующем примере расширенное свойство добавляется к типу.

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

И. Добавление расширенного свойства к пользователю

В следующем примере создается пользователь, к которому добавляется расширенное свойство.

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

См. также

Справочник

Хранимые процедуры ядра СУБД (Transact-SQL)

fn_listextendedproperty (Transact-SQL)

sp_dropextendedproperty (Transact-SQL)

sp_updateextendedproperty (Transact-SQL)

Основные понятия

Использование расширенных свойств с объектами базы данных

Просмотр расширенных свойств