FORMAT (Transact-SQL)FORMAT (Transact-SQL)

SE APLICA A: síSQL Server (a partir de 2012) síAzure SQL Database noAzure SQL Data Warehouse noAlmacenamiento de datos paralelos APPLIES TO: yesSQL Server (starting with 2012) yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Devuelve un valor con formato con el formato y la referencia cultural opcional especificados en SQL Server 2017SQL Server 2017.Returns a value formatted with the specified format and optional culture in SQL Server 2017SQL Server 2017. Use la función FORMAT para aplicar formato específico de la configuración regional de los valores de fecha/hora y de número como cadenas.Use the FORMAT function for locale-aware formatting of date/time and number values as strings. Para las conversiones de tipos de datos generales, use CAST o CONVERT.For general data type conversions, use CAST or CONVERT.

Icono de vínculo de tema Convenciones de sintaxis de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxisSyntax

FORMAT ( value, format [, culture ] )  

ArgumentosArguments

valuevalue
Expresión de un tipo de datos compatible a la que se va a dar formato.Expression of a supported data type to format. Para obtener una lista de tipos válidos, vea la tabla de la sección Comentarios.For a list of valid types, see the table in the following Remarks section.

formatformat
Patrón de formato nvarchar.nvarchar format pattern.

El argumento format debe contener una cadena de formato de .NET Framework válida, ya sea como una cadena de formato estándar (por ejemplo, "C" o "D") o como un modelo de caracteres personalizados para los valores de fecha y numéricos (por ejemplo, "DD de MMMM, aaaa (dddd)").The format argument must contain a valid .NET Framework format string, either as a standard format string (for example, "C" or "D"), or as a pattern of custom characters for dates and numeric values (for example, "MMMM DD, yyyy (dddd)"). No se admite el formato compuesto.Composite formatting is not supported. Para obtener una explicación completa de estos modelos de formato, vea la documentación de .NET Framework sobre el formato de cadena en general, los formatos de fecha y hora personalizados, y los formatos de número personalizados.For a full explanation of these formatting patterns, consult the .NET Framework documentation on string formatting in general, custom date and time formats, and custom number formats. Un buen punto de partida es el tema "Formatting Types" (Tipos de formato).A good starting point is the topic, "Formatting Types."

cultureculture
Argumento opcional de tipo nvarchar que especifica una referencia cultural.Optional nvarchar argument specifying a culture.

Si no se proporciona el argumento culture, se usará el idioma de la sesión actual.If the culture argument is not provided, the language of the current session is used. Este idioma se establece implícitamente, o explícitamente mediante la instrucción SET LANGUAGE.This language is set either implicitly, or explicitly by using the SET LANGUAGE statement. culture acepta como argumento cualquier referencia cultural compatible con .NET Framework; no se limita a los idiomas admitidos explícitamente por SQL ServerSQL Server.culture accepts any culture supported by the .NET Framework as an argument; it is not limited to the languages explicitly supported by SQL ServerSQL Server. Si el argumento culture no es válido, FORMAT desencadena un error.If the culture argument is not valid, FORMAT raises an error.

Tipos devueltosReturn Types

nvarchar o nullnvarchar or null

La longitud del valor devuelto viene determinada por format.The length of the return value is determined by the format.

NotasRemarks

FORMAT devuelve NULL para los errores distintos de culture que no son válidos.FORMAT returns NULL for errors other than a culture that is not valid. Por ejemplo, se devuelve NULL si el valor especificado en format no es válido.For example, NULL is returned if the value specified in format is not valid.

La función FORMAT es no determinista.The FORMAT function is nondeterministic.

FORMAT se basa en la presencia de Common Language Runtime (CLR) de .NET Framework.FORMAT relies on the presence of the .NET Framework Common Language Runtime (CLR).

Esta función no se puede enviar de forma remota puesto que depende de la presencia del CLR.This function cannot be remoted since it depends on the presence of the CLR. El envío remoto de una función que necesita CLR produciría un error en el servidor remoto.Remoting a function that requires the CLR, could cause an error on the remote server.

