Closes #7598: Enable custom field filtering for GraphQL

docs/development/adding-models.md

@@ -76,11 +76,13 @@ Create the following for each model:
 
 ## 13. GraphQL API components
 
-Create a GraphQL object type for the model in `graphql/types.py` by subclassing the appropriate class from `netbox.graphql.types`.
+Create the following for each model:
 
-**Note:** GraphQL unit tests may fail citing null values on a non-nullable field if related objects are prefetched. You may need to fix this by setting the type annotation to be `= strawberry_django.field(select_related=["policy"])` or similar.
+* GraphQL object type for the model in `graphql/types.py` (subclass the appropriate class from `netbox.graphql.types`)
+* Add a GraphQL filter for the model in `graphql/filters.py`
+* Extend the query class for the app in `graphql/schema.py` with the individual object and object list fields
 
-Also extend the schema class defined in `graphql/schema.py` with the individual object and object list fields per the established convention.
+**Note:** GraphQL unit tests may fail citing null values on a non-nullable field if related objects are prefetched. You may need to fix this by setting the type annotation to be `= strawberry_django.field(select_related=["foo"])` or similar.
 
 ## 14. Add tests
 

docs/integrations/graphql-api.md

@@ -11,7 +11,7 @@ curl -H "Authorization: Token $TOKEN" \
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 http://netbox/graphql/ \
---data '{"query": "query {circuit_list(status:\"active\") {cid provider {name}}}"}'
+--data '{"query": "query {circuit_list(filters:{status: STATUS_ACTIVE}) {cid provider {name}}}"}'
 ```
 
 The response will include the requested data formatted as JSON:
@@ -51,19 +51,48 @@ For more detail on constructing GraphQL queries, see the [GraphQL queries docume
 
 ## Filtering
 
-The GraphQL API employs the same filtering logic as the UI and REST API. Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only sites within the North Carolina region with a status of active:
+!!! note "Changed in NetBox v4.3"
+    The filtering syntax fo the GraphQL API has changed substantially in NetBox v4.3.
+
+Filters can be specified as key-value pairs within parentheses immediately following the query name. For example, the following will return only active sites:
 
 ```
 query {
-  site_list(filters: {region: "us-nc", status: "active"}) {
+  site_list(
+    filters: {
+      status: STATUS_ACTIVE
+    }
+  ) {
     name
   }
 }
 ```
-In addition, filtering can be done on list of related objects as shown in the following query:
+
+Filters can be combined with logical operators, such as `OR` and `NOT`. For example, the following will return every site that is planned _or_ assigned to a tenant named Foo:
 
 ```
-{
+query {
+  site_list(
+    filters: {
+      status: STATUS_PLANNED,
+      OR: {
+        tenant: {
+          name: {
+            exact: "Foo"
+          }
+        }
+      }
+    }
+  ) {
+    name
+  }
+}
+```
+
+Filtering can also be applied to related objects. For example, the following query will return only enabled interfaces for each device:
+
+```
+query {
   device_list {
     id
     name

docs/plugins/development/filtersets.md

@@ -1,6 +1,6 @@
 # Filters & Filter Sets
 
-Filter sets define the mechanisms available for filtering or searching through a set of objects in NetBox. For instance, sites can be filtered by their parent region or group, status, facility ID, and so on. The same filter set is used consistently for a model whether the request is made via the UI, REST API, or GraphQL API. NetBox employs the [django-filters2](https://django-tables2.readthedocs.io/en/latest/) library to define filter sets.
+Filter sets define the mechanisms available for filtering or searching through a set of objects in NetBox. For instance, sites can be filtered by their parent region or group, status, facility ID, and so on. The same filter set is used consistently for a model whether the request is made via the UI or REST API. (Note that the GraphQL API uses a separate filter class.) NetBox employs the [django-filters2](https://django-tables2.readthedocs.io/en/latest/) library to define filter sets.
 
 ## FilterSet Classes
 

netbox/circuits/graphql/enums.py

@@ -0,0 +1,20 @@
+import strawberry
+
+from circuits.choices import *
+
+__all__ = (
+    'CircuitStatusEnum',
+    'CircuitCommitRateEnum',
+    'CircuitTerminationSideEnum',
+    'CircuitTerminationPortSpeedEnum',
+    'CircuitPriorityEnum',
+    'VirtualCircuitTerminationRoleEnum',
+)
+
+
+CircuitCommitRateEnum = strawberry.enum(CircuitCommitRateChoices.as_enum())
+CircuitPriorityEnum = strawberry.enum(CircuitPriorityChoices.as_enum())
+CircuitStatusEnum = strawberry.enum(CircuitStatusChoices.as_enum())
+CircuitTerminationSideEnum = strawberry.enum(CircuitTerminationSideChoices.as_enum())
+CircuitTerminationPortSpeedEnum = strawberry.enum(CircuitTerminationPortSpeedChoices.as_enum())
+VirtualCircuitTerminationRoleEnum = strawberry.enum(VirtualCircuitTerminationRoleChoices.as_enum())

netbox/circuits/graphql/filter_mixins.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from typing import Annotated, TYPE_CHECKING
+
+import strawberry
+import strawberry_django
+
+from netbox.graphql.filter_mixins import OrganizationalModelFilterMixin
+
+if TYPE_CHECKING:
+    from netbox.graphql.enums import ColorEnum
+
+__all__ = (
+    'BaseCircuitTypeFilterMixin',
+)
+
+
+@dataclass
+class BaseCircuitTypeFilterMixin(OrganizationalModelFilterMixin):
+    color: Annotated['ColorEnum', strawberry.lazy('netbox.graphql.enums')] | None = strawberry_django.filter_field()

netbox/circuits/graphql/filters.py

@@ -1,7 +1,30 @@
+from datetime import date
+from typing import Annotated, TYPE_CHECKING
+
+import strawberry
 import strawberry_django
+from strawberry.scalars import ID
+from strawberry_django import FilterLookup, DateFilterLookup
+
+from circuits import models
+from core.graphql.filter_mixins import BaseObjectTypeFilterMixin, ChangeLogFilterMixin
+from dcim.graphql.filter_mixins import CabledObjectModelFilterMixin
+from extras.graphql.filter_mixins import CustomFieldsFilterMixin, TagsFilterMixin
+from netbox.graphql.filter_mixins import (
+    DistanceFilterMixin,
+    ImageAttachmentFilterMixin,
+    OrganizationalModelFilterMixin,
+    PrimaryModelFilterMixin,
+)
+from tenancy.graphql.filter_mixins import ContactFilterMixin, TenancyFilterMixin
+from .filter_mixins import BaseCircuitTypeFilterMixin
 
-from circuits import filtersets, models
-from netbox.graphql.filter_mixins import autotype_decorator, BaseFilterMixin
+if TYPE_CHECKING:
+    from core.graphql.filters import ContentTypeFilter
+    from dcim.graphql.filters import InterfaceFilter
+    from ipam.graphql.filters import ASNFilter
+    from netbox.graphql.filter_lookups import IntegerLookup
+    from .enums import *
 
 __all__ = (
     'CircuitFilter',
@@ -19,66 +42,160 @@
 
 
 @strawberry_django.filter(models.CircuitTermination, lookups=True)
-@autotype_decorator(filtersets.CircuitTerminationFilterSet)
-class CircuitTerminationFilter(BaseFilterMixin):
-    pass
+class CircuitTerminationFilter(
+    BaseObjectTypeFilterMixin,
+    CustomFieldsFilterMixin,
+    TagsFilterMixin,
+    ChangeLogFilterMixin,
+    CabledObjectModelFilterMixin,
+):
+    circuit: Annotated['CircuitFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    term_side: Annotated['CircuitTerminationSideEnum', strawberry.lazy('circuits.graphql.enums')] | None = (
+        strawberry_django.filter_field()
+    )
+    termination_type: Annotated['ContentTypeFilter', strawberry.lazy('core.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    termination_id: ID | None = strawberry_django.filter_field()
+    port_speed: Annotated['IntegerLookup', strawberry.lazy('netbox.graphql.filter_lookups')] | None = (
+        strawberry_django.filter_field()
+    )
+    upstream_speed: Annotated['IntegerLookup', strawberry.lazy('netbox.graphql.filter_lookups')] | None = (
+        strawberry_django.filter_field()
+    )
+    xconnect_id: FilterLookup[str] | None = strawberry_django.filter_field()
+    pp_info: FilterLookup[str] | None = strawberry_django.filter_field()
+    description: FilterLookup[str] | None = strawberry_django.filter_field()
 
 
 @strawberry_django.filter(models.Circuit, lookups=True)
-@autotype_decorator(filtersets.CircuitFilterSet)
-class CircuitFilter(BaseFilterMixin):
-    pass
+class CircuitFilter(
+    ContactFilterMixin,
+    ImageAttachmentFilterMixin,
+    DistanceFilterMixin,
+    TenancyFilterMixin,
+    PrimaryModelFilterMixin
+):
+    cid: FilterLookup[str] | None = strawberry_django.filter_field()
+    provider: Annotated['ProviderFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_id: ID | None = strawberry_django.filter_field()
+    provider_account: Annotated['ProviderAccountFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_account_id: ID | None = strawberry_django.filter_field()
+    type: Annotated['CircuitTypeFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    type_id: ID | None = strawberry_django.filter_field()
+    status: Annotated['CircuitStatusEnum', strawberry.lazy('circuits.graphql.enums')] | None = (
+        strawberry_django.filter_field()
+    )
+    install_date: DateFilterLookup[date] | None = strawberry_django.filter_field()
+    termination_date: DateFilterLookup[date] | None = strawberry_django.filter_field()
+    commit_rate: Annotated['IntegerLookup', strawberry.lazy('netbox.graphql.filter_lookups')] | None = (
+        strawberry_django.filter_field()
+    )
 
 
 @strawberry_django.filter(models.CircuitType, lookups=True)
-@autotype_decorator(filtersets.CircuitTypeFilterSet)
-class CircuitTypeFilter(BaseFilterMixin):
+class CircuitTypeFilter(BaseCircuitTypeFilterMixin):
     pass
 
 
 @strawberry_django.filter(models.CircuitGroup, lookups=True)
-@autotype_decorator(filtersets.CircuitGroupFilterSet)
-class CircuitGroupFilter(BaseFilterMixin):
+class CircuitGroupFilter(TenancyFilterMixin, OrganizationalModelFilterMixin):
     pass
 
 
 @strawberry_django.filter(models.CircuitGroupAssignment, lookups=True)
-@autotype_decorator(filtersets.CircuitGroupAssignmentFilterSet)
-class CircuitGroupAssignmentFilter(BaseFilterMixin):
-    pass
+class CircuitGroupAssignmentFilter(
+    BaseObjectTypeFilterMixin, CustomFieldsFilterMixin, TagsFilterMixin, ChangeLogFilterMixin
+):
+    member_type: Annotated['ContentTypeFilter', strawberry.lazy('core.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    member_id: ID | None = strawberry_django.filter_field()
+    group: Annotated['CircuitGroupFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    group_id: ID | None = strawberry_django.filter_field()
+    priority: Annotated['CircuitPriorityEnum', strawberry.lazy('circuits.graphql.enums')] | None = (
+        strawberry_django.filter_field()
+    )
 
 
 @strawberry_django.filter(models.Provider, lookups=True)
-@autotype_decorator(filtersets.ProviderFilterSet)
-class ProviderFilter(BaseFilterMixin):
-    pass
+class ProviderFilter(ContactFilterMixin, PrimaryModelFilterMixin):
+    name: FilterLookup[str] | None = strawberry_django.filter_field()
+    slug: FilterLookup[str] | None = strawberry_django.filter_field()
+    asns: Annotated['ASNFilter', strawberry.lazy('ipam.graphql.filters')] | None = strawberry_django.filter_field()
 
 
 @strawberry_django.filter(models.ProviderAccount, lookups=True)
-@autotype_decorator(filtersets.ProviderAccountFilterSet)
-class ProviderAccountFilter(BaseFilterMixin):
-    pass
+class ProviderAccountFilter(ContactFilterMixin, PrimaryModelFilterMixin):
+    provider: Annotated['ProviderFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_id: ID | None = strawberry_django.filter_field()
+    account: FilterLookup[str] | None = strawberry_django.filter_field()
+    name: FilterLookup[str] | None = strawberry_django.filter_field()
 
 
 @strawberry_django.filter(models.ProviderNetwork, lookups=True)
-@autotype_decorator(filtersets.ProviderNetworkFilterSet)
-class ProviderNetworkFilter(BaseFilterMixin):
-    pass
+class ProviderNetworkFilter(PrimaryModelFilterMixin):
+    name: FilterLookup[str] | None = strawberry_django.filter_field()
+    provider: Annotated['ProviderFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_id: ID | None = strawberry_django.filter_field()
+    service_id: FilterLookup[str] | None = strawberry_django.filter_field()
 
 
 @strawberry_django.filter(models.VirtualCircuitType, lookups=True)
-@autotype_decorator(filtersets.VirtualCircuitTypeFilterSet)
-class VirtualCircuitTypeFilter(BaseFilterMixin):
+class VirtualCircuitTypeFilter(BaseCircuitTypeFilterMixin):
     pass
 
 
 @strawberry_django.filter(models.VirtualCircuit, lookups=True)
-@autotype_decorator(filtersets.VirtualCircuitFilterSet)
-class VirtualCircuitFilter(BaseFilterMixin):
-    pass
+class VirtualCircuitFilter(TenancyFilterMixin, PrimaryModelFilterMixin):
+    cid: FilterLookup[str] | None = strawberry_django.filter_field()
+    provider_network: Annotated['ProviderNetworkFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_network_id: ID | None = strawberry_django.filter_field()
+    provider_account: Annotated['ProviderAccountFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    provider_account_id: ID | None = strawberry_django.filter_field()
+    type: Annotated['VirtualCircuitTypeFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    type_id: ID | None = strawberry_django.filter_field()
+    status: Annotated['CircuitStatusEnum', strawberry.lazy('circuits.graphql.enums')] | None = (
+        strawberry_django.filter_field()
+    )
+    group_assignments: Annotated['CircuitGroupAssignmentFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
 
 
 @strawberry_django.filter(models.VirtualCircuitTermination, lookups=True)
-@autotype_decorator(filtersets.VirtualCircuitTerminationFilterSet)
-class VirtualCircuitTerminationFilter(BaseFilterMixin):
-    pass
+class VirtualCircuitTerminationFilter(
+    BaseObjectTypeFilterMixin, CustomFieldsFilterMixin, TagsFilterMixin, ChangeLogFilterMixin
+):
+    virtual_circuit: Annotated['VirtualCircuitFilter', strawberry.lazy('circuits.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    virtual_circuit_id: ID | None = strawberry_django.filter_field()
+    role: Annotated['VirtualCircuitTerminationRoleEnum', strawberry.lazy('circuits.graphql.enums')] | None = (
+        strawberry_django.filter_field()
+    )
+    interface: Annotated['InterfaceFilter', strawberry.lazy('dcim.graphql.filters')] | None = (
+        strawberry_django.filter_field()
+    )
+    interface_id: ID | None = strawberry_django.filter_field()
+    description: FilterLookup[str] | None = strawberry_django.filter_field()

netbox/circuits/graphql/types.py

@@ -1,4 +1,4 @@
-from typing import Annotated, List, Union
+from typing import Annotated, List, TYPE_CHECKING, Union
 
 import strawberry
 import strawberry_django
@@ -10,11 +10,15 @@
 from tenancy.graphql.types import TenantType
 from .filters import *
 
+if TYPE_CHECKING:
+    from dcim.graphql.types import InterfaceType, LocationType, RegionType, SiteGroupType, SiteType
+    from ipam.graphql.types import ASNType
+
 __all__ = (
-    'CircuitTerminationType',
-    'CircuitType',
     'CircuitGroupAssignmentType',
     'CircuitGroupType',
+    'CircuitTerminationType',
+    'CircuitType',
     'CircuitTypeType',
     'ProviderType',
     'ProviderAccountType',
@@ -62,7 +66,7 @@ class ProviderNetworkType(NetBoxObjectType):
 
 @strawberry_django.type(
     models.CircuitTermination,
-    exclude=('termination_type', 'termination_id', '_location', '_region', '_site', '_site_group', '_provider_network'),
+    exclude=['termination_type', 'termination_id', '_location', '_region', '_site', '_site_group', '_provider_network'],
     filters=CircuitTerminationFilter
 )
 class CircuitTerminationType(CustomFieldsMixin, TagsMixin, CabledObjectMixin, ObjectType):
@@ -117,7 +121,7 @@ class CircuitGroupType(OrganizationalObjectType):
 
 @strawberry_django.type(
     models.CircuitGroupAssignment,
-    exclude=('member_type', 'member_id'),
+    exclude=['member_type', 'member_id'],
     filters=CircuitGroupAssignmentFilter
 )
 class CircuitGroupAssignmentType(TagsMixin, BaseObjectType):