sp_addextendedproperty (Transact-SQL)

Artículo
12/15/2008

Actualizado: 5 de diciembre de 2005

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

Icono de vínculo a temas 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:
USER y TYPE como tipos de nivel 0 se quitarán en una versión futura de SQL Server. Evite utilizar estas características en los nuevos trabajos de programación y planee modificar las aplicaciones que actualmente las utilizan. En lugar de USER, use SCHEMA como tipo de nivel 0. 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 varchar(128) y su valor predeterminado es NULL. Las entradas válidas son AGGREGATE, DEFAULT, FUNCTION, LOGICAL FILE NAME, PROCEDURE, QUEUE, RULE, SYNONYM, TABLE, 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.

Notas

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 se define como 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 sólo 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 la réplica de objetos de base de datos, vea Publicar datos y objetos de base de datos.

Esquema y usuario

En versiones anteriores de SQL Server, los usuarios eran propietarios de objetos de base de datos, como tablas, vistas y desencadenadores. Por tanto, se permitía agregar una propiedad extendida a uno de estos objetos y especificar un nombre de usuario como tipo de nivel 0. Sin embargo, en SQL Server 2005, los objetos de base de datos se incluyen en esquemas, que son independientes de los usuarios que los poseen.

En SQL Server 2005 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 cada uno contiene una tabla denominada MyTable. Si Mary agrega una propiedad extendida a la tabla MyTable y especifica @level0type = N'USER',@level0name = Mary, no está claro a qué tabla se debe aplicar 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 las funciones fijas de las bases de datos db_owner y db_ddladmin pueden agregar las propiedades extendidas a cualquier objeto con la siguiente excepción: db_ddladmin no puede agregar propiedades a la base de datos, a los usuarios o a las funciones.

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.

Valores de código de retorno

0 (correcto) o 1 (error)

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 'AdventureWorks Sample OLTP Database' a la base de datos de ejemplo AdventureWorks.

USE AdventureWorks;
GO
--Add a caption to the AdventureWorks Database object itself.
EXEC sp_addextendedproperty 
@name = N'Caption', @value = 'AdventureWorks 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 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

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

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

Vea también

Historial de cambios

Versión	Historial
5 de diciembre de 2005	Contenido nuevo: Se ha agregado la sección Replicar propiedades extendidas.