Overview
Geode implements comprehensive type conversion functions as specified in the ISO/IEC 39075:2024 GQL standard. These functions enable safe type casting, type introspection, and data transformation for robust query operations.
Supported Functions
| Function | Purpose | Input Types | Output Type |
|---|---|---|---|
type() | Return type name | Any | STRING |
toString() | Convert to string | Any | STRING |
toInteger() | Convert to integer | String, Numeric | INTEGER |
toReal() | Convert to real number | String, Numeric | DECIMAL |
type() Function
Description
Returns the data type name of any value as a string.
Syntax
type(value) → STRING
Parameters
- value: Any GQL value (required)
Return Value
String representation of the value’s type according to GQL type system.
Type Names
| GQL Type | Returned String |
|---|---|
| Integer | "INTEGER" |
| Decimal/Float | "DECIMAL" |
| String | "STRING" |
| Boolean | "BOOLEAN" |
| Null | "NULL" |
| Date | "DATE" |
| Time | "TIME" |
| DateTime | "DATETIME" |
| Duration | "DURATION" |
| List | "LIST" |
| Map | "MAP" |
| Node | "NODE" |
| Relationship | "RELATIONSHIP" |
| Path | "PATH" |
Examples
Basic Types:
RETURN type(123) -- "INTEGER"
RETURN type('hello') -- "STRING"
RETURN type(123.45) -- "DECIMAL"
RETURN type(true) -- "BOOLEAN"
RETURN type(null) -- "NULL"
Temporal Types:
RETURN type(date('2026-01-24')) -- "DATE"
RETURN type(time('10:30:15')) -- "TIME"
RETURN type(datetime('2026-01-24T10:30:15')) -- "DATETIME"
RETURN type(duration('PT1H30M')) -- "DURATION"
Collection Types:
RETURN type([1, 2, 3]) -- "LIST"
RETURN type({name: 'Alice', age: 30}) -- "MAP"
Graph Types:
MATCH (n:Person)
RETURN type(n) -- "NODE"
MATCH ()-[r:KNOWS]->()
RETURN type(r) -- "RELATIONSHIP"
MATCH p = (:Person)-[:KNOWS*]->(:Person)
RETURN type(p) -- "PATH"
Use Cases
Runtime Type Checking:
-- Conditional logic based on type
MATCH (n)
RETURN n,
CASE type(n.value)
WHEN 'INTEGER' THEN 'Numeric value'
WHEN 'STRING' THEN 'Text value'
ELSE 'Other type'
END AS value_category
Type Validation:
-- Find nodes with unexpected property types
MATCH (p:Product)
WHERE type(p.price) <> 'DECIMAL'
RETURN p.id, type(p.price) AS wrong_type, p.price
Schema Discovery:
-- Discover property types in graph
MATCH (n:User)
UNWIND keys(n) AS prop_name
WITH prop_name, n[prop_name] AS prop_value
RETURN DISTINCT prop_name, type(prop_value) AS prop_type
ORDER BY prop_name
toString() Function
Description
Converts any value to its string representation.
Syntax
toString(value) → STRING
Parameters
- value: Any GQL value (required)
Return Value
String representation of the input value, or null if conversion fails.
Conversion Rules
| Input Type | Output Example |
|---|---|
| Integer | toString(123) → "123" |
| Decimal | toString(123.45) → "123.450000" |
| Boolean | toString(true) → "true" |
| String | toString("hello") → "hello" |
| Null | toString(null) → "null" |
| Date | toString(date('2026-01-24')) → "2026-01-24" |
| DateTime | toString(datetime(...)) → "2026-01-24T10:30:15Z" |
| List | toString([1,2,3]) → "[1, 2, 3]" |
| Map | toString({a:1}) → "{a: 1}" |
Examples
Basic Conversion:
RETURN toString(123) -- "123"
RETURN toString(true) -- "true"
RETURN toString(null) -- "null"
RETURN toString(123.45) -- "123.450000"
Temporal Values:
RETURN toString(date('2026-01-24'))
-- "2026-01-24"
RETURN toString(datetime('2026-01-24T10:30:15'))
-- "2026-01-24T10:30:15Z"
RETURN toString(duration('PT1H30M'))
-- "PT1H30M"
Collection Values:
RETURN toString([1, 2, 3, 4, 5])
-- "[1, 2, 3, 4, 5]"
RETURN toString({name: 'Alice', age: 30})
-- "{name: 'Alice', age: 30}"
Use Cases
String Concatenation:
-- Build formatted strings
MATCH (p:Person)
RETURN 'Person #' + toString(p.id) + ': ' + p.name AS label
Export Formatting:
-- Format data for export
MATCH (o:Order)
RETURN toString(o.created_date) + ',' +
toString(o.id) + ',' +
toString(o.total) AS csv_row
Logging & Debugging:
-- Convert values for logging
MATCH (n)
WHERE n.updated_at > datetime().subtract(PT1H)
RETURN 'Updated: ' + toString(n.id) + ' at ' + toString(n.updated_at) AS log_entry
toInteger() Function
Description
Converts strings and numeric values to integers with overflow protection.
Syntax
toInteger(value) → INTEGER | NULL
Parameters
- value: String or numeric value (required)
Return Value
Integer value, or null if conversion fails or value is invalid.
Conversion Rules
| Input | Output | Notes |
|---|---|---|
| String (valid) | Integer | toInteger('456') → 456 |
| String (invalid) | null | toInteger('abc') → null |
| Decimal | Integer | toInteger(123.7) → 123 (truncated) |
| Integer | Integer | toInteger(123) → 123 (unchanged) |
| Boolean | null | toInteger(true) → null |
| Null | null | toInteger(null) → null |
| Overflow | null | Value too large → null |
Examples
String Conversion:
RETURN toInteger('456') -- 456
RETURN toInteger('123.45') -- 123 (decimal part ignored)
RETURN toInteger('abc') -- null (invalid format)
RETURN toInteger('') -- null (empty string)
Numeric Conversion:
RETURN toInteger(123) -- 123
RETURN toInteger(123.7) -- 123 (truncated, not rounded)
RETURN toInteger(123.999) -- 123 (truncated)
RETURN toInteger(-456.789) -- -456
Edge Cases:
RETURN toInteger(null) -- null
RETURN toInteger(' 123 ') -- 123 (whitespace trimmed)
RETURN toInteger('+456') -- 456 (plus sign allowed)
RETURN toInteger('-789') -- -789 (negative numbers)
Overflow Protection
Safe Range (64-bit signed integer):
- Minimum:
-9,223,372,036,854,775,808 - Maximum:
9,223,372,036,854,775,807
Overflow Behavior:
RETURN toInteger('9999999999999999999999') -- null (overflow)
RETURN toInteger('-9999999999999999999999') -- null (underflow)
Use Cases
User Input Processing:
-- Convert user input to integer
WITH '42' AS user_input
MATCH (p:Product)
WHERE p.id = toInteger(user_input)
RETURN p.name
Data Cleaning:
-- Clean imported data
MATCH (n:ImportedData)
WHERE n.count_str IS NOT NULL
SET n.count = toInteger(n.count_str)
Pagination:
-- Convert pagination parameters
WITH '10' AS page_size_param, '2' AS page_num_param
MATCH (n:Article)
RETURN n
SKIP toInteger(page_size_param) * (toInteger(page_num_param) - 1)
LIMIT toInteger(page_size_param)
toReal() Function
Description
Converts values to floating-point numbers (returned as DECIMAL type).
Syntax
toReal(value) → DECIMAL | NULL
Parameters
- value: String or numeric value (required)
Return Value
Decimal value, or null if conversion fails.
Conversion Rules
| Input | Output | Notes |
|---|---|---|
| String (valid) | Decimal | toReal('123.45') → 123.450000 |
| String (invalid) | null | toReal('abc') → null |
| Integer | Decimal | toReal(123) → 123.000000 |
| Decimal | Decimal | toReal(123.45) → 123.450000 |
| Scientific | Decimal | toReal('1.5e2') → 150.000000 |
| Null | null | toReal(null) → null |
Examples
String Conversion:
RETURN toReal('123.45') -- 123.450000
RETURN toReal('456') -- 456.000000
RETURN toReal('1.5e2') -- 150.000000 (scientific notation)
RETURN toReal('abc') -- null (invalid format)
Numeric Conversion:
RETURN toReal(123) -- 123.000000
RETURN toReal(123.45) -- 123.450000
RETURN toReal(-456.789) -- -456.789000
Scientific Notation:
RETURN toReal('1.23e-4') -- 0.000123
RETURN toReal('5.67E+3') -- 5670.000000
RETURN toReal('2.5e10') -- 25000000000.000000
Precision
Default Precision: 6 decimal places
Range:
- Minimum: Approximately
-1.7976931348623157e+308 - Maximum: Approximately
1.7976931348623157e+308
Use Cases
Financial Calculations:
-- Convert price strings to decimals
MATCH (p:Product)
WHERE p.price_str IS NOT NULL
SET p.price = toReal(p.price_str)
Statistical Analysis:
-- Calculate averages from string data
MATCH (m:Metric)
WITH toReal(m.value_str) AS value
WHERE value IS NOT NULL
RETURN avg(value) AS average_value
Percentage Calculations:
-- Convert percentage strings to decimals
MATCH (s:Sale)
SET s.discount_rate = toReal(s.discount_percent_str) / 100.0
Type Conversion Compatibility
Conversion Matrix
| From ↓ / To → | STRING | INTEGER | DECIMAL | BOOLEAN | DATE |
|---|---|---|---|---|---|
| STRING | ✓ | ✓ | ✓ | ✗ | ✗ |
| INTEGER | ✓ | ✓ | ✓ | ✗ | ✗ |
| DECIMAL | ✓ | ✓ (truncate) | ✓ | ✗ | ✗ |
| BOOLEAN | ✓ | ✗ | ✗ | ✓ | ✗ |
| DATE | ✓ | ✗ | ✗ | ✗ | ✓ |
| NULL | ✓ ("null") | null | null | null | null |
Legend:
- ✓ : Supported conversion
- ✗ : Not supported (returns
null)
Safe Conversion Patterns
Check Before Convert:
-- Validate before conversion
MATCH (n)
WHERE n.value IS NOT NULL
AND type(n.value) IN ['STRING', 'INTEGER', 'DECIMAL']
WITH toInteger(n.value) AS int_value
WHERE int_value IS NOT NULL
RETURN int_value
Provide Defaults:
-- Use COALESCE for default values
MATCH (n)
RETURN coalesce(toInteger(n.value), 0) AS value_or_default
Chain Conversions:
-- Convert through intermediate types
MATCH (n)
WITH toString(n.id) AS id_str
RETURN 'ID: ' + id_str AS formatted_id
Common Patterns
Data Import
-- Import CSV data with type conversion
LOAD CSV FROM 'data.csv' AS row
CREATE (p:Product {
id: toInteger(row.id),
name: row.name,
price: toReal(row.price),
in_stock: row.in_stock = 'true',
created_date: date(row.created_date)
})
Data Validation
-- Find invalid data
MATCH (p:Product)
WHERE toReal(p.price_str) IS NULL
AND p.price_str IS NOT NULL
RETURN p.id, p.price_str AS invalid_price
Type-Safe Aggregations
-- Aggregate with type conversion
MATCH (m:Metric)
WITH toReal(m.value) AS numeric_value
WHERE numeric_value IS NOT NULL
RETURN avg(numeric_value) AS average,
max(numeric_value) AS maximum,
min(numeric_value) AS minimum
String Formatting
-- Build formatted reports
MATCH (s:Sale)
RETURN 'Sale #' + toString(s.id) +
' on ' + toString(date(s.created_date)) +
' for $' + toString(s.amount) AS summary
Known Limitations
Property Access
Current Issue: Property access within function calls may return null
-- This may not work as expected
MATCH (n:Person)
RETURN toString(n.name) -- May return null
-- Workaround: Use WITH clause
MATCH (n:Person)
WITH n.name AS name
RETURN toString(name) -- Works correctly
Status: Known issue, targeted for future improvement
Type Function Context
The type() function has dual semantics in GQL:
Graph Element Type (relationship labels):
MATCH ()-[r]->() RETURN type(r) -- Returns relationship type nameValue Data Type (our implementation):
RETURN type(123) -- Returns "INTEGER"
Current: Works with literals, limited property support
Testing
Unit Tests
# Run type conversion tests
zig test tests/test_type_conversion.zig
# Regression tests
./tests/type_conversion_functions_regression_test.sh
Test Coverage
Tested Scenarios:
- ✓ All basic types (INTEGER, STRING, DECIMAL, BOOLEAN, NULL)
- ✓ Temporal types (DATE, TIME, DATETIME, DURATION)
- ✓ Collection types (LIST, MAP)
- ✓ Graph types (NODE, RELATIONSHIP, PATH)
- ✓ Edge cases (overflow, underflow, invalid formats)
- ✓ Null handling
- ✓ Whitespace trimming
- ✓ Scientific notation
Example Tests
-- Basic function tests
RETURN toString(123) = '123' -- true
RETURN toInteger('456') = 456 -- true
RETURN toReal('123.45') = 123.45 -- true
RETURN type(123) = 'INTEGER' -- true
-- Edge case tests
RETURN toInteger('abc') IS NULL -- true
RETURN toReal('invalid') IS NULL -- true
RETURN toInteger(' 123 ') = 123 -- true (whitespace)
Performance
Benchmark Results
toString():
- Overhead: <1μs per conversion
- Throughput: >1M conversions/second
- Memory: Allocates new string (minimal)
toInteger():
- Efficient parsing for valid integers
- Format validation
- Returns null on invalid input
toReal():
- Handles decimal and scientific notation
- Precision: 6 decimal places (standard)
type():
- Constant time type lookup
- Cached string literals for common types
Best Practices
Type Safety
Always Validate:
-- Check conversion success WITH toInteger(user_input) AS value WHERE value IS NOT NULL RETURN valueProvide Defaults:
-- Use COALESCE for safety RETURN coalesce(toInteger(n.value), 0)Type Check First:
-- Verify type before conversion WHERE type(n.value) IN ['STRING', 'INTEGER']
Error Handling
Production Pattern:
-- Comprehensive error handling
MATCH (n:Data)
WITH n,
toInteger(n.count_str) AS count_int,
toReal(n.price_str) AS price_real
WHERE count_int IS NOT NULL AND price_real IS NOT NULL
RETURN n.id, count_int, price_real
Logging Invalid Data:
-- Track conversion failures
MATCH (n:ImportedData)
WITH n, toInteger(n.value) AS int_value
WHERE n.value IS NOT NULL AND int_value IS NULL
CREATE (e:ConversionError {
entity_id: n.id,
field: 'value',
attempted_value: n.value,
error_time: datetime()
})
References
Standards
- ISO/IEC 39075:2024: GQL Type System and Type Conversion
- Section on scalar type functions
- Type compatibility matrix
Code Location
- Implementation:
src/types/evaluator_functions.zig - Registration:
src/eval.zig - Tests:
tests/type_conversion_functions_regression_test.sh - Documentation:
docs/TYPE_CONVERSION_FUNCTIONS.md
Related Documentation
- Data Types Reference - Complete type system
- GQL Functions - All built-in functions
- Type System - Data model overview
Next Steps
For New Users:
- Data Types Overview - Type system fundamentals
- GQL Guide - Query language basics
- Quick Reference - Command reference
For Developers:
- API Reference - Complete function reference
- Testing Strategies - Type validation testing
- Client Libraries - Type handling in clients
Document Version: 1.0 Last Updated: January 24, 2026 Status: Production Ready ISO Compliance: ISO/IEC 39075:2024 GQL Type System CANARY: REQ-GQL-TYPE-CONV-001 (TESTED)