API Reference

Complete reference documentation for Geode’s query language, functions, operators, and system procedures.

Index Operations

CREATE INDEX

Creates an index on node properties for improved query performance.

Syntax:

CREATE [UNIQUE] INDEX [IF NOT EXISTS] index_name
ON label(property[, ...])
[USING {btree | hash | fulltext | spatial | vector}]

Index Types:

  • btree (Default) - B-tree index for range queries and sorted access
  • hash - Hash index for exact match lookups
  • fulltext - Full-text search with tokenization and ranking
  • spatial - R-tree index for geographic and spatial data
  • vector - HNSW index for vector similarity search
  • patricia_trie - IP prefix matching and CIDR queries

Examples:

-- B-tree index for range queries
CREATE INDEX person_age_idx ON Person(age) USING btree;

-- Hash index for exact matches
CREATE INDEX person_email_idx ON Person(email) USING hash;

-- Full-text search index
CREATE INDEX article_content_idx ON Article(content) USING fulltext;

-- Spatial index for geographic queries
CREATE INDEX location_coords_idx ON Location(coordinates) USING spatial;

-- Vector index for similarity search
CREATE INDEX embedding_idx ON Document(embedding) USING vector;

-- Unique constraint
CREATE UNIQUE INDEX person_email_unique ON Person(email);

DROP INDEX

Removes an existing index.

Syntax:

DROP INDEX [IF EXISTS] index_name

Example:

DROP INDEX IF EXISTS person_age_idx;

SHOW INDEXES

Lists all indexes in the database.

Syntax:

SHOW INDEXES;

Returns:

  • Index name
  • Label
  • Properties
  • Type (btree, hash, fulltext, spatial, vector)
  • Unique constraint
  • Statistics (entries, size, last updated)

Variable-Length Path Patterns

Path Pattern Syntax 

(start)-[relationship*min..max]->(end)

Patterns

Any Length (*):

MATCH (a:Person)-[*]->(b:Company) RETURN b;

Exact Length (*n):

MATCH (a:Person)-[*2]->(b:Person) RETURN b;

Range (*min..max):

MATCH (a:Person)-[*1..3]->(b:Person) RETURN b;

Up To (*..max):

MATCH (a:Person)-[*..5]->(b:Person) RETURN b;

At Least (*min..):

MATCH (a:Person)-[*2..]->(b:Person) RETURN b;

Path Functions

length(path) - Returns path length:

MATCH path = (a)-[*]->(b) RETURN length(path);

nodes(path) - Returns all nodes in path:

MATCH path = (a)-[*]->(b) RETURN nodes(path);

relationships(path) - Returns all relationships in path:

MATCH path = (a)-[*]->(b) RETURN relationships(path);

shortestPath() - Finds shortest path:

MATCH path = shortestPath((a:Person)-[*]->(b:Company))
RETURN path;

allShortestPaths() - Finds all shortest paths:

MATCH path = allShortestPaths((a:Person)-[*]->(b:Company))
RETURN path;

Vector Operations

Vector Search Functions

similarity(vector1, vector2) - Calculates similarity (0-1, higher is more similar):

MATCH (d:Document)
WHERE similarity(d.embedding, VectorF32('[0.1, 0.2, 0.3]')) > 0.8
RETURN d;

distance(vector1, vector2, metric) - Calculates distance using specified metric:

MATCH (d:Document)
WHERE distance(d.embedding, VectorF32('[0.1, 0.2, 0.3]'), 'l2') < 0.5
RETURN d;

Supported Metrics:

  • 'l2' - Euclidean distance
  • 'cosine' - Cosine distance (1 - cosine similarity)
  • 'dot' - Negative dot product
  • 'manhattan' - L1 distance
  • 'hamming' - Hamming distance (integer vectors)
  • 'jaccard' - Jaccard distance (set similarity)

knn(property, query_vector, k) - Returns k nearest neighbors:

MATCH (d:Document)
WITH d, knn(d.embedding, VectorF32('[0.1, 0.2, 0.3]'), 10) AS neighbors
RETURN neighbors;

cosineSimilarity(v1, v2) - Cosine similarity [-1, 1]:

MATCH (d:Document)
RETURN d.title, cosineSimilarity(d.embedding, VectorF32('[0.1, 0.2, 0.3]')) AS similarity
ORDER BY similarity DESC;

dotProduct(v1, v2) - Dot product:

RETURN dotProduct(VectorF32('[1, 2, 3]'), VectorF32('[4, 5, 6]')) AS dot;

norm(vector) - L2 norm (magnitude):

RETURN norm(VectorF32('[3, 4]')) AS magnitude;  -- Returns 5.0

normalize(vector) - Unit vector normalization:

MATCH (d:Document)
SET d.embedding = normalize(d.embedding);

Spatial Operations

Spatial Functions

LatLon(string) - Creates geographic coordinate:

CREATE (l:Location {coords: LatLon('40.7128,-74.0060'), name: 'NYC'});

distanceKm(point1, point2) - Haversine distance in kilometers:

MATCH (l:Location)
WHERE distanceKm(l.coords, LatLon('40.0,-74.0')) < 100
RETURN l;

bearingTo(point1, point2) - Initial bearing in degrees [0, 360):

MATCH (a:Location), (b:Location)
RETURN bearingTo(a.coords, b.coords) AS bearing;

within(geometry, boundary) - Tests if geometry is within boundary:

MATCH (l:Location)
WHERE within(l.coords, polygon(...))
RETURN l;

bbox(min_x, min_y, max_x, max_y) - Creates bounding box:

MATCH (l:Location)
WHERE intersects(l.area, bbox(40.0, -75.0, 41.0, -73.0))
RETURN l;

