FORMAT_STRING

Format a string using printf-style placeholders (alias for PRINTF).

Category: miscReturns: STRINGDialect: Standard

Syntax

FORMAT_STRING(fmt, args...)

Description

## Overview Formats a string by substituting positional arguments into printf-style placeholders in the format string. Supports the common %-directives used in C-style formatting. Use this function to compose log lines, labels, and other display strings from structured data. FORMAT_STRING is an alias for PRINTF; use whichever name reads better in your codebase. ## Behavior - Returns NULL if the format string is NULL. - NULL argument values are rendered as the literal text `null`. - Supported placeholders include %s, %d, %f, %.Nf, %x, and %%. - Too few or too many arguments relative to the placeholders raises an error. - Deterministic with respect to its inputs; side effect free. ## Compatibility - Matches the standard analytical SQL FORMAT_STRING semantics. PRINTF is the PG-compat alias.

Parameters

Name	Type	Description
`fmt`		Specifies the format string. Supported placeholders include %s (string), %d (integer), %f (floating-point), and %.Nf (fixed precision float).
`args`		Specifies the positional arguments substituted into the placeholders, in order. Each %-directive consumes one argument.

Examples

-- Simple string substitution
SELECT FORMAT_STRING('Hello, %s!', 'world');  -- 'Hello, world!'

-- Integer and fixed-precision float
SELECT FORMAT_STRING('Count: %d, Avg: %.2f', 42, 3.14159);  -- 'Count: 42, Avg: 3.14'

-- Multiple arguments in one call
SELECT FORMAT_STRING('%s has %d items at $%.2f each', 'Order', 5, 9.99);

-- NULL arguments are rendered as 'null' text
SELECT FORMAT_STRING('Value: %s', NULL);  -- 'Value: null'

-- Compose a log line
SELECT FORMAT_STRING('[%s] %s logged in from %s', CURRENT_TIMESTAMP, CURRENT_USER(), INET_CLIENT_ADDR()) AS log_line;

Pitfalls

FORMAT_STRING and PRINTF are synonyms. Pick one spelling for the codebase to avoid confusion.
NULL arguments are rendered as literal `null`, not an empty string. Wrap arguments with COALESCE if you want a different fallback.
The format string must have exactly as many placeholders as arguments. Mismatched counts raise an error at execution, not at parse time.
Type coercion is limited. A `%d` with a floating-point argument raises an error; cast to INT first if that is what you want.