Standardize filtering logic for the parents of recursively-nested models #9338

New Issue

adam · 2025-12-29T20:48:42+01:00

adam commented

2025-12-29 20:48:42 +01:00

Originally created by @jeremystretch on GitHub (Mar 8, 2024).

Originally assigned to: @jeremystretch on GitHub.

NetBox version

v3.7.3

Feature type

Change to existing functionality

Proposed functionality

I'm opening this FR to address an inconsistency in the filtering of parent objects of self-recursive models (e.g. regions, site groups, locations, etc.).

For most of these objects, filtering by the parent object will return only the immediate children of the specified parent. For example, filtering for all regions belonging to North America (PK 1) will return only the countries assigned to that continent; it will not include child states or cities within each country.

# Returns immediate children only
GET /api/dcim/regions/?parent_id=1

However, this is not true for locations. Per #6124, filtering locations by a parent location will return all of the parent object's descendants. For example, if dealing with a hierarchy of buildings, floors, and rooms, filtering for a specific building will return both rooms and floors within it.

# Returns *all* descendants in the hierarchy
GET /api/dcim/locations/?parent_id=1

I am proposing a two-part change:

Standardize the behavior of the parent & parent_id filters so that they behave consistently across all nested models. (This will likely mean modifying the current behavior of the location filter, as it would be the smallest breaking change.)
Introducing an alternative filters for all models to provide the complementary filtering behavior (perhaps named ancestor).

Edit: For example, you could then do

GET /api/dcim/regions/?parent_id=1

to return only the immediate children of region 1, OR

GET /api/dcim/regions/?ancestor_id=1

to return all regions within region 1.

Use case

Neither behavior described above is objectively correct or incorrect: Both have valid use cases. However, we should address the inconsistency and prescribe a clear mechanism for achieving either behavior for all relevant models.

Database changes

None expected

External dependencies

None

Originally created by @jeremystretch on GitHub (Mar 8, 2024). Originally assigned to: @jeremystretch on GitHub. ### NetBox version v3.7.3 ### Feature type Change to existing functionality ### Proposed functionality I'm opening this FR to address an inconsistency in the filtering of parent objects of self-recursive models (e.g. regions, site groups, locations, etc.). For most of these objects, filtering by the parent object will return only the immediate children of the specified parent. For example, filtering for all regions belonging to North America (PK 1) will return only the countries assigned to that continent; it will _not_ include child states or cities within each country. ``` # Returns immediate children only GET /api/dcim/regions/?parent_id=1 ``` However, this is not true for locations. Per #6124, filtering locations by a parent location will return _all_ of the parent object's descendants. For example, if dealing with a hierarchy of buildings, floors, and rooms, filtering for a specific building will return both rooms and floors within it. ``` # Returns *all* descendants in the hierarchy GET /api/dcim/locations/?parent_id=1 ``` I am proposing a two-part change: 1. Standardize the behavior of the `parent` & `parent_id` filters so that they behave consistently across all nested models. (This will likely mean modifying the current behavior of the location filter, as it would be the smallest breaking change.) 2. Introducing an alternative filters for all models to provide the complementary filtering behavior (perhaps named `ancestor`). **Edit:** For example, you could then do ``` GET /api/dcim/regions/?parent_id=1 ``` to return only the _immediate_ children of region 1, OR ``` GET /api/dcim/regions/?ancestor_id=1 ``` to return _all_ regions within region 1. ### Use case Neither behavior described above is objectively correct or incorrect: Both have valid use cases. However, we should address the inconsistency and prescribe a clear mechanism for achieving either behavior for all relevant models. ### Database changes None expected ### External dependencies None

adam added the status: accepted type: feature breaking change labels 2025-12-29 20:48:42 +01:00

adam closed this issue

2025-12-29 20:48:42 +01:00

Sign in to join this conversation.

Branches Tags

main

update-changelog-comments-docs

feature-removal-issue-type

20911-dropdown

20239-plugin-menu-classes-mutable-state

21097-graphql-id-lookups

feature

fix_module_substitution

20923-dcim-templates

20044-elevation-stuck-lightmode

feature-ip-prefix-link

v4.5-beta1-release

20068-import-moduletype-attrs

20766-fix-german-translation-code-literals

20378-del-script

7604-filter-modifiers-v3

circuit-swap

12318-case-insensitive-uniqueness

20637-improve-device-q-filter

20660-script-load

19724-graphql

20614-update-ruff

14884-script

02496-max-page

19720-macaddress-interface-generic-relation

19408-circuit-terminations-export-templates

20203-openapi-check

fix-19669-api-image-download

7604-filter-modifiers

19275-fixes-interface-bulk-edit

fix-17794-get_field_value_return_list

11507-show-aggregate-and-rir-on-api

9583-add_column_specific_search_field_to_tables

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/netbox#9338