Infragraph query language reference

The query language allows users to traverse the graph, filter nodes by properties, and navigate edges between resources.

Refer to Example queries for a collection of example queries.

Query model

Infragraph queries are a JSON body with a top level query object, which is structured as a nested sequence of alternating node and edge blocks, defining a traversal path through the graph. The top-level node object defines the starting node in the traversal, and the top-level edge block finds nodes that match the defined relationship. Each edge block contains a nodeQuery block, where you can continue to next node and edge blocks to traverse the graph.

Infragraph supports a maximum traversal depth of 20 nodes.

The following list defines the specification for a query:

node: map | required
- unifiedTypes: list[string] | required unless sourceTypes defined
- sourceTypes: list[string] | required unless unifiedTypes defined
- ids: list[string] | optional
- alias: string | optional
- where: list[match and filterGroup objects] | optional
  - match map | required unless [filterGroup] defined
    - left: map | required
      - property: map | required
        name: string | required
        alias: string | optional
    - comparator: string | required
    - right: map | required
      - value: map | required unless valueList defined
      - valueList map | required unless value defined
        values list[value] | required
  - filterGroup map | required unless match defined
    - operator string | required
    - filter list[match] | required
edge: map | required
- edgeTypes: list[string] | required
- direction: string | required
- absent: boolean | optional
- nodeQuery: map | required
  - node: map | required
  - edge: map | optional

Complete model

The following query includes all supported arguments:

{
  "node": {
    "sourceTypes": [ "<VALUE>" ],
    "alias": "<VALUE>",
    "where": [
      {
        "filterGroup": {
          "operator": "<OPERATOR>",
          "filter": [
            {
              "match": {
                "left": { "property": { "name": "<VALUE>" } },
                "comparator": "<COMPARATOR>",
                "right": { "valueList": { "values": [ 
                  { "string": "<VALUE>" },
                  { "string": "<VALUE>" }
                ]}}
              }
            },
            {
              "match": {
                "left": { "property": { "name": "<VALUE>" } },
                "comparator": "<COMPARATOR>",
                "right": { "value": { "string": "<VALUE>" } }
              }
            }
          ]
        }
      }
    ]
  },
  "edge": {
    "direction": "<DIRECTION>",
    "nodeQuery": {
      "node": {
        "unifiedTypes": [ "<VALUE>" ],
        "ids": ["<VALUE>", "<VALUE>"],
        "alias": "<VALUE>",
        "where": [
          {
            "match": {
              "left": { "property": { "alias": "<REFERENCE.TO.ALIAS>", "name": "<VALUE>" } },
              "comparator": "EQUAL",
              "right": { "property": { "alias": "<REFERENCE.TO.ALIAS>", "name": "<VALUE>" } }
            }
          }
        ]
      }
    },
    "edgeTypes": [ "<EDGE.TYPE>" ]
  }
}

Specification

This section provides details about the fields used to create a JSON-based Infragraph query.

node

A node block defines which nodes to match at the current step of the traversal. You must specify at least one of unifiedTypes or sourceTypes, and may optionally provide a specific ids filter.

Default: None
This field is required
Data type: Object containing at least one unifiedTypes or sourceTypes. You may define both.
- unifiedTypes: Matches nodes based on their generalized abstract type across providers. Supports a single "*" wildcard per query to match any node type.
- sourceTypes: Matches nodes based on their exact provider-specific type. Does not support wildcards.
- ids: Matches specific graph node IDs. Does not support wildcards.
- where: A list of property filters to apply to the matched nodes.

These dimensions are combined using a logical AND. For example, providing both unifiedTypes=["VIRTUAL_MACHINE"] and sourceTypes=["AWS_EC2_INSTANCE"] looks for nodes that satisfy both constraints.

The following is an example of a node block:

