# sort_key

Converts INT256/INT512/UINT256/UINT512 to a sortable BLOB for use in ORDER BY. Necessary because Determica's default BLOB ordering doesn't handle signed integers correctly. Use sort_key only inside ORDER BY or comparison-key workflows; it is not a human-readable number conversion, hash, or portable serialization.

Canonical HTML: <https://determica.com/docs/functions/sort_key>

- Kind: scalar function
- Category: [EVM utilities](/docs/category/evm-utilities.md)
- Tags: Types, EVM

Converts INT256/INT512/UINT256/UINT512 to a sortable BLOB for use in ORDER BY. Necessary because Determica's default BLOB ordering doesn't handle signed integers correctly. Use sort_key only inside ORDER BY or comparison-key workflows; it is not a human-readable number conversion, hash, or portable serialization.

## Overload 1: sort_key(INT256)

```sql
sort_key(INT256)
```

Builds a sortable key for signed INT256 values. The returned BLOB is for ordering, not display.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `value` (INT256; required; positional) — INT256, INT512, UINT256, or UINT512 value to turn into an ordering key.

### Returns

Sortable binary key

Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

- `sortable_key` (BLOB)

Sortable binary key. Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

### Examples

_Local SQL · Local_

```sql
-- Sort signed accounting deltas numerically
WITH pnl(label, delta) AS (
  VALUES
    ('loss', '-2500000'::INT256),
    ('flat', '0'::INT256),
    ('profit', '1750000'::INT256)
)
SELECT label, delta::VARCHAR AS raw_delta
FROM pnl
ORDER BY sort_key(delta);
-- => [{"label":"loss","raw_delta":"-2500000"},{"label":"flat","raw_delta":"0"},{"label":"profit","raw_delta":"1750000"}]
```

## Overload 2: sort_key(INT512)

```sql
sort_key(INT512)
```

Builds a sortable key for signed INT512 values. The returned BLOB is for ordering, not display.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `value` (INT512; required; positional) — INT256, INT512, UINT256, or UINT512 value to turn into an ordering key.

### Returns

Sortable binary key

Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

- `sortable_key` (BLOB)

Sortable binary key. Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

### Examples

_Local SQL · Local_

```sql
SELECT value::VARCHAR FROM (VALUES ('-2'::INT512), (1::INT512)) t(value) ORDER BY sort_key(value);
```

## Overload 3: sort_key(UINT256)

```sql
sort_key(UINT256)
```

Builds a sortable key for unsigned UINT256 values. The returned BLOB is for ordering, not display.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `value` (UINT256; required; positional) — INT256, INT512, UINT256, or UINT512 value to turn into an ordering key.

### Returns

Sortable binary key

Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

- `sortable_key` (BLOB)

Sortable binary key. Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

### Examples

_Local SQL · Local_

```sql
-- Sort balances wider than native 128-bit integers
WITH balances(label, raw_balance) AS (
  VALUES
    ('small', 100::UINT256),
    ('whale', '340282366920938463463374607431768211456'::UINT256),
    ('medium', 1000000::UINT256)
)
SELECT label, raw_balance::VARCHAR AS raw_balance
FROM balances
ORDER BY sort_key(raw_balance) DESC;
-- => [{"label":"whale","raw_balance":"340282366920938463463374607431768211456"},{"label":"medium","raw_balance":"1000000"},{"label":"small","raw_balance":"100"}]
```

## Overload 4: sort_key(UINT512)

```sql
sort_key(UINT512)
```

Builds a sortable key for unsigned UINT512 values. The returned BLOB is for ordering, not display.

- Kind: scalar
- Execution context: Offline
- Behavior: Transform
- Execution modes: Offline
- Input shape: Scalar Arguments
- Planning contract: Runtime
- Cardinality: One Per Input
- Determinism: Deterministic
- Return shape: Scalar
- Schema stability: Fixed
- Stability: Stable
- Side effects: None documented

### Inputs

- `value` (UINT512; required; positional) — INT256, INT512, UINT256, or UINT512 value to turn into an ordering key.

### Returns

Sortable binary key

Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

- `sortable_key` (BLOB)

Sortable binary key. Returns a BLOB whose byte ordering matches numeric ordering. It is not a display or hash format.

### Examples

_Local SQL · Local_

```sql
SELECT value::VARCHAR FROM (VALUES (2::UINT512), (1::UINT512)) t(value) ORDER BY sort_key(value);
```

## Guidance

### Ordering wide integers

Use sort_key inside ORDER BY when signed or wide EVM integers must sort numerically. The returned BLOB is an implementation detail for ordering.

- Do not display sort_key output to users.
- Use format_units or format_ether when you need a human-readable amount.

```sql
WITH balances(raw_amount) AS (
  VALUES (parse_units('2500', 6)), (parse_units('125', 6))
)
SELECT raw_amount
FROM balances
ORDER BY sort_key(raw_amount) DESC;
```

## Related functions

- [format_units](/docs/functions/format_units.md) — See Also
- [format_ether](/docs/functions/format_ether.md) — See Also