Build PnP Search filters in SharePoint: refiners, managed properties, and KQL

How do you build a PnP Search Filter in SharePoint that actually displays the correct values and reliably filters when clicked?

The short answer: A working filter starts in the SharePoint search schema. The relevant column must exist in the search index, be assigned to a refinable Managed Property, and be connected to the correct Search Results Webpart in the PnP Search Filters Webpart. The KQL query then narrows down only the general search scope. The selectable facets should instead be built using Refiners rather than an increasingly complex query.

If any of these layers is missing, the filter remains empty, displays incomplete values, or suddenly returns no hits after selection. This guide shows how the individual components work together and how errors can be systematically narrowed down.

What PnP Search filters do and where they are often misused

The PnP Search Filters Webpart is not a standalone search index and does not search SharePoint itself. It receives possible filter values from the connected Search Results Webpart, displays them as facets, and returns the selection back to the result query.

The typical data flow looks like this:

1. The Search Results Webpart sends a query to the configured search source.
2. The search source returns hits and available Refiner values.
3. The Filters Webpart displays these values, for example as checkboxes, dropdown lists, date ranges, or taxonomy trees.
4. The user selects a value.
5. The selection is passed as an additional filter condition to the Results Webpart.
6. Hits, filter values, and hit counts are recalculated.

A Refiner is therefore not a freely defined list of search terms. Its values normally come from the metadata of the currently found and visible content for the user.

Distinguish between refiners and static filters

PnP Modern Search fundamentally distinguishes between dynamic Refiners and static filters:

• Refiners: The values are loaded from the search source and the current result set. If there are no hits, there are normally also no Refiner values.
• Static Filter: The selectable values are predefined independently of the current search results. A typical example is a fixed date range.

For columns such as Department, Document Type, Location, Business Team, or Status, a Refiner is usually appropriate. Static filters are better suited for deliberately predefined areas that should not be derived directly from the index.

When filters are misused

Problems often arise when a basic search scope is modeled as a user filter. If a search page is to display only documents from a specific area, this restriction normally belongs in the base query of the Results Webpart. It should not appear as a selectable facet.

A practical division is:

• KQL Base Query: defines the fixed search scope, such as Site, Path, Content Type, or Document Class.
• Search Text: contains the user's input.
• Refiners: enable interactive narrowing within the already defined search scope.

This ensures it remains clear which restrictions always apply and which users can change themselves.

Crawled properties, managed properties, and refinable fields

Before configuring a filter, it must be clear how SharePoint ingests metadata into the search index. The preparatory steps for columns, Crawled Properties, and refinable Managed Properties are described in more detail in the article Using Managed Properties for Filters. Three terms are critical for building the filter.

Crawled property

A Crawled Property is a raw signal detected during crawling. For SharePoint columns, it can originate from the internal name of a Site Column. Often, such a name looks similar to ows_Dokumentart. For Managed Metadata columns, additional properties with prefixes like ows_taxId_ can appear.

The specific name should always be checked in the search schema. It cannot be derived solely from the visible column name, because renaming and different column types can lead to different internal names.

Managed property

A Managed Property is the property usable in the search index. Only through it can a property be reliably used in a KQL condition, a result template, a sort, or a refiner.

The Crawled Property provides the value. The Managed Property determines how this value can be used in search.

Refinable managed property

For a property to be usable as a facet, the Managed Property must be refinable. In SharePoint Online, no arbitrary new refinable properties can be created. Instead, free properties provided by Microsoft are reused, for example:

• RefinableString00 to RefinableString219 for text values
• RefinableInt00 to RefinableInt49 for integers
• RefinableDate00 to RefinableDate19 for date values
• RefinableDecimal00 to RefinableDecimal09 for decimal values

Which property is used should be documented in a central mapping list. Without this documentation, the same RefinableStringXX property might later be used for several domain-specific fields.

Example of a clean mapping

Domain Information: Document Type

Crawled Property: ows_Dokumentart

Managed Property: RefinableString20

Alias: DokumentartFilter

Domain Information: Business Unit

Crawled Property: ows_Fachbereich

