Memory Management

Overview

Understanding and managing computing engine memory usage is essential for optimal performance. This page covers memory budget allocation, estimation, partial caching strategies, and troubleshooting.

Memory Budget Allocation

The computing engine divides its memory budget into three components:

Topology Budget (60% default)

• CSR matrix for outgoing edges
• CSC matrix for incoming edges
• Label-indexed adjacency structures
• Node/edge ID mappings

Property Budget (30% default)

• Columnar storage for cached properties
• Per-label property arrays
• String interning for text properties

Working Budget (10% default)

• Temporary allocations during queries
• Algorithm working memory
• Build/rebuild operations

These percentages are defaults that work well for most workloads. The system automatically manages allocation within your configured limit.

Memory Estimates

Use these estimates to plan your memory allocation:

Topology Memory Formula:

Memory = 2 * (N + 1) * 8 + 4 * E * 8 bytes

Where N = number of nodes, E = number of edges

This accounts for:

• CSR row pointers: (N+1) * 8 bytes
• CSR column indices + edge data: 2 * E * 8 bytes
• CSC (mirror of CSR): same as above

Property Memory:

• Integer/Float: 8 bytes per value
• Boolean: 1 byte per value
• String: 8 bytes pointer + string length (interned)
• Multiply by number of cached properties

Reference Table:

Properties column assumes 5 integer/float properties per node

Calculate memory for a social network:

GQL
-- Example: Social network with 5M users, 50M follows
-- Topology: 2 * (5M + 1) * 8 + 4 * 50M * 8 = ~1.7 GB
-- Properties (name, age, verified): ~60 MB
-- Recommended limit: 2GB

ALTER GRAPH socialNetwork SET COMPUTE MEMORY_LIMIT 2GB

Calculate memory for a knowledge graph:

GQL
-- Example: Knowledge graph with 20M entities, 200M relations
-- Topology: 2 * (20M + 1) * 8 + 4 * 200M * 8 = ~6.7 GB
-- Properties (title, type): ~320 MB
-- Recommended limit: 8GB

ALTER GRAPH knowledgeGraph SET COMPUTE MEMORY_LIMIT 8GB

Partial Caching Strategy

For graphs larger than available memory, the computing engine supports partial caching:

How Partial Caching Works:

1. Topology builds until memory limit reached
2. Most-connected nodes prioritized (hubs cached first)
3. Uncached nodes fall back to disk-based storage
4. Queries still work correctly, just slower for uncached portions

Optimizing Partial Caching:

• Set limit to cache your "hot" subgraph
• Frequently traversed nodes get cached first
• Monitor cache hit rates and adjust

Best Practices:

• Cache at least 50% of graph for meaningful speedup
• Profile your queries to identify hot nodes
• Consider separate graphs for hot/cold data

Partial caching for large graphs:

GQL
-- Large graph with limited memory
-- Cache only the most important portion

ALTER GRAPH massiveGraph SET COMPUTE ENABLED
ALTER GRAPH massiveGraph SET COMPUTE MEMORY_LIMIT 16GB

-- Queries will use cache when possible
-- Falls back to disk for uncached nodes
MATCH (popular:User WHERE popular.followers > 10000)
      -[:FOLLOWS]->{1,3}(audience)
RETURN popular.name, count(audience)

Monitoring Memory Usage

Monitor computing engine memory to optimize your configuration:

Key Metrics:

• Topology memory used - Actual bytes used by CSR/CSC
• Property memory used - Bytes used by cached properties
• Cache coverage - Percentage of graph cached
• Cache hit rate - Percentage of lookups served from cache

Tuning Tips:

• Low hit rate? Increase memory limit or cache more properties
• High memory, low benefit? Reduce limit, disable for this graph
• Frequent rebuilds? Consider ASYNC mode during writes

View computing engine statistics:

GQL
-- Check computing engine status
SHOW GRAPH myGraph COMPUTE STATUS

-- Expected output:
-- enabled: true
-- sync_mode: SYNC
-- memory_limit: 4GB
-- memory_used: 3.2GB
-- topology_coverage: 100%
-- property_coverage: 85%
-- cache_hit_rate: 94%

Troubleshooting

Common memory-related issues and solutions:

Build Fails or Incomplete

• Symptom: Topology build stops early
• Cause: Memory limit too low
• Solution: Increase memory limit or accept partial caching

High Memory, No Speedup

• Symptom: Memory used but queries not faster
• Cause: Queries don't traverse cached portions
• Solution: Profile queries, adjust what's cached

Out of Memory Errors

• Symptom: Process crashes during build
• Cause: Memory limit exceeds available RAM
• Solution: Reduce limit, leave headroom for OS/queries

Slow After Writes

• Symptom: Queries slow immediately after mutations
• Cause: SYNC mode blocking on cache updates
• Solution: Use ASYNC mode for write-heavy periods

NOTE

Warning: Always leave at least 20% of system RAM for the operating system and query execution. Setting memory limits too high can cause system instability.