Maybe you could relate, you’re maintaining an Azure Data Explorer database or KQL database in Fabric, and there are just a bunch of tables and functions. You don’t know what a table is created for or what it contains. If you get lucky, the name is self explanatory.

In this article I will explain a way how to document and organize your KQL (Kusto Query Language) queries.

Documentation

It is essential to document your code, to:

  • Help others (and your future self) to understand what your code does and why certain decisions were made
  • Maintain, update, and debug your code
  • Improve code quality, it forces you to think it through
  • Support onboarding by reducing the learning curve for new team member

Comments

Imagine a colleague needs to update the following query that is written over a year ago:

DeliveryOrders
| where OrderId == '1234'
| sort by Timestamp

What is this query used for? Why is there a filter?

By adding comments these questions are easily answered. In KQL (Kusto Query Language), you can add comments by adding // before your text. This does not necessarily have to be at the beginning of the line. Now look at the updated query:

// This query is an example to display a specific order of person X.
DeliveryOrders
| where OrderId == '1234' // filter on the delivery the specific OrderId
| sort by Timestamp

This already gives more context to the query and what it is used for. This is of course a very simple example, but with complex queries it will help you so much more.

Docstring

Another great way to improve the documentation is by adding a docstring to your functions and tables. This way you can add a description to your functions and tables. Let’s try this with the DeliveryOrders table:

.alter table DeliveryOrders docstring "This table contains all delivery orders"

Simple right?

Now when you hover over the table in Azure Data Explorer or in Fabric, an information icon will appear.

If you then hover over the information icon, you will get the description of the table:

When you are using Kusto.Explorer, a desktop tool to query and analyse the data, the description is already in the column next to the column name:

Let’s organize

Now that we documented our code, tables and functions, let’s create a bit more overview by organizing the tables and queries.

By adding a folder to a function or table, it is possible to create a hierarchy and therefore a better overview. This groups tables and functions that belong together and helps to quickly find tables and functions.

The command to add a folder is simple, and you can even add multiple levels, for example:

.alter table DeliveryOrders folder @"First Level\Second Level"

This will result in a more organized database, where you can easily find the things your looking for:

Summary

By organizing and documenting KQL tables, functions and queries, it becomes much easier to maintain, update, and debug your code. In this article I gave some examples on how to this by using comments and using the docstring and folder commands.

ps. Did you notice the tables from the Kusto Detective Agency? This is a exciting interactive big data contest from Microsoft using KQL.