From 524576aa37ae5033f75444ad518e973d157600eb Mon Sep 17 00:00:00 2001 From: dharshini-2007 Date: Fri, 10 Oct 2025 09:06:47 +0530 Subject: [PATCH 1/2] add query block cache documentation --- docs/adding-a-new-api-version.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/adding-a-new-api-version.md b/docs/adding-a-new-api-version.md index 1a7b495e3ff..04cc0ab9f4c 100644 --- a/docs/adding-a-new-api-version.md +++ b/docs/adding-a-new-api-version.md @@ -35,3 +35,26 @@ have been rolled out to production (hosted-service): 7. Release in NPM 5. Update `graph-docs` with the new `apiVersion` content. + +## Query Block Cache + +The query block cache is used to speed up subgraph queries by storing recently +processed blocks in memory. This helps avoid re-fetching and recomputing +block data repeatedly. + +### Modules Reading from the Cache +- `GraphQLExecutor`: Reads blocks before executing queries. +- `Store`: Retrieves cached blocks when processing subgraph queries. + +### Modules Writing to the Cache +- `BlockStreamProcessor`: Writes newly processed blocks to the cache. +- `Indexer`: Updates the cache after syncing new events. + +### Configuration +- `CACHE_SIZE`: Maximum number of blocks stored in memory. +- `CACHE_EXPIRY`: Time (in seconds) before cached blocks are considered stale. + +### Debugging Tips +- To check cache hits/misses, enable debug logging in the `graph-node` service. +- If queries are slow, verify that `CACHE_SIZE` is sufficient and `CACHE_EXPIRY` is reasonable. + From c940e27f940f147ba5284a26c4b990df47c9cd72 Mon Sep 17 00:00:00 2001 From: dharshini-2007 Date: Fri, 10 Oct 2025 09:11:55 +0530 Subject: [PATCH 2/2] add timeseries, aggregations, and query block cache documentation --- docs/aggregations.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/aggregations.md b/docs/aggregations.md index fafbd4d3305..695bbdc0d01 100644 --- a/docs/aggregations.md +++ b/docs/aggregations.md @@ -201,3 +201,24 @@ token_stats(interval: "hour", avgVolume } ``` +## Query Block Cache + +The **query block cache** improves performance for timeseries and aggregation queries +by storing recently processed blocks in memory. Instead of recomputing results +or fetching blocks from storage repeatedly, `graph-node` reads from this cache. + +### Modules Reading from the Cache +- `GraphQLExecutor`: Reads blocks before executing queries. +- `Store`: Retrieves cached blocks when processing timeseries and aggregation queries. + +### Modules Writing to the Cache +- `BlockStreamProcessor`: Writes newly processed blocks to the cache. +- `Indexer`: Updates the cache after syncing new events. + +### Configuration +- `CACHE_SIZE`: Maximum number of blocks stored in memory (default 1000). +- `CACHE_EXPIRY`: Time (in seconds) before cached blocks expire (default 300s). + +### Debugging Tips +- To monitor cache hits/misses, enable debug logs in `graph-node`. +- If queries are slow, check that `CACHE_SIZE` is sufficient and `CACHE_EXPIRY` is reasonable.