sp_addextendedproperty (Transact-SQL)

Agrega una nueva propiedad extendida a un objeto de base de datos.

Convenciones de sintaxis de Transact-SQL

Sintaxis

        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' }
  Es el nombre de la propiedad que se va a agregar. property_name es de tipo sysname y no puede ser NULL. Los nombres también pueden incluir espacios en blanco o cadenas de caracteres no alfanuméricos, y valores binarios.

• [ @value= ] { 'value'}
  Es el valor que se va a asociar a la propiedad. value es de tipo sql_variant y su valor predeterminado es NULL. El tamaño de value no puede ser superior a 7.500 bytes.

• [ @level0type= ] { 'level0_object_type' }
  Es el tipo de objeto de nivel 0. level0_object_type es de tipo varchar(128) y su valor predeterminado es NULL.

  Las entradas válidas son ASSEMBLY, CONTRACT, EVENT NOTIFICATION, FILEGROUP, MESSAGE TYPE, PARTITION FUNCTION, PARTITION SCHEME, REMOTE SERVICE BINDING, ROUTE, SCHEMA, SERVICE, USER, TRIGGER, TYPE y NULL.

  Importante

  La capacidad para especificar USER como tipo de nivel 0 en una propiedad extendida de un objeto de tipo de nivel 1 se quitará en una futura versión de SQL Server. En su lugar, utilice SCHEMA como tipo de nivel 0. Por ejemplo, al definir una propiedad extendida en una tabla, especifique el esquema de la tabla en lugar de un nombre de usuario. La capacidad para especificar TYPE como tipo de nivel 0 se quitará en una futura versión de SQL Server. Para TYPE, use SCHEMA como tipo de nivel 0 y TYPE como tipo de nivel 1.

• [ @level0name= ] { 'level0_object_name' }
  Es el nombre del tipo de objeto de nivel 0 especificado. level0_object_name es de tipo sysname y su valor predeterminado es NULL.

• [ @level1type= ] { 'level1_object_type' }
  Es el tipo de objeto de nivel 1. level1_object_type es de tipo varchar(128) y su valor predeterminado es NULL. Las entradas válidas son AGGREGATE, DEFAULT, FUNCTION, LOGICAL FILE NAME, PROCEDURE, QUEUE, RULE, SYNONYM, TABLE, TABLE_TYPE, TYPE, VIEW, XML SCHEMA COLLECTION y NULL.

• [ @level1name= ] { 'level1_object_name' }
  Es el nombre del tipo de objeto de nivel 1 especificado. level1_object_name es de tipo sysname y su valor predeterminado es NULL.

• [ @level2type= ] { 'level2_object_type' }
  Es el tipo de objeto de nivel 2. level2_object_type es de tipo varchar(128) y su valor predeterminado es NULL. Las entradas válidas son COLUMN, CONSTRAINT, EVENT NOTIFICATION, INDEX, PARAMETER, TRIGGER y NULL.

• [ @level2name= ] { 'level2_object_name' }
  Es el nombre del tipo de objeto de nivel 2 especificado. level2_object_name es de tipo sysname y su valor predeterminado es NULL.

Valores de código de retorno

0 (correcto) o 1 (error)

Comentarios

Para especificar propiedades extendidas, los objetos de una base de datos de SQL Server se clasifican en tres niveles: 0, 1 y 2. El nivel 0 es el más alto y corresponde a los objetos contenidos en el ámbito de la base de datos. Los objetos de nivel 1 están contenidos en el ámbito de esquema o usuario, y los objetos de nivel 2 están contenidos en objetos de nivel 1. Se pueden definir propiedades extendidas para los objetos de cualquiera de estos niveles.

Las referencias a un objeto de un nivel deben estar calificadas con los nombres de los objetos del nivel superior, que son sus propietarios o que los contienen. Por ejemplo, cuando se agrega una propiedad extendida a una columna de tabla (nivel 2), también se debe especificar el nombre de la tabla (nivel 1) que contiene la columna y el esquema (nivel 0) que contiene la tabla.

