---
title: "Query Threading"
description: "Optimize Aerospike Graph queries using Query Threading to parallelize execution for high fan-out and supernode tasks."
---

# Query Threading

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

Query Threading is a powerful feature that enables individual queries to run across multiple threads in parallel. It’s especially effective for complex graph traversals or queries that touch a large number of elements, such as stepping off supernodes with hundreds of thousands of edges. By distributing the work, you can dramatically boost performance and reduce response times for heavy-duty operations.

## Standard query execution

With the default configurations, each Gremlin query in AGS executes on a single thread from the thread pool controlled by the [aerospike.graph-service.gremlinPool](https://aerospike.com/docs/graph/reference/config/#aerospikegraph-servicegremlinpool) configuration parameter. This single-threaded execution can become a bottleneck when processing queries that touch hundreds of thousands of graph elements. For example, traversing [supernodes](https://aerospike.com/docs/graph/3.1.0/develop/query/supernodes) (vertices with extremely high connectivity) or performing a deep multi-hop query with high connectivity on each hop.

## Threaded query execution

Query Threading is configured with [`aerospike.graph.parallelize`](https://aerospike.com/docs/graph/reference/config/#aerospikegraphparallelize), which enables individual queries to utilize multiple threads during execution, distributing the workload across available compute resources. This threaded execution model is particularly effective for I/O-bound operations in which the query spends significant time waiting for data retrieval from the Aerospike database.

## When to use parallel query execution

Query Threading is particularly beneficial for:

-   High fan-out queries: queries that expand to touch many vertices from a single starting point.
-   Supernode processing: queries involving vertices with thousands to hundreds of thousands of edges.

## How to use parallel query execution

To enable Query Threading for a specific query, include the [`aerospike.graph.parallelize`](https://aerospike.com/docs/graph/reference/config/#aerospikegraphparallelize) parameter in your query as shown below.

```txt
g.with("aerospike.graph.parallelize", <NUM-THREADS>).<QUERY>
```

::: note
Query Threading is configured per query and is not a global setting.
:::

## Batch vs single record reads

Threading runs your query across multiple threads. Batching decides how each thread reads records.

### Batch reading controls

Batch reading is governed by three settings:

-   Threshold: [`aerospike.client.batch-threshold.per-node`](https://aerospike.com/docs/graph/reference/config/#aerospikeclientbatch-thresholdper-node) Threshold between single record reads and batch reads measured per Aerospike node.
-   Per-node batch cap: [`aerospike.client.batch.read.size.per-node`](https://aerospike.com/docs/graph/reference/config/#aerospikeclientbatchreadsizeper-node) Target batch size per node. The batch size across all nodes scales with the number of Aerospike nodes.
-   Flat batch cap: [`aerospike.client.batch.read.size`](https://aerospike.com/docs/graph/reference/config/#aerospikeclientbatchreadsize) Cluster-wide flat cap. When non-zero it overrides the per-node cap. The flat cap is a fixed limit that does not scale with the number of Aerospike nodes.

See [Graph configuration options](https://aerospike.com/docs/graph/reference/config) for threshold and sizing details.

::: note
Test with different values to determine what works best for your specific query pattern and data size. Start with small increments and monitor performance to tune these parameters.
:::

### Pagination controls

Pagination uses two settings:

-   Per-node page size: [`aerospike.graph.pagination.page.size.per-node`](https://aerospike.com/docs/graph/reference/config/#aerospikegraphpaginationpagesizeper-node) Page size per Aerospike node. The page size across all nodes scales with the number of Aerospike nodes.
-   Flat page size: [`aerospike.graph.pagination.page.size`](https://aerospike.com/docs/graph/reference/config/#aerospikegraphpaginationpagesize) Cluster-wide flat page size. When non-zero it overrides the per-node page size. The flat cap is a fixed limit that does not scale with the number of Aerospike nodes.