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

Annotate related objects counts on a REST API queryset only when the field is active on the serializer #9241

New Issue
Closed
opened 2025-12-29 20:47:24 +01:00 by adam · 1 comment
adam commented 2025-12-29 20:47:24 +01:00
Owner
Copy Link

Originally created by @jeremystretch on GitHub (Feb 13, 2024).

Originally assigned to: @jeremystretch on GitHub.

NetBox version

v3.7.2

Feature type

New functionality

Proposed functionality

Many REST API endpoints annotate the count of certain related objects. For example, the sites endpoint includes counts for assigned racks, devices, racks, etc.:

{
    ...
    "circuit_count": 1,
    "device_count": 2,
    "prefix_count": 0,
    "rack_count": 1,
    "virtualmachine_count": 0,
    "vlan_count": 0
}

These values are annotated on the queryset statically under the view class:

class SiteViewSet(NetBoxModelViewSet):
    queryset = Site.objects.annotate(
        device_count=count_related(Device, 'site'),
        rack_count=count_related(Rack, 'site'),
        prefix_count=count_related(Prefix, 'site'),
        vlan_count=count_related(VLAN, 'site'),
        circuit_count=count_related(Circuit, 'terminations__site'),
        virtualmachine_count=count_related(VirtualMachine, 'cluster__site')
    )

This issue proposes moving these annotations to the serializer class, effected as discrete fields which can be optionally included or omitted per the new functionality being introduced under #15087. (The current counts are retained by default to preserve existing behavior, but are omitted when the API client has requested a specific subset of fields which does not include the related object counts.)

This will require the introduction of a new field type which can be employed to automatically attach an annotation to the underlying queryset (similar to how we prefetch only relevant fields under #15087). I imagine something like this:

class SiteSerializer(NetBoxModelSerializer):
    ...
    rack_count = ObjectCountField(model='dcim.Rack', related_field='site')
    device_count = ObjectCountField(model='dcim.Device', related_field='site')
    circuit_count = ObjectCountField(model='circuits.Circuit', related_field='terminations__site')

The view class will likely need to be extended to automatically annotate the queryset for ObjectCountFields which are included for the request.

Use case

Moving these annotations to a serializer class and annotating their values only when necessary will greatly optimize the underlying querysets.

For instance, the devices list currently annotates counts for six different related object types: racks, devices, prefixes, VLANs, circuits, and virtual machines. These annotations are always computed and attached to the API results, even if their respective values are not conveyed in the response (due to the use of brief mode or because a subset of fields was requested). This can lead to significant unnecessary overhead when dealing with large numbers of objects.

Database changes

None; this change does not impact the underlying database schema in anyway, just the manner in which object relations are queried.

External dependencies

None

Originally created by @jeremystretch on GitHub (Feb 13, 2024). Originally assigned to: @jeremystretch on GitHub. ### NetBox version v3.7.2 ### Feature type New functionality ### Proposed functionality Many REST API endpoints annotate the count of certain related objects. For example, the sites endpoint includes counts for assigned racks, devices, racks, etc.: ``` { ... "circuit_count": 1, "device_count": 2, "prefix_count": 0, "rack_count": 1, "virtualmachine_count": 0, "vlan_count": 0 } ``` These values are annotated on the queryset statically under the view class: ```python class SiteViewSet(NetBoxModelViewSet): queryset = Site.objects.annotate( device_count=count_related(Device, 'site'), rack_count=count_related(Rack, 'site'), prefix_count=count_related(Prefix, 'site'), vlan_count=count_related(VLAN, 'site'), circuit_count=count_related(Circuit, 'terminations__site'), virtualmachine_count=count_related(VirtualMachine, 'cluster__site') ) ``` This issue proposes moving these annotations to the serializer class, effected as discrete fields which can be optionally included or omitted per the new functionality being introduced under #15087. (The current counts are retained by default to preserve existing behavior, but are omitted when the API client has requested a specific subset of fields which does not include the related object counts.) This will require the introduction of a new field type which can be employed to automatically attach an annotation to the underlying queryset (similar to how we prefetch only relevant fields under #15087). I imagine something like this: ```python class SiteSerializer(NetBoxModelSerializer): ... rack_count = ObjectCountField(model='dcim.Rack', related_field='site') device_count = ObjectCountField(model='dcim.Device', related_field='site') circuit_count = ObjectCountField(model='circuits.Circuit', related_field='terminations__site') ``` The view class will likely need to be extended to automatically annotate the queryset for ObjectCountFields which are included for the request. ### Use case Moving these annotations to a serializer class and annotating their values only when necessary will greatly optimize the underlying querysets. For instance, the devices list currently annotates counts for six different related object types: racks, devices, prefixes, VLANs, circuits, and virtual machines. These annotations are _always_ computed and attached to the API results, even if their respective values are not conveyed in the response (due to the use of brief mode or because a subset of fields was requested). This can lead to significant unnecessary overhead when dealing with large numbers of objects. ### Database changes None; this change does not impact the underlying database schema in anyway, just the manner in which object relations are queried. ### External dependencies None
adam added the status: acceptedtype: feature labels 2025-12-29 20:47:24 +01:00
adam closed this issue 2025-12-29 20:47:24 +01:00
adam commented 2025-12-29 20:47:25 +01:00
Author
Owner
Copy Link

@jeremystretch commented on GitHub (Feb 13, 2024):

Tagging this for v4.0 as it will provide ancillary benefit to FR #15087

@jeremystretch commented on GitHub (Feb 13, 2024): Tagging this for v4.0 as it will provide ancillary benefit to FR #15087
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 status: accepted 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#9241
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?