Introduction to Keyword Query Language (KQL) – Part 1

Keyword Query Language (KQL) is a search syntax used to query data within a variety of search sources. KQL searches can be performed in applications such as SharePoint, Office 365, and other Microsoft products. It is designed for easy use by end users, allowing them to quickly find relevant information without having to understand the underlying information architecture and data structure.

KQL can be used to search through text, numbers, and date types stored in SharePoint lists and libraries on-prem and in the cloud. KQL allows users to narrow down the query by adding conditions such as date ranges and wildcards. KQL also provides operators to refine the search results.

KQL can be used in the search box, in Highlighted Content Web Part, but it also allows developers to query the search index from their own applications.

---

Example Data

In our simple example, let’s say we have items (restaurants) with the following properties:

---

Free text query

In the simplest case, your query can be “Dave”:

In this case, you’ll see the restaurant “Dave’s Burgers” in the results, but also everything, where the owner or author’s name is Dave, or the word “Dave” can be found in the description or content, or any other property.

Which might lead to a result set full of irrelevant results.

You might want to add additional search terms to your query. For example, you still want to find “Dave’s Burgers” in Austin, so your query might look like this:

In this case, the restaurant named “Dave’s Burgers” in Austin will be in the results, but also every person whose name is “Dave Austin”, as well as the documents which have either “Dave” or “Austin” in their description, content, or any properties.

Of course, you can go further and search for “Dave’s Burger Austin” or “Austin Americal restaurant”, and you’ll probably get the restaurant you want to find in the search results. Also, most probably, the more words your query contains, and the more specific they are, the better chance you have the right result to be on the top of the result set. But if you want to be sure you get the result you need, there are options to narrow down the query in KQL beyond free-text queries.

---

Exact phrase match

If you know the exact name of the restaurant, you can do and exact phrase query. If you want to find Dave’s Burgers in Austin, you don’t search for Dave’s Burgers, because these are considered to be two separate words in the query, and it might find irrelevant results as well:

Instead, you put ” ” (quotation marks) around the text, indicating to the search engine that it’s a phrase query. Now your query will only return restaurants with the name “Dave’s Burgers”. All other results will be excluded from this result set.

---

Property Restrictions

KQL also supports querying for specific properties. For example, if you want to find a certain restaurant from our example above, but you only know that the restaurant can be found in Austin, you can use the following query:

The result set will contain two restaurants from our example list: “Dave’s Burgers” and “Nepellini’s Pizza”, because these two are located in Austin.

In a similar way, if you remember that the name of the restaurant contains “Dave”, you can use the property name “Name”, and search for this:

---

Note to search administrators: These property restrictions only work with “Queriable” Managed Properties. If you want your users to be able to query for your custom properties (customer name, product ID, project ID, invoice number, etc.), make sure the managed property is “queriable”.

---

Boolean Operators: AND, OR, NOT

In KQL queries, we can also use the following Boolean operators: AND, OR, NOT.

You can combine the two search queries with the AND operator, to query against both properties:

The result would be the restaurant with the name “Dave’s Burgers” in Austin.

We can also use the OR operator in our KQL queries:

This query will give us all the restaurants which have either Mexican or Italian cuisine.

If we want to exclude something, the NOT operator is what we need. We can use it with various syntaxes in our queries, the result is always the very same:

Note: When the query is simple, or we just want to exclude one single value, the easiest and fastest way is using “-” in front of the query: -Mexican.

However, when the query is more complex, and we want to exclude complex set of values or property restrictions, using the NOT operator and the ( ) together is the best:

---

Note: All these Boolean operators are case sensitive.

---

The Wildcard Operator: *

KQL offers a lot of additional search features, and the more you use them, the better results you get from your queries. For example, to find partial matches in your search terms, there’s the wildcard operator (*). It can be used at the end of the keywords. For example, if you remember the name of the restaurant starts with “P”, your KQL query can be:

It’s important to note that you can use * only at the end of the keyword in KQL.

---

Summary

Keyword Query Language (KQL) is a search language used to build structured queries and retrieve relevant information from SharePoint Online or on-prem, OneDrive, and other search sources. In this post, you could see the basic KQL query syntax, the most common Boolean and property operators. With these, you can build complex queries, and can use these in as an end user (in the search box), in Highlighted Content Web Part, as well as in search-driven applications.

---

Further Resources

Of course, we can do much more with Keyword Query Language. If you want to learn about more advanced operators such as NEAR, or querying for number or date intervals, here are a few resources to learn from:

• Keyword Query Language (KQL) syntax reference | Microsoft Learn
• SharePoint Search Queries Explained: A guide to writing search queries in SharePoint 2013 and SharePoint Online: Svenson, Mikael: 9781505887037: Amazon.com: Books
• Tech and me: SharePoint Search Queries Explained – The Series (techmikael.com)