Using Scan Queries
Use scan queries to retrieve cache entries in a distributed manner, with optional predicates, transformers, and local or asynchronous execution.
Overview
IgniteCache has several query methods, all of which receive a subclass of the Query class and return a QueryCursor.
A Query represents an abstract paginated query to be executed on a cache. The page size is configurable via the Query.setPageSize(...) method (default is 1024).
QueryCursor represents the query result set and allows for transparent page-by-page iteration. When a user starts iterating over the last page, QueryCursor automatically requests the next page in the background. For cases when pagination is not needed, you can use the QueryCursor.getAll() method, which fetches the entries and stores them in a collection.
Executing Scan Queries
A scan query is a simple search query used to retrieve data from a cache in a distributed manner. When executed without parameters, a scan query returns all entries from the cache.
IgniteCache<Integer, Person> cache = ignite.getOrCreateCache("myCache");
QueryCursor<Cache.Entry<Integer, Person>> cursor = cache.query(new ScanQuery<>());var cursor = cache.Query(new ScanQuery<int, Person>());Cache<int64_t, Person> cache = ignite.GetOrCreateCache<int64_t, ignite::Person>("personCache");
QueryCursor<int64_t, Person> cursor = cache.Query(ScanQuery());Scan queries return entries that match a predicate, if specified. The predicate is applied on the remote nodes.
IgniteCache<Integer, Person> cache = ignite.getOrCreateCache("myCache");
// Find the persons who earn more than 1,000.
IgniteBiPredicate<Integer, Person> filter = (key, p) -> p.getSalary() > 1000;
try (QueryCursor<Cache.Entry<Integer, Person>> qryCursor = cache.query(new ScanQuery<>(filter))) {
qryCursor.forEach(
entry -> System.out.println("Key = " + entry.getKey() + ", Value = " + entry.getValue()));
}class SalaryFilter : ICacheEntryFilter<int, Person>
{
public bool Invoke(ICacheEntry<int, Person> entry)
{
return entry.Value.Salary > 1000;
}
}
public static void ScanQueryFilterDemo()
{
var ignite = Ignition.Start();
var cache = ignite.GetOrCreateCache<int, Person>("person_cache");
cache.Put(1, new Person {Name = "person1", Salary = 1001});
cache.Put(2, new Person {Name = "person2", Salary = 999});
using (var cursor = cache.Query(new ScanQuery<int, Person>(new SalaryFilter())))
{
foreach (var entry in cursor)
{
Console.WriteLine("Key = " + entry.Key + ", Value = " + entry.Value);
}
}
}unsupported
Scan queries also support an optional transformer closure which lets you convert the entry on the server node before sending it back. This is useful, for example, when you want to fetch only several fields of a large object and want to minimize the network traffic. The example below shows how to fetch only the keys without sending the values.
unsupported
unsupported
Asynchronous Scan Queries
In .NET, a query cursor (IQueryCursor) implements IAsyncEnumerable<T> and IAsyncDisposable in addition to IEnumerable<T> and IDisposable. This lets you iterate the results with await foreach and release the cursor's server-side resources with await using, without blocking the calling thread on network I/O.
Query returns the cursor as usual; each page is then fetched without blocking the calling thread as you iterate:
To release the cursor asynchronously as well, wrap it in an await using block:
unsupported
unsupported
Local Scan Query
By default, a scan query is distributed to all nodes. However, you can execute the query locally, in which case the query runs against the data stored on the local node (i.e. the node where the query is executed).
Related Topics
This page is: Copyright © 2026 MariaDB. All rights reserved.
Last updated
Was this helpful?

