Support cursor-based pagination in GraphQL API #625

New Issue

MrUnknownDE · 2026-04-05T16:56:25+02:00

MrUnknownDE commented

2026-04-05 16:56:25 +02:00

Originally created by @jeremystretch on 1/9/2026

NetBox version

v4.5.0

Feature type

New functionality

Proposed functionality

The GraphQL API currently supporting paginating through results by passing offset and limit parameters with a request. For example:

query {
    device_list(
        pagination: {
            offset: $offset,
            limit: $limit
        }
    ) {
        id
        name
    }
}

This FR proposes an alternative to the offset parameter which specifies the primary key of the first object to fetch. For now, let's call this parameter start. Passing this parameter forces results to be ordered by primary key only, ensuring a deterministic set of results. The existing limit parameter can also be included to limit the number of results returned. For example:

query {
    device_list(
        pagination: {
            start: 4629,
            limit: 100
        }
    ) {
        id
        name
    }
}

The above query would yield (roughly) the following Django queryset:

Device.objects.order_by('pk').filter(pk__gte=4629)[:100]

The pagination strategy to be applied for a request is inferred from the parameter passed. The offset and start parameters are to be mutually exclusive.

Rough implementation plan

Subclass OffsetPaginationInput to introduce the start parameter:

import strawberry
from strawberry_django.pagination import OffsetPaginationInput

@strawberry.input
class StartIdPaginationInput(OffsetPaginationInput):
    start: int | None = None

Subclass StrawberryDjangoField to create a custom GraphQL field which employs our custom pagination by default:

from strawberry_django.fields.field import StrawberryDjangoField

class StartIdStrawberryDjangoField(StrawberryDjangoField):
    def apply_pagination(self, queryset, pagination=None):
        if pagination is not None:
            if start = getattr(pagination, "start", None):
                # TODO: Raise error if `offset` is also present
                queryset = queryset.filter(pk__gte=start).order_by("pk")

        return super().apply_pagination(queryset, pagination)

Use this field in place of strawberry_django.field() for all GraphQL lists:

# netbox/netbox/graphql/fields.py (new, or wherever NetBox keeps shared GraphQL helpers)
from functools import partial
import strawberry_django

from .pagination import StartIdPaginationInput, StartIdStrawberryDjangoField

netbox_field = partial(
    strawberry_django.field,
    pagination=StartIdPaginationInput,
    field_cls=StartIdStrawberryDjangoField,
)

from netbox.graphql.fields import netbox_field

foo_list: list[FooType] = netbox_field()

Use case

The current pagination approach relies on a relative offset. This struggles with very large result sets, because the offset must be calculated by scanning the entire table up to the offset position. Employing an object's unique primary key as a cursor avoids this, as we can leverage simple numeric comparison to filter for all PKs greater than or equal to a given value. Combined with the existing limit capability, this affords very efficient pagination at the cost of a fixed (and not very meaningful) ordering.

Database changes

N/A

External dependencies

N/A

*Originally created by @jeremystretch on 1/9/2026* ### NetBox version v4.5.0 ### Feature type New functionality ### Proposed functionality The GraphQL API currently supporting paginating through results by passing `offset` and `limit` parameters with a request. For example: ```graphql query { device_list( pagination: { offset: $offset, limit: $limit } ) { id name } } ``` This FR proposes an alternative to the `offset` parameter which specifies the primary key of the first object to fetch. For now, let's call this parameter `start`. Passing this parameter forces results to be ordered by primary key only, ensuring a deterministic set of results. The existing `limit` parameter can also be included to limit the number of results returned. For example: ```graphql query { device_list( pagination: { start: 4629, limit: 100 } ) { id name } } ``` The above query would yield (roughly) the following Django queryset: ```python Device.objects.order_by('pk').filter(pk__gte=4629)[:100] ``` The pagination strategy to be applied for a request is inferred from the parameter passed. The `offset` and `start` parameters are to be mutually exclusive. #### Rough implementation plan Subclass `OffsetPaginationInput` to introduce the `start` parameter: ```python import strawberry from strawberry_django.pagination import OffsetPaginationInput @strawberry.input class StartIdPaginationInput(OffsetPaginationInput): start: int | None = None ``` Subclass `StrawberryDjangoField` to create a custom GraphQL field which employs our custom pagination by default: ```python from strawberry_django.fields.field import StrawberryDjangoField class StartIdStrawberryDjangoField(StrawberryDjangoField): def apply_pagination(self, queryset, pagination=None): if pagination is not None: if start = getattr(pagination, "start", None): # TODO: Raise error if `offset` is also present queryset = queryset.filter(pk__gte=start).order_by("pk") return super().apply_pagination(queryset, pagination) ``` Use this field in place of `strawberry_django.field()` for all GraphQL lists: ```python # netbox/netbox/graphql/fields.py (new, or wherever NetBox keeps shared GraphQL helpers) from functools import partial import strawberry_django from .pagination import StartIdPaginationInput, StartIdStrawberryDjangoField netbox_field = partial( strawberry_django.field, pagination=StartIdPaginationInput, field_cls=StartIdStrawberryDjangoField, ) ``` ```python from netbox.graphql.fields import netbox_field foo_list: list[FooType] = netbox_field() ``` ### Use case The current pagination approach relies on a relative offset. This struggles with very large result sets, because the offset must be calculated by scanning the entire table up to the offset position. Employing an object's unique primary key as a cursor avoids this, as we can leverage simple numeric comparison to filter for all PKs greater than or equal to a given value. Combined with the existing `limit` capability, this affords very efficient pagination at the cost of a fixed (and not very meaningful) ordering. ### Database changes N/A ### External dependencies N/A

MrUnknownDE closed this issue

2026-04-05 16:56:25 +02:00

Sign in to join this conversation.

Branches Tags

main

21455-sql-indexes-audit

21357-register-model-actions

feature

20924-plugin-ui-components

21766-improve-test-coverage-for-sortable-table-columns

21157-export-template-public-models

21025-pre-render-config-contexts

21364-swagger

feature-ip-prefix-link

20911-dropdown-3

fix_module_substitution

21160-filterset

20911-dropdown-2

20044-elevation-stuck-lightmode

7604-filter-modifiers-v3

20660-script-load

19724-graphql

14884-script

19720-macaddress-interface-generic-relation

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

No Label complexity: high complexity: high complexity: high complexity: high complexity: high complexity: high complexity: high complexity: high complexity: high netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox netbox status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted status: accepted type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature type: feature

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/netbox#625