starred/netbox
1
0
Fork 0
mirror of https://github.com/netbox-community/netbox.git synced 2026-01-11 21:10:29 +01:00
Code Issues 273 Packages Projects Releases 10 Wiki Activity

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

New Issue
Closed
opened 2025-12-29 21:40:10 +01:00 by adam · 12 comments
adam commented 2025-12-29 21:40:10 +01:00
Owner
Copy Link

Originally created by @tyler-8 on GitHub (Apr 27, 2025).

Originally assigned to: @bctiemann on GitHub.

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

Originally created by @tyler-8 on GitHub (Apr 27, 2025). Originally assigned to: @bctiemann on GitHub. ### 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: ```graphql 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. ```graphql 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
adam closed this issue 2025-12-29 21:40:10 +01:00
adam commented 2025-12-29 21:40:11 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Apr 28, 2025):

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}
  }
}
@jeremystretch commented on GitHub (Apr 28, 2025): The existing filters provide an `in_list` operator, which I think is what you want. This is provided by Strawberry's [`BaseFilterLookup`](https://github.com/strawberry-graphql/strawberry-django/blob/11bf86a90670eff04bb6fdf8b762feab053e5dbd/strawberry_django/fields/filter_types.py#L27). ```graphql query MyQuery { circuit_list(filters: {provider: {name: {in_list: ["CenturyLink", "Level 3"]}}}) { id provider {name} } } ```
adam commented 2025-12-29 21:40:11 +01:00
Author
Owner
Copy Link

@tyler-8 commented on GitHub (Apr 28, 2025):

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).

@tyler-8 commented on GitHub (Apr 28, 2025): 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).
adam commented 2025-12-29 21:40:11 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Apr 28, 2025):

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.

@jeremystretch commented on GitHub (Apr 28, 2025): We could change the `id` filter to support lookups: ```python 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.
adam commented 2025-12-29 21:40:12 +01:00
Author
Owner
Copy Link

@tyler-8 commented on GitHub (May 12, 2025):

I updated the issue title & OP text to match our discussion

@tyler-8 commented on GitHub (May 12, 2025): I updated the issue title & OP text to match our discussion
adam commented 2025-12-29 21:40:12 +01:00
Author
Owner
Copy Link

@arthanson commented on GitHub (Jul 31, 2025):

More research will need to be done for the preferred solution as a research project.

@arthanson commented on GitHub (Jul 31, 2025): More research will need to be done for the preferred solution as a research project.
adam commented 2025-12-29 21:40:12 +01:00
Author
Owner
Copy Link

@AdilsonTorres commented on GitHub (Sep 18, 2025):

Has anyone checked the possibility of a solution to be able to use in_list operator on filters? I can work my way out on my plugins but not on the core models.

@AdilsonTorres commented on GitHub (Sep 18, 2025): Has anyone checked the possibility of a solution to be able to use `in_list` operator on filters? I can work my way out on my plugins but not on the core models.
adam commented 2025-12-29 21:40:12 +01:00
Author
Owner
Copy Link

@tyler-8 commented on GitHub (Sep 18, 2025):

Has anyone checked the possibility of a solution to be able to use in_list operator on filters? I can work my way out on my plugins but not on the core models.

The in_list operator is available for just about every possible filter except IDs and enums (like status or interface types). Are you asking for something beyond that scope?

@tyler-8 commented on GitHub (Sep 18, 2025): > Has anyone checked the possibility of a solution to be able to use `in_list` operator on filters? I can work my way out on my plugins but not on the core models. The `in_list` operator is available for just about every possible filter except IDs and enums (like `status` or interface types). Are you asking for something beyond that scope?
adam commented 2025-12-29 21:40:13 +01:00
Author
Owner
Copy Link

@AdilsonTorres commented on GitHub (Sep 18, 2025):

In my case is for the IDs specially. I would like to filter a model list (any model list, device_list, site_list, ...) by a list of ids when possible, instead requesting for each id in the list.

@AdilsonTorres commented on GitHub (Sep 18, 2025): In my case is for the IDs specially. I would like to filter a model list (any model list, device_list, site_list, ...) by a list of ids when possible, instead requesting for each id in the list.
adam commented 2025-12-29 21:40:13 +01:00
Author
Owner
Copy Link

@sverrep commented on GitHub (Sep 23, 2025):

I'd also really like being able to filter IDs with "in_list". Currently we have a workaround of chaining "OR"s like so: {"id": "112", "OR": {"id": "4"} which can become a really long chain when searching for a longer list of IDs.

@sverrep commented on GitHub (Sep 23, 2025): I'd also really like being able to filter IDs with "in_list". Currently we have a workaround of chaining "OR"s like so: `{"id": "112", "OR": {"id": "4"}` which can become a really long chain when searching for a longer list of IDs.
adam commented 2025-12-29 21:40:13 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Sep 29, 2025):

I'm tagging this for v4.5 with the understanding that the current terse form (id: 123) will not be supported any longer. As with other fields, an explicit lookup filter will be required (e.g. id: {exact: 123} or id: {in_list: [123, 456, 789]}.

(If a reasonable means of maintaining backward compatibility is identified in the course of this work, I'm happy to pursue it, but it appears unlikely.)

@jeremystretch commented on GitHub (Sep 29, 2025): I'm tagging this for v4.5 with the understanding that the current terse form (`id: 123`) will _not_ be supported any longer. As with other fields, an explicit lookup filter will be required (e.g. `id: {exact: 123}` or `id: {in_list: [123, 456, 789]}`. (If a reasonable means of maintaining backward compatibility is identified in the course of this work, I'm happy to pursue it, but it appears unlikely.)
adam commented 2025-12-29 21:40:14 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Oct 20, 2025):

As we've identified a number of breaking changes to the GraphQL API targeted for NetBox v4.5, we've opted to introduce a second version of the API to be operated in parallel to the original (see #20603). As such, v1 of the API will continue to work as before: This change will be implemented only for GraphQL API v2.

@jeremystretch commented on GitHub (Oct 20, 2025): As we've identified a number of breaking changes to the GraphQL API targeted for NetBox v4.5, we've opted to introduce a second version of the API to be operated in parallel to the original (see #20603). As such, v1 of the API will continue to work as before: This change will be implemented only for GraphQL API v2.
adam commented 2025-12-29 21:40:14 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Nov 7, 2025):

Unfortunately we've had to push out work on v2 of the GraphQL API due to limitation discovered in django-strawberry. We've decided to proceed with this breaking change in NetBox v4.5 per the original plan.

@jeremystretch commented on GitHub (Nov 7, 2025): Unfortunately we've had to push out work on v2 of the GraphQL API due to limitation discovered in django-strawberry. We've decided to proceed with this breaking change in NetBox v4.5 per the [original plan](https://github.com/netbox-community/netbox/issues/19338#issuecomment-3348781431).
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
beta
breaking change
complexity: high
complexity: low
complexity: medium
needs milestone
netbox
pending closure
plugin candidate
pull-request
Mirrored from GitHub Pull Request
 severity: high
severity: low
severity: medium
status: accepted
status: backlog
status: blocked
status: duplicate
status: needs owner
status: needs triage
status: revisions needed
status: under review
topic: GraphQL
topic: Internationalization
topic: OpenAPI
topic: UI/UX
topic: cabling
topic: event rules
topic: htmx navigation
topic: industrialization
topic: migrations
topic: plugins
topic: scripts
topic: templating
topic: testing
type: bug
type: deprecation
type: documentation
type: feature
type: housekeeping
type: translation
No Label breaking change complexity: high netbox status: accepted topic: GraphQL type: feature
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/netbox#11091
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?