> ## Content Index
> Fetch the complete content index at: https://www.techielass.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Documenting your KQL queries
- URL: https://www.techielass.com/documenting-your-kql-queries/
- Published: 2025-02-25T08:01:47.000Z
- Updated: 2025-03-29T14:51:45.000Z
- Description: Join me as I explore why you should add comments to your Kusto Query Language (KQL) queries.
- Author: Sarah Lean
- Tags: Kusto

Documentation is important. It helps your colleagues to understand why you did something. It helps you later on remember why you did something. 

Documenting your [Kusto Query Language (KQL)](https://www.techielass.com/tag/kusto/) queries is just important. 

In this blog, we’ll explore why documenting your queries matters, how to write effective comments in KQL, and practical tips for maintaining clarity and structure.

### Why documenting queries matters

There are several benefits to documenting your queries. 

1. When something breaks, clear comments and documentation make troubleshooting faster.
2. Team members can quickly understand your query logic, even if they didn’t write it.
3. Documentation reduces the learning curve for new team members.
4. Clear notes help you (or someone else) understand the query’s purpose months or years later.

Imagine encountering this query months after writing it:

```kql
SecurityEvent 
| where EventID == 4625 
| summarize count() by AccountName

```

Without comments, you might not remember the query’s purpose. Proper documentation solves this problem.

### How to add comments in KQL

Within KQL you can denote a comment using two forward slashes: //

You can use this either on a single line or multiple lines. 

An example query would be: 

```kql
// Filter for failed login attempts
SecurityEvent
| where EventID == 4625

```

Alternatively, you could write a more in-depth description in your query like this:// Show Microsoft Defender for Cloud pricing per subscription

```kql
// Returns Microsoft Defender plans’ pricing per subscription.
// 
// The query uses 'project' to show the listed properties in the results. You can add or remove properties.
// 
securityresources
| where type == 'microsoft.security/pricings'
| project Subscription= subscriptionId, Azure_Defender_plan= name, Status= properties.pricingTier

```

Every line that you want to to write a comment on, or if you are leaving blank lines need to start with the two forward slashes. If not they might be mistaken as part of the query, which could cause problems when you run the query. 

You can also add comments per line such as this:

```kql
SecurityEvent // The dataset
| where TimeGenerated > ago(1h) // Activity in the last hour
| where EventID == 4624 // Successful logon
| where AccountType =~ "user" // case insensitive

```

Over the years I’ve learnt that well-placed documentation or comments in queries can be really helpful. Some of the things I include in comments on my queries:

- The purpose of the query and what it is trying to achieve.
- Explaining key steps, especially on multi step or complex queries.
- Assumptions or limitations. For example if a time or date is part of the query, I explain if it’s using American date format (MM/DD/YYYY) or if it’s using European/International date format (DD/MM/YYYY).
- Who created the query and when.

💡

Check out my other Kusto blogs:  
\- [Visualising data with KQL](https://www.techielass.com/visualising-data-with-kql/)  
\- [Understanding KQL functions](https://www.techielass.com/understanding-kql-functions/)  
\- [Understanding KQL operators](https://www.techielass.com/understanding-kql-operators/)

### Conclusion

Documenting your KQL queries isn’t just best practice - it’s necessary to help with collaboration, debugging and future-proofing. 

Add purposeful comments to your queries and they’ll become a valuable library over time. 

Start documenting your queries today, and share your favourite tips in the comments!