FORMAT se basa en las reglas de formato de CLR, que dictan que los signos de punto y de dos puntos deben incluir caracteres de escape.FORMAT relies upon CLR formatting rules, which dictate that colons and periods must be escaped. Por tanto, cuando la cadena de formato (segundo parámetro) contiene un signo de punto o de dos puntos, estos deben incluir caracteres de escape, como una barra diagonal inversa, cuando un valor de entrada (primer parámetro) es del tipo de datos time.Therefore, when the format string (second parameter) contains a colon or period, the colon or period must be escaped with backslash when an input value (first parameter) is of the time data type. Vea D. FORMAT con tipos de datos de tiempo.See D. FORMAT with time data types.

En esta tabla se muestran los tipos de datos aceptables para el argumento value, junto con sus tipos equivalentes de asignación de .NET Framework.The following table lists the acceptable data types for the value argument together with their .NET Framework mapping equivalent types.

CategoríaCategory TipoType Tipo de .NET.NET type
NuméricoNumeric BIGINTbigint Int64Int64
NuméricoNumeric INTint Int32Int32
NuméricoNumeric SMALLINTsmallint Int16Int16
NuméricoNumeric TINYINTtinyint ByteByte
NuméricoNumeric Decimaldecimal SqlDecimalSqlDecimal
NuméricoNumeric NUMERICnumeric SqlDecimalSqlDecimal
NuméricoNumeric FLOATfloat DobleDouble
NuméricoNumeric REALreal ÚnicoSingle
NuméricoNumeric SMALLMONEYsmallmoney DecimalDecimal
NuméricoNumeric moneymoney DecimalDecimal
Fecha y horaDate and Time Datedate DateTimeDateTime
Fecha y horaDate and Time timetime TimespanTimeSpan
Fecha y horaDate and Time DATETIMEdatetime DateTimeDateTime
Fecha y horaDate and Time smalldatetimesmalldatetime DateTimeDateTime
Fecha y horaDate and Time datetime2datetime2 DateTimeDateTime
Fecha y horaDate and Time datetimeoffsetdatetimeoffset DateTimeOffsetDateTimeOffset

EjemplosExamples

A.A. Ejemplo de FORMAT sencilloSimple FORMAT example

En el ejemplo siguiente se devuelve una fecha simple con formato para distintas referencias culturales.The following example returns a simple date formatted for different cultures.

DECLARE @d DATETIME = '10/01/2011';  
SELECT FORMAT ( @d, 'd', 'en-US' ) AS 'US English Result'  
      ,FORMAT ( @d, 'd', 'en-gb' ) AS 'Great Britain English Result'  
      ,FORMAT ( @d, 'd', 'de-de' ) AS 'German Result'  
      ,FORMAT ( @d, 'd', 'zh-cn' ) AS 'Simplified Chinese (PRC) Result';
  
SELECT FORMAT ( @d, 'D', 'en-US' ) AS 'US English Result'  
      ,FORMAT ( @d, 'D', 'en-gb' ) AS 'Great Britain English Result'  
      ,FORMAT ( @d, 'D', 'de-de' ) AS 'German Result'  
      ,FORMAT ( @d, 'D', 'zh-cn' ) AS 'Chinese (Simplified PRC) Result';  

El conjunto de resultados es el siguiente.Here is the result set.

US English Result Great Britain English Result  German Result Simplified Chinese (PRC) Result  
----------------  ----------------------------- ------------- -------------------------------------  
10/1/2011         01/10/2011                    01.10.2011    2011/10/1  
  
(1 row(s) affected)  
  
US English Result            Great Britain English Result  German Result                    Chinese (Simplified PRC) Result  
---------------------------- ----------------------------- -----------------------------  ---------------------------------------  
Saturday, October 01, 2011   01 October 2011               Samstag, 1. Oktober 2011        2011年10月1日  
  
(1 row(s) affected)  

B.B. FORMAT con cadenas de formato personalizadoFORMAT with custom formatting strings

En el ejemplo siguiente se muestran valores numéricos de formato especificando un formato personalizado.The following example shows formatting numeric values by specifying a custom format. En el ejemplo se da por supuesto que la fecha actual es el 27 de septiembre de 2012.The example assumes that the current date is September 27, 2012. Para más información sobre estos y otros formatos personalizados, vea Cadenas con formato numérico personalizado.For more information about these and other custom formats, see Custom Numeric Format Strings.