Para obtener una lista completa de objetos y sus tipos de nivel 0, 1 y 2 válidos, vea Usar propiedades extendidas en objetos de base de datos.

Si todos los tipos y nombres de objetos son NULL, la propiedad pertenece a la base de datos actual.

No se permiten propiedades extendidas en los objetos del sistema, en los objetos que se encuentren fuera del ámbito de una base de datos definida por el usuario o en los objetos que no estén incluidos como entradas válidas en la sección Argumentos.

Replicar propiedades extendidas

Las propiedades extendidas solo se replican en la sincronización inicial entre el publicador y el suscriptor. Si agrega o modifica una propiedad extendida después de la sincronización inicial, el cambio no se replica. Para obtener más información acerca de cómo replicar los objetos de base de datos, vea Publicar datos y objetos de base de datos.

Esquema y usuario

No se recomienda especificar USER como tipo de nivel 0 cuando se aplica una propiedad extendida a un objeto de base de datos, ya que esto puede producir ambigüedad en la resolución de nombres. Supongamos, por ejemplo, que el usuario Mary posee dos esquemas (Mary y MySchema) y que ambos contienen una tabla denominada MyTable. Si Mary agrega una propiedad extendida a la tabla MyTable y especifica @level0type = N'USER', @level0name = Mary, no queda claro a qué tabla se aplica la propiedad extendida. Por compatibilidad con versiones anteriores, SQL Server aplicará la propiedad a la tabla contenida en el esquema Mary. Para obtener más información acerca de usuarios y esquemas, vea Separación de esquemas de usuario.

Permisos

Los miembros de los roles fijos de base de datos db_owner y db_ddladmin pueden agregar propiedades extendidas a cualquier objeto con la siguiente excepción: db_ddladmin no puede agregar propiedades a la propia base de datos, a los usuarios ni a los roles.

Los usuarios pueden agregar propiedades extendidas a los objetos que poseen o en los que tienen permisos ALTER o CONTROL. Para obtener una lista completa de los permisos necesarios, vea Usar propiedades extendidas en objetos de base de datos.

Ejemplos

A. Agregar una propiedad extendida a una base de datos

En el ejemplo siguiente se agrega el nombre de la propiedad 'Caption' con el valor 'AdventureWorks2008R2 Sample OLTP Database' a la base de datos de ejemplo 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. Agregar una propiedad extendida a una columna de una tabla

En el ejemplo siguiente se agrega una propiedad de título (Caption) a la columna PostalCode de la tabla 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. Agregar una propiedad de máscara de entrada a una columna

En el ejemplo siguiente se agrega una propiedad de máscara de entrada '99999 or 99999-9999 or #### ###' a la columna PostalCode de la tabla 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. Agregar una propiedad extendida a un grupo de archivos

En el ejemplo siguiente se agrega una propiedad extendida al grupo de archivos 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. Agregar una propiedad extendida a un esquema

En el ejemplo siguiente se agrega una propiedad extendida al 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. Agregar una propiedad extendida a una tabla

En el siguiente ejemplo se agrega una propiedad extendida a la tabla Address del 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. Agregar una propiedad extendida a un rol

En el ejemplo siguiente se crea un rol de aplicación y se agrega una propiedad extendida al rol.

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. Agregar una propiedad extendida a un tipo

En el ejemplo siguiente se agrega una propiedad extendida a un 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. Agregar una propiedad extendida a un usuario

En el ejemplo siguiente se crea un usuario y se agrega una propiedad extendida al usuario.

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

Vea también

Referencia

Procedimientos almacenados del motor de base de datos (Transact-SQL)

fn_listextendedproperty (Transact-SQL)

sp_dropextendedproperty (Transact-SQL)

sp_updateextendedproperty (Transact-SQL)

Conceptos

Usar propiedades extendidas en objetos de base de datos

Ver las propiedades extendidas