Cache management

Aerospike Graph Service (AGS) caches individual vertex and edge records that are read during traversal execution. Query results are not cached. You can tune caching behavior to reduce Aerospike database reads and improve traversal latency for read-heavy workloads.

Cache modes

The cache supports two modes, controlled by the aerospike.graph.cache.mode configuration option:

TRANSACTIONAL (default): Thread-local caches that are reset on each new traversal. This is effectively per request/query execution.
GLOBAL: Caches shared across threads within a graph instance. Caches are not reset between traversals. Best for read-heavy workloads with repeated access to the same data.

Each graph instance maintains its own caches. Switching cache modes on one graph does not affect caches in other graphs.

When to switch to GLOBAL cache

GLOBAL cache mode is most appropriate when all of the following are true:

Workloads are read-only, or read-write operations are independent enough that shared cached reads do not introduce correctness risks for your use case.
Aerospike database access is the current performance bottleneck, and reducing backend reads is expected to improve end-to-end latency and throughput.
The hot working set (the records your queries access repeatedly) can fit in memory, and AGS instances have enough RAM to hold the cache without putting memory pressure on other workloads.

Clear stale cached data in GLOBAL mode

In GLOBAL mode, cached data can become stale. AGS does not guarantee that cached reads reflect the latest writes, including writes made through AGS traversals. AGS also does not detect changes made by other AGS instances or non-graph applications sharing the same namespace.

Run admin/cache/reset to clear the cache when you need fresh reads.

Configure cache weight

Increasing cache_weight allows AGS to keep more records cached, which reduces Aerospike database reads and can improve traversal latency. Increase cache_weight only when needed, because it increases the amount of memory AGS can use for shared caching within a graph instance and can put memory pressure on other workloads.

The cache_weight parameter sets the cache size limit in weight units (not raw bytes). One weight unit is approximately 200 bytes, but actual memory depends on record shape and cache contents.

Default values:

TRANSACTIONAL: 1,000,000 weight units
GLOBAL: 20,000,000 weight units

You can check current consumption with admin/cache/status, which reports weighted_size (consumed weight units) and estimated_memory_bytes (approximate memory usage).

In GLOBAL mode, AGS also maintains a separate supernode edge-ID cache for supernode traversals. This cache is bounded by cache_weight and included in the status metrics.

Manage caches at runtime

Use admin services to monitor cache usage and switch modes at runtime. Start with the default TRANSACTIONAL mode, measure baseline latency and backend load, then switch to GLOBAL if your workload fits. Use admin/cache/status to monitor hit/miss counts and increase cache_weight as needed.

Admin services are available as Gremlin call steps and as HTTP endpoints. Changes to cache mode and weight are saved to graph configuration and persist when you restart the AGS instance. Treat admin changes as configuration changes and revert them explicitly when finished testing.

Get cache status

Returns the current cache mode and usage statistics.

g.call("aerospike.graph.admin.cache.status").next()

Returns a map with the following fields:

Field	Description
`mode`	Current cache mode (`TRANSACTIONAL` or `GLOBAL`).
`cache_weight`	Current cache weight limit in weight units.
`estimated_entry_count`	Approximate number of cached entries. This is an estimate and may aggregate multiple internal caches.
`weighted_size`	Current consumption in weight units.
`estimated_memory_bytes`	Estimated memory usage in bytes. Treat as approximate, not exact.
`estimated_memory_formatted`	Human-readable memory usage (for example, “1.5 MB”).
`hit_count`	Number of cache hits.
`miss_count`	Number of cache misses.

Example output:

{
    'mode': 'TRANSACTIONAL',
    'cache_weight': 1000000,
    'estimated_entry_count': 0,
    'weighted_size': 0,
    'estimated_memory_bytes': 0,
    'estimated_memory_formatted': '0 B',
    'hit_count': 0,
    'miss_count': 0
}

Set cache mode

Changes the cache mode at runtime.

g.call("aerospike.graph.admin.cache.set-mode")
  .with("mode", "GLOBAL")
  .next()

To specify a custom cache weight at the same time:

g.call("aerospike.graph.admin.cache.set-mode")
  .with("mode", "GLOBAL")
  .with("cache_weight", "50000000")
  .next()

Parameters:

Parameter	Required	Description
`mode`	Yes	Cache mode to set. Valid values: `TRANSACTIONAL`, `GLOBAL` (case-insensitive).
`cache_weight`	No	Cache weight in weight units (not raw bytes). Default: 1000000 for `TRANSACTIONAL`, 20000000 for `GLOBAL`.

Returns a map with the following fields:

Field	Description
`status`	`success` if the operation completed.
`previous_mode`	Cache mode before the change.
`current_mode`	New cache mode.
`cache_weight`	Cache weight being used (weight units).

Example output:

{
    'status': 'success',
    'previous_mode': 'TRANSACTIONAL',
    'current_mode': 'GLOBAL',
    'cache_weight': 20000000
}

Reset cache

Clears and reinitializes the current caches.

g.call("aerospike.graph.admin.cache.reset").next()

Returns a map with the following fields:

Field	Description
`status`	`success` if the operation completed.
`mode`	Current cache mode.
`previous_entry_count`	Entry count before reset.
`previous_weighted_size`	Weighted size before reset.
`current_entry_count`	Entry count after reset (0).
`current_weighted_size`	Weighted size after reset (0).

Example output:

{
    'status': 'success',
    'mode': 'GLOBAL',
    'previous_entry_count': 1523,
    'previous_weighted_size': 45690,
    'current_entry_count': 0,
    'current_weighted_size': 0
}

Use HTTP endpoints

Cache admin services are also available as HTTP REST endpoints:

http://localhost:9090/0/admin/cache/status
http://localhost:9090/0/admin/cache/set-mode?mode=GLOBAL
http://localhost:9090/0/admin/cache/set-mode?mode=GLOBAL&cache_weight=50000000
http://localhost:9090/0/admin/cache/reset

For multi-tenant deployments, replace 0 with the graph name.