# Veza Query Language

{% hint style="success" %}
**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.
{% endhint %}

### 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.
* Enrich query results with related entity data from adjacent integrations using enrichment clauses.

VQL queries follow consistent patterns for different types of operations:

```vql
-- 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:**

```vql
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:**

```vql
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 [Quick Start Guide](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-quickstart.md).

### 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`.
* **Enrichment:** Augment source or destination nodes with related entity data from other integrations using `ENRICH WITH`, `ENRICH SOURCE WITH`, or `ENRICH DESTINATION WITH`.
* **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:

```vql
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)]
[ENRICH WITH [NodeSpec | (NodeSpec, ...)]]
[ENRICH SOURCE WITH [NodeSpec | (NodeSpec, ...)]]
[ENRICH DESTINATION WITH [NodeSpec | (NodeSpec, ...)]];
```

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 [VQL Syntax](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-syntax.md#comparison-operators).

### Example Queries

#### Query All S3 Buckets

Retrieve all AWS S3 Buckets:

```vql
SHOW S3Bucket;
```

#### Query IAM Users Related to S3 Buckets

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

```vql
SHOW AwsIamUser
RELATED TO S3Bucket;
```

#### Apply Attribute Filters

List active AWS IAM Users in the Engineering department:

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

#### Include Destination Nodes

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

```vql
SHOW AwsIamUser
RELATED TO S3Bucket
RESULT INCLUDE DESTINATION NODES;
```

#### Use Path Requirements

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

```vql
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:

```vql
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:

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

#### Enrich Results with Related Entity Data

Show Okta Users related to AWS IAM Roles, enriched with Workday employee data:

```vql
SHOW OktaUser RELATED TO AwsIamRole ENRICH WITH WorkdayEmployee
```

Enrich with multiple types at once:

```vql
SHOW OktaUser RELATED TO AwsIamRole ENRICH WITH (WorkdayEmployee, ActiveDirectoryUser)
```

#### Filter by Related Entity Count

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

```vql
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:

```vql
SHOW OktaUser
WHERE last_login_at >= CURRENT_DATE - 30;
```

### Executing VQL Queries

There are two ways to execute VQL queries:

1. **VQL API**: Execute VQL queries programmatically through Veza's Assessment Query API endpoints
2. **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 [VQL API Reference](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-api.md).

Example API request:

```bash
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:

```json
{
  "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:

* [VQL Quick Start](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-quickstart.md): Learn how to construct basic queries with examples
* [VQL Syntax Reference](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-syntax.md): Guide to VQL syntax, operators, and advanced features
* [VQL API Reference](/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-api.md): API documentation for executing VQL queries programmatically


---

# 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/features/search/vql.md?ask=<question>
```

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.