---
title: "Filtering records"
description: "Filter Aerospike records using Voyager's visual builder or the advanced Aerospike Expression Language."
---

# Filtering records

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

Aerospike Voyager provides two ways to filter records. Both produce the same underlying expression string that the Aerospike cluster evaluates.

-   The **Filters tab** is a visual builder for common conditions. Enter field names, pick operators, and enter values without writing any syntax.
-   The **Expression tab** accepts the full [Aerospike Expression Language](https://aerospike.com/docs/develop/expressions) for advanced queries, including collection data type (CDT) operations and record metadata.

Open the filter panel by clicking the **Filter records** button in the records toolbar. The panel has two tabs: **Filters** and **Expression**.

 ![Filter panel showing the Filters tab with an empty filter row containing Field, Operator (= equals), Value, and Data type (string) inputs, plus Add condition and Apply buttons](https://aerospike.com/docs/_astro/filter_panel_empty.B03hx6jM_ZIzkDW.png)

## Filters tab (visual builder)

The visual filter builder lets you construct filter conditions by entering field names, selecting operators, and entering values. Click **Apply** to execute the filter against the cluster.

### Adding a filter row

1.  Enter a **Field** name (the bin name to filter on).
2.  Choose an **Operator** from the dropdown (for example, `= equals`, `> greater than`, `exists`).
3.  Enter a **Value** if the operator requires one.
4.  Click **Add condition** to add another filter row.
5.  Click **Apply** to run the filter.

 ![Filter panel Filters tab with Field age, Operator greater than, Value 30, Data type integer, the generated expression $.age > 30 shown at the bottom, and the Apply button](https://aerospike.com/docs/_astro/filter_builder_age_gt_30.BB1BVi4u_Z1qycQX.png)

### Available operators

The operator dropdown in the visual builder supports the following operators:

| UI label | Applies to | Description | Example |
| --- | --- | --- | --- |
| `= equals` | String, Integer, Float | Exact value match | `country = US` |
| `!= not equal` | String, Integer, Float | Negated match | `status != inactive` |
| `> greater than` | Integer, Float | Numeric greater-than | `age > 30` |
| `< less than` | Integer, Float | Numeric less-than | `price < 50` |
| `>= greater than or equal` | Integer, Float | Inclusive greater-than | `count >= 10` |
| `<= less than or equal` | Integer, Float | Inclusive less-than | `count <= 100` |
| `is true` | Boolean | Boolean true check | `is_active is true` |
| `is false` | Boolean | Boolean false check | `is_active is false` |
| `exists` | Any | Bin is present on the record | `email exists` |
| `does not exist` | Any | Bin is absent from the record | `phone does not exist` |

The visual builder does not filter on Blob bins, or on values inside list or map (CDT) bins. Use the Expression tab to reach CDT elements.

### Combining conditions

Use the **AND/OR** toggle to combine multiple filter rows. The combinator is uniform per query: all rows are joined with AND, or all rows are joined with OR. You cannot mix AND and OR in the visual builder. For mixed logic, use the Expression tab.

### Data type

Voyager auto-detects whether the value you enter is an integer, float, or string. A value like `30` is treated as an integer. A value like `3.14` is treated as a float. Everything else is treated as a string.

To override the detected type, use the **Data type** dropdown next to the value field. This is useful when a numeric-looking value (such as a zip code) should be treated as a string.

### Metadata filters

The visual builder currently filters on bin values only. To filter on record metadata ([TTL](https://aerospike.com/docs/database/manage/namespace/retention), last update time, or record size), use the Expression tab. See [Record metadata](#record-metadata) below.

### Clearing filters

Click **Clear all** to remove every filter row and return to the unfiltered view. Click **Cancel** to close the filter panel without applying changes.

To filter on Blob bins or to reach into list or map (CDT) bin contents, use the Expression tab below.

## Expression tab (expression editor)

The Expression tab is a free-text editor that accepts the full Aerospike Expression Language. Use it for queries that the visual builder cannot express, such as [CDT](https://aerospike.com/docs/database/learn/architecture/data-storage/data-model) operations, nested path traversal, and mixed boolean logic.

### Syntax basics

In Aerospike Expression Language, the `$` prefix denotes a bin reference. For example, `$.age > 30` filters records where the age bin exceeds 30.

```text
$.age > 30

$.country == 'US'
```

**Compound conditions** use `and` and `or`:

```text
$.age > 30 and $.country == 'US'
```

::: note
Logical operators in the expression editor are case-sensitive. Use lowercase `and`, `or`, and `not`. Uppercase forms will not parse.
:::

**Comparison operators:**

| Operator | Meaning |
| --- | --- |
| `==` | Equals |
| `!=` | Not equals |
| `>` | Greater than |
| `>=` | Greater than or equal |
| `<` | Less than |
| `<=` | Less than or equal |

**Logical operators:** `and`, `or`, `not()`, `exclusive()`

### CDT list access

Access elements in list bins using bracket notation:

```text
$.scores.[0]          # by index (first element)

$.scores.[=90]        # by value (element equal to 90)

$.scores.[#2]         # by rank (third-lowest value)

$.scores.count()      # number of elements
```

### CDT map access

Access entries in map bins:

```text
$.user.name           # by key

$.user.{0}            # by index (first entry)

$.user.count()        # number of entries
```

### Nested structures

Combine map and list access for deeply nested data:

```text
$.user.roles.[0] == 'admin'
```

### The `in` operator

Check if a bin value is in a list of values:

```text
$.status in ['active', 'pending']
```

### Record metadata

Access record-level metadata using function syntax:

```text
$.ttl() > 3600

$.lastUpdate() > 1700000000

$.deviceSize() < 1024

$.setName() == 'users'
```

### Built-in functions

Numeric functions are available for use in expressions:

`abs()`, `ceil()`, `floor()`, `log()`, `min()`, `max()`

### When to use the expression editor

Use the Expression tab when you need:

-   CDT operations (list or map access, counts, rank-based lookups)
-   Nested path traversal
-   Record metadata queries
-   Mixed AND/OR logic
-   The `in` operator or built-in functions

## How the two tabs relate

Both tabs produce the same expression string that is sent to the Aerospike cluster. Building a filter in the visual builder populates the Expression tab with the equivalent expression. Editing an expression in the Expression tab updates the visual builder when the expression maps to supported operators.

You can start with the visual builder to learn expression syntax, then switch to the Expression tab for more advanced queries.

## Canceling a query

Click the **Cancel** button in the toolbar to abort a running query at any time.

## Bin name validation

Bin names in Aerospike are limited to 15 bytes. The visual builder enforces this limit when you enter a custom bin name.

## Next steps

-   [Expressions and SDK code](https://aerospike.com/docs/database/tools/voyager/guides/expressions-and-sdk-code): Copy expression strings into your application code.