Managed Property: RefinableString21

Alias: FachbereichFilter

Business Information: Valid until

Crawled Property: ows_GueltigBis

Managed Property: RefinableDate05

Alias: GueltigBisFilter

The actual crawled properties may differ from these examples and must be verified in the respective tenant.

Set up managed property

1. Create the required site column and use it in at least one list or library.
2. Test-fill the column with different values across multiple items.
3. Wait for SharePoint to crawl the property, or request a reindex.
4. Open the search schema at the tenant or site collection level.
5. Find the matching crawled property.
6. Select an unused RefinableStringXX, RefinableDateXX, or similar standard property.
7. Map the crawled property to this managed property.
8. Optionally assign a clear alias.
9. Request a reindex for the affected list, library, or site.

The final reindex is critical. A change to the search schema does not automatically cause existing items to be reprocessed immediately with the new mapping.

Configure filter webpart and connect to search results

A correct search schema alone is insufficient. The PnP Search Filters Webpart and the PnP Search Results Webpart must be connected. The basic configuration of the search page with Search Box and Results should already work; the necessary steps are covered in the article Configure PnP Search Webpart.

Prerequisites

• PnP Modern Search is deployed in the App Catalog and available on the site.
• The page contains a PnP Search Results Webpart.
• The search source of the Results Webpart already returns hits.
• The required managed property contains values for these hits.
• The property is refinable and has been reindexed after mapping.

1. Prepare search results

First, configure the Results Webpart. Initially, use a simple base query so that errors in the KQL configuration are not confused with errors in the filter.

A fixed restriction to documents within a specific site can look like this, for example:

Path:"https://tenant.sharepoint.com/sites/wissen" AND IsDocument:1

Next, check whether the expected content is displayed. Only after the base query works should the Filter Webpart be added.

2. Add search filters

Add the PnP Search Filters Webpart to the same modern SharePoint page. Open its properties and select the Results Webpart as the connected results source.

3. Establish connection in both directions

The connection must be set up in both directions:

• The Filters Webpart retrieves its filter values from the Search Results Webpart.
• The Search Results Webpart receives the selected values from the Filters Webpart.

If only one direction is configured, the filter may remain empty or display a selection without changing the hit list.

4. Configure filter row

For a filter on document type, the configuration might look like this, for example:

For technical configuration, the actual managed property name is usually less ambiguous than a freely chosen display name. If an alias is used, the alias and the original managed property should be documented together.

Use AND or OR correctly

The operators should match the expected user logic:

• OR within a filter: Document type is "Contract" or "Policy".
• AND within a filter: An item must have multiple selected values simultaneously. This is mainly useful for multi-value columns.
• AND between different filters: Document type is "Contract" and business team is "Procurement".
• OR between different filters: Document type is "Contract" or business team is "Procurement". This setting often leads to unexpectedly broad results.

For classic facet navigation, OR between multiple values of the same facet and AND between different facets are usually understandable.

Select appropriate representations

• Check box: for few, understandable categories.
• Combo selection: for longer value lists where users should search directly.
• Date range: for from-to boundaries.
• Date intervals: for fixed periods such as today, last week, or last year.
• People view: for authors or responsible persons.
• Hierarchical refiner: for taxonomies with parent and child terms.

A hierarchical filter should only be used for taxonomy values that are actually maintained hierarchically. A flat selection with many independent terms will not automatically become more clear through a tree representation.

Keep KQL focused instead of overloading it

KQL, the Keyword Query Language, should define the stable base set of the search in the Results Webpart. It is not the right place to permanently represent every possible user selection.

Write property queries correctly

A property restriction generally follows this pattern:

ManagedProperty:Wert

Do not put a space between the property, operator, and value. Values with spaces are enclosed in quotation marks:

Author:"Max Mustermann"

Combine multiple conditions using uppercase operators:

Path:"https://tenant.sharepoint.com/sites/wissen"
AND IsDocument:1
AND ContentTypeId:0x0101*

What belongs in the base query

Appropriate fixed restrictions include, for example:

