> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/filtering-and-sorting.md).

# Filtering and sorting

Use filter and orderBy on list queries to control which results come back and in what order, including text search and sort rules that affect pagination cursors.

List queries (those returning multiple items, like `devices`, `assets`, or `schedules`) accept `filter` and `orderBy` arguments that let you control which results come back and in what order. Instead of fetching everything and processing it client-side, you can request exactly what you need.

For navigating through large result sets, see [Pagination](/docs/navixy-graphql-api/pagination.md).

## Filtering

Pass a `filter` argument to any list query to narrow down results:

```graphql
query {
  bdr {
    devices(
      filter: {
        statusIds: ["status-active-uuid"]
      }
    ) {
      nodes {
        id
        title
        status { title }
      }
    }
  }
}
```

This returns only devices with the specified status.

Each entity type has its own filter input with different available fields. For example, `DeviceFilter` supports filtering by type, model, status, vendor, and inventory, while `ScheduleFilter` only supports a partial match on the title. Use [introspection](/docs/navixy-graphql-api/graphql-basics.md#introspection) or the entity's reference page to see available filter fields.

### Filtering logic

Filters combine conditions using two types of logic:

| Location       | Logic | Meaning                 |
| -------------- | ----- | ----------------------- |
| Within a field | OR    | Match any of the values |
| Between fields | AND   | Match all conditions    |

Consider this filter:

```graphql
filter: {
  typeIds: ["type-truck-uuid", "type-van-uuid"]
  statusIds: ["status-active-uuid"]
}
```

This translates to:

```
(type = truck OR type = van) AND (status = active)
```

The result includes active trucks and active vans, but not inactive trucks or vehicles of other types.

### Empty values are ignored

If a filter field is `null` or an empty array, the API ignores it entirely:

```graphql
filter: {
  typeIds: []                        # Ignored — no filtering by type
  statusIds: ["status-active-uuid"]  # Applied
}
```

This is useful when building dynamic filters, so you don't need to conditionally omit empty fields from your query.

### Text search

Most filters include a `titleContains` field for partial text matching:

```graphql
query {
  bdr {
    devices(
      filter: {
        titleContains: "delivery"
      }
    ) {
      nodes {
        id
        title
      }
    }
  }
}
```

This returns devices with "delivery" anywhere in their title, like "Delivery Van 1" or "North Delivery Truck". The search is case-insensitive.

Some filters have additional text search fields. For example, `DeviceFilter` includes `identifierContains` for searching hardware identifiers like IMEI numbers. Like `titleContains`, identifier search is case-insensitive.

### Limitations

The API does not support complex boolean expressions with nested AND/OR/NOT operators. If you need more complex filtering logic, apply the most restrictive server-side filter you can, then filter the results further in your application.

For filtering assets and geo objects by their custom field values, see [Custom field filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting/custom-field-filtering.md).

## Sorting

Use the `orderBy` argument to control the order of results:

```graphql
query {
  bdr {
    devices(
      orderBy: { field: TITLE, direction: ASC }
    ) {
      nodes {
        id
        title
      }
    }
  }
}
```

The `direction` can be ASC (ascending: A→Z, 0→9, oldest→newest) or DESC (descending: Z→A, 9→0, newest→oldest).

Each entity type has its own set of sortable fields. For example, devices can be sorted by TITLE, while audit events can be sorted by OCCURRED\_AT. Use introspection or the API reference to see available sort fields.

### Sort behavior

Text fields use natural sorting with ICU collation:

* Case-insensitive: "apple" and "Apple" sort together
* Locale-aware: accented characters sort correctly (é sorts with e, not after z)
* Numeric-aware: "item2" comes before "item10"

NULL values appear last when sorting ASC, and first when sorting DESC.

For sorting assets and geo objects by custom field values, see [Custom field filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting/custom-field-filtering.md).

### Sorting and pagination

A cursor encodes a position in one sort order. If you change `orderBy` between pagination requests, the API returns no error, but the next page is cut at a position that means nothing in the new order, so items are skipped or repeated. Always use the same `orderBy` value when paginating through a result set. If you need a different sort order, start from the beginning.

## See also

* [Pagination](/docs/navixy-graphql-api/pagination.md): Page through large result sets with cursors
* [Custom field filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting/custom-field-filtering.md): Filter and sort assets and geo objects by custom field values


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://navixy.com/docs/navixy-graphql-api/filtering-and-sorting.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.