netbox-graphql

NetBox GraphQL Best Practices

Use Query Optimizer (CRITICAL)

Always use netbox-graphql-query-optimizer to analyze queries before production.

pip install netbox-graphql-query-optimizer
netbox-query-optimizer analyze query.graphql --config optimizer.yaml

Always Paginate (CRITICAL)

Every list query MUST have pagination limits.

# WRONG: No pagination
query {
  device_list {
    name
    interfaces { name }
  }
}

# CORRECT: Explicit pagination
query {
  device_list(first: 100) {
    name
    interfaces(first: 50) { name }
  }
}

Paginate at Every Nesting Level (HIGH)

Nested lists multiply result sizes exponentially.

# WRONG: Unpaginated nested lists
query {
  site_list(first: 10) {
    devices { interfaces { ip_addresses { ... } } }
  }
}

# CORRECT: Pagination at each level
query {
  site_list(first: 10) {
    devices(first: 50) {
      interfaces(first: 20) {
        ip_addresses(first: 10) { ... }
      }
    }
  }
}

Offset Pagination Degrades at Scale (HIGH)

NetBox uses offset pagination which slows as you paginate deeper:

Offset	Impact
0-1000	Fast
10,000+	Slow
100,000+	Timeout risk

Version-specific strategies:

Version	Strategy
4.4.x	Offset only (avoid deep pagination)
4.5.0-4.5.1	ID range filtering workaround
4.5.2+	Cursor-based (start param) - #21110

4.5.2+ cursor-based pagination - Use the start parameter with the primary key:

query GetDevices($startPk: Int, $limit: Int!) {
  device_list(pagination: { start: $startPk, limit: $limit }) {
    id  # Track max(id) for next page's start value
    name
  }
}

The start parameter yields: Device.objects.order_by('pk').filter(pk__gte=start)[:limit]

For the next page, use start = max(id) + 1 from the previous result.