# Query Builder Parameters When calling [query spec](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecresult.md) endpoints or [saving a query](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/createassessmentquery.md), 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](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentqueryspecdestinationnodes.md) or [GetAssessmentQueryDestinationNodes](/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/getassessmentquerydestinationnodes.md) to return related entities for an individual source entity in a query result. {% hint style="success" %} As the Veza [Query Builder](/4yItIzMvkpAvMVFAamTf/features/search/query-builder.md) 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*. {% endhint %} ### Query parameters | Field | Type | Notes | | ---------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `all_entity_condition` | [ConditionExpression](#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](#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](#nodespeccollection) | If specified, results only include entities with a relationship to the destination node type. | | `effective_permissions` | [Effective Permission Collection](#effectivepermissioncollection) | 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](#rawpermissioncollection) | If specified, only return results that have the listed raw permissions. | | `relates_to_exp` | [RelatesToExp](#relatestoexp) object | Specify related note constraints | | `required_intermediate_node_types` | [NodeSpecCollection](#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](#risksuppressedconstraintscollection) object | Adds a risk exception for nodes matching the specification. | | `source_node_types` | [NodeSpecCollection](#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` | | `waypoint_nodes` | [NodeSpecCollection](#nodespeccollection) | Specifies a specific intermediate entity that must exist in the path between source and destination. Limited to one waypoint per query. | | `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 | Reserved field (not currently used). Use `RelatesToExpression.operator` for AND/OR logic with multiple destinations. | ### 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](#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](#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](#nodetypegroupingconstraint) object | Contains an operator and list of node types to include or exclude | | `tags` | [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: ```json { "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: **Comparison operators:** * `EQ`: Equals * `LT`: Less Than * `LTE`: Less Than or Equal * `GT`: Greater Than * `GTE`: Greater Than or Equal **String operators:** * `STARTS_WITH`: Starts With * `CONTAINS`: Contains * `ENDS_WITH`: Ends With * `REGEX`: Matches Regular Expression * `EXISTS`: Property Exists **Set operators:** * `IN`: Value is in list * `IN_FROM_QUERY_SOURCE_RESULTS`: Value is in results from another query **List property operators** (for properties that contain arrays): * `LIST_CONTAINS`: List Contains (deprecated, use `LIST_ANY_ELEMENT_EQ`) * `LIST_ALL_ELEMENTS_IN`: All list elements are in the specified set * `LIST_ANY_ELEMENT_EQ`: Any list element equals value * `LIST_ANY_ELEMENT_STARTS_WITH`: Any list element starts with value * `LIST_ANY_ELEMENT_CONTAINS`: Any list element contains value * `LIST_ANY_ELEMENT_ENDS_WITH`: Any list element ends with value * `LIST_ANY_ELEMENT_REGEX`: Any list element matches regex * `LIST_ANY_ELEMENT_IN`: Any list element is in the specified set Date-based operators can be: `LT`: 'Not in the Last', `LTE`: 'Before', `GT`: 'In the Last', `GTE`: 'After', `EQ`: 'At', For example: ```json { "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: ```json { "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-": ```json { "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: ```json "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: ```json "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": ```json { "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: ```json ... "no_relation": false, "avoids_intermediate_node_types": { "nodes": [ { "node_type": "AwsIamRole" } ] } ``` ### Waypoint nodes Waypoint nodes allow you to filter query results to only include paths that pass through a specific intermediate entity. This is useful for auditing access that flows through particular roles, groups, or service accounts. Unlike `required_intermediate_node_types` which specifies that *any* entity of a given type must exist in the path, `waypoint_nodes` requires a *specific* entity (identified by node\_id or name) to be in the path. **Key differences:** * `required_intermediate_node_types`: "Path must include some Snowflake Role" * `waypoint_nodes`: "Path must include the specific ACCOUNTADMIN role" **Important notes:** * Currently limited to one waypoint entity per query * The waypoint must be an intermediate entity (not the source or destination) * The Query Builder UI presents waypoints and summary entities as alternative options, but both can be specified in API requests **Example**: Find Okta users accessing Snowflake databases through the ACCOUNTADMIN role: ```json { "query_type": "SOURCE_TO_DESTINATION", "source_node_types": { "nodes": [ { "node_type": "OktaUser" } ] }, "destination_node_types": { "nodes": [ { "node_type": "SnowflakeDatabase" } ] }, "waypoint_nodes": { "nodes": [ { "node_type": "SnowflakeRole", "condition_expression": { "specs": [ { "fn": "EQ", "property": "name", "value": "ACCOUNTADMIN" } ] } } ] }, "include_nodes": true } ``` Alternatively, you can specify the waypoint by node\_id: ```json { "waypoint_nodes": { "nodes": [ { "node_type": "SnowflakeRole", "node_id": "SnowflakeRole:12345:ACCOUNTADMIN" } ] } } ``` ### 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`). | {% hint style="warning" %} 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. {% endhint %} ### 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`. #### Multiple Destination Types with OR Logic You can query for relationships to multiple destination entity types simultaneously by using `RelatesToExp` with an `OR` operator. This returns source entities that have a relationship to **any** of the specified destination types. **Example**: Find Okta users with access to any AWS data storage service (S3 OR RDS OR DynamoDB): ```json { "query_type": "SOURCE_TO_DESTINATION", "source_node_types": { "nodes": [ { "node_type": "OktaUser" } ] }, "relates_to_exp": { "operator": "OR", "specs": [ { "node_types": { "nodes": [ { "node_type": "S3Bucket" } ] } }, { "node_types": { "nodes": [ { "node_type": "RDSDatabase" } ] } }, { "node_types": { "nodes": [ { "node_type": "DynamoDBTable" } ] } } ] }, "include_nodes": true } ``` In this example: * A user appears in results if they have access to S3 **OR** RDS **OR** DynamoDB (or any combination) * Each destination type can have its own filters, tags, and permission requirements * The `OR` operator creates a union of results across all destination types **Adding filters to each destination type:** ```json { "relates_to_exp": { "operator": "OR", "specs": [ { "node_types": { "nodes": [ { "node_type": "S3Bucket", "tags": [ { "key": "Environment", "value": "Production" } ] } ] } }, { "node_types": { "nodes": [ { "node_type": "RDSDatabase", "condition_expression": { "specs": [ { "fn": "EQ", "property": "publicly_accessible", "value": true } ] } } ] } } ] } } ``` This query finds users with access to **either**: * Production S3 buckets, **OR** * Publicly accessible RDS databases #### 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: ```txt 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: ```txt 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](#nodespeccollection) object | | | `direction` | string | `RelatesToDirection` | | `effective_permissions` | [EffectivePermissionCollection](#permissions) object | | | `no_relation` | boolean | | | `node_types` | [NodeSpecCollection](#nodespeccollection) object | | | `raw_permissions` | object | A collection of raw permission names | | `required_intermediate_node_types` | [NodeSpecCollection](#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](#nodespec) define conditions on entity types to mark exceptions for queries with a risk level. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/query-builder/parameters.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.