Advanced SharePoint Online Search REST API — Mastering KQL, FQL, Refiners, and “Real-World” Query Patterns

This is the “part 2” style deep dive: how to build powerful queries (KQL), how to filter properly (FQL refinement filters), and how this maps cleanly to tools like PnP Modern Search (Query Template vs Refinement Filters).

SharePoint’s Search REST service supports both GET and POST, and you can submit queries using KQL (Keyword Query Language / KeyQL) or FQL (FAST Query Language). (Microsoft Learn)

1) KQL vs FQL: the single most important distinction

KQL (KeyQL) is your “match” language

Use KQL in:

• querytext='...' (SharePoint Search REST)
• “Query template” (PnP Modern Search)

KQL is the standard “search expression” language for SharePoint search: boolean logic, phrases, property restrictions, etc. (Microsoft Learn)

FQL is your “filter / refinement” language

Use FQL in:

• refinementfilters='...' (GET)
• RefinementFilters: { results: [...] } (POST)

Microsoft explicitly calls out: RefinementFilters is specified as an FQL filter. (Microsoft Learn)

Why this matters

If you try to write KQL inside refinementfilters, you’ll get confusing behavior or zero results. Treat it as a different language.

2) KQL building blocks (advanced patterns you’ll actually use)

2.1 Boolean logic and grouping (always use parentheses)

KQL supports AND, OR, NOT with grouping. (Microsoft Learn)

(budget OR forecast OR "cost center") AND (FileExtension:pdf OR FileExtension:docx)

Tip: Always group when mixing AND/OR. Don’t rely on “operator precedence.”

2.2 Phrase queries (quotes)

"project charter"

Add property restriction:

Title:"project charter"

KQL supports phrases and property restrictions as core syntax elements. (Microsoft Learn)

2.3 Property restrictions (your precision weapon)

Property restriction is how you force search to match where you want:

Author:"John Doe"
FileExtension:pdf
Path:https://contoso.sharepoint.com/sites/ExampleSite/

These are standard KQL patterns described in the syntax reference. (Microsoft Learn)

2.4 Prefix matching and wildcards (use carefully)

KQL supports wildcard-style patterns for many scenarios. Exact support can vary by property/type, so treat this as “use sparingly and validate,” but typical patterns are:

FileName:Report*
Title:Budget*

(Use this especially for user-entered partial values.)

2.5 “Scope to a subtree” using Path

A practical approach to “search inside a folder/library/site” is Path restriction:

(Path:https://contoso.sharepoint.com/sites/ExampleSite/Shared%20Documents/Policies/)
AND (security OR compliance)

This remains one of the most common enterprise patterns.

3) Advanced ranking: XRANK (boost results without changing matches)

XRANK lets you keep the same match set, but boost certain matches higher in ranking.

Microsoft calls out XRANK as a mechanism to affect ranking (commonly referenced in search ranking guidance and KQL usage). (GitHub)

Conceptual pattern

• “Match expression” (what must match)
• “Rank expression” (what boosts ranking)

Example (illustrative):

XRANK(cb=100) (sharepoint OR "project site") (Title:"project site")

How to use this in real life

• Boost files where the term appears in Title (or another high-signal property)
• Boost “official” content types higher than random documents
• Boost a “primary library” higher than archives

Practical note: XRANK is powerful but easy to overdo. Keep boosts modest and test with real queries.

4) Refiners vs Refinement Filters (PnP Search and REST get confused here)

4.1 “Refiners” = facets you want returned

Example REST:

• refiners='fileExtension,Author'

This tells Search to compute facet buckets. Refiners tie deeply to query refinement concepts. (Microsoft Learn)

4.2 “RefinementFilters” = the actual filter constraints (FQL)

Microsoft’s example:

...&refinementfilters='fileExtension:equals("docx")'

(Microsoft Learn)

Common FQL patterns you’ll use

Single value

fileExtension:equals("pdf")

OR

or(fileExtension:equals("pdf"),fileExtension:equals("docx"))

AND

and(fileExtension:equals("pdf"),Author:equals("John Doe"))

(That’s the style you should default to for refinementfilters.)

5) “RefinableString00…199” and why your custom metadata won’t filter until you map it

In SharePoint Online, you can’t create new refinable managed properties. Instead, you map your crawled property to built-in refinables like RefinableString00, RefinableInt00, etc. (Microsoft Learn)

Implication:

• If you want refiners/filters on custom columns at scale, you usually map them into a refinable managed property and use that property in refiners/filters.

6) Real-world “advanced recipes” (copy/paste patterns)

6.1 Search only documents (exclude folders) + rank newest first

GET https://contoso.sharepoint.com/sites/ExampleSite/_api/search/query
?querytext='IsDocument:true AND -ContentType:Folder AND (invoice OR billing)'
&sortlist='LastModifiedTime:descending'
&selectproperties='Title,Path,FileExtension,LastModifiedTime,Author'
&rowlimit=20

Search REST supports rich query parameters and KQL matching. (Microsoft Learn)

6.2 Scope to a library, then filter by file type using FQL (best practice)

KQL for scope + user keywords:

(Path:https://contoso.sharepoint.com/sites/ExampleSite/Shared%20Documents/Contracts/)
AND (nda OR "non disclosure")

FQL refinement filter for file extension:

or(fileExtension:equals("pdf"),fileExtension:equals("docx"))

This pattern matches Microsoft’s guidance that refinement filters are FQL. (Microsoft Learn)

6.3 Use refiners to power a faceted UI (fileExtension + author)

GET https://contoso.sharepoint.com/sites/ExampleSite/_api/search/query
?querytext='(handover OR "handoff")'
&refiners='fileExtension,Author'
&selectproperties='Title,Path,FileExtension,Author'
&rowlimit=50

Query refinement is a first-class capability in SharePoint search. (Microsoft Learn)

6.4 Hard-scope results using ListId (high precision)

In many enterprise scenarios, scoping by ListId is cleaner than long Path chains (especially if paths change).

PnP Modern Search guidance and community examples often use ListId-style filtering (commonly via refinement filters). (pnp.github.io)

7) How this maps to PnP Modern Search (so you don’t mix syntax)

PnP Modern Search (Search Results web part) uses:

• Query template = KQL
• Refinement filters = FQL
• URL parameter filters can override defaults, and refinement behavior is documented in the PnP Search Results docs. (microsoft-search.github.io)

So your mental model should be:

1. Query Template (KQL) defines what matches
2. Refinement Filters (FQL) define “hard constraints”
3. Refiners define which facets you want calculated for UI

8) Mini “debugging” checklist for zero-result nightmares

1. Validate the query in parts
   • Start with querytext='sharepoint'
   • Add one restriction at a time (Path, FileExtension, etc.)
2. Confirm the managed property exists and is retrievable/refinable
   • Especially if you’re filtering on custom metadata (map to refinables if needed). (Microsoft Learn)
3. Don’t put KQL into refinementfilters
   • RefinementFilters is FQL. (Microsoft Learn)

Summary Tables

A) Steps (how to build a “pro” query)

B) Technical cheat sheet