If you need help constructing a VQL query, navigate to the Network Flow Reports page and click New Network Flow Report. From the top left, open the Filters menu. Create a filter and click the View as VQL button at the top of the Filters menu to see a filter’s VQL representation. You can copy this syntax to use within your API calls.
Network Flow Reports VQL Schema
VQL for Network Flow Reports comprises one namespace,network_flow_logs, which represents the available filters on Network Flow Reports in the Vantage console. To reference a filter, use the following syntax: namespace.field (e.g., network_flow_logs.account_id). The following fields are available within the network_flow_logs namespace.
| Namespace | Field | VQL Example |
|---|---|---|
network_flow_logs | account_id | Account ID example |
network_flow_logs | az_id | Availability Zone ID example |
network_flow_logs | dstaddr | Destination Address example |
network_flow_logs | dsthostname | Destination Hostname example |
network_flow_logs | interface_id | Interface ID example |
network_flow_logs | instance_id | Instance ID example |
network_flow_logs | peer_resource_uuid | Peer Resource UUID example |
network_flow_logs | peer_account_id | Peer Account ID example |
network_flow_logs | peer_vpc_id | Peer VPC ID example |
network_flow_logs | peer_regions | Peer Regions example |
network_flow_logs | peer_az_id | Peer AZ ID example |
network_flow_logs | peer_subnet_id | Peer Subnet ID example |
network_flow_logs | peer_interface_id | Peer Interface ID example |
network_flow_logs | peer_instance_id | Peer Instance ID example |
network_flow_logs | region | Region example |
network_flow_logs | resource_uuid | Resource UUID example |
network_flow_logs | srcaddr | Source Address example |
network_flow_logs | srchostname | Source Hostname example |
network_flow_logs | subnet_id | Subnet ID example |
network_flow_logs | traffic_category | Traffic Category example |
network_flow_logs | traffic_path | Traffic Path example |
network_flow_logs | vpc_id | VPC ID example |
Keywords
VQL includes a set of keywords to create complex filter conditions. These keywords function similar to their SQL equivalents. Note that each expression started withprovider = 'aws', followed by additional filters.
| Keyword | Description | VQL Sample | Explanation |
|---|---|---|---|
AND | Logical AND operator | (network_flow_logs.account_id = '123456789012') AND (network_flow_logs.dsthostname = 'datadoghq.com') | This example filters for a specific account and destination hostname, where both conditions must be true. |
OR | Logical OR operator | (network_flow_logs.account_id = '123456789012') AND (network_flow_logs.dsthostname = 'datadoghq.com') OR (network_flow_logs.account_id = '09876543212') AND (network_flow_logs.dsthostname = 'github.com') | This example looks for results associated with two accounts and destination hostnames. At least one condition must be true. |
!= | Is not | (network_flow_logs.dsthostname != 'github.com') | This example looks for results that are any destination hostname type except for github.com. |
IN and NOT IN | Used to compare against an array/list | (network_flow_logs.peer_regions IN ('us-east-1','us-west-2')) | This example searches for results within a set of regions. This same query also works for NOT IN where the results are anything matching everything except for these regions: (network_flow_logs.peer_regions NOT IN ('us-east-1','us-west-2')). |
LIKE and NOT LIKE | Performs string comparisons | (network_flow_logs.az_id LIKE '%use1%') | This example selects data where the Availability Zone contains use1, such as use1-az1. This same query also works for NOT LIKE where data does not contain a particular string: (network_flow_logs.az_id NOT LIKE '%use1%'). |
VQL Examples
The following examples cover common use cases for VQL.Network Flows by Account ID
Network flows from a set of account IDs.Network Flows by Availability Zone ID
Filter for a substring based on Availability Zone.Network Flows by Destination Address
All network flows that do not match a particular destination adddress.Network Flows by Destination Hostname
Network flows from a set of destination hostnames.Network Flows by Interface ID
Network flows for a particular interface ID.Network Flows by Instance ID
Network flows for a particular instance ID.Network Flows by Peer Resource UUID
Network flows for peer resource UUIDs matching a substring.Network Flows by Peer Account ID
Network flows for anything that’s not a particular peer account ID.Network Flows by Peer VPC ID
Network flows for two different peer VPC IDs.Network Flows by Peer Regions
Network flows for anything outside a set of peer regions.Network Flows by Peer AZ ID
Network flows for a specific peer AZ.Network Flows by Peer Subnet ID
Network flows for any peer subnet IDs that do not contain a substring.Network Flows by Peer Interface ID
Network flows based on a peer interface ID substring.Network Flows by Peer Instance ID
Network flows excluding a particular peer instance ID.Network Flows by Region
Network flows in multiple regions.Network Flows by Resource UUID
Network flows for resources not matching a specific UUID substring.Network Flows by Source Address
Network flows from a set of source addresses.Network Flows by Source Hostname
Network flows excluding specific source hostnames.Network Flows by Subnet ID
Network flows for subnets with a specific prefix.Network Flows by Traffic Category
Only cross-region traffic.Network Flows by Traffic Path
Network flows for Inter-Region VPC Peering. Traffic paths have a specific key, as described below.| Key | Traffic Path |
|---|---|
| 1 | In VPC |
| 2 | Internet Gateway or Gateway VPC Endpoint |
| 3 | Virtual Private Gateway |
| 4 | Intra-Region VPC Peering |
| 5 | Inter-Region VPC Peering |
| 6 | Local Gateway |
| 7 | Gateway VPC Endpoint (Nitro-based instances) |
| 8 | Internet Gateway (Nitro-based instances) |
Network Flows by VPC ID
Everything except for a specific VPC.Multiple Filters
Complex filter that shows combining two different statements usingOR with multiple criteria.