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 } }

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.

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.

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: [...] } }

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).

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.

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 }}

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