DECLARE @d DATETIME = GETDATE();  
SELECT FORMAT( @d, 'dd/MM/yyyy', 'en-US' ) AS 'DateTime Result'  
       ,FORMAT(123456789,'###-##-####') AS 'Custom Number Result';  

El conjunto de resultados es el siguiente.Here is the result set.

DateTime Result  Custom Number Result  
--------------   --------------------  
27/09/2012       123-45-6789  
  
(1 row(s) affected)  

C.C. FORMAT con tipos numéricosFORMAT with numeric types

En este ejemplo se devuelven 5 filas de la tabla Sales.CurrencyRate de la base de datos AdventureWorks2012AdventureWorks2012.The following example returns 5 rows from the Sales.CurrencyRate table in the AdventureWorks2012AdventureWorks2012 database. La columna EndOfDateRate se almacena como el tipo money en la tabla.The column EndOfDateRate is stored as type money in the table. En este ejemplo, la columna se devuelve sin formato y después con formato especificando el formato Number de .NET, el formato General y los tipos de formato Currency.In this example, the column is returned unformatted and then formatted by specifying the .NET Number format, General format, and Currency format types. Para más información sobre estos y otros formatos numéricos, vea Cadenas con formato numérico estándar.For more information about these and other numeric formats, see Standard Numeric Format Strings.

SELECT TOP(5)CurrencyRateID, EndOfDayRate  
            ,FORMAT(EndOfDayRate, 'N', 'en-us') AS 'Number Format'  
            ,FORMAT(EndOfDayRate, 'G', 'en-us') AS 'General Format'  
            ,FORMAT(EndOfDayRate, 'C', 'en-us') AS 'Currency Format'  
FROM Sales.CurrencyRate  
ORDER BY CurrencyRateID;  

El conjunto de resultados es el siguiente.Here is the result set.

CurrencyRateID EndOfDayRate  Numeric Format  General Format  Currency Format  
-------------- ------------  --------------  --------------  ---------------  
1              1.0002        1.00            1.0002          $1.00  
2              1.55          1.55            1.5500          $1.55  
3              1.9419        1.94            1.9419          $1.94  
4              1.4683        1.47            1.4683          $1.47  
5              8.2784        8.28            8.2784          $8.28  
  
(5 row(s) affected)  
  

En este ejemplo se especifica la referencia cultural de alemán (de-de).This example specifies the German culture (de-de).

SELECT TOP(5)CurrencyRateID, EndOfDayRate  
      ,FORMAT(EndOfDayRate, 'N', 'de-de') AS 'Numeric Format'  
      ,FORMAT(EndOfDayRate, 'G', 'de-de') AS 'General Format'  
      ,FORMAT(EndOfDayRate, 'C', 'de-de') AS 'Currency Format'  
FROM Sales.CurrencyRate  
ORDER BY CurrencyRateID;  
CurrencyRateID EndOfDayRate  Numeric Format  General Format  Currency Format  
-------------- ------------  --------------  --------------  ---------------  
1              1.0002        1,00            1,0002          1,00 €  
2              1.55          1,55            1,5500          1,55 €  
3              1.9419        1,94            1,9419          1,94 €  
4              1.4683        1,47            1,4683          1,47 €  
5              8.2784        8,28            8,2784          8,28 €  
  
 (5 row(s) affected)  

D.D. FORMAT con tipos de datos de tiempoFORMAT with time data types

FORMAT devuelve NULL en estos casos porque . y : no incluyen caracteres de escape.FORMAT returns NULL in these cases because . and : are not escaped.

SELECT FORMAT(cast('07:35' as time), N'hh.mm');   --> returns NULL  
SELECT FORMAT(cast('07:35' as time), N'hh:mm');   --> returns NULL  

FORMAT devuelve una cadena con formato porque . y : incluyen caracteres de escape.Format returns a formatted string because the . and : are escaped.

SELECT FORMAT(cast('07:35' as time), N'hh\.mm');  --> returns 07.35  
SELECT FORMAT(cast('07:35' as time), N'hh\:mm');  --> returns 07:35  

Consulte tambiénSee Also

CAST y CONVERT (Transact-SQL)CAST and CONVERT (Transact-SQL)
STR (Transact-SQL)STR (Transact-SQL)
Funciones de cadena (Transact-SQL)String Functions (Transact-SQL)