> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FORMAT_STRING

> Formats values using a printf-style pattern.

<div className="e6-meta"><span className="e6-eyebrow e6-eyebrow--quiet">Scalar function</span></div>

**Aliases:** [`format`](/query/sql/functions/string/format)

NULL pattern returns NULL. For an accepted specifier, NULL integer/floating-point/decimal/string/date/time/timestamp values render the text null; NULL boolean values render false (FALSE with %B, uppercase with %S). Untyped NULL renders text null only when its specifier passes type validation.

## Syntax

### Scalar

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
format_string(pattern [, value, ...])
```

## Arguments

| Name | Type | Required | Description |
| - | - | - | - |
| pattern | STRING | Yes | The format. |
| value | BOOLEAN, TINYINT, SMALLINT, INTEGER, BIGINT, FLOAT, DOUBLE, DECIMAL(p, s), STRING, DATE, TIME or TIMESTAMP | No | A format argument; more may follow. The format conversion must match the value type; see the formatting restrictions below. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). This argument can repeat. |

## Returns

* Type: STRING
* Possible values: Formatted text.
* NULL behavior: NULL pattern returns NULL. For an accepted specifier, NULL integer/floating-point/decimal/string/date/time/timestamp values render the text null; NULL boolean values render false (FALSE with %B, uppercase with %S). Untyped NULL renders text null only when its specifier passes type validation.

## Properties

| Property | Value |
| - | - |
| Deterministic | Yes |
| Supports window usage | No |
| Exact result | Yes |

## Usage notes

* Pattern can vary by row; %% renders a percent sign.
* Patterns support sequential arguments, one-based positional n\$ arguments, \< reuse, width, precision, flags -, +, space, #, 0, comma and parentheses. %% emits percent; %n emits newline.
* Integer conversions d/o/x/X and c/C require integers. Floating-point conversions e/E/f/g/G/a/A require supported numeric types; they do not convert integer inputs to floating point, and hexadecimal floating-point formats do not accept DECIMAL. b/B requires BOOLEAN; t/T requires a date/time value. s/S accepts the scalar types listed above.
* INTEGER and INT mean the same type; STRING means VARCHAR text. NULL can be used with a supported type. Cast NULL explicitly when its type would otherwise be unclear.

## Examples

### Typical behavior

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT format_string('%s=%d', 'n', 7) AS "value";
```

| value |
| - |
| n=7 |

### NULL conversions

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT format_string('%s|%d|%f|%b', CAST(NULL AS STRING),CAST(NULL AS BIGINT),CAST(NULL AS DOUBLE),CAST(NULL AS BOOLEAN)) AS "value";
```

| value |
| - |
| null\|null\|null\|false |

## Limitations

* Malformed patterns, missing arguments, and unsupported type/conversion pairs raise errors. BINARY, ARRAY, MAP, and STRUCT values are not supported, including with %s. Integer character conversions require a valid Unicode code point. Use the function name shown here; PRINTF is not an established alias.
* With %s or %S, DECIMAL values are printed as their unscaled integer, and date/time values as their integer epoch value. Use an explicit STRING cast when you need the usual SQL text representation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.