Skip to main content

KQL

Keyword Query Language (KQL) is the search syntax behind SharePoint and Microsoft Search. It combines free-text keywords with property restrictions, such as author, file type, or content type, and operators like AND, OR, and NOT to return exactly the content you need. Power users rely on it to drive the Highlighted Content web part, search verticals, result sources, and eDiscovery queries, all without custom development. One well-built query can power a page section that updates itself as new content is published.
Related
Crawled Properties, Managed Properties, Microsoft Search, Search Schema, Search Verticals

Common Use Cases

  • Refining search results: build queries that combine keywords, phrases, and operators to find very specific content
  • Search-driven web parts: power the Highlighted Content and PnP Modern Search web parts with custom queries
  • Property-based filtering: target specific managed properties such as Author, FileType, ContentType, or Department
  • Search verticals and result sources: create custom verticals or result sources scoped to specific document types, sites, or business units
  • Compliance and eDiscovery: locate content for retention policies, legal holds, or audit reviews using property-based queries

Benefits

  • Precise targeting: locate exactly the content you need across millions of items in the tenant
  • Managed Property-aware: query against any managed property surfaced in the search schema
  • No-code solution: power users can build advanced queries without writing custom development code
  • Self-maintaining pages: a Highlighted Content web part driven by a KQL query updates itself as matching content is published
  • One skill, many surfaces: the same syntax works in web parts, verticals, result sources, and eDiscovery, so the learning investment pays off across Microsoft 365
  • Metadata payoff: custom site columns mapped to managed properties become precise, reusable search filters

Details

  • Feature Category: Search & AI

How It Works

  • Three ingredients: a KQL query is a line of text made of free-text keywords, property restrictions, and operators that combine them, evaluated against the search index to return matching, permission-trimmed results
  • Free-text keywords: match words and exact phrases; put phrases in quotation marks, like employee handbook
  • Property restrictions: target managed properties with no spaces, such as author:John Smith, filetype:docx, or ContentType:Policy
  • Operators: AND, OR, and NOT combine conditions, and parentheses group them
  • Wildcards: the asterisk enables prefix matching: budget* finds budget, budgets, and budgeting
  • Ranges and comparisons: date and number properties support them, such as LastModifiedTime greater than or equal to 2026-01-01
  • Advanced operators: NEAR and XRANK fine-tune proximity and ranking for power users

Limits and Nuances

  • Syntax is strict: operators AND, OR, NOT must be uppercase (lowercase becomes a search word), and curly smart quotes pasted from Word break phrase matching, so use straight quotes
  • Property and wildcard rules: property restrictions take no spaces (author:Smith works, author : Smith does not), and the asterisk wildcard only works at the end of a word, not the start
  • Query length caps: queries typed through the search UI are limited to 2,048 characters; programmatic queries default to 4,096
  • Queryable properties only: a custom site column must be mapped to a queryable managed property in the search schema before KQL can use it
  • Index lag: new or edited content appears only after the search index catches up; allow minutes, sometimes longer, before troubleshooting a query
  • Always security trimmed: KQL cannot surface content the user lacks permission to see
  • Learning curve: operators, quoting, and property names take practice; test queries in the search box before embedding them in a web part
  • Not Kusto: Keyword Query Language shares the KQL abbreviation with Azure’s Kusto Query Language but not the syntax

Common Questions About KQL

What is KQL used for in SharePoint?

KQL is the query language behind SharePoint search. Every time you build a custom query for the Highlighted Content web part, scope a search vertical, define a result source, or run an eDiscovery search, you are writing KQL. It lets you say precisely what you want, such as PDF policy documents authored by HR and modified this year, instead of hoping the right keywords float to the top.

What does a basic KQL query look like?

A simple example: filetype:docx AND author:John Smith returns Word documents by that author. Keywords stand alone (budget), exact phrases go in quotes (such as travel policy), and property restrictions attach a managed property to a value with a colon and no spaces. Operators AND, OR, and NOT – always uppercase – chain the pieces together, and parentheses group conditions.

Why does my KQL query return no results?

Check the usual suspects in order: lowercase operators (and, or) are treated as search words, not operators; a space crept into a property restriction; the property you queried is not marked queryable in the search schema; smart quotes replaced straight quotes; or the content is simply too new and has not been indexed yet. Testing the query in the regular search box isolates the problem quickly.

Can I use my own site columns in a KQL query?

Yes, once they are mapped. SharePoint automatically creates a crawled property for every site column, but KQL can only target managed properties that are marked queryable. Out-of-the-box, that means mapping your crawled property to a refinable managed property in the search schema, then waiting for a re-index. After that, your custom metadata becomes a first-class search filter.

Is KQL the same as Kusto Query Language?

No – they share an abbreviation and nothing else. Keyword Query Language is the search syntax for SharePoint and Microsoft Search; Kusto Query Language is the analytics language used in Azure Data Explorer, Microsoft Sentinel, and Log Analytics. The naming collision trips up plenty of search results, so when you look for help, include the word SharePoint to land on the right documentation.

Where can you use KQL in SharePoint?

The same KQL syntax works across several surfaces. The Highlighted Content web part’s Custom query source opens a KQL box for rolling up documents, pages, or news onto any page, and the open-source PnP Modern Search web parts accept KQL for tailored search pages. You can scope search verticals and reusable result sources with a KQL filter, and eDiscovery and compliance searches use property-based queries for legal holds and audits. The standard search box also accepts KQL directly, which makes it the quickest place to test a query.

Where does KQL show up when building an intranet?

Mostly inside the Highlighted Content web part. Switching its source to a Custom query unlocks a KQL box, and one good query can power an automatically updating page section – latest policies, this quarter’s templates, everything tagged for a department. Greg Zelfond leans on this pattern in client intranets because the content maintains itself: publish a matching document and it appears, no manual curation.