Filter Queries

What Is a Filter Spec?

A filter spec is a small JSON object that tells SandsBytes which records to show in a page or view. Filters are usually sent as a list of objects, for example:

[
  { "field": "cases.name", "op": "==", "value": "Case 42" },
  { "field": "cases.status", "op": "in", "value": ["open", "in_progress"] }
]

Basic JSON Structure

The base shape of a filter spec is:

[
  {
    "field": "field_name_or_path",
    "op": "operator",
    "value": "value-or-list"
  }
]

field: The field to filter on (for example status, cases.name, or events_count).
op: The comparison operator.
value: The value to compare against.

Field Formats

Filters support several field formats:

Field on the main item: field is a field on the main record, for example:
- "field": "status"
Field on a related item: field uses entity.field to reference a related object:
- "field": "users.username"
Global text search: field is the special value "_string" (explained below).

Simple Examples

Equality on a simple field:

[
  { "field": "status", "op": "==", "value": "open" }
]

Multiple independent filters (combined with AND logic):

[
  { "field": "status", "op": "==", "value": "open" },
  { "field": "priority", "op": ">=", "value": 3 }
]

Supported Operators

Filter specs support a focused set of operators. Always set op explicitly so behavior is clear.

Operator	Description	Example
`==`	Equals a single value	`"status" == "open"`
`!=`	Does not equal a single value	`"status" != "closed"`
`>`	Greater than a value (number or date)	`"priority" > 2`
`<`	Less than a value (number or date)	`"created_at" < "2024-01-01"`
`>=`	Greater than or equal to a value	`"priority" >= 3`
`<=`	Less than or equal to a value	`"priority" <= 5`
`=~`	Contains text (case-insensitive)	`name contains "error"`
`between`	Between two values, inclusive	`created_at between ["2024-01-01", "2024-12-31"]`
`in`	One of several allowed values	`status in ["open", "closed"]`
`not_in`	Not in a list of values	`status not_in ["open", "closed"]`

Operator Examples

Substring match (case-insensitive):

[
  { "field": "cases.name", "op": "=~", "value": "ransomware" }
]

Range filter with between:

[
  {
    "field": "created_at",
    "op": "between",
    "value": ["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]
  }
]

Set membership with in:

[
  {
    "field": "status",
    "op": "in",
    "value": ["open", "in_progress", "pending_approval"]
  }
]

Boolean Groups (`and` / `or`)

To build more complex logic, you can group filters with and and or keys. The value is a list of inner filter specs.

Top-level AND group:

[
  {
    "and": [
      { "field": "status", "op": "==", "value": "open" },
      { "field": "priority", "op": ">=", "value": 3 }
    ]
  }
]

Top-level OR group:

[
  {
    "or": [
      { "field": "status", "op": "==", "value": "open" },
      { "field": "status", "op": "==", "value": "in_progress" }
    ]
  }
]

Nested groups (mixing and and or):

[
  {
    "or": [
      {
        "and": [
          { "field": "status", "op": "==", "value": "open" },
          { "field": "priority", "op": ">=", "value": 3 }
        ]
      },
      {
        "and": [
          { "field": "status", "op": "==", "value": "in_progress" },
          { "field": "owner", "op": "==", "value": "analyst1" }
        ]
      }
    ]
  }
]

SandsBytes combines these into nested logical AND and OR expressions when it evaluates the query.

Global Text Search with `_string`

Some pages support global text search across many string fields at once. In that case, you can use the special field name _string.

field: must be "_string".
value: the text to search for.

Example:

[
  { "field": "_string", "op": "=~", "value": "10.0.0.5" }
]

Internally, SandsBytes builds an OR across eligible fields (for example name, description, ip, etc.), so this behaves like a single search box that looks across multiple columns.

To filter by attributes on related items, use the entity.field pattern in field.

The part before the dot selects the related item (for example users).
The part after the dot selects its field (for example username).

Example, filter cases by owner username:

[
  { "field": "users.username", "op": "==", "value": "alice" }
]

In this example:

The main list shows cases.
The filter keeps only cases where an associated user has username == "alice".

Where Filters Are Used in SandsBytes

Most SandsBytes API endpoints that list objects accept a query parameter. This parameter contains the filter JSON described on this page.

Typical usage:

The client builds a filter list like:

[
  { "field": "status", "op": "==", "value": "open" },
  { "field": "priority", "op": ">=", "value": 3 }
]

The client sends this list as the query parameter (usually JSON-encoded in the request).
SandsBytes uses that filter spec to decide which items to include in the response.

You will see this pattern whenever you call SandsBytes APIs that list or search for objects (for example cases, tasks, users, workflows, and more).

Filter Queries

On this page