sp_addextendedproperty （Transact-SQL）

發行項
08/11/2023

適用於：SQL Server Azure SQL Database Azure 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 '}
這是要與屬性相關聯的值。值為 SQL_variant ，預設值為 Null。值 的大小 不能超過 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、PLAN GUIDE 和 Null。

重要

未來版本的 SQL Server 將會移除將 USER 指定為層級 0 類型的擴充屬性中的層級 0 類型。請改用 SCHEMA 作為層級 0 類型。例如，在資料表上定義擴充屬性時，請指定資料表的架構，而不是使用者名稱。未來版本的 SQL Server 將會移除將 TYPE 指定為 level-0 類型的功能。針對 TYPE，請使用 SCHEMA 作為層級 0 類型，並使用 TYPE 作為層級 1 類型。

[ @level0name= ] { ' level0_object_name ' }
這是指定的層級 0 物件類型名稱。 level0_object_name 是 預設值為 Null 的 sysname 。

[ @level1type= ] { ' level1_object_type ' }
這是層級 1 物件的類型。 level1_object_type 為 Varchar（128）， 預設值為 Null。有效的輸入包括 AGGREGATE、DEFAULT、FUNCTION、LOGICAL FILE NAME、PROCEDURE、QUEUE、RULE、SEQUENCE、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）。

如果所有物件類型和名稱都是 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 許可權。

範例

A. 將擴充屬性新增至資料庫

下列範例會將具有值 AdventureWorks Sample OLTP Database 的屬性名稱 Caption 新增至 AdventureWorks2022 範例資料庫。

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

B. 將擴充屬性新增至資料表中的資料行

下列範例會將 caption 屬性新增至資料表 Address 中的資料行 PostalCode 。

USE AdventureWorks2022;  
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. 將輸入遮罩屬性新增至資料行

下列範例會將輸入遮罩屬性 ' 99999 or 99999-9999 or #### ### ' 新增至資料表 Address 中的資料行 PostalCode 。

USE AdventureWorks2022;  
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. 將擴充屬性新增至檔案群組

下列範例會將擴充屬性新增至 PRIMARY 檔案群組。

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

E. 將擴充屬性新增至架構

下列範例會將擴充屬性新增至 HumanResources 架構。

USE AdventureWorks2022;  
GO  
EXECUTE sys.sp_addextendedproperty   
@name = N'MS_DescriptionExample',  
@value = N'Contains objects related to employees and departments.',  
@level0type = N'SCHEMA',   
@level0name = '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 = N'SCHEMA', @level0name = 'Person',  
@level1type = N'TABLE',  @level1name = '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 = N'USER',  
@level0name = '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 = N'SCHEMA',   
@level0name = N'dbo',   
@level1type = N'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 = N'USER',   
@level0name = N'CustomApp';

另請參閱

Database Engine 預存程式（Transact-SQL）
sys.fn_listextendedproperty （Transact-SQL）
sp_dropextendedproperty （Transact-SQL）
sp_updateextendedproperty （Transact-SQL）