Inside $LISTBUILDContestant

Most IRIS developers use $LISTBUILD every day — often without even noticing it.

It is not just a convenient function for building lists. It is also the default internal format used to store row data, global values, and many intermediate structures inside the database engine.

Despite this, the actual binary representation of $LISTBUILD values is rarely discussed. Most developers rely on its behavior, but never look at how the data is really stored.

This article focuses strictly on the binary layout of $LISTBUILD values, based on direct inspection via zzdump.

Element Structure

A $LISTBUILD value is a sequence of elements. Each element is encoded as:

[length][type][payload]

For small elements:

• length is 1 byte and includes the entire element
• type is 1 byte
• payload is variable

Example:

$lb("hello")
→ 07 01 68 65 6C 6C 6F

Endianness

Updated: thanks to @Steven Hobbs 

All examples in this article use little-endian byte order — and this is not incidental.

Despite IRIS supporting both little-endian and big-endian platforms internally, $LISTBUILD uses a consistent little-endian encoding for all binary payloads.

This applies to:

• integer values
• decimal mantissas
• floating-point values (08, 09)
• UTF-16 strings (UTF-16LE)

For example:

• integers are stored least-significant byte first
• IEEE floating-point values follow little-endian layout
• Unicode strings use UTF-16LE encoding

Extended Length Encoding

When the element size exceeds one byte capacity, IRIS switches to extended forms:

• 00 + 2-byte length
• 00 00 + 4-byte length

Example:

00 01 01 01 ...

Length encoding is therefore variable-width and marker-based.

String Types

Examples:

$lb("")       → 02 01
$lb("hello")  → 07 01 68 65 6C 6C 6F
$lb("привет") → 0E 02 ...

Unicode strings are stored as UTF-16.

Surrogate Pairs

Characters outside the Basic Multilingual Plane use UTF-16 surrogate pairs:

$lb("🔟")
→ 06 02 3D D8 1F DD

D83D DD1F → U+1F51F

Unicode values are stored as raw UTF-16 (platform endianness), without compression.

Integer Encoding

Encoding is variable-length.

Special cases:

0  → 02 04
-1 → 02 05

Examples:

1     → 03 04 01
255   → 03 04 FF
256   → 04 04 00 01

-2    → 03 05 FE
-256  → 03 05 00
-257  → 04 05 FF FE

Observations:

• positive integers use unsigned binary representation
• negative integers use two’s complement with variable width
• payload grows only when required

Decimal Numbers

Structure:

[length][type][scale][mantissa...]

• scale — 1 byte (decimal exponent)
• mantissa — variable-length integer

Example:

0.1     → 04 06 FF 01
0.01    → 04 06 FE 01
0.00002 → 04 06 FB 02

Large value:

2^32 + 0.1
→ 08 06 FF 01 00 00 00 0A

Interpretation:

value = mantissa × 10^exponent

Negative values mirror the same structure:

-0.00002 → 04 07 FB FE

Decimal values are stored as scaled integers, preserving exact decimal semantics.

Binary Floating-Point

IRIS supports two binary floating-point encodings.

Compact Float (Type 08)

[length][08][payload...]

• IEEE 754 single-precision (float32)
• little/big-endian depending on platform
• trailing zero bytes are omitted

Examples:

1.5  → 04 08 C0 3F
1.25 → 04 08 A0 3F
0.5  → 03 08 3F
10.0 → 04 08 20 41

IEEE Double (Type 09)

[length][09][8 bytes]

• IEEE 754 double-precision (float64)
• fixed 8-byte payload

Example:

$double(0.1)
→ 0A 09 9A 99 99 99 99 99 B9 3F

Special IEEE Values

$LISTBUILD also preserves special IEEE floating-point values such as NaN and Infinity.

Example:

zzdump $lb($double("-NAN")),$lb($double("NAN")),$lb($double("INF")),$lb($double("-INF"))

0000: 04 09 F8 FF
0000: 04 09 F8 7F
0000: 04 08 80 7F
0000: 04 08 80 FF

Observations

These encodings match the expected IEEE bit patterns:

• NaN → exponent all ones, non-zero mantissa
• Infinity → exponent all ones, zero mantissa
• sign bit preserved in the high byte

Type Selection Behavior

Unlike regular numeric values, special IEEE values do not strictly follow the usual 08 vs 09 distinction:

• NaN is stored using type 09
• Infinity is stored using type 08

This shows that IRIS does not enforce a fixed storage width for floating-point values. Instead, it appears to choose the most compact representation that preserves the value.

Practical Implication

The distinction between types 08 and 09 is not purely “float32 vs float64”. It is influenced by whether the value can be represented in a smaller IEEE form without loss.

For finite values, this usually means:

• 08 → compact IEEE single-precision
• 09 → full IEEE double-precision

For special values, IRIS may use either type depending on which representation is shorter.

Summary

$LISTBUILD is not just a helper function — it is a core binary storage format inside IRIS.

It combines:

• variable-length element encoding

• compact integer representation

• decimal values as scaled integers

• binary floating-point in two forms:

  • compact float32 (08)
  • full float64 (09)

The format is:

• space-efficient
• self-delimiting
• internally consistent across types

While not formally documented, its structure is stable and precise enough to be reverse-engineered and implemented outside IRIS.