• a defined site or library path,
• documents instead of sites or list items,
• a specific content type,
• a fixed organizational search source,
• technical exclusions that users should not change.

What does not belong in the base query

Interactive categories such as business team, document type, language, or status should not appear simultaneously as a hard-coded KQL condition and as a selectable refiner. Otherwise, a filter selection may contradict the base query.

A problematic example would be:

RefinableString20:"Vertrag"

If the same property is offered as a filter named "Document Type," users can select "Policy," but the fixed KQL condition continues to allow only contracts. The result is an empty hit list, even though the filter works technically.

Test KQL step by step

Build more complex queries step by step:

1. Test only the search text or placeholder.
2. Add the path condition.
3. Add the document or content type.
4. Add each additional property condition individually.
5. Activate refiners only after that.

This way, you can identify which condition unexpectedly reduces the number of hits.

Typical error patterns for empty or incorrect facets

The filter shows no values at all

Check in this order:

1. Does the Search Results Web part return results?
2. Is the Filter Web part connected to the correct Results Web part?
3. Is the connection to the Filter Web part also enabled in the Results Web part?
4. Is the correct Managed Property name entered in the filter field?
5. Is the Managed Property refinable?
6. Is the correct Crawled Property mapped?
7. Was the list or library reindexed after the mapping?
8. Do the found items actually have values in the relevant column?

The property works in KQL but not as a refiner

A property can be queryable without being refinable. A custom-created Managed Property of type Text is therefore not automatically sufficient as a filter field. For a refiner, a suitable RefinableStringXX or comparable standard property must be used.

After filter selection, there are zero results

Common causes are:

• The static KQL query contradicts the selected facet.
• The Filter Web part uses a different property than the result query.
• An AND operator was used when OR was expected.
• The visible text does not match the actually indexed value.
• Taxonomy values are processed as tokens or GUIDs instead of simple text.
• The user has no access to the content with the selected value.

The filter shows old or unexpected values

Check whether multiple Crawled Properties have been mapped to the same Managed Property. Depending on the mapping setting, values from multiple sources can be merged or taken over in a defined order.

Already indexed old values can also play a role. After changes to columns, mappings, or metadata, a reindexing should be requested and then checked with several test items.

A multi-valued field is treated as a single text

Multi-value SharePoint columns must arrive as individual values in the search index. If all values are indexed as a single continuous string, facets appear as "Purchasing;Legal;Finance" instead of three independent entries.

In this case, check the column type, the crawled property used, and the mapping. For managed metadata, also use the property intended for taxonomy values.

Taxonomy filters show guids or technical prefixes

Managed metadata values can contain technical taxonomy information in the index alongside the label. If these values are output using a simple text representation, IDs or tokens may appear.

Check:

• whether the correct taxonomy crawled property has been mapped,
• whether the localization option of the SharePoint search source is enabled,
• whether the hierarchical refiner is assigned to the correct term set,
• whether the terms are maintained in the required languages.

Values are missing at the end of the filter list

PnP Modern Search limits the number of loaded refiner values. By default, not all possible values are necessarily displayed for extensive refiners. The maximum number can be increased in the filter configuration; the allowable maximum value is 1,000.

Increasing the limit does not solve every problem. A field with several hundred or thousand different values is usually not a good refiner. For unique IDs, transaction numbers, or file names, text input is often more suitable than a long facets list.

Filter counts differ between users

SharePoint Search considers permissions. Users see only hits they have access to. Consequently, available filter values and hit counts can also differ.

Therefore, do not test the search exclusively with an administrator account. Additionally, use at least one regular user account with realistic read permissions.

Systematically test and reset filters

Direct test of the managed property

First, check whether the managed property provides values in general:

RefinableString20:"Vertrag"

If the expected content is found, mapping and indexing are likely functioning. If the results remain empty, the problem still exists before the filter web part.

Use a test matrix

Control the browser console

If refiner lists are truncated or behavior is unexpected, check the browser's developer tools. PnP Modern Search can output hints there when a configured refiner limit is reached.

Failed connections, unavailable properties, or issues with a custom template are also often detected faster there than through the visible interface alone.