Full-Text Search

Text Search Functions

CONTAINS - Searches for text within property:

MATCH (a:Article)
WHERE a.content CONTAINS 'graph database'
RETURN a;

STARTS WITH - Matches text at beginning:

MATCH (p:Person)
WHERE p.name STARTS WITH 'John'
RETURN p;

ENDS WITH - Matches text at end:

MATCH (e:Email)
WHERE e.address ENDS WITH '@example.com'
RETURN e;

REGEX - Matches using regular expressions:

MATCH (p:Product)
WHERE p.code =~ '^SKU-[0-9]{4}$'
RETURN p;

score() - Returns relevance score for full-text results:

MATCH (a:Article)
WHERE a.content CONTAINS 'machine learning'
RETURN a, score() AS relevance
ORDER BY relevance DESC;

Aggregation Functions

Basic Aggregations

count() - Count rows:

MATCH (n:Person) RETURN count(*) AS total;
MATCH (n:Person) RETURN count(n.email) AS with_email;

sum() - Sum values:

MATCH (o:Order) RETURN sum(o.total) AS revenue;

avg() - Average value:

MATCH (p:Person) RETURN avg(p.age) AS average_age;

min() - Minimum value:

MATCH (p:Product) RETURN min(p.price) AS cheapest;

max() - Maximum value:

MATCH (p:Product) RETURN max(p.price) AS most_expensive;

Collection Functions

collect() - Collect values into array:

MATCH (p:Person)-[:KNOWS]->(f)
RETURN p.name, collect(f.name) AS friends;

collect(DISTINCT) - Collect unique values:

MATCH (p:Person)
RETURN p.city, collect(DISTINCT p.country) AS countries;

Transaction Control

BEGIN

Starts a new transaction:

BEGIN;

COMMIT

Commits the current transaction:

COMMIT;

ROLLBACK

Rolls back the current transaction:

ROLLBACK;

SAVEPOINT

Creates a savepoint within a transaction:

SAVEPOINT my_savepoint;

ROLLBACK TO

Rolls back to a specific savepoint:

ROLLBACK TO my_savepoint;

System Functions

Database Information

db.info() - Returns database information:

RETURN db.info();

db.stats() - Returns database statistics:

RETURN db.stats();

db.indexes() - Returns index information:

RETURN db.indexes();

db.constraints() - Returns constraint information:

RETURN db.constraints();

Temporal Functions

now() - Current timestamp with microseconds:

RETURN now() AS current_time;

current_date - Today’s date:

RETURN current_date AS today;

current_time - Current time:

RETURN current_time AS now;

date_add(date, interval) - Add interval to date:

RETURN date_add(Date('2024-01-01'), Interval('P1M')) AS next_month;

date_sub(date, interval) - Subtract interval:

RETURN date_sub(now(), Interval('P7D')) AS week_ago;

date_part(part, datetime) - Extract date/time part:

RETURN date_part('year', now()) AS current_year;

Type Conversion Functions

to_int(value) - Convert to integer:

RETURN to_int('42') AS num;

to_float(value) - Convert to float:

RETURN to_float('3.14') AS pi;

to_string(value) - Convert to string:

RETURN to_string(42) AS str;

to_boolean(value) - Convert to boolean:

RETURN to_boolean('true') AS bool;

Type Constructors

Numeric Types 

SmallInt(42)           -- i16
Int(1000)              -- i32
BigInt(9999999)        -- i64
Real(3.14)             -- f32
Double(3.14159)        -- f64
Decimal(123.45, 2)     -- Decimal with scale

String Types 

Char('Hello', 10)      -- Fixed length
Varchar('World', 50)   -- Variable length
Text('Long text...')   -- Unlimited

Temporal Types 

Date('2024-12-25')
Time('14:30:00.123456')
TimeTZ('14:30:00', -28800)
Timestamp('2024-12-25 14:30:00')
TimestampTZ('2024-12-25 14:30:00 -08:00')
Interval('P1Y2M3DT4H5M6S')

Network Types 

IpAddr('192.168.1.1')
IpAddr('2001:db8::1')
Subnet('192.168.0.0/24')
Mac('00:11:22:33:44:55')

Geographic Types 

LatLon('40.7128,-74.0060')
LatLonAlt('40.7128,-74.0060,100.0')
GeoPoint('37.7749,-122.4194')

Vector Types 

VectorF32('[1.0, 2.0, 3.0]')
VectorI32('[1, 2, 3]')

Advanced Types 

UUID('550e8400-e29b-41d4-a716-446655440000')
Json('{"key": "value"}')
Jsonb('{"key": "value"}')
Xml('<root><child/></root>')
Bytea('\\xDEADBEEF')
URL('https://example.com')

Error Codes

Geode follows ISO/IEC SQL error code standards:

CodeDescription
00000Success
0A000Feature not supported
22000Data exception
23000Integrity constraint violation
42000Syntax error or access rule violation
42P01Undefined table
42P07Duplicate table/index
53000Insufficient resources
58000System error
XX000Internal error

Performance Tips

Index Usage

  1. Create indexes on frequently queried properties
  2. Use unique indexes for high cardinality properties
  3. Use hash indexes for exact match queries only
  4. Use btree indexes for range queries and sorting
  5. Use vector indexes for similarity search
  6. Use spatial indexes for geographic queries

Query Optimization

  1. Use EXPLAIN to understand query plans
  2. Limit result sets with LIMIT clause
  3. Filter early with WHERE clauses
  4. Use index hints when necessary
  5. Avoid cartesian products without filters
  6. Always use ORDER BY with LIMIT for deterministic results

Next Steps