Add "in_list" operator to GraphQL API filters for IDs and Enums

[tyler-8]

NetBox version

v4.3.0

Feature type

Change to existing functionality

Proposed functionality

Introduce support for the in_list operator across all GraphQL filters for ID and Enum fields (like status or interface types) in NetBox's v4.3.0, aligning with most other filter options for other fields in the NetBox GraphQL API.

This operator allows filtering objects by specifying multiple values simultaneously using a concise syntax:

query {
  circuit_list {
    terminations(filter: { site: { id: { in_list: [1, 2] } } }) {
      id
      site { name }
    }
  }
}

Use case

This feature significantly simplifies and optimizes common automation tasks and data integrations. Examples include:

Batch Object Retrieval

Quickly query multiple objects by IDs or statuses within one GraphQL request. While GraphQL does offer other logical operators like OR, they don't cleanly fit every use case where filtering by multiple values is needed.

query {
  device_list(filter: { status: { in_list: [ACTIVE, PLANNED, STAGED] } }) {
    id
    name
    status
  }
}

Dashboard Filtering

Simplify dashboards displaying entities filtered by various criteria, making queries cleaner and easier to maintain.

The REST API currently supports similar functionality, and the v4.3.0 GraphQL API also provides similar capability on most endpoints/field filters. Adding in_list to the current GraphQL filtering mechanism for IDs and Enums continues this existing theme, eliminating the need for chaining multiple "OR" filters - which are difficult to produce dynamically without awkward/cumbersome string manipulation.

The ability to combine in_list, OR filters, and pagination would provide maximum API flexibility; serving diverse use cases.

Database changes

N/A

External dependencies

N/A

[jeremystretch]

The existing filters provide an in_list operator, which I think is what you want. This is provided by Strawberry's BaseFilterLookup.

query MyQuery {
  circuit_list(filters: {provider: {name: {in_list: ["CenturyLink", "Level 3"]}}}) {
    id
    provider {name}
  }
}

[tyler-8]

Thanks @jeremystretch - you're absolutely right; I think I got my wires crossed from a few days ago when I was tinkering with the 4.3 beta for the previous GraphQL issue.

However, there are two filter/field types that don't appear to have the in_list options: enum fields (like status on circuits or devices, or in particular interface types of which there are a lot of) and ID fields (on everything).

[jeremystretch]

We could change the id filter to support lookups:

class ChangeLogFilterMixin(BaseFilterMixin):
    # id: ID | None = strawberry.UNSET
    id: strawberry_django.BaseFilterLookup[int] | None = strawberry.UNSET

However, that does preclude filtering by a bare ID ({id: 123}) and forces the use of the exact filter when not using a different lookup ({id: {exact: 123}}). This is in keeping with the other filters, so IMO it makes sense.