Query Builder Parameters

Options for saved and spec query requests

When calling query spec endpoints or saving a query, you will specify the search parameters in a JSON object in the request body. Saved queries and query specifications support a range of parameters and options, described in this document.

Queries begin with a source node type and optionally a destination node type. A simple query might show "all Okta users with relationships to S3 Buckets". A more advanced query will add additional constraints on entity attributes or tags, or filter on relationships to intermediate entities, such as a role, group, or local user.

Most requests will return entities of the source node type. Use GetAssessmentQuerySpecDestinationNodes or GetAssessmentQueryDestinationNodes to return related entities for an individual source entity in a query result.

As the Veza Query Builder uses these APIs, you can preview different sample requests and responses by constructing queries from the web interface, opening the Save dropdown menu, and choosing View Query Spec API.

Query parameters

Field	Type	Notes
all_entity_condition	ConditionExpression object	A constraint to apply on all entities that happen to be a part of the query result (specified or not)
analysis_type	string	For built-in queries, indicates where the query originated (Query Builder or the Analysis page). Values can be UNSET USER GROUP ROLE or SEPARATION_OF_DUTY
avoided_intermediate_node_types	NodeSpecCollection	Any entity types that cannot exist in the path between the query source and destination.
description	string	A description of the assessment query, shown in the query details.
destination_node_types	NodeSpecCollection	If specified, results only include entities with a relationship to the destination node type.
effective_permissions	Effective Permission Collection	Effective permissions to search, and operator to use.
labels	array of strings	List of assessment labels for categorization in reports.
name	string	The name of the assessment query, shown in the Veza UI.
no_relation	boolean	deprecated (use relates_to_exp)
node_relationship_type	string	Query mode EFFECTIVE_ACCESS (default) or CONFIGURED.
query_type	string	always use SOURCE_TO_DESTINATION
raw_permissions	Raw Permission Collection	If specified, only return results that have the listed raw permissions.
relates_to_exp	RelatesToExp object	Specify related note constraints
required_intermediate_node_types	NodeSpecCollection	Specifies requirements for the path connecting the source and destination nodes.
risk_level	string	Sets whether results are marked as risks based on the risk level: NONE (default), WARNING, or CRITICAL
risk_suppressed_constraints	RiskSuppressedConstraintsCollection object	Adds a risk exception for nodes matching the specification.
source_node_types	NodeSpecCollection	The source node type to return as results for SOURCE_TO_DESTINATION queries (for example AwsIamUser). Required to have only 1.
violation	boolean	Deprecated, use risk_level instead
visibility	string	Sets whether a query is public or visible only to owners. PUBLIC (default) or PRIVATE
include_nodes	boolean	When true, only return a result count.

NodeSpecCollection

A collection of node specifications, defining constraints or other query parameters on each entity type.

You can query for a single principal or resource by filtering on node ID.

Field	Type	Notes
nodes	node spec array	Contains an object for each node type
nodes_operator	string	Sets whether all or any of the node conditions must be true (AND(default), OR).

NodeSpec

Contains the type, tags, and conditions applied to a node, narrowing the focus of the query.

Note that you can add conditions and tags to either the source node type or the destination.

Field	Type	Notes
condition_expression	ConditionExpression object	Logical tree of constraints to apply
conditions	array	Deprecated, use condition_expression
count_conditions	array	Count condition functions and values. count_conditions are only accepted in assessment queries, when the node spec defines destination_node_types.
direct_relationship_only	boolean	When set to true, self-referential edges on this node type will not be traversed. For example, if the node type is Role and direct_relationship_only is true, then any edge Role -> Role will be ignored. Can only be used with destination or source node types with self-referential edges. Cannot be used with labels.
excluded_tags	Tags array	tags to exclude from results.
node_id	string	For specifying an individual entity, a single graph entity ID
node_type	string	Concrete node type (e.g. AwsIamUser) or node label (e.g. User)
node_type_grouping_constraint	NodeTypeGroupingConstraint object	Contains an operator and list of node types to include or exclude
tags	Tags array	tags to require, specified with key value pairs.

