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

# TO_CHAR

> Formats a temporal, numeric, binary or string value as text.

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

**Aliases:** [`to_varchar`](/query/sql/functions/date-time/to_varchar)

Typed NULL value returns NULL for the documented input types. A NULL format returns NULL. A malformed format, unsupported type/format pairing or invalid UTF-8 binary conversion raises an error.

## Syntax

### Default (scalar)

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
to_char(value)
```

* Use ordinary STRING values, TIMESTAMP with microsecond precision, and DECIMAL scale from 0 through 38. Formatting timestamps with negative fractional seconds before the Unix epoch is outside these forms.

### Formatted (scalar)

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
to_char(value, format)
```

* Microsecond TIMESTAMP and DECIMAL scale 0..38; ordinary STRING formats may be constants or per-row columns.
* Floating-point values must be finite, have magnitude below the unsigned 64-bit limit, and use at most 18 fractional digit positions. DECIMAL formats use at most 38 fractional positions. Timestamps with negative fractional seconds before the Unix epoch are outside these forms.

## Arguments

### Default

| Name | Type | Required | Description |
| - | - | - | - |
| value | STRING, DATE, TIMESTAMP, INTEGER, BIGINT, FLOAT, DOUBLE or DECIMAL(p, s) | Yes | Value to render. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |

### Formatted

| Name | Type | Required | Description |
| - | - | - | - |
| value | DATE, TIMESTAMP, INTEGER, BIGINT, FLOAT, DOUBLE, DECIMAL(p, s) or BINARY | Yes | Value to render. For DECIMAL(p, s), p is precision (total digits) and s is scale (digits after the decimal point). |
| format | STRING | Yes | Type-specific formatting pattern. Temporal MySQL (%) or Java-style datetime pattern; numeric digit/sign/grouping pattern; BINARY hex, base64 or utf-8 (case-insensitive). |

## Returns

* Type: STRING
* NULL behavior: Typed NULL value returns NULL for the documented input types. A NULL format returns NULL. A malformed format, unsupported type/format pairing or invalid UTF-8 binary conversion raises an error.

## Properties

| Property | Value |
| - | - |
| Deterministic | Yes |
| Exact result | Partial (Numeric formatting intentionally rounds to the requested fractional positions; floating arithmetic can introduce additional rounding. Temporal output includes only the fields selected by the format.) |

## Units

* Input unit: Type-specific value and optional format
* Output unit: STRING
* DATE default format is yyyy-MM-dd; TIMESTAMP default format is yyyy-MM-dd HH:mm:ss.
* Numeric 0 positions pad with zeros and 9 positions pad with spaces; decimal D/., grouping G/,, currency \$, and sign S/MI/PR tokens are supported.
* Integer and DECIMAL numeric formatting use integer arithmetic. DECIMAL rounding increments the magnitude at a discarded digit of 5 or more; floating formatting rounds the absolute scaled DOUBLE, then restores the sign.
* Too many integral or fractional digits for a numeric pattern replace digit positions with # while retaining separators, currency and the applicable sign layout.

## Usage notes

* The one-argument STRING form passes its value through; one-argument numeric values use plain conversion.
* Formatting uses the timestamp’s stored UTC clock time and does not adjust it to its named time zone.
* The format may be a per-row ordinary STRING column; NULL values or NULL formats preserve NULL rows.
* BINARY hex uses uppercase hexadecimal; base64 and utf-8 are also accepted, with invalid UTF-8 producing an error.
* Deterministic: A fixed value and format produce the same text.

## Examples

### Formatted example 1

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT to_char(DATE '2024-03-15','yyyy-MM-dd') AS result;
```

| result |
| - |
| 2024-03-15 |

### Formatted example 2

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT to_char(X'537061726B','hex') AS result;
```

| result |
| - |
| 537061726B |

## Limitations

* STRING input with an explicit format and BINARY input without a format are not supported.
* Use the types listed for each form. Narrower integer types, decimals beyond 128-bit storage, timestamps with other precision, and alternate STRING representations are outside these forms.
* DECIMAL values with negative scale, NaN, infinity, and floating-point values beyond the stated range are outside these formatting forms.
* Avoid timestamps with negative fractional seconds before 1970-01-01 00:00:00 UTC; they can be formatted incorrectly.


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