sp_addextendedproperty (Transact-SQL)

适用于:SQL Server Azure SQL 数据库 Azure SQL 托管实例

将新扩展属性添加到数据库对象中。

Transact-SQL 语法约定

语法

sp_addextendedproperty
    [ @name = ] N'name'
    [ , [ @value = ] value ]
    [ , [ @level0type = ] 'level0type' ]
    [ , [ @level0name = ] N'level0name' ]
    [ , [ @level1type = ] 'level1type' ]
    [ , [ @level1name = ] N'level1name' ]
    [ , [ @level2type = ] 'level2type' ]
    [ , [ @level2name = ] N'level2name' ]
[ ; ]

参数

[ @name = ] N'name'

要添加的属性的名称。 @name是 sysname,没有默认值,不能NULL。 名称可以包括空白或非字母数字字符串,以及二进制值。

[ @value = ] value

要与属性关联的值。 @value为sql_variant,默认值为 NULL. @value的大小不能超过 7,500 字节。

[ @level0type = ] 'level0type'

级别 0 对象的类型。 @level0type为 varchar(128),默认值为 NULL.

有效输入为:

  • ASSEMBLY
  • CONTRACT
  • EVENT NOTIFICATION
  • FILEGROUP
  • MESSAGE TYPE
  • PARTITION FUNCTION
  • PARTITION SCHEME
  • REMOTE SERVICE BINDING
  • ROUTE
  • SCHEMA
  • SERVICE
  • USER
  • TRIGGER
  • TYPE
  • PLAN GUIDE
  • NULL

重要

在级别 1 类型对象的扩展属性中指定 USER 为 level-0 类型的功能将在 SQL Server 的未来版本中删除。 请改为用作 SCHEMA 级别 0 类型。 例如,在定义表的扩展属性时,指定表的架构而不是用户名。 在 SQL Server 的未来版本中,将删除指定为 level-0 类型的功能 TYPE 。 对于 TYPE,用作 SCHEMA level-0 类型和 TYPE 级别 1 类型。

[ @level0name = ] N'level0name'

指定的级别 0 对象类型的名称。 @level0name为 sysname,默认值为 NULL.

[ @level1type = ] 'level1type'

级别 1 对象的类型。 @level1typevarchar(128),默认值为 NULL.

有效输入为:

  • AGGREGATE
  • DEFAULT
  • FUNCTION
  • LOGICAL FILE NAME
  • PROCEDURE
  • QUEUE
  • RULE
  • SEQUENCE
  • SYNONYM
  • TABLE
  • TABLE_TYPE
  • TYPE
  • VIEW
  • XML SCHEMA COLLECTION
  • NULL

[ @level1name = ] N'level1name'

指定的级别 1 对象类型的名称。 @level1name为 sysname,默认值为 NULL.

[ @level2type = ] 'level2type'

级别 2 对象的类型。 @level2type为 varchar(128),默认值为 NULL.

有效输入为:

  • COLUMN
  • CONSTRAINT
  • EVENT NOTIFICATION
  • INDEX
  • PARAMETER
  • TRIGGER
  • NULL

[ @level2name = ] N'level2name'

指定的级别 2 对象类型的名称。 @level2name为 sysname,默认值为 NULL.

返回代码值

0(成功)或 1(失败)。

注解

指定扩展属性时,SQL Server 数据库中的对象分为三个级别:0、1 和 2。 级别 0 是最高级别,定义为在数据库作用域内包含的对象。 级别 1 的对象包含在架构作用域或用户作用域中,而级别 2 的对象包含在级别 1 对象中。 可以为这些级别中任一级别的对象定义扩展属性。

引用某个级别中的对象必须用拥有或包含它们的更高级别对象的名称进行限制。 例如,当将扩展属性添加到表列(级别 2)时,还必须指定包含该列的表名(级别 1)以及包含该表的架构(级别 0)。

如果所有对象类型和名称都为空,则属性属于当前数据库本身。

系统对象、用户定义数据库范围之外的对象或参数中未列为有效输入的对象不允许扩展属性。

内存优化表上不允许扩展属性。

复制扩展属性

仅在发布服务器和订阅服务器之间的初始同步中复制扩展属性。 如果在初始同步后添加或修改扩展属性,则不会复制更改。 有关如何复制数据库对象的详细信息,请参阅 发布数据和数据库对象

架构与用户

不建议在将扩展属性应用于数据库对象时指定 USER 为级别 0 类型,因为这可能会导致名称解析不明确。 例如,假设用户 Mary 拥有两个架构(MaryMySchema),并且这些架构都包含一个名为 MyTable的表。 如果 Mary 将扩展属性添加到表 MyTable 并指定 @level0type = 'USER', @level0name = N'Mary',则不清楚应用扩展属性的表。 为了保持向后兼容性,SQL Server 将属性应用于名为 Mary 的架构中包含的表。

权限

db_ownerdb_ddladmin固定数据库角色的成员可以将扩展属性添加到任何对象,但有以下例外:db_ddladmin无法向数据库本身或用户或角色添加属性。

用户可以将扩展属性添加到他们所拥有的对象中,或者添加到他们对其具有 ALTER 或 CONTROL 权限的对象中。

示例

A. 将扩展属性添加到数据库

Caption 以下示例将值为 AdventureWorks2022 Sample OLTP Database 的属性名称 AdventureWorks2022 添加到 示例数据库中。

USE AdventureWorks2022;
GO

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

B. 向表中的列添加扩展属性

PostalCode 以下示例将 caption 属性添加到 Address表中的 列。

USE AdventureWorks2022;
GO

EXEC sp_addextendedproperty @name = N'Caption',
    @value = 'Postal code is a required column.',
    @level0type = 'SCHEMA', @level0name = N'Person',
    @level1type = 'TABLE', @level1name = N'Address',
    @level2type = 'COLUMN', @level2name = N'PostalCode';
GO

°C 向列添加输入掩码属性

以下示例将输入掩码属性99999 or 99999-9999 or #### ###添加到表中Address的列PostalCode

USE AdventureWorks2022;
GO

EXEC sp_addextendedproperty @name = N'Input Mask ',
    @value = '99999 or 99999-9999 or #### ###',
    @level0type = 'SCHEMA', @level0name = N'Person',
    @level1type = 'TABLE', @level1name = N'Address',
    @level2type = 'COLUMN', @level2name = N'PostalCode';
GO

D. 将扩展属性添加到文件组

PRIMARY 下面的示例向 文件组添加了一个扩展属性。

USE AdventureWorks2022;
GO

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

E. 将扩展属性添加到架构

下面的示例向 架构添加了一个扩展属性。 HumanResources

USE AdventureWorks2022;
GO

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

F. 向表添加扩展属性

Address 下面的示例将扩展属性添加到 Person 架构中的 表。

USE AdventureWorks2022;
GO

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

G. 将扩展属性添加到角色

下面的示例创建了一个应用程序角色并向该角色添加了一个扩展属性。

USE AdventureWorks2022;
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 = 'USER', @level0name = N'Buyers';

H. 将扩展属性添加到类型

下面的示例向类型添加了一个扩展属性。

USE AdventureWorks2022;
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 = 'SCHEMA', @level0name = N'dbo',
    @level1type = 'TYPE', @level1name = N'OrderNumber';

I. 将扩展属性添加到用户

下面的示例创建了一个用户并向该用户添加了一个扩展属性。

USE AdventureWorks2022;
GO

CREATE USER CustomApp WITHOUT LOGIN;
GO

EXEC sys.sp_addextendedproperty @name = N'MS_Description',
    @value = N'User for an application.',
    @level0type = 'USER', @level0name = N'CustomApp';