NodeTypeGroupingConstraint

Query specs support supertypes with constraints. They can specified in the same way as concrete node types. node_type_grouping_constraint can be used to limit the concrete node type set belonging to the specified super type, with possible constraint type values EXCLUDE or INCLUDE. Example spec:

{
    "node_relationship_type": "EFFECTIVE_ACCESS",
    "query_type": "SOURCE_TO_DESTINATION",
    "include_nodes": true,
    "source_node_types": {
        "nodes": [
            {
                "node_type": "User",
                "node_type_grouping_constraint" :{
                    "constraint_type" : "INCLUDE",
                    "node_types" : ["CustomIDPUser", "OktaUser"]
                }
            }
        ]
    },
    "destination_node_types": {
        "nodes": [
            {
                "node_type": "S3Bucket"
            }
        ]
    }
}

ConditionExpression

Additional constraints can be applied using a node condition_expression. Conditions specified within the expression can target node attributes such as name, date created, or any other properties Veza has discovered.

Conditions can always apply to source and destination node types. Conditions can only apply to intermediate node types when the query defines required_intermediate_node_types.

Conditions have a function (fn). Valid operators are:

• EQ: 'Equals',

• LT: 'Less Than',

• LTE: 'Less Than or Equal',

• GT: 'Greater Than',

• GTE: 'Greater Than or Equal',

• LIST_CONTAINS: 'List Contains',

• IN: 'In',

• STARTS_WITH: 'Starts With',

• CONTAINS: 'Contains',

• ENDS_WITH: 'Ends With',

• EXISTS: 'Exists',

• REGEX: 'Matches Regular Expression',

Date-based operators can be:

LT: 'Not in the Last', LTE: 'Before', GT: 'In the Last', GTE: 'After', EQ: 'At',

For example:

{
  "query_type": "SOURCE_TO_DESTINATION",
  "source_node_types": {
    "nodes": [
      {
        "node_type": "AwsIamUser",
        "condition_expression": {
          "operator": "AND",
          "specs": [
            {
              "fn": "LTE",
              "property": "last_used_at",
              "value": "2022-01-02T17:59:59.494Z"
            },
            {
              "fn": "GTE",
              "property": "last_used_at",
              "value": "2022-01-01T06:00:00.494Z"
            }
          ]
        }
      }
    ]
  }
}

The condition value can be true, false, a number, an RFC3339 timestamp, or a string. For example, to find S3 Bucket destinations where public ACLs haven't been blocked:

{
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "S3Bucket",
        "condition_expression": {
          "specs": [
            {
              "fn": "EQ",
              "property": "block_public_acls",
              "value": false,
              "not": false
            }
          ]
        }
      }
    ]
  }
}

Conditions can also contain a string-typed value. For example, to find all Okta users with the prefix "sa-":

{
  "node_type": "OktaUser",
  "condition_expression": {
    "specs": [
      {
        "fn": "STARTS_WITH",
        "property": "name",
        "value": "sa-",
        "not": false
      }
    ]
  }
}

Note that you can specify nodes where the condition doesn't apply by setting "not": true for the constraint.

There can also be a not on the whole expression:

"condition_expression": {
  "operator": "OR",
  "not": true,
  "specs": [
    {
      "not": true,
      "fn": "EQ",
      ..
    },
    ..
  ]
}

You can get all the properties available for different node types (which vary depending on the provider and service) by searching for the entities in Access Graph and viewing the node details.

Tags

When applied to source or destination node types, results will only show entities with (or without) a specific Veza Tag or a discovered AWS tag. For example:

    "destination_node_types": {
      "nodes": [
        {
          "node_type": "S3Bucket",
          "tags": [
            {
              "key": "awstag_PII",
              "value": "PCI"
            }
          ],
          "excluded_tags": [
            {
              "key": "environment",
              "value": "production"
            }
          ]
        }
      ]
    }

