Understanding the Azure Resource Graph query language

The query language for the Azure Resource Graph supports a number of operators and functions. Each work and operate based on Kusto Query Language (KQL). To learn about the query language used by Resource Graph, start with the tutorial for KQL.

This article covers the language components supported by Resource Graph:

Resource Graph tables

Resource Graph provides several tables for the data it stores about Resource Manager resource types and their properties. These tables can be used with join or union operators to get properties from related resource types. Here is the list of tables available in Resource Graph:

Resource Graph tables Description
Resources The default table if none defined in the query. Most Resource Manager resource types and properties are here.
ResourceContainers Includes subscription (in preview -- Microsoft.Resources/subscriptions) and resource group (Microsoft.Resources/subscriptions/resourcegroups) resource types and data.
AlertsManagementResources Includes resources related to Microsoft.AlertsManagement.
SecurityResources Includes resources related to Microsoft.Security.

Note

Resources is the default table. While querying the Resources table, it isn't required to provide the table name unless join or union are used. However, the recommended practice is to always include the initial table in the query.

Use Resource Graph Explorer in the portal to discover what resource types are available in each table. As an alternative, use a query such as <tableName> | distinct type to get a list of resource types the given Resource Graph table supports that exist in your environment.

The following query shows a simple join. The query result blends the columns together and any duplicate column names from the joined table, ResourceContainers in this example, are appended with 1. As ResourceContainers table has types for both subscriptions and resource groups, either type might be used to join to the resource from resources table.

Resources
| join ResourceContainers on subscriptionId
| limit 1

The following query shows a more complex use of join. The query limits the joined table to subscriptions resources and with project to include only the original field subscriptionId and the name field renamed to SubName. The field rename avoids join adding it as name1 since the field already exists in Resources. The original table is filtered with where and the following project includes columns from both tables. The query result is a single key vault displaying type, the name of the key vault, and the name of the subscription it's in.

Resources
| where type == 'microsoft.keyvault/vaults'
| join (ResourceContainers | where type=='microsoft.resources/subscriptions' | project SubName=name, subscriptionId) on subscriptionId
| project type, name, SubName
| limit 1

Note

When limiting the join results with project, the property used by join to relate the two tables, subscriptionId in the above example, must be included in project.

Supported KQL language elements

Resource Graph supports all KQL data types, scalar functions, scalar operators, and aggregation functions. Specific tabular operators are supported by Resource Graph, some of which have different behaviors.

Supported tabular/top level operators

Here is the list of KQL tabular operators supported by Resource Graph with specific samples:

KQL Resource Graph sample query Notes
count Count key vaults
distinct Show distinct values for a specific alias
extend Count virtual machines by OS type
join Key vault with subscription name Join flavors supported: innerunique, inner, leftouter. Limit of 3 join in a single query. Custom join strategies, such as broadcast join, aren't allowed. May be used within a single table or between the Resources and ResourceContainers tables.
limit List all public IP addresses Synonym of take
mv-expand List Cosmos DB with specific write locations RowLimit max of 400
order List resources sorted by name Synonym of sort
project List resources sorted by name
project-away Remove columns from results
sort List resources sorted by name Synonym of order
summarize Count Azure resources Simplified first page only
take List all public IP addresses Synonym of limit
top Show first five virtual machines by name and their OS type
union Combine results from two queries into a single result Single table allowed: T | union [kind= inner|outer] [withsource=ColumnName] Table. Limit of 3 union legs in a single query. Fuzzy resolution of union leg tables isn't allowed. May be used within a single table or between the Resources and ResourceContainers tables.
where Show resources that contain storage

Escape characters

Some property names, such as those that include a . or $, must be wrapped or escaped in the query or the property name is interpreted incorrectly and doesn't provide the expected results.

  • . - Wrap the property name as such: ['propertyname.withaperiod']

    Example query that wraps the property odata.type:

    where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.['odata.type']
    
  • $ - Escape the character in the property name. The escape character used depends on the shell Resource Graph is run from.

    • bash - \

      Example query that escapes the property $type in bash:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.\$type
      
    • cmd - Don't escape the $ character.

    • PowerShell - `

      Example query that escapes the property $type in PowerShell:

      where type=~'Microsoft.Insights/alertRules' | project name, properties.condition.`$type
      

Next steps