Overview
BINARY (alias VARBINARY) stores variable-length byte sequences. Unlike STRING, the value is not interpreted as UTF-8 text, making it suitable for payloads such as digests, compressed data, or serialized objects. Use conversion functions like UNHEX, FROM_BASE64, and TO_HEX to encode or decode values when reading or writing the data.
Examples
Insert Raw Bytes
CREATE TABLE binary_samples (
id INT,
raw BINARY
);
INSERT INTO binary_samples VALUES
(1, UNHEX('68656c6c6f')), -- "hello"
(2, FROM_BASE64('ZGF0YWJlbmQ=')); -- "databend"
SELECT
id,
HEX(raw) AS hex_value,
LENGTH(raw) AS byte_len
FROM binary_samples
ORDER BY id;
Result:
┌────┬──────────────┬──────────┐
│ id │ hex_value │ byte_len │
├────┼──────────────┼──────────┤
│ 1 │ 68656c6c6f │ 5 │
│ 2 │ 6461746162656e64 │ 8 │
└────┴──────────────┴──────────┘
Convert Back to Text
Binary values can be converted to strings when needed:
SELECT
id,
TO_VARCHAR(raw) AS text_value
FROM binary_samples
ORDER BY id;
Result:
┌────┬─────────────┐
│ id │ text_value │
├────┼─────────────┤
│ 1 │ hello │
│ 2 │ databend │
└────┴─────────────┘
Binary columns accept NULL values and can also be nested inside ARRAY, MAP, or TUPLE structures when you need to store byte payloads alongside other data.