FORMAT (Transact-SQL)

  • Artículo

Se aplica a: SQL Server Base de datos de Azure SQL Azure SQL Managed Instance Azure Synapse Analytics Punto de conexión de análisis SQL en Microsoft Fabric Almacén en Microsoft Fabric

Devuelve un valor con formato con el formato y la referencia cultural opcional especificados. Use la FORMAT función para el formato compatible con la configuración regional de valores de fecha y hora y número como cadenas. Para las conversiones generales de tipos de datos, use CAST o CONVERT.

Convenciones de sintaxis de Transact-SQL

Sintaxis

FORMAT( value , format [ , culture ] )

Argumentos

value

Expresión de un tipo de datos compatible a la que se va a dar formato. Para obtener una lista de tipos válidos, vea la tabla en la sección Comentarios.

format

Patrón de formato nvarchar.

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 patrón de caracteres personalizados para fechas y valores numéricos (por ejemplo, "MMMM DD, yyyy (dddd)"). No se admite el formato compuesto.

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. Para obtener más información, consulte Aplicar formato a tipos.

referencia cultural

Argumento opcional de tipo nvarchar que especifica una referencia cultural.

Si no se proporciona el argumento de referencia cultural , se usa el idioma de la sesión actual. Este lenguaje se establece implícitamente o explícitamente mediante la SET LANGUAGE instrucción . culture acepta cualquier referencia cultural compatible con .NET Framework como argumento; no se limita a los lenguajes admitidos explícitamente por SQL Server. Si el argumento de referencia cultural no es válido, FORMAT genera un error.

Tipos de valores devueltos

nvarchar o null

La longitud del valor devuelto viene determinada por format.

Comentarios

FORMAT devuelve NULL errores distintos de una referencia cultural que no es válida. Por ejemplo, NULL se devuelve si el valor especificado en formato no es válido.

La FORMAT función no es determinista.

FORMAT se basa en la presencia de Common Language Runtime (CLR) de .NET Framework.

Esta función no se puede remoto, ya que depende de la presencia de CLR. El envío remoto de una función que necesita CLR produciría un error en el servidor remoto.

FORMAT se basa en las reglas de formato CLR, que dictan que deben escaparse los dos puntos y puntos. Por lo tanto, cuando la cadena de formato (segundo parámetro) contiene dos puntos o punto, los dos puntos o el punto se deben escapar con barra diagonal inversa cuando un valor de entrada (primer parámetro) es del tipo de datos time. Vea D. FORMAT con tipos de datos de tiempo.

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.

Category Tipo Tipo de .NET
Numeric bigint Int64
Numeric int Int32
Numeric smallint Int16
Numeric tinyint Byte
Numeric decimal SqlDecimal
Numeric numeric SqlDecimal
Numeric float Double
Numeric real Single
Numeric smallmoney Decimal
Numeric money Decimal
Fecha y hora date DateTime
Fecha y hora time TimeSpan
Fecha y hora datetime DateTime
Fecha y hora smalldatetime DateTime
Fecha y hora datetime2 DateTime
Fecha y hora datetimeoffset DateTimeOffset

Ejemplos

A. Ejemplo de FORMAT sencillo

En el ejemplo siguiente se devuelve una fecha simple con formato para distintas referencias culturales.

DECLARE @d AS DATE = '11/22/2020';

SELECT FORMAT(@d, 'd', 'en-US') AS 'US English',
       FORMAT(@d, 'd', 'en-gb') AS 'British English',
       FORMAT(@d, 'd', 'de-de') AS 'German',
       FORMAT(@d, 'd', 'zh-cn') AS 'Chinese Simplified (PRC)';

SELECT FORMAT(@d, 'D', 'en-US') AS 'US English',
       FORMAT(@d, 'D', 'en-gb') AS 'British English',
       FORMAT(@d, 'D', 'de-de') AS 'German',
       FORMAT(@d, 'D', 'zh-cn') AS 'Chinese Simplified (PRC)';

Este es el conjunto de resultados.

US English   British English  German      Simplified Chinese (PRC)
-----------  ---------------- ----------- -------------------------
8/9/2024     09/08/2024       09.08.2024  2024/8/9

US English              British English  German                    Chinese (Simplified PRC)
----------------------- ---------------- ------------------------  -------------------------
Friday, August 9, 2024  09 August 2024   Freitag, 9. August 2024   2024年8月9日

B. FORMAT con cadenas de formato personalizado

En el ejemplo siguiente se muestran valores numéricos de formato especificando un formato personalizado. En el ejemplo se supone que la fecha actual es el 9 de agosto de 2024. Para más información sobre estos y otros formatos personalizados, vea Cadenas con formato numérico personalizado.

DECLARE @d AS DATE = GETDATE();

SELECT FORMAT(@d, 'dd/MM/yyyy', 'en-US') AS 'Date',
       FORMAT(123456789, '###-##-####') AS 'Custom Number';

Este es el conjunto de resultados.

Date         Custom Number
-----------  --------------
09/08/2024   123-45-6789

C. FORMAT con tipos numéricos

En el ejemplo siguiente se devuelven cinco filas de la Sales.CurrencyRate tabla de la AdventureWorks2022 base de datos. La columna EndOfDateRate se almacena como tipo money en la tabla. 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. Para más información sobre estos y otros formatos numéricos, vea Cadenas con formato numérico estándar.

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

Este es el conjunto de resultados.

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

En este ejemplo se especifica la referencia cultural alemana (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 €

D. FORMAT con tipos de datos de tiempo

FORMAT devuelve NULL en estos casos porque . y : no se escapan.

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.

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

El formato devuelve una hora actual con formato con am o PM especificado.

SELECT FORMAT(SYSDATETIME(), N'hh:mm tt'); --> returns 03:46 PM
SELECT FORMAT(SYSDATETIME(), N'hh:mm t');  --> returns 03:46 P

El formato devuelve la hora especificada, que muestra AM.

SELECT FORMAT(CAST('2018-01-01 01:00' AS DATETIME2), N'hh:mm tt'); --> returns 01:00 AM
SELECT FORMAT(CAST('2018-01-01 01:00' AS DATETIME2), N'hh:mm t');  --> returns 01:00 A

El formato devuelve la hora especificada, que muestra PM.

SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'hh:mm tt'); --> returns 02:00 PM
SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'hh:mm t');  --> returns 02:00 P

El formato devuelve la hora especificada en formato de 24 horas.

SELECT FORMAT(CAST('2018-01-01 14:00' AS DATETIME2), N'HH:mm'); --> returns 14:00

Contenido relacionado