{
  "node": {
    "unifiedTypes": ["VIRTUAL_MACHINE"],
    "where": [
      {
        "match": {
          "left": { "property": { "name": "status" } },
          "comparator": "EQUAL",
          "right": { "value": { "string": "running" } }
        }
      }
    ]
  }
}

unifiedTypes

Matches nodes based on their generalized abstract type across providers, such as ["VIRTUAL_MACHINE"]. Supports a single "*" wildcard per query to match any node type.

Default: None
This field is required unless you define sourceTypes. You may define both.
Data type: List of strings
Supports a maximum of 5 elements

sourceTypes

Matches nodes based on their exact provider-specific type, such as ["AWS_EC2_INSTANCE"]. Does not support wildcards.

Default: None
This field is required unless you define unifiedTypes. You may define both.
Data type: List of strings
Supports a maximum of 5 elements

ids

Matches specific graph node IDs. Does not support wildcards.

Default: None
Data type: List of strings
Supports a maximum of 10 elements

alias

Optional reference alias to assign to this node. You can reference this alias in left or right blocks in a where clause to perform comparisons between a property on the current node and a property on an aliased node from earlier in the traversal.

Default: None
Data type: string

where

A list of property filters to apply to the matched nodes. Infragraph matches top-level entries in a where block with a logical AND operator. Use a filterGroup to match multiple filters with an OR operator.

You can combine multiple filterGroup blocks to create a combination of AND and OR operators. For example, to match the logic of (A OR B) AND (C OR D) you can create one filterGroup to match at least one A or B filter, and it must also match one of the C or D filters.

Default: None
Data type: A list of match and filterGroup objects
Supports a maximum of 10 elements

match

Finds a node object that satisfies every match clause or the filterGroup clause.

Default: None
Data type: map
- left: The property to inspect.
- comparator: The operation to perform.
- right: The value to compare against the left value.

The following is an example match clause using the IN comparator:

{
  "match": {
    "left": { "property": { "name": "region" } },
    "comparator": "IN",
    "right": {
      "valueList": {
        "values": [
          { "string": "us-east-1" },
          { "string": "us-west-2" }
        ]
      }
    }
  }
}

left

The property to inspect in a match clause.

Default: None
Data type: One property object

property

Each property object contains the following fields:

Field	Description	Required
`name`	The name of the property to compare to the value defined in the `right` field	Yes
`alias`	Identifies a node elsewhere in the traversal so that the filter compares against that node's property rather than the current node	No

To reference a node by an alias, both the left and right properties of a match clause must refer to nodes by alias. The following is an example of a match clause that refers to a node by alias:

"match": {
  "left": { "property": { "alias": "vm", "name": "tags.Environment" } },
  "comparator": "EQUAL",
  "right": { "property": { "alias": "group", "name": "tags.Environment" } }
}

comparator

The operation to perform to compare the values of the left and right fields of a match clause.

Default: None
Data type: string

Refer to Comparators for more information on the supported comparators.

right

The value to compare against the left value.

Default: None
Data type: One of property, value, or valueList

Refer to property for information on the property field.

A value is an object that contains exactly one data type and one value. The following is a list of example value objects:

"right": { "value": { "string": "us-east-1" } }
"right": { "value": { "int": 42 } }
"right": { "value": { "float": 1.5 } }
"right": { "value": { "bool": true } }
"right": { "value": { "timestamp": "2025-02-07T23:00:00-01:00" } }

A valueList is a list of value objects. Infragraph only supports valueList objects when you set the comparator to IN or NOT_IN. This block supports a maximum of 10 elements, and all elements must be of the same type.

The following is a an example right object that provides a valueList:

"right": {
  "valueList": {
    "values": [
      { "string": "us-east-1" },
      { "string": "us-west-2" }
    ]
  }
}

Defines one operator and one or more filter used to refine the results of the traversal.

Default: None
Data type: Object containing one operator and one filter.
- One required operator. Must be a string with the value AND or OR.
- One required filter. Must be a list of match blocks.
Supports a maximum of 10 filter blocks

