Cómo funciona la función FORMAT() en SQL Server (T-SQL)

En SQL Server, puede usar T-SQL FORMAT() función para devolver valores como números y fechas como cadenas formateadas.

Usted proporciona el valor al que se va a dar formato y especifica el formato que se va a utilizar. La función acepta un argumento opcional que le permite especificar una referencia cultural para usar al formatear el valor.

Sintaxis

La sintaxis es así:

FORMAT ( value, format [, culture ] )

Donde value es el valor que desea formatear, y format es una cadena de formato válida que especifica el formato deseado.

La culture opcional El argumento se puede utilizar para especificar una referencia cultural. Si se omite, se utiliza el idioma de la sesión actual.

El FORMAT la función no es determinista.

Ejemplo 1:Dar formato a un número

Este es un ejemplo de formateo de un número:

SELECT FORMAT(1, 'N') AS Result;

Resultado:

+----------+
| Result   |
|----------|
| 1.00     |
+----------+

En este caso, usé N como cadena de formato. Este es un especificador de formato numérico estándar para generar el valor como un número. Este especificador de formato particular da como resultado que la salida se formatee con dígitos enteros y decimales, separadores de grupo y un separador decimal con signo negativo opcional. Este especificador de formato no distingue entre mayúsculas y minúsculas, por lo que N o n está bien.

Ejemplo 2:Formato a una moneda

Este es un ejemplo de formato de un número como moneda:

SELECT FORMAT(1, 'C') AS Result;

Resultado:

+----------+
| Result   |
|----------|
| $1.00    |
+----------+

Más formatos numéricos

Hay muchas más cadenas de formato que se pueden usar con FORMAT() función. Por ejemplo, hay cadenas de formato para porcentajes, punto fijo, exponencial (científico), hexadecimal y más.

Las cadenas de formato numérico se separan en estándar y personalizado.

Los siguientes dos artículos enumeran todas las cadenas de formato numérico, incluidos ejemplos:

• Cadenas de formato numérico estándar
• Cadenas de formato numérico personalizado

Consulte también Cómo dar formato a números en SQL Server para obtener más ejemplos de cómo dar formato a números.

Ejemplo 3:Dar formato a una fecha

Este es un ejemplo de cómo dar formato a una fecha:

SELECT 
  GETDATE() AS 'Unformatted Date',
  FORMAT( GETDATE(), 'D') AS 'Formatted Date';

Resultado:

+-------------------------+------------------------+
| Unformatted Date        | Formatted Date         |
|-------------------------+------------------------|
| 2019-05-08 06:16:55.613 | Wednesday, May 8, 2019 |
+-------------------------+------------------------+

En este caso, usé D que especifica un patrón de fecha larga.

Más formatos de fecha

Hay muchas más cadenas de formato que se pueden usar para formatear fechas. Al igual que con las cadenas de formato numérico, las cadenas de formato de fecha y hora se separan en estándar y personalizadas, por lo que puede crear sus propios formatos personalizados o confiar en uno estándar.

Los siguientes dos artículos enumeran todas las cadenas de formato de fecha y hora, incluidos ejemplos:

• Cadenas de formato de fecha y hora estándar
• Cadenas de formato de fecha y hora personalizado

Consulte también Cómo formatear la fecha y la hora en SQL Server para obtener más ejemplos.

Ejemplo 4:la culture opcional Argumento

Aquí hay un ejemplo del uso de la culture argumento para devolver un valor en varias monedas:

SELECT 
    FORMAT(1, 'C', 'fr-FR') AS 'France', 
    FORMAT(1, 'C', 'th-TH') AS 'Thailand', 
    FORMAT(1, 'C', 'ja-JP') AS 'Japan';

Resultado:

+----------+------------+---------+
| France   | Thailand   | Japan   |
|----------+------------+---------|
| 1,00 €   | ฿1.00      | ¥1      |
+----------+------------+---------+

El FORMAT() la función acepta cualquier referencia cultural admitida por .NET Framework como argumento; no se limita a los idiomas soportados explícitamente por SQL Server.

Si no proporciona este argumento, se utiliza el idioma de la sesión actual.

Para obtener más ejemplos, consulte Cómo la configuración de idioma puede afectar su FORMAT() Resultados.

Ejemplo 5:culture no válida Argumento