Fallback for a faulty configuration

If a new facet makes the search page unusable, first remove or disable only the affected filter row. The working base query and the remaining filters stay intact.

If the search schema mapping is incorrect, restore the documented previous mapping and re-index the affected source. Avoid spontaneously repurposing a RefinableStringXX property already used elsewhere. This can affect other search pages, sorts, or result templates.

Technical block: search schema, performance, and maintenance

Tenant-wide or local search schema

A mapping at the tenant level suits metadata that share the same meaning across the organization. A mapping at the site collection level applies only within that area.

For reusable filters like document type, organizational unit, or language, a centrally coordinated tenant mapping is usually easier to maintain. Local properties make sense when metadata is used only within a clearly defined area.

Avoid high cardinality

A good refiner has a limited and user-understandable set of recurring values. Inappropriate examples are often:

• unique transaction numbers,
• complete filenames,
• free-text inputs,
• individual timestamps,
• technical IDs.

Such properties create long lists, low reuse, and unnecessary queries. You should find them instead through search text or targeted KQL inputs.

Keep base queries short

A KQL query should not become a collection grown over years with numerous OR blocks and individual exceptions. Long queries are hard to test and can reach technical length limits.

If the same complex logic is needed on multiple search pages, check whether the content can be structured more cleanly through consistent metadata, content types, paths, or separate search verticals.

Maintain a managed-property register

Document at least:

• business meaning,
• physical managed property,
• alias,
• data type,
• mapped crawled property,
• search schema scope,
• using search pages and web parts,
• date of last change.

This register prevents duplicate assignments and makes later error analysis much faster.

Roll out changes in a controlled manner

Test new filters first on a separate search page or a non-prominently linked draft page. Check there for different metadata values, user permissions, multiple selections, and empty fields.

Only after successful testing should the configuration be transferred to production search pages. For multiple pages, it is recommended to document the configuration and property assignments in a version-controlled manner.

Practical example: filters for a SharePoint knowledge base

A typical scenario is a knowledge base where policies, templates, instructions, and project documents are to be found together. The search should return full-text matches and help users quickly filter the larger result set to find the matching document type, business team, or validity period.

For this case, a clear separation of search logic is helpful: The base query limits results to the knowledge base, while refiners handle business navigation. A sensible starting structure can look like this:

Element: Search Scope

Task on the Search Page: Show only content from the knowledge base

Typical Implementation: Path restriction or custom result source

Element: Document Type

Task on the Search Page: Filter results by policy, template, or instruction

Typical Implementation: Choice column on RefinableString

Element: Business Team

Task on the Search Page: Limit content to an organizational unit

Typical Implementation: Managed Metadata or controlled choice values

Element: Valid Until

Task on the Search Page: Identify expired or soon-to-expire documents

Typical Implementation: Date field on RefinableDate

If the knowledge base is additionally set up as a self-service area, the filter structure fits well with a SharePoint knowledge base with PnP Search. The filters should not be planned in isolation, but together with content types, required metadata, and editorial maintenance.

Checklist before production use

• Each filter property is documented and assigned to exactly one managed property.
• The base query contains only restrictions that users should not change.
• Multiple selection, empty values, and different user permissions have been tested.
• The filter remains understandable even with many documents and shows no technical IDs.
• For changes to managed properties, there is a rollback path.

This check may seem unremarkable, but it prevents many later search problems. Especially with multiple search pages, a shared property register is more important than a quick individual configuration in the web part.

How to keep filters logical, fast, and maintainable

A stable PnP Search filter consists of a clear chain: The SharePoint column provides metadata, the crawled property takes over this during crawling, a refinable managed property makes it available in the index, and the Search Filters web part uses it as a facet for the connected results web part.

The most important rule is: KQL defines the fixed search scope, and refiners handle interactive narrowing. Mixing both tasks creates contradictory conditions and hard-to-trace zero results.

Therefore, start with a simple result query, test the managed property directly, then establish the two-way web part connection, and add filters one by one. This allows each level to be checked separately, and issues can be targetedly reset if problems arise.