How to use vlan_vid__empty to fetch prefixes?

[purpose-robot]

Hello there,

I am trying to fetch all prefixes which are associated with a VLAN.

For that I found the vlan_vid__empty filter set to do so. However I am not sure how to use this filter.

As per the OpenAPI docs, the value should be an integer with a range from 1 to 4094 which I find strange for an isnull kind of filter.
If I enter a integer, I got the error The QuerySet value for an isnull lookup must be True or False. which again sounds correct, but I can also not enter a boolean value. Doing so results in the error Enter a number.

I am using Netbox community version 4.1.3 on Rocky Linux.

[candlerb]

I agree with you that the vlan_vid__empty filter does appear to be broken:

vlan_vid__empty=       # (has no effect)
vlan_vid__empty=0      # {"error": "The QuerySet value for an isnull lookup must be True or False.", "exception": "ValueError", "netbox_version": "4.1.3", "python_version": "3.12.3"}
vlan_vid__empty=false  # {"vlan_vid__empty":["Enter a number."]}
vlan_vid__empty=False  # {"vlan_vid__empty":["Enter a number."]}
vlan_vid__empty=no     # {"vlan_vid__empty":["Enter a number."]}

You could raise a bug report for this (more details below).

I am trying to fetch all prefixes which are associated with a VLAN.

I think the nearest you can do is:

/api/ipam/prefixes/?vlan_vid__gt=0

That will find prefixes which are associated with a VLAN object where that VLAN object has a VID assigned, which is not exactly what you asked for, but may be sufficient if all your VLAN objects have VIDs (i.e. 802.1q tags).

Since any non-empty VID must be between 1 and 4094, this is pretty much equivalent to vlan_vid__empty=false.

The vlan_vid filter is defined in netbox/ipam/filtersets.py

    vlan_vid = django_filters.NumberFilter(
        field_name='vlan__vid',
        label=_('VLAN number (1-4094)'),
    )

Based on that code, I don't think vlan_vid__empty would do what you asked for either. I expect that it would check whether the VLAN object which is associated with the prefix has an empty VID; not whether or not any VLAN object is associated with the prefix. (The field vlan__vid which it uses internally is a Django ORM join, via the vlan(_id) accessor to the vid attribute on the joined table)

I can't find any other filter that would do exactly what you want, and it seems like a reasonable feature request to ask for, e.g. vlan_id__empty=true or vlan__empty=true, to check whether or not the prefix is associated with a VLAN (regardless of whether that VLAN has a VID)

---

Looking into the issue with vlan_vid__empty there appears to be some Netbox-specific magic for handling __empty in netbox/netbox/filtersets.py:

                    filter_cls = django_filters.BooleanFilter if lookup_expr == 'empty' else type(existing_filter)

and there are a couple of test cases in netbox/utilities/tests/test_filters.py:

        self.assertEqual(self.filters['charfield__empty'].lookup_expr, 'empty')
        self.assertEqual(self.filters['charfield__empty'].exclude, False)
...
        self.assertEqual(self.filters['numberfield__empty'].lookup_expr, 'isnull')
        self.assertEqual(self.filters['numberfield__empty'].exclude, False)

but I guess it hasn't been tested with actual REST API calls to ensure the string value is converted appropriately.