Infrahub’s GraphQL API provides powerful filtering capabilities using a double-underscore syntax for attribute-level filters and relationship traversal.
Filter Syntax
Filters use a field__operator__subfield pattern:
query {
BuiltinIPAddress(
address__value: "192.168.1.1"
description__isnull: false
) {
edges {
node {
id
}
}
}
}
Attribute Filters
Value Filters
Filter by exact attribute value:
query {
CoreAccount(
name__value: "admin"
account_type__value: "User"
) {
edges {
node {
id
name {
value
}
}
}
}
}
Exact match on the attribute value
Match any value in the provided list (OR operation)
Multiple Values (OR)
Filter for nodes matching any of several values:
query {
BuiltinTag(
name__values: ["production", "staging", "development"]
) {
edges {
node {
name {
value
}
}
}
}
}
Null Checks
Filter for null or non-null values:
query {
CoreAccount(
description__isnull: false
label__isnull: true
) {
edges {
node {
id
}
}
}
}
true to match null values, false to match non-null values
Protected Status
Filter by whether an attribute is protected:
query {
BuiltinIPAddress(
address__is_protected: true
) {
edges {
node {
address {
value
is_protected
}
}
}
}
}
Filter by protected status of the attribute
Relationship Filters
Direct Relationship
Filter based on related node attributes:
query {
BuiltinIPAddress(
ip_namespace__name__value: "default"
ip_prefix__prefix__value: "10.0.0.0/8"
) {
edges {
node {
address {
value
}
ip_namespace {
node {
name {
value
}
}
}
}
}
}
}
Multiple Relationship Filters
Combine multiple relationship filters:
query {
CoreArtifact(
definition__name__value: "device-config"
object__display_label__value: "edge-router-01"
status__value: "completed"
) {
edges {
node {
name {
value
}
}
}
}
}
Null Relationships
Filter for nodes with or without relationships:
query {
BuiltinIPPrefix(
parent__isnull: true # Top-level prefixes only
) {
edges {
node {
prefix {
value
}
}
}
}
}
true for nodes without this relationship, false for nodes with it
Relationship IDs
Filter by related node IDs:
query {
CoreAccount(
member_of_groups__ids: ["group-id-1", "group-id-2"]
) {
edges {
node {
name {
value
}
}
}
}
}
Filter by list of related node IDs
Lineage Filters
Source Filter
Filter by the source of an attribute value:
query {
BuiltinTag(
name__source__id: "source-node-id"
) {
edges {
node {
name {
value
source {
id
}
}
}
}
}
}
Filter by source node ID for lineage tracking
Owner Filter
Filter by the owner of an attribute:
query {
CoreAccount(
description__owner__id: "owner-account-id"
) {
edges {
node {
description {
value
owner {
id
}
}
}
}
}
}
Filter by owner node ID for lineage tracking
Text Search
Partial Match
Enable partial string matching:
query {
CoreAccount(
name__value: "admin"
partial_match: true
) {
edges {
node {
name {
value
}
}
}
}
}
Enable partial/substring matching for text filters (default: false)
Any Field Search
Search across all text attributes:
query {
BuiltinTag(
any__value: "prod"
partial_match: true
) {
edges {
node {
name {
value
}
description {
value
}
}
}
}
}
Search across all text attributes of the node
Display Label Filter
Filter by the computed display label:
query {
CoreAccount(
display_label__value: "Administrator"
) {
edges {
node {
display_label
}
}
}
}
Filter for null/non-null display labels
Creation Time
Filter by when nodes were created:
query {
BuiltinTag(
node_metadata__created_at__after: "2024-01-01T00:00:00Z"
node_metadata__created_at__before: "2024-12-31T23:59:59Z"
) {
edges {
node {
id
}
}
}
}
node_metadata__created_at
Filter by exact creation timestamp
node_metadata__created_at__after
Filter for nodes created after this timestamp
node_metadata__created_at__before
Filter for nodes created before this timestamp
Update Time
Filter by when nodes were last updated:
query {
CoreAccount(
node_metadata__updated_at__after: "2024-06-01T00:00:00Z"
) {
edges {
node {
id
name {
value
}
}
}
}
}
node_metadata__updated_at
Filter by exact update timestamp
node_metadata__updated_at__after
Filter for nodes updated after this timestamp
node_metadata__updated_at__before
Filter for nodes updated before this timestamp
Creator/Updater
Filter by account that created or updated the node:
query {
BuiltinTag(
node_metadata__created_by__id: "account-id-123"
node_metadata__updated_by__ids: ["account-id-456", "account-id-789"]
) {
edges {
node {
id
}
}
}
}
node_metadata__created_by__id
Filter by creator account UUID
node_metadata__created_by__ids
Filter by list of creator account UUIDs
node_metadata__updated_by__id
Filter by updater account UUID
node_metadata__updated_by__ids
Filter by list of updater account UUIDs
Advanced Filters
ID Filters
Filter by node IDs:
query {
CoreAccount(
ids: ["id-1", "id-2", "id-3"]
) {
edges {
node {
id
}
}
}
}
Filter by list of node IDs
Human-Friendly ID (HFID)
Filter by human-friendly identifiers:
query {
BuiltinIPPrefix(
hfid: ["10.0.0.0/8", "default"]
) {
edges {
node {
id
hfid
}
}
}
}
Filter by human-friendly identifier components
Kind Filter
Filter by node kind (useful for polymorphic queries):
query {
BuiltinIPAddress(
kinds: ["BuiltinIPAddress"]
) {
edges {
node {
id
}
}
}
}
Filter by list of node kind names
Combining Filters
All filters combine with AND logic:
query ComplexFilter {
BuiltinIPPrefix(
# Must match ALL of these conditions
prefix__value: "10.0.0.0/8"
is_pool__value: true
member_type__value: "address"
ip_namespace__name__value: "production"
node_metadata__created_at__after: "2024-01-01T00:00:00Z"
utilization__value: 50
) {
edges {
node {
id
prefix {
value
}
}
}
}
}
Index Usage
Some filters perform better than others:
- ✅ Fast: Exact value matches, ID lookups, null checks
- ⚠️ Moderate: Relationship traversal, metadata filters
- ⚠️ Slower: Partial text matching,
any__value searches
Best Practices
- Start specific: Use ID or exact value filters when possible
- Limit results: Always use
limit parameter for large result sets
- Avoid wildcards: Partial matching is slower than exact matches
- Index relationships: Filter on indexed relationship fields first
Example: Production IP Prefixes
query ProductionPrefixes {
BuiltinIPPrefix(
# In production namespace
ip_namespace__name__value: "production"
# Is a pool
is_pool__value: true
# Under 80% utilization
utilization__value: 80
# Created this year
node_metadata__created_at__after: "2024-01-01T00:00:00Z"
# Not deleted
display_label__isnull: false
# Tagged appropriately
member_of_groups__name__value: "ipam-managed"
# Paginate
limit: 50
offset: 0
) {
count
edges {
node {
prefix {
value
}
utilization {
value
}
ip_namespace {
node {
name {
value
}
}
}
}
}
}
}
See Also