Optimizing SurrealDB Graph Traversals: Resolving Query Latency

When SurrealDB queries suddenly transition from milliseconds to seconds as your dataset grows, the bottleneck is rarely the engine itself—it is usually the query optimizer forced into a linear scan. In multi-model databases like SurrealDB, graph traversals using RELATE and FETCH require specific indexing on foreign keys to scale. Without them, the engine must inspect every record in a table to resolve a relationship.

This guide helps you diagnose why your graph queries are slowing down and provides the specific indexing strategies needed to restore performance.

Diagnosing the Bottleneck

If you are experiencing high latency, compare your symptoms against the common diagnostic table below:

Symptom	Likely Cause
High latency on FETCH operations	Missing HASH or FIELD index on the target record ID.
Slow RELATE traversals	Missing index on the edge table's record pointers.
Memory spikes during aggregations	Large result sets without LIMIT or server-side filtering.
Slow write throughput	Over-indexing on volatile, frequently updated fields.

Step 1: Analyze the Query Plan

The first step is to determine how SurrealDB is executing your query. Use the EXPLAIN command to see the execution plan without actually running the query.

Run the following command in the SurrealDB Studio or via your client:

EXPLAIN SELECT * FROM person WHERE id = 'user:123' FETCH out->follows-><>

What to look for in the output:

• TableScan: This is a red flag. It means the engine is reading the entire table.
• IndexScan: This is ideal. It indicates the engine is using an index to find the data.
• Subquery cost: If nested subqueries show high cost, the latency will compound exponentially.

Step 2: Implement Targeted Indexing

Once you have identified a TableScan, you must define indexes on the fields used in the relationship. In a graph structure, these are often the record IDs stored in the edge table.

Indexing Edge Tables

If you are traversing a relationship like follows between users, you should ensure the in and out fields are indexed:

# Run this with administrative permissions
DEFINE INDEX follows_out_idx ON follow FIELD out;
DEFINE INDEX follows_in_idx ON follow FIELD in;

Indexing Filter Keys

If your traversal filters the graph by a specific attribute (e.g., status) before fetching related records, use a HASH index for high-speed lookups:

DEFINE INDEX person_status_idx ON person FIELD status TYPE HASH;

Step 3: Verify the Fix

After applying the index, you must verify that the query plan changed. Use EXPLAIN ANALYZE to execute the query and view the actual execution metrics.

EXPLAIN ANALYZE SELECT * FROM person WHERE id = 'user:123' FETCH out->follows-><>

Check that the output now lists an IndexScan. Compare the execution time against your initial baseline to ensure the improvement is significant.

Practical Constraints and Trade-offs

While indexing accelerates reads, it is not free. Consider these factors before deploying changes:

• Write Amplification: Every index adds overhead to CREATE and UPDATE operations. In high-frequency ingestion scenarios, index only essential fields.
• Schema Inconsistency: SurrealDB is schema-less by default. If one record has a string for a field and another has a number, the optimizer may choose a less efficient plan. Define schema constraints where possible.
• Backend Differences: Performance behavior varies between the TiDB backend (distributed) and the RocksDB backend (embedded) due to different locking mechanisms. Test on your target backend.

Escalation Criteria

If query latency remains high after indexing and query plan verification, escalate by checking:

• System memory usage during traversals—ensure the working set fits within allocated limits.
• Network latency between application and database, especially in distributed TiDB deployments.
• Whether the query can be restructured to use server-side filtering instead of client-side post-processing.