# Quick Start

### 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).

* Every query constructed using the [Veza Query Language](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/vql) 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.

  ```vql
  SHOW S3Bucket;
  ```
* After specifying the source node, you can apply filters (`WHERE` clauses) and relationship constraints (`RELATED TO`) to further narrow your search.

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

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

For the detailed VQL specification, see [VQL Syntax](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-syntax).

### Query for Entities

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

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:

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

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

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

Conversely, to list S3 Buckets accessible by IAM Users:

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

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

```vql
SHOW AwsIamUser
RELATED TO S3Bucket
WITH PATH AwsIamRole;
```

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

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

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

This output format is equivalent to the [Show Destination Entities](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/query-builder#result-options) option in Query Builder or the format of an [Access Review](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/access-reviews/configuration/access-reviews-query-builder).

### Including Summary Entities

VQL supports [summary entities](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/access-reviews/configuration/presentation-options#summary-entities) 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:

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

{% hint style="info" %}
Including path summary will automatically include all destination nodes. You don’t need to explicitly use the keyword `INCLUDE DESTINATION NODES`.
{% endhint %}

### Filtering by Related Entity Count

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:

```vql
SHOW AwsIamUser
RELATED TO S3Bucket
HAVING entity_result_count > 10;
```

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

```vql
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 [Over-Provisioned Score](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/activity-monitoring#over-provisioned-score) (available for supported integrations):

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

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

```vql
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 [VQL Syntax](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/features/search/vql/vql-syntax)