SharePoint Search Deep Dive: KQL, Managed Properties & Custom Result Sources

How SharePoint Search Works Under the Hood

SharePoint Search is a full-text search engine built on top of Microsoft's enterprise search technology, now tightly integrated with Microsoft Search in Microsoft 365. Understanding its architecture is essential before you try to customise it. The engine operates in three stages: crawling, indexing, and querying. The crawler traverses SharePoint content (sites, libraries, lists, pages, user profiles) and extracts raw metadata into crawled properties. The schema processing stage maps crawled properties to managed properties — a curated, queryable layer of the index. At query time, KQL expressions filter and rank documents based on managed property values.

In SharePoint Online, the crawl schedule is continuous — Microsoft crawls content within minutes of a change for sites that are actively used. However, new crawled properties and managed property mappings can take up to 24 hours to propagate. This is the most common source of confusion when teams create a new column, populate it with data, and then wonder why their KQL query returns zero results. The fix is to trigger a full reindex of the site (Site Settings > Search and offline availability > Reindex site), but even then propagation is asynchronous.

Microsoft Search unifies results from SharePoint, Exchange, OneDrive, Teams, and external connectors (Graph Connectors) in a single index. When you build a custom search experience using the SharePoint Search REST API or the PnPjs search service, you are querying this unified index unless you explicitly scope your result source to SharePoint content only. For enterprise intranet search, scoping is critical — you almost always want to exclude Exchange emails from intranet search results.

KQL Syntax Basics Every Developer Must Know

Keyword Query Language (KQL) is SharePoint's query language. It supports free-text keywords, property restrictions, Boolean operators, and wildcard expansions. The most important KQL pattern for developers is the property restriction: ManagedPropertyName:value. This targets a specific managed property rather than performing a full-text search across all indexed fields, which is dramatically faster and more precise.

# Free-text keyword search
SharePoint migration

# Property restriction — exact match
Department:Engineering

# Property restriction — range (dates)
LastModifiedTime:range(2025-01-01, 2025-12-31)

# Boolean AND (default between terms)
Department:Engineering Title:roadmap

# Boolean OR
Department:Engineering OR Department:Product

# Exclude results (NOT)
ContentType:Document NOT ContentType:Wiki

# Wildcard (trailing only in KQL)
Title:share*

# Phrase match
Title:"quarterly business review"

# File type restriction
FileType:pdf Department:Legal

# Path scope (specific site or library)
Path:"https://tenant.sharepoint.com/sites/HR" ContentType:Document

Boolean precedence in KQL follows AND before OR, which can produce unexpected results if you mix them without parentheses. Always use parentheses to group OR clauses: Department:(Engineering OR Product) AND FileType:docx is unambiguous. KQL does not support leading wildcards — *ation is not valid. If you need substring matching, consider Microsoft Search's natural language mode or pre-index derived fields.

Crawled Properties vs Managed Properties

Crawled properties are the raw metadata extracted by the crawler. Every SharePoint column, site property, document metadata field, and user profile attribute produces one or more crawled properties. Crawled properties follow naming conventions based on their data type: ows_Department for a text column named "Department" in a list, People:Department for the user profile department attribute. You cannot query crawled properties directly — they must first be mapped to a managed property.

Managed properties are the query-facing layer. SharePoint ships with hundreds of built-in managed properties (Title, Author, LastModifiedTime, FileType, Path, etc.). Each managed property has a set of attributes that control how it behaves in search: Searchable (full-text indexed), Queryable (usable in KQL property restrictions), Retrievable (returned in result sets), Refinable (usable as a refiner/facet), and Sortable (usable in ORDER BY). You cannot enable all attributes simultaneously — for example, a managed property cannot be both Sortable and Multi-valued.

Creating Custom Managed Properties

To create a custom managed property, navigate to the SharePoint Admin Center, then More features > Search > Manage search schema. Click New managed property and define the name (must start with a letter, no spaces), type, and the attributes you need. After saving, map one or more crawled properties to it using the Mappings to crawled properties field — you can map multiple crawled properties if the same logical value comes from different content types.

