Aerospike Predicate Filtering: Trimming Query Results Without Dropping Your Indexes

The over-fetching problem

You have an Aerospike users set with a secondary index on age. A query for age >= 18 returns the right records, but your application only cares about users who are active and have logged in recently. Without server-side filtering, the client pulls every record the index selects, parses each one, and discards the unwanted ones in application code. On a large namespace, that wastes bandwidth, serializes records you will never use, and burns client CPU.

What predicate filtering actually does

Aerospike predicate filtering—usually called filter expressions—lets you attach boolean bin-level logic to a query or scan. Introduced in the 3.12 server line, it pushes that logic into the server so non-matching records are discarded before serialization and network transfer. The key detail is where it happens: the server first selects a working set using the secondary index, then evaluates your predicate against those records, and only then serializes the survivors.

That ordering matters. Predicate filtering is orthogonal to secondary indexes. It does not replace them; it shrinks the final result set after the index has already done its job.

A concrete example

Imagine the users set again. You have a secondary index on age, and you want records where age >= 18, status == "active", and last_login > cutoff. The index handles the range on age. The predicate handles the two additional bin conditions.

Because client APIs differ across Java, Python, Go, and C# libraries, the exact builder syntax varies. Conceptually, you are constructing an expression tree that the server evaluates:

AND(
  age >= 18,
  status == "active",
  last_login > cutoff
)

The server applies this after index selection. Compared with the alternatives, the trade-offs look like this:

Approach	Records read by server	Bytes on wire	Maintenance
No predicate (filter in app)	All index hits	High	Simple, but wasteful
Record UDF (Lua)	All index hits	Low	Harder to test and evolve
Predicate filter	All index hits	Low	Client-native, testable

Notice that the server still reads the same number of records in all three cases. The predicate saves network payload and client-side parsing, not server-side I/O.

The limitation: predicates are not indexes

The most common mistake is treating predicate filtering as a performance silver bullet. It is not. If your secondary index is poorly chosen, the server still builds a large working set before the predicate runs. For example, if you index on age but 99 percent of records match that range and only 1 percent are active, the server still reads 99 percent of the namespace. The predicate trims the response, but it does not reduce the scan cost.

Advanced expression features—such as geo predicates or nested collection iteration—may also require newer server or client versions than your current stack. Operator availability is not uniform across languages or releases.

How to verify it in your environment

Start with version assumptions. Predicate filtering has been available since the Aerospike 3.12 server line, but you should confirm support and available operators against your exact server release notes and your client library changelog. Java, Python, Go, and C# drivers expose different builder methods and operator sets.

Then run a controlled test in a non-production namespace. Execute the same query with and without the predicate and compare the returned record counts and bytes transferred. Inspect server metrics such as query and scan counters to confirm that filtering is happening server-side and that the predicate has not unexpectedly triggered a full scan. Finally, review your client's expression or filter builder documentation to ensure the syntax matches your language and driver version.

When to reach for it

Use predicate filtering when your secondary index already narrows the working set to a manageable size, but you need to discard a meaningful fraction of records before they hit the network. It is a tool for reducing payload, not for rescuing a bad index. If the working set is enormous, fix the index first; the predicate will thank you.