Reference

Comprehensive technical reference documentation for Geode covering all APIs, commands, error codes, operators, and specifications.

Overview

This section provides detailed reference material for developers, operators, and administrators working with Geode. Unlike guides that focus on how-to instructions, reference documentation provides exhaustive, structured information about every command, function, operator, and error code.

Use this section when you need precise details about specific functionality, error messages, or command syntax. All reference material is organized for quick lookup and includes complete specifications.

Topics in This Section

  • Complete API Reference - Comprehensive API documentation covering all functions, methods, and interfaces
  • CLI and API - Command-line interface reference including all CLI commands and options
  • DSN Specification - Official DSN format for QUIC/gRPC connection strings
  • Data Types - All 50+ data types with constructors and storage characteristics
  • Index Types - B-tree, Hash, Full-text, Spatial, Vector, and specialized indexes
  • Statistics and Metrics - Query statistics, storage metrics, and Prometheus integration
  • Error Codes - Complete error code reference with descriptions and resolution steps
  • Status Codes - GQL status codes following ISO/IEC 39075:2024 standard
  • Operators - All supported operators including comparison, arithmetic, logical, and pattern operators
  • Type Conversion - Type conversion rules, coercion, and promotion specifications
  • Unicode Support - Unicode normalization, collation, and string handling
  • Changelog - Version history with detailed changes, features, and bug fixes

Quick Reference

Common Functions

Aggregation Functions:

COUNT(*), COUNT(expr)
SUM(expr), AVG(expr)
MIN(expr), MAX(expr)

String Functions:

lower(str), upper(str)
substring(str, start, length)
trim(str), ltrim(str), rtrim(str)

Temporal Functions:

now(), timestamp()
date('2024-01-01')
duration({days: 7})

Spatial Functions:

distance(point1, point2)
point({latitude: 47.6, longitude: -122.3})

See API Reference for complete function list.

Common Operators

Comparison:

=, <>, <, <=, >, >=
IS NULL, IS NOT NULL
IN, NOT IN

Arithmetic:

+, -, *, /, %

Logical:

AND, OR, NOT, XOR

Pattern:

STARTS WITH, ENDS WITH, CONTAINS
=~  -- Regular expression match

See Operators for complete reference.

CLI Commands

Server Management:

geode serve              # Start server
geode shell              # Interactive shell
geode --version          # Show version

Client Operations:

geode query "query"      # Execute query
geode query -f file.gql  # Execute file
geode query --format json "RETURN 1"  # JSON output

Administration:

geode backup             # Create backup
geode restore            # Restore backup
geode validate           # Validate data

See CLI and API for complete CLI reference.

Error Code Categories

Client Errors (4xxxx)

Errors caused by client requests:

  • 40001: Syntax error in query
  • 40002: Semantic error (invalid operation)
  • 40003: Parameter mismatch
  • 40004: Constraint violation

Server Errors (5xxxx)

Errors caused by server issues:

  • 50001: Internal server error
  • 50002: Storage error
  • 50003: Network error
  • 50004: Resource exhausted

Security Errors (6xxxx)

Authentication and authorization errors:

  • 60001: Authentication failed
  • 60002: Authorization denied
  • 60003: Session expired
  • 60004: Invalid credentials

See Error Codes for complete list with resolution steps.

Status Codes (ISO GQL)

GQL status codes following ISO/IEC 39075:2024:

  • 00000: Successful completion
  • 01xxx: Warning conditions
  • 02xxx: No data (query returned empty)
  • 22xxx: Data exception
  • 23xxx: Integrity constraint violation
  • 42xxx: Syntax error or access violation

See Status Codes for ISO compliance details.

Type System Reference

Core Types 

NULL
BOOLEAN
INTEGER
FLOAT
STRING
BYTES

Temporal Types 

DATE
TIME
TIMESTAMP
ZONED_DATETIME
DURATION
INTERVAL

Collection Types 

LIST<T>
MAP<K, V>
SET<T>

Advanced Types 

VECTOR<T>
POINT
POLYGON
UUID
JSON
BIGDECIMAL
MONEY
CIDR

See Type Conversion for conversion rules.

Unicode Support

Geode provides comprehensive Unicode support:

  • Normalization: NFD, NFC, NFKD, NFKC
  • Collation: Locale-aware string comparison
  • Case Folding: Unicode case-insensitive comparison
  • Grapheme Clusters: Proper string length and indexing

See Unicode Support for details.

Version Information

Current version: v0.1.3 (Production Ready)

Key metrics:

  • Test Coverage: 97.4% (1,644/1,688 tests passing)
  • GQL Compliance: see conformance profile
  • CANARY Markers: 1,735 tracking 2,190+ requirements

See Changelog for version history.

API Categories

Query Execution API

Execute GQL queries programmatically:

// Go client example
result, err := client.Query(ctx, "MATCH (n) RETURN n LIMIT 10")

# Python client example
from geode_client import Client

client = Client(host="localhost", port=3141)
async with client.connection() as conn:
    page, _ = await conn.query("MATCH (n) RETURN n LIMIT 10")
    for row in page.rows:
        print(row)

Transaction API

Manage transactions:

tx, err := db.BeginTx(ctx, nil)
if err != nil {
    return err
}
defer tx.Rollback()

_, err = tx.ExecContext(ctx, "CREATE (:Person {name: 'Alice'})")
if err != nil {
    return err
}
return tx.Commit()

Schema API

Manage indexes and constraints:

-- Index management
CREATE INDEX person_email ON :Person(email);
DROP INDEX person_email;

-- Constraint management
CREATE CONSTRAINT person_email_unique
FOR (p:Person)
REQUIRE p.email IS UNIQUE;

