GraphQL Queries

Query data from Infrahub using GraphQL queries with filtering, pagination, and relationship traversal

Infrahub provides a comprehensive GraphQL API for querying nodes, relationships, and metadata. All queries support filtering, pagination, and nested relationship traversal.

Basic Query Structure

Query any node type using its kind name. The API returns paginated results with edges containing the actual nodes.

query {
  BuiltinTag {
    count
    edges {
      node {
        id
        name {
          value
        }
        description {
          value
        }
      }
    }
  }
}

Core Query Types

Branch Queries

Retrieve information about branches in your Infrahub instance.

query {
  Branch(name: "main") {
    id
    name
    description
    created_at
    branched_from
    is_default
    status
    has_schema_changes
  }
}

ids · [ID]

Filter branches by their IDs

name · String

Filter by branch name

Account Profile Query

Get information about the currently authenticated account.

query {
  AccountProfile {
    id
    name {
      value
    }
    account_type {
      value
    }
    display_label
  }
}

IP Address Queries

Query IP addresses with rich filtering options.

query {
  BuiltinIPAddress(
    address__value: "192.168.1.1"
    limit: 10
    offset: 0
  ) {
    count
    edges {
      node {
        id
        display_label
        address {
          value
        }
        ip_namespace {
          node {
            name {
              value
            }
          }
        }
        ip_prefix {
          node {
            prefix {
              value
            }
          }
        }
      }
    }
  }
}

address__value · String

Filter by exact IP address value

address__values · [String]

Filter by multiple IP address values

ip_namespace__name__value · String

Filter by IP namespace name

ip_prefix__prefix__value · String

Filter by parent prefix CIDR notation

IP Prefix Queries

Query IP prefixes with hierarchical relationships.

query {
  BuiltinIPPrefix(
    prefix__value: "10.0.0.0/8"
    is_top_level__value: true
  ) {
    count
    edges {
      node {
        id
        prefix {
          value
        }
        network_address {
          value
        }
        broadcast_address {
          value
        }
        netmask {
          value
        }
        is_pool {
          value
        }
        utilization {
          value
        }
        children(limit: 10) {
          count
          edges {
            node {
              prefix {
                value
              }
            }
          }
        }
      }
    }
  }
}

Attribute Access

All node attributes in Infrahub are objects with metadata. Access the actual value using the .value field.

query {
  CoreAccount {
    edges {
      node {
        name {
          value           # The actual value
          is_protected    # Whether the attribute is protected
          is_default      # Whether this is the default value
          updated_at      # When the attribute was last updated
          source {        # Source of the attribute value
            id
          }
          owner {         # Owner of the attribute
            id
          }
        }
      }
    }
  }
}

Relationship Traversal

Traverse relationships between nodes using nested queries.

query {
  CoreAccountGroup {
    edges {
      node {
        id
        name {
          value
        }
        members(limit: 20) {
          count
          edges {
            node {
              ... on CoreAccount {
                name {
                  value
                }
                account_type {
                  value
                }
              }
            }
          }
        }
        roles {
          edges {
            node {
              name {
                value
              }
            }
          }
        }
      }
    }
  }
}

Metadata Filtering

Filter nodes by creation and update metadata.

query {
  BuiltinTag(
    node_metadata__created_at__after: "2024-01-01T00:00:00Z"
    node_metadata__updated_by__id: "abc-123-def"
  ) {
    edges {
      node {
        id
        name {
          value
        }
      }
    }
  }
}

node_metadata__created_at · DateTime

Filter by exact creation timestamp

node_metadata__created_at__after · DateTime

Filter for objects created after this timestamp

node_metadata__created_at__before · DateTime

Filter for objects created before this timestamp

node_metadata__updated_at · DateTime

Filter by exact update timestamp

node_metadata__updated_at__after · DateTime

Filter for objects updated after this timestamp

node_metadata__updated_at__before · DateTime

Filter for objects updated before this timestamp

node_metadata__created_by__id · ID

Filter by creator account UUID

node_metadata__updated_by__id · ID

Filter by updater account UUID

Common Parameters

These parameters are available on most queries:

ids · [ID]

Filter by a list of node IDs

limit · Int

Maximum number of results to return (pagination)

offset · Int

Number of results to skip (pagination)

order · OrderInput

Ordering configuration for results. See Pagination for details.

partial_match · Boolean

Enable partial string matching for text filters (default: false)

display_label__value · String

Filter by display label

any__value · String

Search across all text attributes

Response Structure

All paginated queries return a consistent structure:

count · Int!

Total number of matching results

edges · [Edge!]!

Array of edges containing the nodes and relationship metadata

permissions · PaginatedObjectPermission

Permission information for the current user on this query

Each edge contains:

node · Object

The actual node data

Example: Complex Query

query ComplexIPAMQuery {
  BuiltinIPPrefix(
    prefix__value: "10.0.0.0/8"
    is_pool__value: true
    member_type__value: "address"
    limit: 50
  ) {
    count
    edges {
      node {
        id
        display_label
        prefix {
          value
          is_protected
          updated_at
        }
        utilization {
          value
        }
        ip_namespace {
          node {
            name {
              value
            }
          }
        }
        ip_addresses(limit: 10) {
          count
          edges {
            node {
              address {
                value
              }
              description {
                value
              }
            }
          }
        }
        member_of_groups {
          edges {
            node {
              name {
                value
              }
            }
          }
        }
      }
    }
  }
}

See Also

• Mutations - Create, update, and delete nodes
• Filtering - Advanced filtering techniques
• Pagination - Pagination and ordering patterns
• Subscriptions - Real-time updates via WebSocket