Data Types Reference
Geode provides 50+ specialized data types optimized for different use cases. This reference documents all types, their constructors, storage characteristics, and indexing recommendations.
Type System Overview
Type Categories
| Category | Types | Description |
|---|---|---|
| Core | NULL, BOOLEAN, INTEGER, FLOAT, STRING, BYTES | Fundamental types |
| Numeric | INT8-INT64, FLOAT32-FLOAT64, DECIMAL | Precision-specific numerics |
| Temporal | DATE, TIME, TIMESTAMP, ZONED_DATETIME, DURATION, INTERVAL | Date and time |
| Collection | LIST, MAP, SET | Compound types |
| Vector | VECTOR_F32, VECTOR_I32 | ML embeddings |
| Geographic | LATLON, GEOPOINT, POLYGON | Spatial data |
| Network | IPADDR, SUBNET, MACADDR | Network addressing |
| Structured | JSON, JSONB | Semi-structured data |
| Identity | UUID, HASH | Unique identifiers |
| Financial | MONEY, BIGDECIMAL | Exact decimals |
Core Types
NULL
Represents the absence of a value.
-- NULL literal
RETURN null AS empty;
-- NULL check
MATCH (p:Person)
WHERE p.middle_name IS NULL
RETURN p.name;
-- NULL coalescing
RETURN coalesce(p.nickname, p.name) AS display_name;
Properties:
- NULL propagates through most operations
- NULL = NULL evaluates to NULL (not true)
- Use
IS NULL/IS NOT NULLfor comparisons
BOOLEAN
Logical true/false values.
Storage: 1 byte
-- Literals
CREATE (:User {active: true, verified: false});
-- Boolean operations
MATCH (u:User)
WHERE u.active AND NOT u.deleted
RETURN u.name;
-- Boolean expressions
MATCH (p:Person)
RETURN p.name, p.age >= 18 AS is_adult;
Constructor:
toBoolean('true') -- true
toBoolean('false') -- false
toBoolean(1) -- true
toBoolean(0) -- false
INTEGER
Whole numbers (default 64-bit signed).
Storage: Variable (1-8 bytes based on value)
-- Literals
CREATE (:Product {id: 42, stock: 1000, price_cents: 1999});
-- Arithmetic
RETURN 10 + 5 * 3 AS result; -- 25
-- Integer division
RETURN 7 / 2 AS quotient; -- 3 (truncates)
Constructor:
toInteger('42') -- 42
toInteger(3.7) -- 3 (truncates)
toInteger(true) -- 1
Range: -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
FLOAT
Floating-point numbers (IEEE 754 double precision).
Storage: 8 bytes
-- Literals
CREATE (:Measurement {value: 3.14159, tolerance: 0.001});
-- Scientific notation
RETURN 1.5e10 AS large_number;
-- Arithmetic
RETURN 7.0 / 2 AS division; -- 3.5
Constructor:
toFloat('3.14') -- 3.14
toFloat(42) -- 42.0
Special values: Infinity, -Infinity, NaN
STRING
UTF-8 encoded text.
Storage: Variable (length prefix + UTF-8 bytes)
-- Literals
CREATE (:Person {name: 'Alice', bio: "Software engineer"});
-- Concatenation
RETURN 'Hello' || ' ' || 'World' AS greeting;
-- String functions
RETURN upper('hello') AS uppercase; -- 'HELLO'
RETURN substring('hello', 0, 3) AS sub; -- 'hel'
RETURN length('hello') AS len; -- 5
Constructor:
toString(42) -- '42'
toString(3.14) -- '3.14'
toString(true) -- 'true'
toString(date('2026-01-28')) -- '2026-01-28'
Escapes: \n, \t, \\, \', \"
BYTES
Raw binary data.
Storage: Variable (length prefix + raw bytes)
-- Hex literal
CREATE (:File {data: bytea('\\x48656c6c6f')});
-- Length
MATCH (f:File)
RETURN length(f.data) AS bytes;
Constructor:
bytea('\\x48656c6c6f') -- Hex encoding; the \x prefix is required
from_hex('\\x48656c6c6f') -- Alias of bytea(), same \x-prefixed input
Base64 decoding is not implemented in the engine — decode client-side and pass
the bytes as a \x-prefixed hex string.
Numeric Types (Precision-Specific)
Integer Variants
| Type | Storage | Range | Use Case |
|---|---|---|---|
INT8 | 1 byte | -128 to 127 | Small counters |
INT16 | 2 bytes | -32,768 to 32,767 | Medium counters |
INT32 | 4 bytes | -2.1B to 2.1B | Default integer |
INT64 | 8 bytes | -9.2Q to 9.2Q | Large IDs |
-- Explicit constructors
RETURN int(127) AS i8;
RETURN int(32000) AS i16;
RETURN int(2000000) AS i32;
RETURN int(9000000000000) AS i64;
Float Variants
| Type | Storage | Precision | Use Case |
|---|---|---|---|
FLOAT32 | 4 bytes | ~7 digits | Approximate decimals |
FLOAT64 | 8 bytes | ~15 digits | High-precision decimals |
RETURN double(3.14) AS f32;
RETURN double(3.14159265358979) AS f64;
DECIMAL / BIGDECIMAL
Arbitrary-precision decimal numbers.
Storage: Variable
-- Exact decimal arithmetic
CREATE (:Account {balance: decimal('1234567.89')});
-- No floating-point errors
RETURN decimal('0.1') + decimal('0.2') AS sum; -- 0.3 (exact)
Constructor:
decimal('123.456')
decimal('999999999999999999.999999999999')
Use cases: Financial calculations, currency, exact arithmetic
Temporal Types
DATE
Calendar date (year, month, day).
Storage: 4 bytes
-- Constructor
RETURN date('2026-01-28') AS d;
-- Current date
RETURN date() AS today;
-- Components
RETURN date('2026-01-28').year AS year; -- 2026
RETURN date('2026-01-28').month AS month; -- 1
RETURN date('2026-01-28').day AS day; -- 28
-- Arithmetic
RETURN date('2026-01-28') + duration('P7D') AS next_week;
Format: ISO 8601 (YYYY-MM-DD)
TIME
Time of day without timezone.
Storage: 8 bytes (nanosecond precision)
-- Constructor
RETURN time('14:30:00') AS t;
RETURN time('14:30:00.123456789') AS precise_time;
-- Components
RETURN time('14:30:45').hour AS hour; -- 14
RETURN time('14:30:45').minute AS minute; -- 30
RETURN time('14:30:45').second AS second; -- 45
Format: ISO 8601 (HH:MM:SS[.nnnnnnnnn])
TIMESTAMP
Date and time with optional timezone.
Storage: 12 bytes
-- Constructor
RETURN timestamp('2026-01-28T14:30:00Z') AS ts;
RETURN timestamp('2026-01-28T14:30:00-05:00') AS ts_est;
-- Current timestamp
RETURN timestamp() AS now;
-- Arithmetic
MATCH (e:Event)
WHERE e.created_at > timestamp() - duration('P30D')
RETURN e.name;
Format: ISO 8601 (YYYY-MM-DDTHH:MM:SS[.nnn][Z|+HH:MM])
ZONED_DATETIME
Date and time with explicit timezone.
Storage: 16 bytes
-- Constructor with timezone
RETURN timestamptz('2026-01-28T14:30:00', 'America/New_York') AS zdt;
-- Timezone conversion
RETURN timestamptz('Europe/London') AS london_time;
DURATION
Time span (ISO 8601 duration).
Storage: 16 bytes
-- Constructor
RETURN duration('P7D') AS one_week; -- 7 days
RETURN duration('PT2H30M') AS two_half_hours; -- 2 hours 30 minutes
RETURN duration('P1Y2M3DT4H5M6S') AS complex; -- 1 year, 2 months, ...
-- Components
RETURN duration('P7D').days AS days; -- 7
RETURN duration('PT2H30M').hours AS hours; -- 2
RETURN duration('PT2H30M').minutes AS mins; -- 30
-- Arithmetic
RETURN timestamp() + duration('P7D') AS next_week;
RETURN timestamp() - duration('PT1H') AS one_hour_ago;
Format: ISO 8601 (PnYnMnDTnHnMnS)
INTERVAL
Time range for overlap queries.
Storage: 24 bytes
-- Constructor
RETURN interval('[2026-01-01, 2026-01-31]') AS january;
-- Open/closed bounds
RETURN interval('[2026-01-01, 2026-02-01)') AS january_exclusive;
-- Overlap query
MATCH (e:Event)
WHERE e.duration OVERLAPS interval('[2026-01-15, 2026-01-20]')
RETURN e.name;
-- Contains
MATCH (e:Event)
WHERE interval_contains(e.duration, timestamp('2026-01-15T12:00:00Z'))
RETURN e.name;
Collection Types
LIST
Ordered collection of values.
Storage: Variable
-- Literal
RETURN [1, 2, 3, 4, 5] AS numbers;
RETURN ['apple', 'banana', 'cherry'] AS fruits;
-- Indexing (0-based)
RETURN [10, 20, 30][0] AS first; -- 10
RETURN [10, 20, 30][2] AS third; -- 30
RETURN [10, 20, 30][-1] AS last; -- 30 (negative indexing)
-- Slicing
RETURN [1, 2, 3, 4, 5][1..3] AS slice; -- [2, 3]
-- Functions
RETURN size([1, 2, 3]) AS len; -- 3
RETURN head([1, 2, 3]) AS first; -- 1
RETURN tail([1, 2, 3]) AS rest; -- [2, 3]
RETURN last([1, 2, 3]) AS final; -- 3
-- List comprehension
RETURN [x * 2 FOR x IN [1, 2, 3]] AS doubled; -- [2, 4, 6]
MAP
Key-value pairs (dictionary/object).
Storage: Variable
-- Literal
RETURN {name: 'Alice', age: 30} AS person;
-- Access
RETURN {name: 'Alice'}.name AS name; -- 'Alice'
RETURN {name: 'Alice'}['name'] AS name; -- 'Alice'
-- Keys and values
RETURN keys({a: 1, b: 2}) AS k; -- ['a', 'b']
RETURN values({a: 1, b: 2}) AS v; -- [1, 2]
-- Merge
RETURN {a: 1} + {b: 2} AS merged; -- {a: 1, b: 2}
SET
Unordered collection of unique values.
Storage: Variable
-- Constructor
RETURN set([1, 2, 2, 3, 3, 3]) AS unique; -- {1, 2, 3}
-- Operations
RETURN set_union({1, 2}, {2, 3}) AS union; -- {1, 2, 3}
RETURN set_intersect({1, 2}, {2, 3}) AS inter; -- {2}
RETURN set_difference({1, 2, 3}, {2}) AS diff; -- {1, 3}
-- Membership
RETURN 2 IN {1, 2, 3} AS contains; -- true
Vector Types
VECTOR_F32
32-bit floating-point vector for ML embeddings.
Storage: 4 bytes per dimension
-- Constructor
RETURN vectorf32('[0.1, 0.2, 0.3, 0.4]') AS v;
-- From array
RETURN vectorf32([0.1, 0.2, 0.3, 0.4]) AS v;
-- Distance functions (lower = more similar)
RETURN vector_l2(v1, v2) AS euclidean;
RETURN manhattan(v1, v2) AS l1;
RETURN distance(v1, v2, 'cosine') AS cosine_distance;
-- Similarity functions (higher = more similar)
RETURN vector_cosine(v1, v2) AS cosine_similarity;
RETURN similarity(v1, v2) AS score;
RETURN vector_dot(v1, v2) AS dot_product;
Indexing: HNSW index for approximate nearest neighbor search
CREATE INDEX doc_embedding_idx ON :Document(embedding) USING VECTOR
WITH (metric = 'cosine');
VECTOR_I32
32-bit integer vector.
Storage: 4 bytes per dimension
RETURN vectori32('[1, 2, 3, 4]') AS v;
RETURN vectori32([1, 2, 3, 4]) AS v;
Geographic Types
LATLON
Latitude/longitude coordinate pair.
Storage: 16 bytes
-- Constructor
RETURN latlon(40.7128, -74.0060) AS nyc;
-- Components
RETURN latlon(40.7128, -74.0060).latitude AS lat; -- 40.7128
RETURN latlon(40.7128, -74.0060).longitude AS lon; -- -74.0060
-- Distance (meters)
RETURN st_distance(latlon(40.7128, -74.0060),
latlon(34.0522, -118.2437)
) AS nyc_to_la;
Indexing: Spatial (R-tree) index
GEOPOINT
Generic geographic point.
Storage: 16 bytes
RETURN st_point(40.7128, -74.0060) AS point;
POLYGON
Geographic polygon (boundary).
Storage: Variable
-- Constructor from points
RETURN geometryfromtext([
latlon(40.70, -74.05),
latlon(40.70, -73.95),
latlon(40.75, -73.95),
latlon(40.75, -74.05)
]) AS manhattan;
-- Containment check
MATCH (s:Store)
WHERE st_within(s.location, $manhattan_polygon)
RETURN s.name;
Network Types
IPADDR
IPv4 or IPv6 address.
Storage: 4 bytes (IPv4) or 16 bytes (IPv6)
-- Constructor
RETURN '192.168.1.100'::ipaddr AS ip4;
RETURN '2001:db8::1'::ipaddr AS ip6;
-- Version check
RETURN ip_version('192.168.1.100'::ipaddr) AS version; -- 4
-- Subnet containment
MATCH (s:Server)
WHERE ip_contains('192.168.0.0/16'::subnet, s.ip)
RETURN s.hostname;
SUBNET
IP network in CIDR notation.
Storage: 5 bytes (IPv4) or 17 bytes (IPv6)
-- Constructor
RETURN '192.168.1.0/24'::subnet AS network;
RETURN '10.0.0.0/8'::subnet AS large_network;
-- Containment
RETURN ip_contains('10.0.0.0/8'::subnet, '10.1.2.3'::ipaddr); -- true
-- Network address
RETURN network_address('192.168.1.100/24'::subnet); -- 192.168.1.0
-- Broadcast address
RETURN broadcast_address('192.168.1.0/24'::subnet); -- 192.168.1.255
Indexing: Patricia trie for efficient prefix queries
MACADDR
MAC (hardware) address.
Storage: 6 bytes
-- Constructor
RETURN '00:1A:2B:3C:4D:5E'::macaddr AS mac;
RETURN '001A.2B3C.4D5E'::macaddr AS mac_cisco;
-- Manufacturer prefix
RETURN mac_manufacturer_prefix('00:1A:2B:3C:4D:5E'::macaddr);
Structured Types
JSON
JSON text (stored as string, parsed on access).
Storage: Variable (UTF-8 string)
-- Constructor (validates the JSON text, stores it as-is)
RETURN json('{"name": "Alice", "age": 30}') AS j;
JSON is stored as validated text and has no path accessor. Use JSONB when you
need to read individual fields server-side.
JSONB
Binary JSON (parsed and validated on insert).
Storage: Variable (binary format)
-- Constructor
RETURN jsonb('{"name": "Alice", "tags": ["a", "b"]}') AS j;
-- Path access: jsonb_get(doc, path), where path is a '$.'-rooted
-- dotted path. Array elements are addressed by numeric index.
RETURN jsonb_get(jsonb('{"name": "Alice"}'), '$.name') AS name;
RETURN jsonb_get(jsonb('{"tags": ["a", "b"]}'), '$.tags.0') AS first_tag;
-- Key existence
RETURN jsonb_exists(jsonb('{"a": 1}'), 'a'); -- true
There is no PostgreSQL-style containment (@>) operator, and -> / ->> are
not JSON accessors in GQL — -> is relationship-pattern syntax. Use
jsonb_get() and jsonb_exists().
Advantages over JSON:
- Faster queries (pre-parsed)
- Indexable with JSONB inverted index
- Supports containment operators
Identity Types
UUID
Universally Unique Identifier (128-bit).
Storage: 16 bytes
-- Generate random UUID (v4)
RETURN uuid_v4() AS id;
-- From string
RETURN '550e8400-e29b-41d4-a716-446655440000'::uuid AS id;
-- Version
RETURN uuid_v4('550e8400-e29b-41d4-a716-446655440000'::uuid); -- 4
Indexing: Hash index recommended for equality lookups
HASH
Cryptographic hash (e.g., SHA-256).
Storage: Variable (depends on algorithm)
-- Build a HASH value from a digest the client computed
RETURN hash('sha3-256', $hex_digest) AS digest;
-- Store it
CREATE (:File {
name: 'document.pdf',
digest: hash('sha3-256', $hex_digest)
});
-- Compare in constant time
MATCH (f:File)
WHERE hash_equals(f.digest, hash('sha3-256', $probe_digest))
RETURN f.name;
The engine does not compute digests — there is no sha256() or md5()
function. hash(algorithm, hex_digest) accepts sha3-256, sha3-512,
blake3, blake2b-256, blake2b-512, blake2s-256 and argon2id, and
requires a hex string of the algorithm’s digest length.
Financial Types
MONEY
Currency amount with precision.
Storage: 8 bytes + currency code
-- Constructor
RETURN currency(99.99, 'USD') AS price;
RETURN currency(1234.56, 'EUR') AS euro_amount;
-- Arithmetic (same currency only)
RETURN currency(10.00, 'USD') + currency(5.50, 'USD') AS total;
-- Currency code
RETURN currency(99.99, 'USD').currency AS code; -- 'USD'
Type Conversion Reference
Explicit Conversion Functions
| From | To | Function | Example |
|---|---|---|---|
| STRING | INTEGER | toInteger() | toInteger('42') |
| STRING | FLOAT | toFloat() | toFloat('3.14') |
| STRING | BOOLEAN | toBoolean() | toBoolean('true') |
| * | STRING | toString() | toString(42) |
| FLOAT | INTEGER | toInteger() | toInteger(3.7) (truncates to 3) |
| INTEGER | FLOAT | toFloat() | toFloat(42) |
| LIST | SET | set() | set([1,1,2]) |
Implicit Type Promotion
| Operation | Result Type |
|---|---|
| INTEGER + INTEGER | INTEGER |
| INTEGER + FLOAT | FLOAT |
| FLOAT + FLOAT | FLOAT |
| INTEGER * FLOAT | FLOAT |
| INTEGER / INTEGER | INTEGER (truncates) |
| INTEGER / FLOAT | FLOAT |
Type Checking Functions
RETURN type(value) AS type_name;
RETURN value IS INTEGER AS is_int;
RETURN value IS STRING AS is_string;
RETURN value IS NULL AS is_null;
Type-to-Index Mapping
| Type | Recommended Index | Operations Supported |
|---|---|---|
| INTEGER, STRING | B-tree | =, <, >, <=, >=, BETWEEN |
| INTEGER, STRING | Hash | = (equality only) |
| STRING (text) | Full-text | Text search, BM25 |
| JSONB | JSONB inverted | Path queries |
| VECTOR_F32/I32 | HNSW | Similarity search |
| LATLON, GEOPOINT | Spatial | Distance, containment |
| IPADDR, SUBNET | Patricia trie | Prefix, containment |
| INTERVAL | Interval tree | Overlap queries |
Related Documentation
- Data Model and Types - Schema design guide
- Type Conversion - Detailed conversion rules
- Index Types Reference - Indexing by type
- Operators Reference - Type-compatible operators
Last Updated: January 28, 2026 Geode Version: v0.8.14+ Type Count: 50+ specialized types