Suggested
View this page as Markdown

format_units

Scales raw EVM integer balances by 10^decimals and returns a VARCHAR string representation. No floating point conversion is introduced. The default decimal scale is 18. INT256 inputs preserve signed values, and trailing fractional zeros are trimmed from the formatted string.

Scalar function TypesEVM

Example

Runs locally

-- Display a raw 6-decimal USDC balance
SELECT format_units(12345678::UINT256, 6) AS usdc;
-- => [{"usdc":"12.345678"}]

API reference

format_units(12 types) #

Display raw integer units with the default 18-decimal scale; signed inputs preserve their sign.

Exact signatures (12)
  • format_units(UINT256)
  • format_units(INT256)
  • format_units(UTINYINT)
  • format_units(USMALLINT)
  • format_units(UINTEGER)
  • format_units(UBIGINT)
  • format_units(UHUGEINT)
  • format_units(TINYINT)
  • format_units(SMALLINT)
  • format_units(INTEGER)
  • format_units(BIGINT)
  • format_units(HUGEINT)

Inputs

Name Type Use
raw_amount UINT256 | INT256 | UTINYINT | USMALLINT | UINTEGER | UBIGINT | UHUGEINT | TINYINT | SMALLINT | INTEGER | BIGINT | HUGEINT

Raw EVM integer units to display. Keep this as an integer type, not FLOAT or DOUBLE.

 required positional

Returns

Name Type
formatted_value VARCHAR

Human-readable decimal string. Returns a VARCHAR decimal representation without converting through FLOAT or DOUBLE.

format_units(12 types, INTEGER | UTINYINT | UINT8) #

Display raw integer units with an explicit integer scale between 0 and 77; signed inputs preserve their sign.

Exact signatures (36)
  • format_units(UINT256, INTEGER)
  • format_units(UINT256, UTINYINT)
  • format_units(UINT256, UINT8)
  • format_units(INT256, INTEGER)
  • format_units(INT256, UTINYINT)
  • format_units(INT256, UINT8)
  • format_units(UTINYINT, INTEGER)
  • format_units(UTINYINT, UTINYINT)
  • format_units(UTINYINT, UINT8)
  • format_units(USMALLINT, INTEGER)
  • format_units(USMALLINT, UTINYINT)
  • format_units(USMALLINT, UINT8)
  • format_units(UINTEGER, INTEGER)
  • format_units(UINTEGER, UTINYINT)
  • format_units(UINTEGER, UINT8)
  • format_units(UBIGINT, INTEGER)
  • format_units(UBIGINT, UTINYINT)
  • format_units(UBIGINT, UINT8)
  • format_units(UHUGEINT, INTEGER)
  • format_units(UHUGEINT, UTINYINT)
  • format_units(UHUGEINT, UINT8)
  • format_units(TINYINT, INTEGER)
  • format_units(TINYINT, UTINYINT)
  • format_units(TINYINT, UINT8)
  • format_units(SMALLINT, INTEGER)
  • format_units(SMALLINT, UTINYINT)
  • format_units(SMALLINT, UINT8)
  • format_units(INTEGER, INTEGER)
  • format_units(INTEGER, UTINYINT)
  • format_units(INTEGER, UINT8)
  • format_units(BIGINT, INTEGER)
  • format_units(BIGINT, UTINYINT)
  • format_units(BIGINT, UINT8)
  • format_units(HUGEINT, INTEGER)
  • format_units(HUGEINT, UTINYINT)
  • format_units(HUGEINT, UINT8)

Inputs

Name Type Use
raw_amount UINT256 | INT256 | UTINYINT | USMALLINT | UINTEGER | UBIGINT | UHUGEINT | TINYINT | SMALLINT | INTEGER | BIGINT | HUGEINT

Raw EVM integer units to display. Keep this as an integer type, not FLOAT or DOUBLE.

 required positional
decimals INTEGER | UTINYINT | UINT8

Decimal precision used by the token contract. Must be an integer between 0 and 77.

 required positional

Returns

Name Type
formatted_value VARCHAR

Human-readable decimal string. Returns a VARCHAR decimal representation without converting through FLOAT or DOUBLE.

Guidance

Raw units vs display strings

format_units is the inverse display helper for parse_units. It turns raw token units into a decimal string without floating point conversion.

  • Use format_units(raw_amount, decimals) for ERC-20 balances.
  • Use format_ether for wei values with the fixed 18-decimal Ether scale.
  • Use parse_units or parse_ether when converting human-entered strings into raw UINT256 values.
  • Do not feed the returned VARCHAR back into calldata or math unless you explicitly parse it again.

Runs locally

SELECT
  format_units(parse_units('2500', 6), 6) AS usdc,
  format_ether(parse_ether('1.25')) AS eth;

Examples

Runs locally

-- Preserve the sign of a raw 6-decimal accounting delta
SELECT format_units((-1234567)::INT256, 6) AS pnl_usdc;
-- => [{"pnl_usdc":"-1.234567"}]