1 of 4

Veza Query Language

Early Access: VQL is currently provided in Early Access, and we're excited for your feedback on what we hope will be a major stride forward for ease of use and flexibility for Veza search. Please contact our support team to enable the feature, and reach out with your input and questions.

Overview

Veza Query Language (VQL) is a powerful and flexible language designed for querying Veza's Identity Graph. It supplements the original Query Builder interface and Assessment Query API, and implements familiar SQL-like conventions for specifying source and destination entities, filters, and other query parameters.

VQL expressions aim to be intuitive and close to natural language, providing a bridge between everyday speech and the full functionality of Veza graph search. With VQL, you can construct complex queries to explore relationships, filter entities based on attributes, and analyze permissions within your identity and access data.

You can use VQL to:

Apply filters using a range of operators to refine your search results.
Query relationships between entities, including intermediate node requirements.
Customize how results appear by including destination nodes and path summaries.
Search by system permissions and effective permissions for full visibility into access and entitlements.

VQL queries follow consistent patterns for different types of operations:

-- Basic entity query
SHOW <entity_type>;

-- Query with filters
SHOW <entity_type>
WHERE <property>[operator]<value>;

-- Relationship query
SHOW <entity_type>
RELATED TO <entity_type>;

-- Complex query with multiple conditions
SHOW <entity_type>
WHERE <condition1> AND <condition2>
RELATED TO <entity_type>
WITH PATH <entity_type>
RESULT INCLUDE DESTINATION NODES;
HAVING entity_result_count > 10;

Getting Started

To begin using VQL, first familiarize yourself with its basic syntax and components. A VQL query starts with a SHOW statement specifying the source entities.

Example:

SHOW S3Bucket;

This query retrieves all AWS S3 Buckets discovered by Veza.

You can then extend your queries by adding filters, relationships, and other options.

Example with Filters and Relationships:

SHOW AwsIamUser
WHERE is_active = true
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

This query retrieves all active AWS IAM Users and shows the S3 Buckets they are related to.

Concepts and Syntax

VQL queries are composed of several key elements:

Target node types: The entities you want to retrieve (e.g., AwsIamUser, OktaUser).
Filters: Conditions applied to source or destination nodes in the WHERE clause.
Relationships: Filter results based on connected entities, specified in the RELATED TO clause.
Intermediate Nodes: Include or exclude results with certain nodes in the path (i.e, intermediate groups or roles) using WITH PATH or NOT WITH PATH.
Result Options: Customize the output to INCLUDE DESTINATION NODES or INCLUDE PATH SUMMARY to get results as source and destination pairs.
Query Options: Options for query execution, such as filtering by over-provisioned score, and pagination.

Basic query structure:

SHOW [SourceNodeSpec]
[ [NOT] RELATED TO [DestinationNodeSpec]]
[WHERE (filter conditions)]
[WITH | NOT WITH] PATH [IntermediateNodeSpec]
HAVING [ ENTITY_RESULT_COUNT | PERCENTAGE_OF_TOTAL_COUNT] [>|>=<|<=|!=] <numeric_value> ]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[WITH QUERY OPTIONS (options)];

VQL supports a variety of operators for filters, including:

Comparison Operators: =, !=, <, >, <=, >=
String Operators: STARTS_WITH, ENDS_WITH, CONTAINS, REGEX
List Operators: IN, LIST_CONTAINS, LIST_ANY_ELEMENT_EQ
Logical Operators: AND, OR
Date/Time Operators: created_at < CURRENT_DATE - 30, created_at < 2023-10-05 14:30:00.123

Example Queries

Query All S3 Buckets

Retrieve all AWS S3 Buckets:

SHOW S3Bucket;

List all AWS IAM Users who have access to S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket;

Apply Attribute Filters

List active AWS IAM Users in the Engineering department:

SHOW OktaUser
WHERE is_active = true AND department = 'Engineering';

Include Destination Nodes

Show AWS IAM Users and the S3 Buckets they can access:

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

Use Path Requirements

Find AWS IAM Users connected to S3 Buckets via an IAM Role:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Exclude Specific Paths

Find AWS IAM Users related to S3 Buckets but not through an IAM Group:

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamRole;

Filter by Over-Provisioned Score

Retrieve AWS IAM Roles with an over-provisioned score greater than 85:

SHOW AwsIamRole
RELATED TO S3Bucket
WITH query options (over_provisioned_score > 85);

Find AWS IAM Users who have access to more than 10 S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

Query Using Time Functions

Retrieve users who have logged in within the last 30 days:

SHOW OktaUser
WHERE last_login_at >= CURRENT_DATE - 30;

Executing VQL Queries

There are two ways to execute VQL queries:

VQL API: Execute VQL queries programmatically through Veza's Assessment Query API endpoints
VQL Playground: Coming soon - a GUI experience for constructing and executing queries

Using the VQL API

Veza two /v1 API endpoints for executing VQL queries:

Get Results (Nodes) - /api/v1/assessments/vql:nodes: Returns detailed results including source nodes, their properties, and access relationship information
Get Results (Count) - /api/v1/assessments/vql:result: Returns result counts, ideal for metrics and reporting use cases

Example API request:

POST /api/v1/assessments/vql:nodes
{
  "query": "SHOW OktaUser WHERE is_active = true RELATED TO S3Bucket RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}

The response supports pagination, and returns a JSON object with the query results, for example:

{
  "values": [],
  "path_values": [
    {
      "source": {
        "id": "00u5pqrs7xyP9uvw30z9",
        "type": "OktaUser",
        "properties": {
          "activated_at": "2023-06-12T15:21:34Z",
          "created_at": "2023-04-20T04:30:37Z",
          "credentials_provider_name": "OKTA",
          "credentials_provider_type": "OKTA",
          "datasource_id": "example.oktapreview.com",
          "email": "jsmith@example.com",
          "first_name": "John",
          "identity_type": "HUMAN",
          "idp_unique_id": "jsmith@example.com",
          "is_active": true,
          "last_login_at": "2024-08-02T05:52:42Z",
          "last_name": "Smith",
          "login": "jsmith@example.com",
          "mfa_active": true,
          "mfa_factors": [
            "question"
          ],
          "name": "jsmith@example.com",
          "okta_user_type_id": "otyf8xyz92hv7mnP60j9",
          "owners": "[{\"entity_id\":\"00ukmnop51qR3s4TU6e8\",\"entity_type\":\"OktaUser\",\"entity_name\":\"Maria Rodriguez\"}]",
          "password_exists": true,
          "password_last_set": "2024-08-02T05:52:42Z",
          "provider_id": "example.oktapreview.com",
          "recovery_question_exists": true,
          "risk_score": 100,
          "status": "ACTIVE",
          "status_updated_at": "2024-08-02T05:52:42Z",
          "updated_at": "2025-01-16T05:53:38Z"
        },
        "risk_level": "CRITICAL"
      },
      "abstract_permissions": [
        "MetadataRead"
      ],
      "concrete_permissions": [
        "s3:ListBucket"
      ],
      "destination": {
        "id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
        "type": "S3Bucket",
        "properties": {
          "allows_acls": false,
          "aws_account_id": "123456789012",
          "aws_account_name": "",
          "block_public_access_enabled": true,
          "block_public_acls": true,
          "block_public_policy": true,
          "created_at": "2024-05-04T04:50:42Z",
          "datasource_id": "123456789012:s3",
          "default_encryption_enabled": true,
          "default_retention_mode": "DISABLED",
          "hosts_website": false,
          "ignore_public_acls": true,
          "name": "aws-cloudtrail-logs-123456789012-abcdef12",
          "object_lock_enabled": false,
          "object_ownership_controls": "BucketOwnerEnforced",
          "provider_id": "123456789012",
          "region": "us-east-1",
          "replication_rules_count": 0,
          "request_payer": "BucketOwner",
          "restrict_public_buckets": true,
          "risk_score": 27,
          "server_access_logs_enabled": false
        },
        "risk_level": "LOW"
      }
    }
  ],
  "next_page_token": "",
  "has_more": false
}

Resources

To learn more about VQL capabilities, see the following resources:

Quick Start

Example searches for understanding fundamental VQL concepts and options.

Getting Started with VQL

This guide will help you learn VQL through practical examples, starting with basic queries and progressing to more complex scenarios. Use the examples in this document to familiarize yourself with Veza graph search concepts, and how they can be expressed using Veza Query Language (VQL).

```
SHOW S3Bucket;
```
After specifying the source node, you can apply filters (WHERE clauses) and relationship constraints (RELATED TO) to further narrow your search.
```
SHOW AwsIamUser
WHERE is_active = true
RELATED TO S3Bucket;
```
By default, the results show the source entity types indicated by the SHOW keywords. Use the INCLUDE clause to change the result output format to include destination nodes and summary entities.
```
SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;
```

Query for Entities

The examples below describe some search scenarios for AWS, which you should adapt based on your actual environment. To retrieve an entity's type and attributes, locate the entity in Graph search and click on it to view details. Note that VQL is case-sensitive for node types, attribute names, and string values unless specified otherwise.

A VQL query consists of at least one source specification, which determines the entity type(s) to return as results.

Here is a simple VQL expression that will return all AWS S3 Buckets that Veza has discovered:

SHOW S3Bucket;

By default, the results contain a selection of entity properties and not the full set of attributes. Modify the SHOW statement to retrieve specific properties you're interested in:

SHOW S3Bucket { created_at, block_public_access_enabled };

For each result, columns will include the S3 Bucket creation date and indicate if the Block Public Access option is enabled.

Query for Relationships

VQL allows you to query relationships between interconnected graph entities using a simple syntax. In this example, we return all AWS IAM Users RELATED TO S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket;

Conversely, to list S3 Buckets accessible by IAM Users:

SHOW S3Bucket
RELATED TO AwsIamUser;

Applying Attribute Filters

To only return results that meet certain conditions, include a WHERE clause. In this example, results are constrained to AWS IAM Users related to S3 Buckets that have public ACLs OR have Object Lock Enabled set to true:

SHOW AwsIamUser
RELATED TO S3Bucket
WHERE block_public_acls != true OR object_lock_enabled = true;

Using Path Requirements

Relationships in the Veza graph can include intermediate entities, such as roles, groups, or policies connecting a source to a destination.

In the example below, use the WITH PATH option to only return AWS IAM Users that are connected to S3 Buckets via an intermediate IAM Role:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Alternately, to exclude paths that include a specific node type:

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamGroup;

Including Destination Entities

By default, query results are a list of source entities and their attributes. You can optionally get results as source and destination pairs, where each row represents a unique path connecting two entities.

Update the previous example to return the exact S3 Buckets each IAM User can access by adding the RESULT INCLUDE DESTINATION NODES keyword. This will show each combination of IAM Users and S3 Buckets connected by IAM Roles:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE DESTINATION NODES;

Including Summary Entities

Use the following query to include the summary and the sequence of IAM Roles granting access to S3 Buckets in the search results:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE PATH SUMMARY;

Including path summary will automatically include all destination nodes. You don’t need to explicitly use the keyword INCLUDE DESTINATION NODES.

With VQL, you can filter results based on the number of destination entities a source is related to. This option can help identify widely-accessible resources, users with overly broad permissions or roles or groups that grant access to a wide range of other entities.

Update the example above with a HAVING clause to only return AWS IAM Users who have access to more than 10 S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

This variation returns users who have access to more than 20% of S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING percentage_of_total_count > 20;

Using Over-Provisioned Score

SHOW AwsIamRole
RELATED TO S3Bucket
WITH QUERY OPTIONS (over_provisioned_score < 85);

Using Pagination

When working with large result sets, use pagination to retrieve results in manageable chunks:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

After receiving the initial results, use the cursor token provided in the response to fetch the next set of results:

SHOW AwsIamUser
RELATED TO S3Bucket
AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ=='
LIMIT 50;

Learning More

Syntax

Reference documentation for Veza Query Language.

Concepts

Early Access: VQL is subject to modifications as we add and improve functionality. Future updates will aim to preserve compatibility with earlier versions.

A VQL query is composed of the following components:

Source Nodes: Node types in VQL represent entity types within Veza's Identity Graph. Each node type can have many individual instances, returned as rows in the query output.
Path requirements: Graph nodes can be interrelated, forming complex graph structures. Specifying related nodes filters results with a matching relationship.
Filters and Modifiers: Filter expressions (WHERE clauses) to constrain results based on attributes or other criteria.

VQL Expression Syntax

A VQL query always includes a SHOW statement describing the source node type. The general syntax is:

SHOW [NodeSpec] -- Specifies the source node type
[ [NOT] RELATED TO [NodeSpec]] -- Filters results by related node type
[WITH | NOT WITH] PATH [NodeSpec] -- Filters on intermediate nodes
[WHERE (filter expressions)]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[HAVING [entity_result_count (condition) | percentage_of_total_count (condition)]]
[WITH QUERY OPTIONS (options)]
[AFTER CURSOR 'cursor_token'] -- For pagination, use cursor token from previous results
[LIMIT <number>]; -- Limit number of results returned

NodeSpec Syntax

A NodeSpec describes a source or destination entity type. It can include attribute selection (which columns to return) and filters using a WHERE clause. The full syntax is:

[NodeType] [{ attribute1, attribute2, ... }] [WHERE (<attribute_name> <operator> <value> [AND|OR] ...)]

Basic Components:

NodeType: The type of node (e.g., AwsIamUser, OktaGroup)
Attribute Selection: Optional curly braces { } containing a comma-separated list of attributes to include in the results
WHERE: Optional clause that applies attribute-based filters to the nodes using the selected operators

Usage Examples

Basic node specification (returns all attributes):

SHOW AwsIamUser

Select specific attributes to display:

SHOW AwsIamUser { created_at, is_active, full_admin }

Apply filters without attribute selection:

SHOW AwsIamUser WHERE is_active = true

Combine attribute selection and filters:

SHOW AwsIamUser { created_at, email } WHERE is_active = true AND risk_score > 70

In this more complex example, we select specific attributes for both the source (OktaUser) and destination (S3Bucket) nodes while also applying filters to the results:

SHOW OktaUser { email, last_login_at, department }
WHERE last_login_at >= CURRENT_DATE - 30
RELATED TO S3Bucket
WHERE block_public_acls = false
WITH PATH OktaGroup
WITH QUERY OPTIONS ( over_provisioned_score > 85 )

Where Clause Operators

A range of operators can be used to filter results depending on node properties. Currently, VQL supports the comparison operators:

Comparison Operators

Operator

Supported Data Types

Example

<, >, <=, >=, =, !=

NUMERIC, TIMESTAMP, TIME FUNCTIONS

risk_score < 80 created_at >= '2023-10-05 14:30:00.123' created_at < CURRENT_DATE - 30

STARTS_WITH

STRING

name STARTS_WITH 'S'

ENDS_WITH

STRING

name ENDS_WITH 'E'

LIST_CONTAINS

STRING

permissions LIST_CONTAINS 'iam:PassRole'

LIST_ALL_ELEMENTS_IN

STRING

accounts_assumed_by LIST_ALL_ELEMENTS_IN ('accountid1', 'accountid2')

REGEX

STRING

name REGEX 'TEst.*'

LIST_ANY_ELEMENT_EQ

STRING

permissions LIST_ANY_ELEMENT_EQ 'iam:SetDefaultPolicyVersion'

LIST_ANY_ELEMENT_STARTS_WITH

STRING

cai_tags LIST_ANY_ELEMENT_STARTS_WITH 'P'

LIST_ANY_ELEMENT_CONTAINS

STRING

cai_tags LIST_ANY_ELEMENT_CONTAINS 'policy'

LIST_ANY_ELEMENT_ENDS_WITH

STRING

cai_tags LIST_ANY_ELEMENT_ENDS_WITH 'admin'

LIST_ANY_ELEMENT_REGEX

STRING

cai_tags LIST_ANY_ELEMENT_REGEX '::'

IS NULL

STRING

show Key WHERE last_rotated_at IS NULL

IS NOT NULL

STRING

show Key WHERE last_rotated_at IS NOT NULL

Data Types and Restrictions

Data Types: VQL supports boolean, integer, string, and null data types.
Case Sensitivity: VQL is typically case-sensitive for:
- Node Types: Must be written exactly as defined (e.g., AwsIamUser, not awsiamuser).
- Attribute Names: Must match the exact casing (e.g., is_active, not Is_Active).

Entity Attributes

Entity attributes in VQL are used to filter and select graph nodes. They consist solely of alphanumeric characters or underscores (e.g., last_login, email_address).

Permissions

In addition to attribute filters, VQL queries can use permission filters. Both system permissions and effective permissions are supported.

System Permissions

System permissions are raw, system-level permissions and vary depending on the specific integration and resource. The following query identifies users that specifically have the ability to create new S3 buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH SYSTEM PERMISSIONS = ANY ('s3:CreateBucket');

ANY: Used to filter for any of the supplied permissions (logical OR).
ALL: Ensures that all permissions passed should be present on the resource (logical AND).

Effective Permissions

Veza supports nine different effective permissions. These are abstracted permissions that express system permissions in common groups:

METADATA_READ
METADATA_WRITE
METADATA_CREATE
METADATA_DELETE
DATA_READ
DATA_WRITE
DATA_CREATE
DATA_DELETE
NON_DATA

The following query shows all AWS IAM Roles that grant effective permissions to read or write S3 bucket metadata:

SHOW AwsIamRole
RELATED TO S3Bucket
WHERE is_active = false
WITH EFFECTIVE PERMISSIONS = ALL ('METADATA_READ', 'METADATA_WRITE');

Effective permissions filters require a destination type (specified by the RELATED TO clause).

Intermediate Nodes

Intermediate node options include or exclude results based on certain node types within the path, for analyzing complex relationships that involve hierarchies of groups, roles, or entities. These queries are often used to find users whose access is (or is not) granted by group membership or role assignment:

Including Intermediate Nodes:

SHOW OktaUser
RELATED TO SnowflakeTable
WITH PATH SnowflakeUser;

Excluding Intermediate Nodes:

SHOW OktaUser
RELATED TO SnowflakeTable
NOT WITH PATH OktaGroup;

Modifiers and Filters

Use the WHERE clause to apply filters. You can combine multiple conditions with AND or OR statements:

Example:

SHOW AwsIamUser
WHERE is_active = true AND risk_score > 70;

Pagination

VQL supports pagination for queries that return large result sets. Two keywords control pagination behavior:

LIMIT: Restricts the number of results returned in a single query
AFTER CURSOR: Used with a cursor token to retrieve the next set of results

Example of initial query with limit:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

For subsequent requests, use the cursor token from the previous response:

SHOW AwsIamUser
RELATED TO S3Bucket
AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ=='
LIMIT 50;

Result Output

By default, queries return a list of source entity types and attributes. Use the RESULT INCLUDE clause to specify how query results appear:

DESTINATION NODES: Includes information about related destination nodes.
DESTINATION NODE COUNT: Provides a count of related destination nodes.
PATH SUMMARY: Summarizes the paths between source and destination nodes.

Example:

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

VQL API

API documentation for executing VQL queries through the Assessment Query API.

Overview

VQL vs. Traditional Approaches

VQL offers a simplified way to interact with Veza's Assessment Query APIs, enabling:

Automated compliance monitoring
Cross-platform integration
Custom investigation and reporting tools built on top of the Veza graph

While Veza's traditional JSON-based interfaces provide robust programmatic functionality, they are developer-focused and require detailed specification of all query components. VQL, with its SQL-like syntax, is more accessible to security practitioners who may already be familiar with similar query languages.

Example Comparison

Here's how the same query appears in both formats:

Traditional JSON Format:

{
  "query_type": "SOURCE_TO_DESTINATION",
  "source_node_types": {
    "nodes": [
      {
        "node_type": "AwsIamUser",
        "condition_expression": {
          "specs": [
            {
              "fn": "EQ",
              "property": "is_active",
              "value": true
            }
          ]
        }
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "S3Bucket"
      }
    ]
  }
}

Equivalent VQL:

SHOW AwsIamUser WHERE is_active = true RELATED_TO S3Bucket

VQL's concise syntax makes queries easier to write, review, and troubleshoot while maintaining the power of Veza's assessment capabilities.

Requirements

To use the VQL API, you will need:

VQL features enabled in your Veza instance

API Endpoints

Get Query Results (Count)

This endpoint retrieves result counts for a VQL query. These queries can execute faster and are optimal for metrics, reporting, and dashboard use cases where you need the total count rather than detailed node information.

Get Query Results (Nodes)

The vql:nodes endpoint retrieves detailed results for VQL queries, showing source nodes, their properties, and access relationship information. This format is useful for security analysis, access reviews, and permission auditing.

Example Request

POST /api/v1/assessments/vql:nodes
{
  "query": "SHOW OktaUser WHERE is_active = true RELATED TO S3Bucket RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}

This example asks: "Show me all active Okta users who have access to AWS S3 buckets, include details about those buckets, and limit results to 50 entries."

Understanding the API Response

When you send a VQL query, Veza returns a structured JSON response with results based on the latest graph data. The response contains:

Path Values: Each entry represents a connection between a source and destination node
Source: Details about the source node, including properties and risk level
Permissions: Both high-level ("abstract") permissions and specific ("concrete") permissions
Destination: Information about the destination node the source can access

Example Response

{
  "path_values": [
    {
      "source": {
        "id": "00u5pqrs7xyP9uvw30z9",
        "type": "OktaUser",
        "properties": {
          "email": "jsmith@example.com",
          "name": "jsmith@example.com",
          "first_name": "John",
          "last_name": "Smith",
          "is_active": true,
          "identity_type": "HUMAN"
        },
        "risk_level": "CRITICAL"
      },
      "abstract_permissions": [
        "MetadataRead"
      ],
      "concrete_permissions": [
        "s3:ListBucket"
      ],
      "destination": {
        "id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
        "type": "S3Bucket",
        "properties": {
          "name": "aws-cloudtrail-logs-123456789012-abcdef12",
          "region": "us-east-1",
          "block_public_access_enabled": true
        },
        "risk_level": "LOW"
      }
    }
  ],
  "cursor": "eyJsaW1pdCI6NTAsInN0YXJ0IjpbInNlcV9pZP...",
  "has_more": true
}

Pagination

For queries that return large result sets, use pagination to retrieve results in manageable chunks using the LIMIT and AFTER CURSOR keywords in your VQL query:

Make an initial request with a specified limit (e.g., LIMIT 50)
Check if has_more is true in the response
If more results exist, make subsequent requests using the cursor token from the previous response with AFTER CURSOR 'token'

Example initial request:

{
  "query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') LIMIT 50;"
}

For subsequent requests, use the cursor token from the previous response:

{
  "query": "SHOW SnowflakeUser RELATED TO SnowflakeTable WITH EFFECTIVE PERMISSIONS = ANY ('DATA_DELETE') AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ==' LIMIT 50;"
}

Quick Start

Example searches for understanding fundamental VQL concepts and options.

Getting Started with VQL

Every query constructed using the starts with a SHOW statement specifying the entities that will be returned as results. Entities that match the search conditions are shown in rows with detailed entity metadata.
```
SHOW S3Bucket;
```
After specifying the source node, you can apply filters (WHERE clauses) and relationship constraints (RELATED TO) to further narrow your search.
```
SHOW AwsIamUser
WHERE is_active = true
RELATED TO S3Bucket;
```
By default, the results show the source entity types indicated by the SHOW keywords. Use the INCLUDE clause to change the result output format to include destination nodes and summary entities.
```
SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;
```

For the detailed VQL specification, see .

Query for Entities

A VQL query consists of at least one source specification, which determines the entity type(s) to return as results.

Here is a simple VQL expression that will return all AWS S3 Buckets that Veza has discovered:

SHOW S3Bucket;

By default, the results contain a selection of entity properties and not the full set of attributes. Modify the SHOW statement to retrieve specific properties you're interested in:

SHOW S3Bucket { created_at, block_public_access_enabled };

For each result, columns will include the S3 Bucket creation date and indicate if the Block Public Access option is enabled.

Query for Relationships

VQL allows you to query relationships between interconnected graph entities using a simple syntax. In this example, we return all AWS IAM Users RELATED TO S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket;

Conversely, to list S3 Buckets accessible by IAM Users:

SHOW S3Bucket
RELATED TO AwsIamUser;

Applying Attribute Filters

SHOW AwsIamUser
RELATED TO S3Bucket
WHERE block_public_acls != true OR object_lock_enabled = true;

Using Path Requirements

Relationships in the Veza graph can include intermediate entities, such as roles, groups, or policies connecting a source to a destination.

In the example below, use the WITH PATH option to only return AWS IAM Users that are connected to S3 Buckets via an intermediate IAM Role:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Alternately, to exclude paths that include a specific node type:

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamGroup;

Including Destination Entities

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE DESTINATION NODES;

This output format is equivalent to the option in Query Builder or the format of an .

Including Summary Entities

VQL supports to provide insight into the intermediate entities in the path connecting a source and destination. This option can help identify deeply nested groups, inherited roles, and other hierarchical relationships.

Use the following query to include the summary and the sequence of IAM Roles granting access to S3 Buckets in the search results:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole
RESULT INCLUDE PATH SUMMARY;

Including path summary will automatically include all destination nodes. You don’t need to explicitly use the keyword INCLUDE DESTINATION NODES.

Update the example above with a HAVING clause to only return AWS IAM Users who have access to more than 10 S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

This variation returns users who have access to more than 20% of S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING percentage_of_total_count > 20;

Using Over-Provisioned Score

While querying for relationships, add a QUERY OPTION to filter results by (available for supported integrations):

SHOW AwsIamRole
RELATED TO S3Bucket
WITH QUERY OPTIONS (over_provisioned_score < 85);

Using Pagination

When working with large result sets, use pagination to retrieve results in manageable chunks:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

After receiving the initial results, use the cursor token provided in the response to fetch the next set of results:

SHOW AwsIamUser
RELATED TO S3Bucket
AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ=='
LIMIT 50;

Learning More

Experimenting with different node types, filters, and relationship constraints can help identify the best queries for your unique environment and security needs. For the full range of where clause operators and all query options, see

Veza Query Language

Overview

You can use VQL to:

Apply filters using a range of operators to refine your search results.
Query relationships between entities, including intermediate node requirements.
Customize how results appear by including destination nodes and path summaries.
Search by system permissions and effective permissions for full visibility into access and entitlements.

VQL queries follow consistent patterns for different types of operations:

-- Basic entity query
SHOW <entity_type>;

-- Query with filters
SHOW <entity_type>
WHERE <property>[operator]<value>;

-- Relationship query
SHOW <entity_type>
RELATED TO <entity_type>;

-- Complex query with multiple conditions
SHOW <entity_type>
WHERE <condition1> AND <condition2>
RELATED TO <entity_type>
WITH PATH <entity_type>
RESULT INCLUDE DESTINATION NODES;
HAVING entity_result_count > 10;

Getting Started

To begin using VQL, first familiarize yourself with its basic syntax and components. A VQL query starts with a SHOW statement specifying the source entities.

Example:

SHOW S3Bucket;

This query retrieves all AWS S3 Buckets discovered by Veza.

You can then extend your queries by adding filters, relationships, and other options.

Example with Filters and Relationships:

SHOW AwsIamUser
WHERE is_active = true
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

This query retrieves all active AWS IAM Users and shows the S3 Buckets they are related to.

To learn more about how Veza search concepts can be expressed with VQL, see the examples queries below and the .

Concepts and Syntax

VQL queries are composed of several key elements:

Target node types: The entities you want to retrieve (e.g., AwsIamUser, OktaUser).
Filters: Conditions applied to source or destination nodes in the WHERE clause.
Relationships: Filter results based on connected entities, specified in the RELATED TO clause.
Intermediate Nodes: Include or exclude results with certain nodes in the path (i.e, intermediate groups or roles) using WITH PATH or NOT WITH PATH.
Result Options: Customize the output to INCLUDE DESTINATION NODES or INCLUDE PATH SUMMARY to get results as source and destination pairs.
Query Options: Options for query execution, such as filtering by over-provisioned score, and pagination.

Basic query structure:

SHOW [SourceNodeSpec]
[ [NOT] RELATED TO [DestinationNodeSpec]]
[WHERE (filter conditions)]
[WITH | NOT WITH] PATH [IntermediateNodeSpec]
HAVING [ ENTITY_RESULT_COUNT | PERCENTAGE_OF_TOTAL_COUNT] [>|>=<|<=|!=] <numeric_value> ]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[WITH QUERY OPTIONS (options)];

VQL supports a variety of operators for filters, including:

Comparison Operators: =, !=, <, >, <=, >=
String Operators: STARTS_WITH, ENDS_WITH, CONTAINS, REGEX
List Operators: IN, LIST_CONTAINS, LIST_ANY_ELEMENT_EQ
Logical Operators: AND, OR
Date/Time Operators: created_at < CURRENT_DATE - 30, created_at < 2023-10-05 14:30:00.123

For details on operators and their usage, see .

Example Queries

Query All S3 Buckets

Retrieve all AWS S3 Buckets:

SHOW S3Bucket;

List all AWS IAM Users who have access to S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket;

Apply Attribute Filters

List active AWS IAM Users in the Engineering department:

SHOW OktaUser
WHERE is_active = true AND department = 'Engineering';

Include Destination Nodes

Show AWS IAM Users and the S3 Buckets they can access:

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

Use Path Requirements

Find AWS IAM Users connected to S3 Buckets via an IAM Role:

SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;

Exclude Specific Paths

Find AWS IAM Users related to S3 Buckets but not through an IAM Group:

SHOW AwsIamUser
RELATED TO S3Bucket
NOT WITH PATH AwsIamRole;

Filter by Over-Provisioned Score

Retrieve AWS IAM Roles with an over-provisioned score greater than 85:

SHOW AwsIamRole
RELATED TO S3Bucket
WITH query options (over_provisioned_score > 85);

Find AWS IAM Users who have access to more than 10 S3 Buckets:

SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;

Query Using Time Functions

Retrieve users who have logged in within the last 30 days:

SHOW OktaUser
WHERE last_login_at >= CURRENT_DATE - 30;

Executing VQL Queries

There are two ways to execute VQL queries:

VQL API: Execute VQL queries programmatically through Veza's Assessment Query API endpoints
VQL Playground: Coming soon - a GUI experience for constructing and executing queries

Using the VQL API

Veza two /v1 API endpoints for executing VQL queries:

Get Results (Nodes) - /api/v1/assessments/vql:nodes: Returns detailed results including source nodes, their properties, and access relationship information
Get Results (Count) - /api/v1/assessments/vql:result: Returns result counts, ideal for metrics and reporting use cases

For detailed API documentation, authentication requirements, and example usage, refer to the .

Example API request:

POST /api/v1/assessments/vql:nodes
{
  "query": "SHOW OktaUser WHERE is_active = true RELATED TO S3Bucket RESULT INCLUDE DESTINATION NODES LIMIT 50;"
}

The response supports pagination, and returns a JSON object with the query results, for example:

{
  "values": [],
  "path_values": [
    {
      "source": {
        "id": "00u5pqrs7xyP9uvw30z9",
        "type": "OktaUser",
        "properties": {
          "activated_at": "2023-06-12T15:21:34Z",
          "created_at": "2023-04-20T04:30:37Z",
          "credentials_provider_name": "OKTA",
          "credentials_provider_type": "OKTA",
          "datasource_id": "example.oktapreview.com",
          "email": "jsmith@example.com",
          "first_name": "John",
          "identity_type": "HUMAN",
          "idp_unique_id": "jsmith@example.com",
          "is_active": true,
          "last_login_at": "2024-08-02T05:52:42Z",
          "last_name": "Smith",
          "login": "jsmith@example.com",
          "mfa_active": true,
          "mfa_factors": [
            "question"
          ],
          "name": "jsmith@example.com",
          "okta_user_type_id": "otyf8xyz92hv7mnP60j9",
          "owners": "[{\"entity_id\":\"00ukmnop51qR3s4TU6e8\",\"entity_type\":\"OktaUser\",\"entity_name\":\"Maria Rodriguez\"}]",
          "password_exists": true,
          "password_last_set": "2024-08-02T05:52:42Z",
          "provider_id": "example.oktapreview.com",
          "recovery_question_exists": true,
          "risk_score": 100,
          "status": "ACTIVE",
          "status_updated_at": "2024-08-02T05:52:42Z",
          "updated_at": "2025-01-16T05:53:38Z"
        },
        "risk_level": "CRITICAL"
      },
      "abstract_permissions": [
        "MetadataRead"
      ],
      "concrete_permissions": [
        "s3:ListBucket"
      ],
      "destination": {
        "id": "arn:aws:s3:::aws-cloudtrail-logs-123456789012-abcdef12",
        "type": "S3Bucket",
        "properties": {
          "allows_acls": false,
          "aws_account_id": "123456789012",
          "aws_account_name": "",
          "block_public_access_enabled": true,
          "block_public_acls": true,
          "block_public_policy": true,
          "created_at": "2024-05-04T04:50:42Z",
          "datasource_id": "123456789012:s3",
          "default_encryption_enabled": true,
          "default_retention_mode": "DISABLED",
          "hosts_website": false,
          "ignore_public_acls": true,
          "name": "aws-cloudtrail-logs-123456789012-abcdef12",
          "object_lock_enabled": false,
          "object_ownership_controls": "BucketOwnerEnforced",
          "provider_id": "123456789012",
          "region": "us-east-1",
          "replication_rules_count": 0,
          "request_payer": "BucketOwner",
          "restrict_public_buckets": true,
          "risk_score": 27,
          "server_access_logs_enabled": false
        },
        "risk_level": "LOW"
      }
    }
  ],
  "next_page_token": "",
  "has_more": false
}

Resources

To learn more about VQL capabilities, see the following resources:

: Learn how to construct basic queries with examples
: Guide to VQL syntax, operators, and advanced features
: API documentation for executing VQL queries programmatically

Syntax

Reference documentation for Veza Query Language.

This document provides information about the VQL (Veza Query Language) query specification, which offers a SQL-like interface to the . See the for detailed usage and examples.

Concepts

Early Access: VQL is subject to modifications as we add and improve functionality. Future updates will aim to preserve compatibility with earlier versions.

A VQL query is composed of the following components:

Source Nodes: Node types in VQL represent entity types within Veza's Identity Graph. Each node type can have many individual instances, returned as rows in the query output.
Path requirements: Graph nodes can be interrelated, forming complex graph structures. Specifying related nodes filters results with a matching relationship.
Filters and Modifiers: Filter expressions (WHERE clauses) to constrain results based on attributes or other criteria.

VQL Expression Syntax

A VQL query always includes a SHOW statement describing the source node type. The general syntax is:

SHOW [NodeSpec] -- Specifies the source node type
[ [NOT] RELATED TO [NodeSpec]] -- Filters results by related node type
[WITH | NOT WITH] PATH [NodeSpec] -- Filters on intermediate nodes
[WHERE (filter expressions)]
[RESULT INCLUDE [DESTINATION NODES | DESTINATION NODE COUNT | PATH SUMMARY]]
[HAVING [entity_result_count (condition) | percentage_of_total_count (condition)]]
[WITH QUERY OPTIONS (options)]
[AFTER CURSOR 'cursor_token'] -- For pagination, use cursor token from previous results
[LIMIT <number>]; -- Limit number of results returned

NodeSpec Syntax

A NodeSpec describes a source or destination entity type. It can include attribute selection (which columns to return) and filters using a WHERE clause. The full syntax is:

[NodeType] [{ attribute1, attribute2, ... }] [WHERE (<attribute_name> <operator> <value> [AND|OR] ...)]

Basic Components:

NodeType: The type of node (e.g., AwsIamUser, OktaGroup)
Attribute Selection: Optional curly braces { } containing a comma-separated list of attributes to include in the results
WHERE: Optional clause that applies attribute-based filters to the nodes using the selected operators

Usage Examples

Basic node specification (returns all attributes):

SHOW AwsIamUser

Select specific attributes to display:

SHOW AwsIamUser { created_at, is_active, full_admin }

Apply filters without attribute selection:

SHOW AwsIamUser WHERE is_active = true

Combine attribute selection and filters:

SHOW AwsIamUser { created_at, email } WHERE is_active = true AND risk_score > 70

In this more complex example, we select specific attributes for both the source (OktaUser) and destination (S3Bucket) nodes while also applying filters to the results:

SHOW OktaUser { email, last_login_at, department }
WHERE last_login_at >= CURRENT_DATE - 30
RELATED TO S3Bucket
WHERE block_public_acls = false
WITH PATH OktaGroup
WITH QUERY OPTIONS ( over_provisioned_score > 85 )

Where Clause Operators

A range of operators can be used to filter results depending on node properties. Currently, VQL supports the comparison operators:

Comparison Operators

Operator

Supported Data Types

Example

<, >, <=, >=, =, !=

NUMERIC, TIMESTAMP, TIME FUNCTIONS

risk_score < 80 created_at >= '2023-10-05 14:30:00.123' created_at < CURRENT_DATE - 30

STARTS_WITH

STRING

name STARTS_WITH 'S'

ENDS_WITH

STRING

name ENDS_WITH 'E'

LIST_CONTAINS

STRING

permissions LIST_CONTAINS 'iam:PassRole'

LIST_ALL_ELEMENTS_IN

STRING

accounts_assumed_by LIST_ALL_ELEMENTS_IN ('accountid1', 'accountid2')

REGEX

STRING

name REGEX 'TEst.*'

LIST_ANY_ELEMENT_EQ

STRING

permissions LIST_ANY_ELEMENT_EQ 'iam:SetDefaultPolicyVersion'

LIST_ANY_ELEMENT_STARTS_WITH

STRING

cai_tags LIST_ANY_ELEMENT_STARTS_WITH 'P'

LIST_ANY_ELEMENT_CONTAINS

STRING

cai_tags LIST_ANY_ELEMENT_CONTAINS 'policy'

LIST_ANY_ELEMENT_ENDS_WITH

STRING

cai_tags LIST_ANY_ELEMENT_ENDS_WITH 'admin'

LIST_ANY_ELEMENT_REGEX

STRING

cai_tags LIST_ANY_ELEMENT_REGEX '::'

IS NULL

STRING

show Key WHERE last_rotated_at IS NULL

IS NOT NULL

STRING

show Key WHERE last_rotated_at IS NOT NULL

Data Types and Restrictions

Data Types: VQL supports boolean, integer, string, and null data types.
Case Sensitivity: VQL is typically case-sensitive for:
- Node Types: Must be written exactly as defined (e.g., AwsIamUser, not awsiamuser).
- Attribute Names: Must match the exact casing (e.g., is_active, not Is_Active).

Entity Attributes

Entity attributes in VQL are used to filter and select graph nodes. They consist solely of alphanumeric characters or underscores (e.g., last_login, email_address).

Permissions

In addition to attribute filters, VQL queries can use permission filters. Both system permissions and effective permissions are supported.

System Permissions

SHOW AwsIamUser
RELATED TO S3Bucket
WITH SYSTEM PERMISSIONS = ANY ('s3:CreateBucket');

ANY: Used to filter for any of the supplied permissions (logical OR).
ALL: Ensures that all permissions passed should be present on the resource (logical AND).

Effective Permissions

Veza supports nine different effective permissions. These are abstracted permissions that express system permissions in common groups:

METADATA_READ
METADATA_WRITE
METADATA_CREATE
METADATA_DELETE
DATA_READ
DATA_WRITE
DATA_CREATE
DATA_DELETE
NON_DATA

The following query shows all AWS IAM Roles that grant effective permissions to read or write S3 bucket metadata:

SHOW AwsIamRole
RELATED TO S3Bucket
WHERE is_active = false
WITH EFFECTIVE PERMISSIONS = ALL ('METADATA_READ', 'METADATA_WRITE');

Effective permissions filters require a destination type (specified by the RELATED TO clause).

Intermediate Nodes

Including Intermediate Nodes:

SHOW OktaUser
RELATED TO SnowflakeTable
WITH PATH SnowflakeUser;

Excluding Intermediate Nodes:

SHOW OktaUser
RELATED TO SnowflakeTable
NOT WITH PATH OktaGroup;

Modifiers and Filters

Use the WHERE clause to apply filters. You can combine multiple conditions with AND or OR statements:

Example:

SHOW AwsIamUser
WHERE is_active = true AND risk_score > 70;

Pagination

VQL supports pagination for queries that return large result sets. Two keywords control pagination behavior:

LIMIT: Restricts the number of results returned in a single query
AFTER CURSOR: Used with a cursor token to retrieve the next set of results

Example of initial query with limit:

SHOW AwsIamUser
RELATED TO S3Bucket
LIMIT 50;

For subsequent requests, use the cursor token from the previous response:

SHOW AwsIamUser
RELATED TO S3Bucket
AFTER CURSOR 'elcl9uYW1lIjoicjJkMiJ9fQ=='
LIMIT 50;

Result Output

By default, queries return a list of source entity types and attributes. Use the RESULT INCLUDE clause to specify how query results appear:

DESTINATION NODES: Includes information about related destination nodes.
DESTINATION NODE COUNT: Provides a count of related destination nodes.
PATH SUMMARY: Summarizes the paths between source and destination nodes.

Example:

SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;

Veza Query Language

Overview

Getting Started

Concepts and Syntax

Example Queries

Query All S3 Buckets

Query IAM Users Related to S3 Buckets

Apply Attribute Filters

Include Destination Nodes

Use Path Requirements

Exclude Specific Paths

Filter by Over-Provisioned Score

Filter by Related Entity Count

Query Using Time Functions

Executing VQL Queries

Using the VQL API

Resources

Quick Start

Getting Started with VQL

Query for Entities

Query for Relationships

Applying Attribute Filters

Using Path Requirements

Including Destination Entities

Including Summary Entities

Filtering by Related Entity Count

Using Over-Provisioned Score

Using Pagination

Learning More

Syntax

Concepts

VQL Expression Syntax

NodeSpec Syntax

Usage Examples

Where Clause Operators

Data Types and Restrictions

Entity Attributes

Permissions

System Permissions

Effective Permissions

Intermediate Nodes

Modifiers and Filters

Pagination

Result Output

VQL API

Overview

VQL vs. Traditional Approaches

Example Comparison

Requirements

API Endpoints

Get Query Results (Count)

Get Query Results (Nodes)

Example Request

Understanding the API Response

Pagination

Related Documentation

Quick Start

Getting Started with VQL

Query for Entities

Query for Relationships

Applying Attribute Filters

Using Path Requirements

Including Destination Entities

Including Summary Entities

Filtering by Related Entity Count

Using Over-Provisioned Score

Using Pagination

Learning More

Veza Query Language

Overview

Getting Started

Concepts and Syntax

Example Queries

Query All S3 Buckets

Query IAM Users Related to S3 Buckets

Apply Attribute Filters

Include Destination Nodes

Use Path Requirements

Exclude Specific Paths

Filter by Over-Provisioned Score