Invoke-NBGraphQL
Since
v4.4.10.0
SYNOPSIS
Executes a GraphQL query against the Netbox API.
SYNTAX
Invoke-NBGraphQL [-Query] <String> [-Variables <Hashtable>] [-OperationName <String>] [-ResultPath <String>]
[-Raw] [-Timeout <UInt16>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
Invokes GraphQL queries against Netbox's /graphql/ endpoint. GraphQL provides efficient querying with precise field selection, reducing over-fetching compared to REST.
This function supports: - Raw GraphQL queries with field selection - Parameterized queries with variables - Multiple operations with operation name selection - Result path extraction for convenient data access
Note: Netbox GraphQL is read-only (no mutations available).
EXAMPLES
EXAMPLE 1
Invoke-NBGraphQL -Query '{ site_list { id name } }'
Returns all sites with their id and name fields.
EXAMPLE 2
Invoke-NBGraphQL -Query '{ device_list { id name status } }' -ResultPath 'device_list'
Returns the device array directly, extracting it from the response.
EXAMPLE 3
$query = @'
query GetActiveDevices($limit: Int!, $status: DeviceStatusEnum) {
device_list(
filters: { status: $status }
pagination: { limit: $limit }
) {
id
name
site { name }
primary_ip4 { address }
}
}
'@
Invoke-NBGraphQL -Query $query -Variables @{ limit = 50 status = "STATUS_ACTIVE" } -ResultPath 'device_list'
Fetches active devices with nested site and IP information using variables.
EXAMPLE 4
```
Complex nested query - replaces multiple REST calls
$query = @' { device_list(filters: { role: { name: { exact: "switch" } } }) { name serial site { name region { name } } primary_ip4 { address } interfaces { name ip_addresses { address } } } } '@ ```
$switches = Invoke-NBGraphQL -Query $query -ResultPath 'device_list'
Gets all switches with their site, region, IPs, and interfaces in a single query.
EXAMPLE 5
$result = Invoke-NBGraphQL -Query '{ invalid_field }' -Raw
if ($result.errors) {
Write-Warning "Query errors: $($result.errors.message -join ', ')"
}
Uses -Raw to handle errors manually instead of throwing.
EXAMPLE 6
```
Pagination example
Invoke-NBGraphQL -Query '{ device_list(pagination: { limit: 10, offset: 20 }) { id name } }' ```
Fetches devices 21-30 using GraphQL pagination.
EXAMPLE 7
```
Pipeline support - execute queries from file
Get-Content ./queries.graphql | Invoke-NBGraphQL ```
Executes GraphQL queries read from a file.
PARAMETERS
-Query
The GraphQL query string. Supports: - Simple queries: { device_list { id name } } - Named queries: query GetDevices { device_list { id } } - Parameterized queries: query GetDevices($limit: Int!) { device_list(pagination: {limit: $limit}) { id } }
```yaml Type: String Parameter Sets: (All) Aliases:
Required: True Position: 1 Default value: None Accept pipeline input: True (ByValue) Accept wildcard characters: False ```
-Variables
Hashtable of variables to substitute in parameterized queries. Variables are serialized to JSON and sent with the request.
```yaml Type: Hashtable Parameter Sets: (All) Aliases:
Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ```
-OperationName
The name of the operation to execute when the query contains multiple named operations.
```yaml Type: String Parameter Sets: (All) Aliases:
Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ```
-ResultPath
Dot-notation path to extract specific data from the response. Example: -ResultPath 'device_list' returns the array directly instead of { data: { device_list: [...] } }
```yaml Type: String Parameter Sets: (All) Aliases:
Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ```
-Raw
Return the complete GraphQL response including potential errors array. Without -Raw, only the data property is returned (or throws on errors).
```yaml Type: SwitchParameter Parameter Sets: (All) Aliases:
Required: False Position: Named Default value: False Accept pipeline input: False Accept wildcard characters: False ```
-Timeout
Request timeout in seconds. Defaults to the global timeout set via Set-NBTimeout or Connect-NBAPI. Useful for complex queries that may take longer to execute.
```yaml Type: UInt16 Parameter Sets: (All) Aliases:
Required: False Position: Named Default value: 0 Accept pipeline input: False Accept wildcard characters: False ```
-ProgressAction
{{ Fill ProgressAction Description }}
```yaml Type: ActionPreference Parameter Sets: (All) Aliases: proga
Required: False Position: Named Default value: None Accept pipeline input: False Accept wildcard characters: False ```
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS
OUTPUTS
[PSCustomObject] The query results or extracted data based on ResultPath.
NOTES
AddedInVersion: v4.4.10.0 Requires Netbox 3.0+ for GraphQL support. Advanced filtering syntax (OR/NOT operators, custom fields) requires Netbox 4.3+.
Pagination: - Default limit is 100 items per query (Netbox server default) - Use pagination: { limit: N, offset: M } to control results - For large datasets, implement client-side pagination
Filter Syntax for Netbox 4.3/4.4: - ID filters: { id: 1 } - Enum filters: { status: STATUS_ACTIVE } - Nested filters: { site: { name: { exact: "Amsterdam" } } } - OR filters: { status: STATUS_ACTIVE, OR: { status: STATUS_PLANNED } }
Note: Netbox 4.5+ requires different filter syntax. See wiki for version-specific examples.
Common parameters
common request params
RELATED LINKS
https://netbox.readthedocs.io/en/stable/integrations/graphql/
https://github.com/ctrl-alt-automate/PowerNetbox/wiki/GraphQL-Examples