The following example defines a filterGroup with two filters. Since the operator is set to OR, this filter group returns nodes that match either filter:

{
  "filterGroup": {
    "operator": "OR",
    "filter": [
      {
        "match": {
          "left": { "property": { "name": "environment" } },
          "comparator": "EQUAL",
          "right": { "value": { "string": "production" } }
        }
      },
      {
        "match": {
          "left": { "property": { "name": "is_critical" } },
          "comparator": "EQUAL",
          "right": { "value": { "bool": true } }
        }
      }
    ]
  }
}

edge

An edge block dictates how to traverse from the currently matched node to the next set of nodes.

Default: None
Data type: Object
- One required edgeTypes. Supports a single * wildcard per query for any edge type.
- One required direction.
- One optional absent.
- One required nodeQuery.

The following is an example of an edge block:

{
  "edge": {
    "edgeTypes": ["ATTACHES_TO"],
    "direction": "OUTGOING",
    "nodeQuery": {
      "node": {
        "unifiedTypes": ["ROLE"]
      }
    }
  }
}

edgeTypes

The relationships to traverse, such as ["MANAGES", "CONTAINS"]. Supports a single * wildcard per query for any edge type.

Default: None
This field is required
Data type: List of strings
Supports a maximum of 5 elements

Infragraph supports the following edge types:

direction

The direction of the relationship to traverse.

Default: OUTGOING
This field is required

The following is a list of valid values for this field:

absent

If set to true, the query behaves as a NOT step, matching nodes that do not have the specified edge.

Default: None
Data type: boolean

nodeQuery

The nested next step in the traversal, containing another node and optional edge.

Default: None
Data type: Object containing one node object.

Comparators

Infragraph supports the following comparators:

Comparator	Right operand	Allowed value types	Notes
`EQUAL`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Exact equality.
`NOT_EQUAL`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Inverse of `EQUAL`.
`GREATER_THAN`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Ordered comparison.
`LESS_THAN`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Ordered comparison.
`GREATER_THAN_OR_EQUAL`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Ordered comparison.
`LESS_THAN_OR_EQUAL`	`value` or `property`	`string`, `int`, `float`, `bool`, `timestamp`	Ordered comparison.
`EXISTS`	None	None	Right operand must be omitted entirely.
`DOES_NOT_EXIST`	None	None	Right operand must be omitted entirely.
`IS_NOT_EMPTY`	None	None	Right operand must be omitted entirely.
`IN`	`valueList` (required)	`string`, `int`, `float` (homogeneous list)	`bool` and `timestamp` values are rejected inside `valueList`.
`NOT_IN`	`valueList` (required)	`string`, `int`, `float` (homogeneous list)	Same restrictions as `IN`.
`STARTS_WITH`	`value` (required)	`string` only, non-empty	Right value must be a non-empty `string` ≤ 1024 chars; any other type/shape is rejected.

Limitations

The Query API enforces the following structural limits on queries. If you exceed these limits, Infragraph returns a 400 Bad Request response containing detailed field violations.

Traversal Depth: Maximum 20 nested node/edge pairs.
Node Filters:
- unifiedTypes: Maximum 5 elements.
- sourceTypes: Maximum 5 elements.
- ids: Maximum 10 elements.
- Only 1 wildcard (*) is allowed across all node types in the entire query.
Edge Filters:
- edgeTypes: Maximum 5 elements.
- Only 1 wildcard (*) is allowed across all edge types in the entire query.
Predicates (where clauses):
- Maximum 10 items in a single where list.
- Maximum 10 items inside a single filterGroup.
- Maximum predicate nesting depth of 10.
Values:
- String values in filters cannot exceed 1024 characters.
- valueList (for IN/NOT_IN) is limited to a maximum of 10 values, and all values must be of the exact same type.
Property Mask:
- The node_properties string cannot exceed 2048 characters.