tags and excluded_tags can always apply to source and destination node types. They can only apply to intermediate node types in assessment queries, when the spec defines required_intermediate_node_types.

No relation

Enable no_relation to only return nodes without a relationship to the destination node types. For example, to show Microsoft Azure AD users that do not belong to the group "Alabama":

{
  "query_type": "SOURCE_TO_DESTINATION",
  "source_node_types": {
    "nodes": [
      {
        "node_type": "AzureADUser"
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "AzureADGroup",
        "condition_expression": {
          "specs": [
            {
              "fn": "EQ",
              "property": "name",
              "stringValue": "Alabama"
            }
          ]
        }
      }
    ]
  },
  "no_relation": true,
  "include_nodes": true
}

Avoids intermediate node types

You may want to query for entities that have direct access to a resource, without a specific intermediate relationship. For example, you can query for IAM users whose resource access does not also involve a role.

To query for relationships that do not include a specific node type in the authorization path, specify an exclusion in the avoids_intermediate_node_types object:

...
"no_relation": false,
"avoids_intermediate_node_types": {
  "nodes": [
    {
      "node_type": "AwsIamRole"
    }
  ]
}

Query type

Query Type	Description
SYSTEM_CREATED	Used for pre-built system queries.
SOURCE_TO_DESTINATION	The search will return entities of the source node type with a relationship to the destination entity type.
DESTINATION_NODES	Return the destination nodes, instead of source nodes (deprecated, use query_spec:destination_nodes).

When copying JSON query specifications from the Query Builder UI, you may see "query_type": "SYSTEM_CREATED" in the generated payload. When using this to create queries via the API, you must change the value to "query_type": "SOURCE_TO_DESTINATION". The API does not accept SYSTEM_CREATED as a valid query type for user-created queries, as this type is reserved for Veza's out-of-the-box queries.

Permissions

To return only entities with one or more permissions to a resource, you can list either system or effective permissions, with an AND or OR operator.

RawPermissionCollection

"Raw" or "System" permissions describe privileges using the service providers terms, for example s3:PutBucketAcl.

Field	Type	Notes
values	string	String list of raw permission names
operator	string	AND, OR (default AND)

You can review all the possible permissions Veza has discovered for an entity by selecting it as a related entity in a Query Builder search. The "Permissions" dropdown menu will include all effective and raw permissions for the resource type.

EffectivePermissionCollection

Field	Type	Notes
values	string	Effective permissions can be METADATA_WRITE, METADATA_READ, METADATA_CREATE, METADATA_DELETE, DATA_READ, DATA_WRITE, DATA_CREATE, DATA_DELETE, NON_DATA ] (default METADATA_WRITE)
operator	string	AND, OR (default AND)

Effective permissions are an abstraction of an entity's authorization to a resource. When discovering authorization metadata for a connected provider, Veza maps each raw permission a principal has on a resource to the corresponding canonical permission, and calculates the cumulative effective permissions.

RelatesToExp

Queries constructed using the v1 API and the Segregation of Duty page can use "relates to" expressions to get results based on relationships to more than one related entity types, with AND | OR logic. For example: Show all users that are in Group A and Group B, or Show users that are in Group X and have Role Y.

RelatesToExp Evaluation

For E = { specs: [A, B, ...], child_expressions: [X, Y, ...], operator, not }

• "source has a path to E" is defined as:

• If operator is AND (default): "source has a path to ALL of (A,B, ..., X, Y, ...)"

• If operator is OR: "source has a path to ANY of (A,B, ..., X, Y, ...)"

• If not = true, boolean invert the result above

RelatesToExp Field Specifications

• and_op_type: AndOperatorType (INFERRED [default], SOURCE_INTERSECT, PAIR_INTERSECT)

• child_expressions: RelatesToExpressions Array

• not: Boolean flag applied to specs and child_expressions

• operator: Operator (AND [default], OR)

• specs: RelatesToSpec array specifying node types and conditions

AndOperatorType

