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.

  Важно!
  В будущей версии SQL Server типы USER и TYPE в качестве типов 0 уровня будут удалены. Избегайте использования этих возможностей в новых разработках и планируйте модификацию приложений, которые сейчас их используют. Вместо USER в качестве типа уровня 0 следует использовать SCHEMA. В значении аргумента 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 при применении расширенного свойства к объекту базы данных, так как это может вызвать неоднозначность при разрешении имен. Например, предположим, что пользователь Владимир владеет двумя схемами (Vladimir и MySchema) и в обеих этих схемах содержится таблица с именем MyTable. Если Владимир добавит расширенное свойство к таблице MyTable и укажет @level0type = N'USER',@level0name = Vladimir, то будет неясно, к какой таблице это свойство применяется. Для поддержки обратной совместимости SQL Server применит свойство к таблице, содержащейся в схеме с именем Vladimir. Дополнительные сведения о пользователях и схемах см. в разделе Отделение пользователей от схем.

Разрешения

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

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

Примеры

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

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

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

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

В следующем примере свойство Caption добавляется к столбцу PostalCode в таблице Address.

USE AdventureWorks;
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 AdventureWorks;
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 AdventureWorks;
GO
EXEC sys.sp_addextendedproperty 
@name = N'MS_DescriptionExample', 
@value = N'Primary filegroup for the AdventureWorks sample database.', 
@level0type = N'FILEGROUP', @level0name = [PRIMARY];
GO

См. также

Справочник

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

fn_listextendedproperty (Transact-SQL)

sp_dropextendedproperty (Transact-SQL)

sp_updateextendedproperty (Transact-SQL)

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

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

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