Filtering and Search

Advanced filtering techniques for GraphQL queries in Infrahub

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

{field}__value · Any

Exact match on the attribute value

{field}__values · [Any]

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

{field}__isnull · Boolean

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

{field}__is_protected · Boolean

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

{relationship}__isnull · Boolean

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

{relationship}__ids · [ID]

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

{field}__source__id · 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
          }
        }
      }
    }
  }
}

{field}__owner__id · 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
        }
      }
    }
  }
}

partial_match · Boolean

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

any__value · String

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

display_label__value · String

Filter by display label

display_label__isnull · Boolean

Filter for null/non-null display labels

Metadata Filters

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 · DateTime

Filter by exact creation timestamp

node_metadata__created_at__after · DateTime

Filter for nodes created after this timestamp

node_metadata__created_at__before · DateTime

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 · DateTime

Filter by exact update timestamp

node_metadata__updated_at__after · DateTime

Filter for nodes updated after this timestamp

node_metadata__updated_at__before · DateTime

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 · ID

Filter by creator account UUID

node_metadata__created_by__ids · [ID]

Filter by list of creator account UUIDs

node_metadata__updated_by__id · ID

Filter by updater account UUID

node_metadata__updated_by__ids · [ID]

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

ids · [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
      }
    }
  }
}

hfid · [String]

Filter by human-friendly identifier components

Kind Filter

Filter by node kind (useful for polymorphic queries):

query {
  BuiltinIPAddress(
    kinds: ["BuiltinIPAddress"]
  ) {
    edges {
      node {
        id
      }
    }
  }
}

kinds · [String]

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

Performance Considerations

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

1. Start specific: Use ID or exact value filters when possible
2. Limit results: Always use limit parameter for large result sets
3. Avoid wildcards: Partial matching is slower than exact matches
4. 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

• Queries - Query data from Infrahub
• Pagination - Pagination and ordering
• GraphQL Schema Reference - Complete schema documentation