Security API

Authentication and authorization:

from geode_client import AuthClient, Client

client = Client(host="localhost", port=3141)
async with client.connection() as conn:
    auth = AuthClient(conn)
    session = await auth.login("admin", "secret")
    print(session.token)

See API Reference for complete API documentation.

Command-Line Interface

Server Commands 

# Start server
geode serve [OPTIONS]
  --listen <address>       # Listen address (default: 127.0.0.1:3141)
  --data-dir <path>        # Data directory
  --cert <path>            # TLS certificate
  --key <path>             # TLS key
  --config <path>          # Configuration file

# Interactive shell
geode shell [OPTIONS]
  --connect <uri>          # Server URI
  --format <txt|json>      # Output format
  --file <path>            # Execute script

Client Commands 

# Execute query
geode query [OPTIONS] <query>
  -f, --file <path>        # Execute from file
  --format <txt|json>      # Output format
  --params <json>          # Query parameters

# Examples
geode query "RETURN 1 AS x"
geode query -f queries.gql --format json
geode query "MATCH (n) WHERE n.id = \$id RETURN n" --params '{"id": 123}'

See CLI and API for complete command reference.

Configuration Reference

Key configuration options:

server:
  listen: '0.0.0.0:3141'
  data_dir: '/var/lib/geode'

tls:
  cert: '/etc/geode/certs/server-cert.pem'
  key: '/etc/geode/certs/server-key.pem'

storage:
  page_size: 8192
  page_cache_size: '16GB'

query:
  max_concurrent_queries: 1000
  query_timeout: 30s

security:
  tde:
    enabled: true
    key_hex: '<32-byte-hex-key>'

logging:
  level: 'info'
  format: 'json'

See Configuration Reference for all options.

Protocol Specification

Protobuf Wire Protocol

Geode uses length-prefixed Protobuf messages over QUIC (default) or gRPC. The full schema is defined in src/proto/geode.proto.

Client Messages:

  • HelloRequest / PingRequest
  • ExecuteRequest (RUN_GQL)
  • PullRequest
  • BeginRequest / CommitRequest / RollbackRequest

Server Responses:

  • HelloResponse
  • ExecutionResponse (payloads: SchemaDefinition, DataPage, Error, ExplainPayload, ProfilePayload)

See Wire Protocol for the full specification.

  • PROFILE: Performance metrics

Performance Characteristics

Reference performance metrics:

Query Performance:

  • Point lookup: <1ms (typically 100-500us)
  • Short path (1-2 hops): 1-5ms
  • Multi-hop path (3-5 hops): 10-100ms
  • Large aggregation (1M rows): 100-500ms

Architecture:

  • Vector similarity: HNSW indexes with SIMD acceleration
  • Storage: Memory-mapped I/O with page-level caching
  • Indexes: Six specialized index types for different workloads

Scalability:

  • Distributed deployment with up to 32 shards
  • Connection pooling for concurrent clients

See Performance Benchmarking for methodology.

Standards Compliance

ISO/IEC 39075:2024 (GQL)

  • ✅ Complete pattern matching syntax
  • ✅ All aggregation functions
  • ✅ Set operations (UNION, INTERSECT, EXCEPT)
  • ✅ Transaction semantics
  • ✅ Error handling with standard codes
  • ✅ 100% compliance; see conformance profile

Other Standards

  • QUIC: RFC 9000
  • TLS 1.3: RFC 8446
  • JSON: RFC 8259
  • UUID: RFC 4122
  • IPv6: RFC 4291
  • CIDR: RFC 4632

Learn More

Contributing to Documentation

Found an error or want to improve the reference docs?

See Contributing Guide for how to submit improvements.

Pages

Complete GQL API Reference

Comprehensive API reference for Geode's GQL implementation including all keywords, functions, data types, operators, and procedures with detailed examples.

16 min read

API Reference and CLI Manual

Command-line reference for `geode` (with geoded/geodec compatibility) and the full Geode GQL surface: keywords, functions, types, procedures, and operational commands

5 min read

DSN (Data Source Name) Specification

Official DSN format for connecting to Geode over QUIC or gRPC, including authentication and TLS options

3 min read

GQL Operators Reference

Complete reference for all GQL operators in Geode including arithmetic, logical, comparison, string, and advanced operators with precedence rules and examples.

14 min read

Index Types Reference

Complete reference for all index types in Geode including B-tree, Hash, Full-text, Spatial, Vector (HNSW), and specialized indexes with configuration options and performance characteristics

10 min read

Data Types Reference

Complete reference for all 50+ data types in Geode including core types, temporal types, collection types, vector types, geographic types, and specialized types with constructors and conversion rules

10 min read

Statistics and Metrics Reference

Complete reference for Geode statistics, metrics, and monitoring including query statistics, storage metrics, index statistics, and Prometheus integration

8 min read

Error Codes Reference

Complete reference for Geode error codes, GQLSTATUS codes, and troubleshooting guidance following ISO/IEC SQL standards

11 min read

ISO GQL Status Codes Reference

Complete reference for ISO GQL status codes and error handling in Geode, including error categories, handling strategies, and troubleshooting guide

14 min read

Changelog

Complete version history and release notes for Geode graph database with breaking changes, new features, and migration guides

10 min read

Type Conversion Functions

Complete reference for GQL type conversion functions in Geode including toString, toInteger, toReal, and type introspection with ISO standard compliance.

9 min read

Unicode Support and Text Processing

Comprehensive Unicode support in Geode including NFC normalization, case folding, UTF-8/UTF-16 conversion, and international text processing capabilities.

10 min read