Skip to content

Commit

Permalink
Update assessment.md - Submission by Tamara
Browse files Browse the repository at this point in the history
Here is a summary of the changes I made to this article:
-Title: changed for clarity
-Added "applies to" links at the top, which I saw in other articles and made sense here as well.
-Intro: I trimmed it down significantly, and tried to remove jargon that seemed extraneous.  I also employed content reuse, by taking some text from an existing article, and applying it here.  It was preferable to the text that was in this version.  I did make some light edits to the "lifted" text however.
-Body of article: 
1. I reordered the content, adding headings and subheadings, blockquotes (notes), code script, bullets, and so on where it seemed to improve clarity.  
2. I removed details about management commands, as it seemed like a diversion from the main focus of the article.  I instead put a link to more information about management commands in the references at the bottom.
3. I added bullets to the links in the KQL in other services
4. I corrected the References section title at the bottom, and at least 1 spelling error in one of the links.  I also reordered these links slightly, in the hopes that it was a more intuitive order.
5. In Types of query statements, I added info I found in my research about the two types of statements... but tried to maintain focus in the article on the three (not two) types of user query statements.
6. I added some helper text introducing the example, and added a heading to that section as well, removing language that seemed too informal.

Items I would have liked to have added with more time and knowledge:
-Concrete examples of each user query statement types
-A more thorough audit of the reference links, making sure anything relevant was included.

Thank you for the opportunity.
  • Loading branch information
TFS-82 authored Dec 10, 2024
1 parent 28fed1c commit a798de1
Showing 1 changed file with 19 additions and 39 deletions.
58 changes: 19 additions & 39 deletions data-explorer/kusto/query/assessment.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,64 +5,44 @@ ms.reviewer: orspod
ms.topic: reference
ms.date: 08/11/2024
---
# Kusto Query Language (KQL) introduction
# Kusto Query Language (KQL): An introduction
> [!INCLUDE [applies](../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../includes/applies-to-version/azure-data-explorer.md)] [!INCLUDE [monitor](../includes/applies-to-version/monitor.md)] [!INCLUDE [sentinel](../includes/applies-to-version/sentinel.md)]
Kusto Query Language (KQL) is a powerful tool for exploring your data, uncovering patterns, identifying anomalies and outliers, creating statistical models, and more.
KQL is a versatile language that allows you to query all types of data structures effectively. The language is expressive and straightforward, making queries easy to read, author, and understand.

This article helps you begin to unlock your data by offering an introduction to KQL, as well as resources to help you start writing valuable queries.

## What is a Kusto query?
A Kusto query is a read-only request to process data and return results. The request appears in plain text, using a highly accessible data format. Any Kusto query is made of one or more query statements, each separated by a semicolon (`;`).

A Kusto query is a read-only request to process data and return results. The request appears in plain text, using a highly accessible data format. Any Kusto query is made of one or more query statements, each separated by a semicolon (`;`).
> [!NOTE]
> KQL is case-sensitive for all inputs, including table names, table column names, operators, functions, and so on.

### What are query statements?
### Types of query statements
Query statements break down into two categories:
- Statements primarily used by users ([user query statements](https://learn.microsoft.com/en-us/kusto/query/statements?view=azure-data-explorer#user-query-statements))
- Statements designed to support scenarios in which mid-tier applications modify user queries and send them to Kusto ([application query statements](https://learn.microsoft.com/en-us/kusto/query/statements?view=azure-data-explorer#application-query-statements)).

This article will focus only on types of user query statements.
This article focuses on types of user query statements only.

### Kinds of user query statements
#### User query statements
There are three kinds of user [query statements](statements.md):

1. A [tabular expression statement](tabular-expression-statements.md)
1. A [let statement](let-statement.md)
1. A [set statement](set-statement.md)

> [!NOTE]
> All KQL queries require at least one tabular expression statement.
### Parameters by query statement type
Each type of user query statement has its own distinct syntax and set of parameters.

#### Tabular expresssion statements

|Name|Type|Required|Description|
|--|--|--|--|
|*Source*| `string` | :heavy_check_mark:|A tabular data source. See [Tabular data sources](#tabular-data-sources).|
|*Operator*| `string` | :heavy_check_mark:|Tabular data operators, such as filters and projections.|
|*RenderInstruction*| `string` ||Rendering operators or instructions.|

#### Let statements

#### Set statements

| Name | Type | Required | Description |
|--|--|--|--|
| *OptionName* | `string` | :heavy_check_mark: | The name of the request property.|
| *OptionValue* | | :heavy_check_mark: | The value of the request property.|

## Access the query environment
To access the query environment, use the [Azure Data Explorer web UI](https://dataexplorer.azure.com/). To learn how to use KQL, see [Tutorial: Learn common operators](tutorials/learn-common-operators.md).
The most common kind of query statement is a tabular expression statement. Tabular statements contain zero or more **operators**, each of which starts with a tabular input and returns a tabular output. Operators are sequenced by a `|` (pipe). The data is filtered or manipulated at each step and then fed into the following step. In this way, it acts like a funnel, filtering, rearranging, or summarizing the data further as it passes through the next operator in the pipeline. [Learn common operators](tutorials/learn-common-operators.md).

> [!NOTE]
> - All KQL queries require at least one tabular expression statement.
> - The sequence of the query operators is important. It determines the order through which the data moves through the funnel, narrowing the results.
It's like a funnel, where you start out with an an entire data table. Each time the data passes through another operator, it's filtered, rearranged, or summarized. Because the piping of information from one operator to another is sequential, the query operator order is important, and can affect both results and performance. At the end of the funnel, you're left with a refined output.

## Example
### Example
The following query counts the number of records in the `StormEvents` table whose `StartTime` is between January 11-12, 2007 and which have a value of `Florida` in the `State` column.

> [!div class="nextstepaction"]
Expand All @@ -79,22 +59,22 @@ The query returned a result of 28 records meeting the requested criteria:
|-----|
| 28|

## Access the query environment
To access the query environment, use the [Azure Data Explorer web UI](https://dataexplorer.azure.com/).

## KQL in other services

KQL is used by many other Microsoft services. For specific information on the use of KQL in these environments, refer to the following links:

[Log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview)
[Kusto Query Language in Microsoft Sentinel](/azure/sentinel/kusto-overview)
[Understanding the Azure Resource Graph query language](/azure/governance/resource-graph/concepts/query-language)
[Proactively hunt for threats with advanced hunting in Microsoft 365 Defender](/microsoft-365/security/defender/advanced-hunting-overview)
[CMPivot queries](/mem/configmgr/core/servers/manage/cmpivot-overview#queries)
- [Log queries in Azure Monitor](/azure/azure-monitor/logs/log-query-overview)
- [Kusto Query Language in Microsoft Sentinel](/azure/sentinel/kusto-overview)
- [Understanding the Azure Resource Graph query language](/azure/governance/resource-graph/concepts/query-language)
- [Proactively hunt for threats with advanced hunting in Microsoft 365 Defender](/microsoft-365/security/defender/advanced-hunting-overview)
- [CMPivot queries](/mem/configmgr/core/servers/manage/cmpivot-overview#queries)

## References and tutorials

* [Tutorial: Learn common operators](tutorials/learn-common-operators.md)
* [Query best practices](best-practices.md)
* [Tutorial: Use aggregation functions](tutorials/use-aggregation-functions.md)
* [KQL quick reference](kql-quick-reference.md)
* [SQL to Kusto Query Language cheat sheet](sql-cheat-sheet.md)
* [Query best practices](best-practices.md)
* [About management commands](../management/index.md)

0 comments on commit a798de1

Please sign in to comment.