An Introduction to Infrahub’s GraphQL Query Engine (With FAQs)

If you've spent time building network automation, you know the drill. You need to generate a configuration file, so you write a script that makes an API call to get device data….

Then another call for interface details. Then another for IP addresses. Then you realize you need VLAN info, so that's another call. Before long, you're stitching together 20+ API responses just to populate a single Jinja template.

Each call adds latency, and each response includes fields you don't need. Your code becomes a maze of loops and data transformations, and when requirements change, you're debugging integration logic instead of solving infrastructure problems.

The fundamental issue is that traditional REST APIs force you to work on their terms. You hit predefined endpoints that return fixed data structures. If you need related data, you make another call. If you need to filter or transform that data, you do it in your application code.

Infrahub takes a different approach with GraphQL. Instead of chasing data across multiple endpoints, you describe exactly what you need in one request and get back precisely that structure.

For infrastructure automation, where you're constantly pulling interconnected data about devices, interfaces, IP addresses, and services, this is a huge advantage.

GraphQL in a nutshell

GraphQL is a schema language, first developed at Facebook, that lets you specify the structure of the data you want to receive.

Instead of hitting multiple REST endpoints that each return fixed data structures, you send one request to a single GraphQL endpoint and get back precisely what you asked for.

Why Infrahub chose GraphQL as its query engine

Infrahub is built on a graph database, which means your infrastructure data is stored as interconnected nodes and relationships: devices connect to interfaces, interfaces have IP addresses, IP addresses belong to prefixes, and so on.

GraphQL was designed to query this kind of complex, interconnected data efficiently. That makes it a natural fit for infrastructure, where relationships matter just as much as individual objects.

What makes it particularly powerful in Infrahub is that the GraphQL API is dynamically generated based on your schema.

When you define your infrastructure data model in Infrahub, the system automatically creates corresponding GraphQL queries and mutations for you. You don't ever have to write API code or maintain endpoints. You define your schema, and Infrahub handles the rest.

If you add a custom object type—say, a new kind of network service or a specific device role—it's immediately available through GraphQL. Your custom data model gets a custom API, with no extra work required.

This schema-driven approach also means you get built-in documentation and type safety. Every query you write is validated against your schema, so you catch errors before they reach production.

The GraphQL advantage for AI

GraphQL's schema-driven design turns out to be particularly valuable as we move into an era where AI agents need to interact with infrastructure data.

The key advantage is that GraphQL provides machine-readable documentation through its schema. An AI agent can introspect a GraphQL API to discover what data is available, what types to expect, and how objects relate to each other, all without human guidance.

With a GraphQL interface, AI can discover available data and relationships automatically, curate the exact data slices it needs, and construct precise queries without over-fetching.

How the GraphQL query engine works in Infrahub

Unlike REST APIs that expose multiple endpoints for different resources, GraphQL uses a single endpoint: /graphql. Everything goes through that one entry point.

The GraphQL schema defines what queries are possible and what data types to expect. Because Infrahub generates this schema from your data model, you always know what's available and what structure your responses will have.

When you write a GraphQL query, you specify exactly which fields you want. Here's a simple example:

{
  InfraDevice {
    edges {
      node {
        name {
          value
        }
      }
    }
  }
}

This query retrieves just the names of your devices. Nothing more. If you also need interface information, you add it to the same query:

{
  InfraDevice {
    edges {
      node {
        name {
          value
        }
        interfaces {
          edges {
            node {
              name {
                value
              }
              status {
                value
              }
            }
          }
        }
      }
    }
  }
}

Now you're traversing relationships—from devices to their interfaces—all in one request. You could keep going deeper, adding IP addresses, connected neighbors, or any other related data your schema defines.

GraphQL supports two main types of operations:

• Queries read data. They're what you use when you need to extract information for reports, dashboards, or configuration generation.
• Mutations change data. They handle creating, updating, or deleting objects.

The structure of your response always matches the structure of your query, which makes parsing straightforward and predictable.

Common use cases for GraphQL in Infrahub

The GraphQL query engine shines when you need to gather complex, interconnected data quickly. Here are some scenarios where it makes a real difference.

• Configuration generation: Efficiency gains are really obvious here. Generating a device configuration with a REST API means making separate calls for each bit of data you want, and getting back lots of data you don't need. With GraphQL, you write one query that requests all the data your Jinja template needs. You get exactly those fields in a single response, which you can feed directly into your template. It's faster to execute and much easier to maintain.
• Topology mapping: GraphQL makes it straightforward to traverse network relationships. You can query a device, follow its interface connections to neighboring devices, and map out your topology in a single request. This is useful for building network diagrams, validating connectivity, or understanding impact before making changes.
• Compliance and validation: Need to find all interfaces with a specific status? Or check whether every router has a loopback address configured? GraphQL filters let you target exactly what you're looking for across hundreds or thousands of objects. You can write queries that check for compliance with your standards and return only the exceptions that need attention.
• Integration with CI/CD pipelines: When your automation pipeline needs infrastructure data to generate artifacts, GraphQL reduces the API overhead. Fewer calls mean faster pipelines and less complexity in your integration code. Since the GraphQL schema includes type information, it's also easier to validate that your pipeline is requesting the correct data.
• Audit and troubleshooting: Infrahub's GraphQL API lets you query not just data but also metadata: who changed a value, when, and why. You can trace configuration values back to their source, whether that's a standard, an override, or an imported value from another system. This makes troubleshooting faster and gives you a clear audit trail for compliance.

GraphQL query engine FAQs

Ready to try GraphQL in Infrahub?

• Explore the Infrahub sandbox: Try GraphQL queries with sample data. The sandbox includes auto-complete and documentation to help you get started.
• Learn GraphQL basics: New to GraphQL? Start with GraphQL Basics: Queries, Mutations, and API Efficiency for Engineers to understand the fundamentals.
• Watch the intro video: See Infrahub CEO Damien Garros walk through queries, filters, and mutations in the GraphQL playground. It's hands-on and beginner-friendly.
• Read the GraphQL documentation: The Infrahub GraphQL docs cover syntax, examples, and best practices.
• Join the community: Connect with other Infrahub users on Discord to ask questions and share what you're building. The community is active and ready to help you get the most out of the GraphQL query engine.