• INFERRED (default): Replaced with SOURCE_INTERSECT or PAIR_INTERSECT based on query execution context.

• SOURCE_INTERSECT: Intersection based on source node.

• PAIR_INTERSECT: Intersection based on pairs of nodes.

Given the following graph relationship:

U1 -- P1 -- R1
    /
U2 -- P2 -- R2

U1 and U2 are entity type U, and R1 and R2 are entity type R. Here U2 is in the result of U-> (P1->R AND P2->R) with SOURCE_INTERSECT. With PAIR_INTERSECT, U2 is not in the result because neither R1 or R2 matches both U->P1->R and U->P2->R.

If we change the graph to have R1 match both U->P1->R and U->P2->R:

U1 -- P1 -- R1
    /     /
U2 -- P2 -

Now U2 is in the result of the same query with PAIR_INTERSECT. PAIR_INTERSECT makes more sense for queries like “users have permission A && B to database” when the meaning is “permission A && B to the same database”

AndOperatorType defaults:

• INFERRED will be replaced with one of SOURCE_INTERSECT or PAIR_INTERSECT when executing the query.

• INFERRED is replaced with PAIR_INTERSECT only if:

  • The query doesn't have RelatesToExpression.Not == true in any child expressions, and

  • All operands of the AND have the same sole node type, and

  • All operands of the AND don't include conflicting "equal to" conditions on unique property (id and name)

• Otherwise INFERRED is replaced with SOURCE_INTERSECT

RelatesToSpec

A RelatesToSpec represents a precise path definition:

• source has a path to any node spec in node_types

  • direction determines the direction of the path

• the path has all required_intermediate_node_types

• the path has none of avoided_intermediate_node_types

• all or any of raw_permissions appear on the path, depending on raw_permissions.operator

• all or any of effective_permissions appear on the path, effective_permissions on raw_permissions.operator

• if no_relation=true, it instead means such a path does not exist

Field	Type	Description
avoided_intermediate_node_types	NodeSpecCollection object
direction	string	RelatesToDirection
effective_permissions	EffectivePermissionCollection object
no_relation	boolean
node_types	NodeSpecCollection object
raw_permissions	object	A collection of raw permission names
required_intermediate_node_types	NodeSpecCollection object

RelatesToDirection can be:

• ANY_DIRECTION : Backend automatically selects ONE optimal direction, preferring paths containing permissions. Returns results from the selected direction only (not from all directions).

• SINGLE_DIRECTIONAL: Direction to be chosen by the API if there is only one valid direction. Otherwise this input is invalid.

• OUTGOING: Only accept result for paths of ( -> ...). This input is invalid if there is no such a path in schema.

• INCOMING: Only accept result for paths of (... -> ). This input is invalid if there is no such a path in schema.

Understanding ANY_DIRECTION Behavior

When ANY_DIRECTION is specified, Veza uses the following logic to select a query direction:

1. Evaluate both directions for valid paths between the source and destination entity types

2. Select the direction containing permission relationships (such as permissions, roles, or group memberships)

3. If both directions have permissions: Choose OUTGOING direction

4. If neither direction has permissions: Choose OUTGOING direction (fallback)

It deterministically selects the single most relevant direction based on where permissions exist in the relationship path.

Example: User to Database Query

• Outgoing path: User → Role → Permission → Database (contains permission edges)

  • Result: Selected by default

• Incoming path: User ← ManagedBy ← Database (no permission edges)

  • Result: Returns outgoing results only, because that path contains permissions

Example: Database to User Query

• Outgoing path: Database → ManagedBy → User (no permission edges)

• Incoming path: Database ← Permission ← Role ← User (contains permission edges)

  • Result: Selected by default

  • Result: Returns incoming results only, because that path contains permissions

The order of entity types in your query (source vs. destination) does NOT determine the direction. Veza chooses based on where permission relationships exist in the graph schema, not based on which entity you specify first.

RiskSuppressedConstraintsCollection

NodeSpec define conditions on entity types to mark exceptions for queries with a risk level.