Graph Traversal
Relevant source files
The following files were used as context for generating this wiki page:
Graph Traversal provides the logic for navigating and querying infrastructure data within Infrahub. It abstracts the underlying GraphQL complexities, allowing developers to interact with nodes and their relationships through structured Python objects. This module is essential for data retrieval, transformation, and validation tasks that depend on the interconnected nature of infrastructure entities.
The system relies on a combination of query rendering, repository configuration, and specific exception handling to ensure that graph queries are constructed correctly and executed efficiently.
Sources: infrahub_sdk/graph_traversal/query.py, infrahub_sdk/graph_traversal/models.py, tasks.py:180-185
Architecture and Core Components
The Graph Traversal architecture follows a layered approach, separating query construction from execution and error handling. It utilizes Pydantic models for configuration and the graphql-core library for syntax validation and node manipulation.
Component Overview
| Component | Description |
|---|---|
| Query Renderer | Manages the inlining of GraphQL fragments and the rendering of final query strings. |
| Repository Config | Defines how GraphQL queries and fragments are declared in .infrahub.yml. |
| Exception Hierarchy | Provides specific error types for syntax, missing fragments, and circular dependencies. |
| CLI Integration | Enables local execution of graph queries via infrahubctl. |
Sources: infrahub_sdk/graphql/query_renderer.py:40-60, infrahub_sdk/schema/repository.py:20-45, specs/infp-496-graphql-fragment-inlining/tasks.md:40-55
Data Flow for Query Rendering
The following diagram illustrates how the SDK processes a GraphQL query by resolving and inlining required fragments before execution.
GraphQL Fragment Inlining
The SDK implements fragment inlining to allow modular GraphQL development. Developers define fragments in separate files, and the SDK automatically includes only the necessary definitions in the final query sent to the server.
Fragment Resolution Logic
- Index Building: The SDK parses all configured fragment files into
FragmentDefinitionNodeobjects. - Dependency Mapping: It identifies direct spreads (e.g.,
...interfaceFragment) within the main query. - Transitive Resolution: If
Fragment AspreadsFragment B, the system ensures both are collected even if the query only referencesFragment A. - Deduplication: The renderer ensures each fragment definition appears only once in the final string, even if referenced multiple times.
Sources: infrahub_sdk/graphql/query_renderer.py:65-90, specs/infp-496-graphql-fragment-inlining/tasks.md:65-75
Exception Handling
Graph traversal operations use a specialized exception hierarchy rooted in GraphQLQueryError. This allows consumers to handle specific failure modes during query preparation.
| Exception Class | Cause |
|---|---|
QuerySyntaxError | Invalid GraphQL syntax in a query or fragment file. |
FragmentNotFoundError | A spread references a name that does not exist in any fragment file. |
DuplicateFragmentError | The same fragment name is defined in multiple locations. |
CircularFragmentError | A circular dependency exists (e.g., A spreads B, and B spreads A). |
FragmentFileNotFoundError | The path specified in the configuration does not exist. |
Sources: infrahub_sdk/exceptions.py, specs/infp-496-graphql-fragment-inlining/tasks.md:40-48
Repository Configuration
Repository configuration defines the location and structure of queries and fragments. These settings are stored in InfrahubRepositoryConfig, typically populated from an .infrahub.yml file.
Configuration Model
The InfrahubRepositoryFragmentConfig class handles the loading of fragment content. It supports both individual file paths and directory paths. When a directory is provided, it loads all .gql files in alphabetical order.
# Example Fragment Configuration in InfrahubRepositoryConfig
graphql_fragments: list[InfrahubRepositoryFragmentConfig] = Field(default_factory=list)
Sources: infrahub_sdk/schema/repository.py:50-65, specs/infp-496-graphql-fragment-inlining/tasks.md:50-55
CLI and Local Execution
The infrahubctl CLI integrates graph traversal through the execute_graphql_query and transform paths. Before a query is executed locally, the CLI calls the render_query entry point.
Execution Flow
When a user runs a command like infrahubctl run, the following sequence occurs:
Conclusion
Graph Traversal in the Infrahub Python SDK provides a robust mechanism for managing complex infrastructure queries. By automating fragment inlining and enforcing strict syntax and dependency validation, the system reduces boilerplate for developers while ensuring query integrity. The integration with the repository configuration and CLI tools makes it a central component for both automated pipelines and interactive data exploration.
Sources: tasks.py:180-185, AGENTS.md:15-25