Si proporciona una referencia cultural no válida, obtendrá un error:

SELECT FORMAT(1, 'C', 'oop-SS!') AS 'Oops!';

Resultado:

The culture parameter 'oop-SS!' provided in the function call is not supported.

Ejemplo 6:valor de formato no válido

Sin embargo, para otros errores, la función devuelve NULL . Por ejemplo, esto es lo que sucede si proporciono un valor no válido para formatear:

SELECT FORMAT(GETDATE(), 'C') AS 'Result';

Resultado:

+----------+
| Result   |
|----------|
| NULL     |
+----------+

En este caso, estaba tratando de formatear una fecha en una moneda y, por lo tanto, el resultado fue NULL .

Tipos de datos válidos

FORMAT() se basa en la presencia de .NET Framework Common Language Runtime (CLR) y utiliza las reglas de formato de CLR.

Los siguientes tipos de datos se pueden formatear con FORMAT() función. Esta lista contiene los tipos de datos aceptables para la cadena de entrada junto con sus tipos equivalentes de asignación de .NET Framework.

Dos puntos y puntos de escape para el tipo de datos 'tiempo'

Al usar FORMAT , los dos puntos y los puntos deben escaparse (esto se adhiere a las reglas de formato de CLR). Por lo tanto, cuando la cadena de formato (segundo parámetro) contiene dos puntos o un punto, los dos puntos o el punto se deben escapar con una barra invertida cuando un valor de entrada (primer parámetro) es de la hora. tipo de datos.

Ejemplo:

SELECT 
  CAST('12:15' AS time) AS 'Unformatted Data',
  FORMAT(CAST('12:15' AS time), N'hh.mm') AS 'Unescaped',
  FORMAT(CAST('12:15' AS time), N'hh\.mm') AS 'Escaped';

Resultado:

+--------------------+-------------+-----------+
| Unformatted Data   | Unescaped   | Escaped   |
|--------------------+-------------+-----------|
| 12:15:00           | NULL        | 12.15     |
+--------------------+-------------+-----------+

Entonces, como se esperaba, la cadena sin escape devuelve NULL .

Como se mencionó, esto solo se aplica al tiempo tipo de datos. Si cambiamos el valor de entrada a un tipo de datos diferente, no necesitamos escaparlo:

SELECT 
  CAST('12:15' AS datetime) AS 'Unformatted Data',
  FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Unescaped',
  FORMAT(CAST('12:15' AS datetime), N'hh.mm') AS 'Escaped';

Resultado:

+-------------------------+-------------+-----------+
| Unformatted Data        | Unescaped   | Escaped   |
|-------------------------+-------------+-----------|
| 1900-01-01 12:15:00.000 | 12.15       | 12.15     |
+-------------------------+-------------+-----------+

En este caso, el valor de entrada es datetime , y por lo tanto, el resultado está bien sin escaparse.

También puede usar la barra invertida para escapar de cualquier otro carácter que desee incluir en la cadena de resultado, que de otro modo se interpretaría como un especificador de formato. Preceder un carácter con una barra invertida significa que el siguiente carácter es un carácter literal que debe incluirse en la cadena de resultados sin cambios.

En una cadena de formato de fecha y hora personalizada, la d , f , F , g , h , H , K , m , M , s , t , y , z , : , o / los caracteres se interpretan como especificadores de formato personalizado en lugar de como caracteres literales.

En una cadena de formato numérico personalizado, el # , 0 , . , , , % y ‰ los símbolos se interpretan como especificadores de formato y no como caracteres literales. La E mayúsculas y minúsculas así como el + y - los símbolos también pueden interpretarse como especificadores de formato, dependiendo de su posición dentro de la cadena de formato.

Si necesita incluir una barra invertida en la cadena de resultados, escápela con otra barra invertida.

Remoto

El FORMAT() La función no puede ser remota ya que depende de la presencia del CLR. La transmisión remota de una función que requiere CLR podría causar un error en el servidor remoto.

Cuándo usar el FORMAT() Función

Microsoft recomienda que FORMAT() La función se utiliza para el formato de fecha/hora y valores numéricos como cadenas de acuerdo con la configuración regional, y para conversiones generales de tipos de datos, ya sea CAST() o la función CONVERT() en su lugar, se debe usar la función.