After creating and mapping, you must trigger a full reindex. For site-scoped content, go to Site Settings and reindex the site. For user profiles, the reindex happens on the next scheduled user profile incremental crawl, which runs every four hours in SharePoint Online. The custom managed property will be available for querying and as a refiner after the reindex completes and the schema propagates.

# Connect to SharePoint Admin Center
Connect-PnPOnline -Url "https://tenant-admin.sharepoint.com" -Interactive

# Create a new managed property
New-PnPSearchManagedProperty `
  -Name "ContractExpiry" `
  -Type "DateTime" `
  -Searchable $false `
  -Queryable $true `
  -Retrievable $true `
  -Refinable "Yes - active" `
  -Sortable "Yes - active"

# Map crawled property to managed property
Set-PnPSearchManagedProperty `
  -Name "ContractExpiry" `
  -MappedCrawledProperties "ows_ContractExpiry"

Building Custom Result Sources

Result sources define where search queries are executed and how results are filtered. The default SharePoint search result source returns content from across the entire Microsoft 365 tenant. Custom result sources let you scope queries to a specific site collection, library, content type, or even an external Graph Connector source. They are configured in the SharePoint Admin Center under Search > Manage result sources.

A result source consists of a protocol (SharePoint Local, Remote SharePoint, OpenSearch, Exchange), a source URL, and an optional query transform. The query transform is a KQL expression that is prepended to every query executed against this source — this is how you scope a result source to a specific content type or site without requiring the end user to include those restrictions in their search. For example, a "Policies" result source might have a transform of {searchTerms} ContentType:"Policy Document" Path:"{SiteURL}".

Query Rules for Promoted Results and Best Bets

Query rules are conditional logic rules that fire when a user's query matches specified criteria — keywords, result types, or the result source being used. When a rule fires, it can promote specific results to the top of the list (Best Bets / Featured Results), change the query, or add result blocks showing content from a different source. Query rules are the backbone of editorial search relevance in SharePoint without requiring ML model customisation.

A typical query rule setup: when a user searches for "IT helpdesk" or "raise ticket", the rule fires and promotes the IT support portal link as a Best Bet. Another common pattern is a result block rule — when a query matches a people search pattern, inject a "People" block above the document results showing matching employee profiles. Configure query rules at the Site Collection, Site, or tenant level depending on the scope of the content they apply to.

Using Search in SPFx Web Parts

The SharePoint Search REST API endpoint is /_api/search/query. From an SPFx web part, use PnPjs's sp.search() method, which wraps the REST API with a fluent builder and TypeScript types. Always specify the SelectProperties parameter explicitly — returning all managed properties is wasteful and slows down your web part significantly. Request only the properties you will actually render.

import { sp } from '@pnp/sp/presets/all';

const results = await sp.search({
  Querytext: `ContentType:"Policy Document" ${userQuery}`,
  SelectProperties: ['Title', 'Path', 'Author', 'LastModifiedTime', 'ContractExpiry'],
  RowLimit: 20,
  StartRow: 0,
  SortList: [{ Property: 'LastModifiedTime', Direction: 1 }],
  RefinementFilters: [`Department:"${selectedDepartment}"`],
  Refiners: 'Department,FileType',
  TrimDuplicates: false,
  EnableQueryRules: true,
  SourceId: '<your-result-source-guid>',
});

const items = results.PrimarySearchResults;
const refiners = results.RawSearchResults.PrimaryQueryResult.RefinementResults;

Relevance Tuning Without ML

SharePoint's default relevance model weights title matches more heavily than body text, recency, and authoritative sites. You can influence relevance without training a custom ML model through three mechanisms: authoritative pages, query rules (already covered), and managed property weights in the relevance model. Authoritative pages are URLs you designate as high-quality anchors — the search engine boosts content that links to or from these URLs. Configure authoritative pages in the Search Admin Center under Authoritative Pages.

For SPFx-based search experiences where you control the full query, you can also boost freshness by applying a temporal decay function yourself: fetch results ordered by relevance, then re-rank client-side applying a decay factor based on LastModifiedTime. This is especially effective for news and announcement scenarios. Alternatively, use the HiddenConstraints query parameter to add system-level KQL constraints that boost specific content types or paths without exposing the logic to the user's query input.