Filter documents with PnP Search: narrow down libraries and build gallery views

How can documents be filtered with PnP Search when only specific SharePoint libraries or folders should appear as a card view? This is one of the most common concrete setup questions around PnP Modern Search. The answer lies in the correct KQL query for the search source, the appropriate managed properties for display, and a layout that shows relevant document metadata clearly on the card.

Without a deliberate restriction, PnP Search Results shows hits from the entire tenant or the entire site search scope by default. This is rarely what is needed for a document library with a specific focus. A contract from the legal department should not appear in a search scope for technical instructions, and photos from the press archive should not take up space in a material list. This guide shows how to filter documents with PnP Search, restrict the correct path or library, and display the result as a structured card layout.

Filter documents with PnP Search: choose the right search source

PnP Modern Search offers several data sources for the Search Results Webpart. For documents from SharePoint libraries, SharePoint Search is usually the data source in question. Microsoft Search is another option, but it does not always provide the same filter parameters and is often less flexible for narrow library queries. If the search page itself has not been set up yet, start with the basic configuration in the article Configure PnP Search Webpart.

SharePoint search as the starting point

SharePoint Search indexes all content in the tenant that the searching person has access to. This is simultaneously a strength and a risk: Without a base query that restricts the search scope, documents from the entire tenant appear. The query determines which part of this index is actually evaluated.

For a document library, there are two main approaches to restriction:

• Path-based: The query contains the SharePoint path of the library or folder.
• Property-based: The query filters by a content type, a column, or a managed property that only carries the desired documents.

Both approaches can be combined. In most cases, a combination of path and content type is more robust than a purely path-based query, because folder structures can change while content types remain stable.

Microsoft Graph as a data source

Microsoft Graph as a search source is suitable mainly for scenarios where Teams files, OneDrive content, and SharePoint documents are to be searched together. The filter logic is less precise for aligning with individual library paths in this case, and the available managed properties do not exactly match those of the classic SharePoint search schema. For narrowly defined document libraries, SharePoint Search is the more reliable choice.

KQL for libraries, folder paths, and sharing status

KQL (Keyword Query Language) is the query language used to restrict the hit set in SharePoint Search. The Query Template of the Search Results Webpart combines the base query with the user's search text.

Basic structure of a base query

A typical base query for a document library looks like this:

{searchTerms} Path:"https://tenant.sharepoint.com/sites/sitename/Bibliotheksname"

The placeholder {searchTerms} is replaced by the entered search term. If the user enters no term, the query searches for all documents within the specified path.

Restrict path at the folder level

If only a specific folder within a library is to be searched, the path is extended accordingly:

{searchTerms} Path:"https://tenant.sharepoint.com/sites/sitename/Bibliotheksname/Ordnername"

Important: The path in the KQL query is case-sensitive. Uppercase and lowercase letters must match the actual library or folder name exactly as displayed in the URL. Spaces in the path are handled by %20 or by enclosing the entire value in quotation marks.

Combine multiple libraries

If documents from multiple libraries are to be combined in a single view, paths can be linked using the KQL operator OR:

{searchTerms} (Path:"https://tenant.sharepoint.com/sites/sitename/Bibliothek1" OR Path:"https://tenant.sharepoint.com/sites/sitename/Bibliothek2")

This variant is practical for small numbers of libraries. If the number of sources grows, it is easier to maintain a separate content type or a common metadata field as a filter condition.

Approval status as a filter condition

If you want only approved or published documents to appear, you can include the approval status in the query. SharePoint indexes the moderation status via the Crawled Property _ModerationStatus. The value 0 stands for approved:

{searchTerms} Path:"..." _ModerationStatus:0

For this restriction to work, content approval must be enabled on the library.

Restrict file type

To display only specific file types, you can use the Property FileExtension:

{searchTerms} Path:"..." (FileExtension:pdf OR FileExtension:docx)

For a pure document library, such restrictions are often unnecessary but can be useful in mixed libraries.

Managed properties for gallery view and metadata display

The gallery layout in PnP Search displays a set of fields for each document. Which fields appear depends on which Managed Properties are linked in the result template. Only fields that are available as a Managed Property in the SharePoint search schema and mapped to the corresponding Crawled Property can be displayed in the layout.

Properties available by default for documents

The following Managed Properties are available by default for SharePoint documents and do not need to be created manually:

Managed Property: Title

Content: Document title (title field of the document)

Managed Property: Author

Content: Document creator

Managed Property: LastModifiedTime

Content: Last modified (timestamp)

Managed Property: FileExtension

Content: File format

Managed Property: Path

Content: Document URL

Managed Property: SiteName

Content: Site name

Managed Property: SPWebUrl

Content: Site URL

Managed Property: ContentType

Content: Content type

You can use these properties directly in the Handlebars template of the card layout without additional configuration in the search schema.

Display custom columns in the card layout

If a document library has custom columns that should appear on the card, such as "Project Name", "Valid Until", or "Document Class", these columns must be represented as managed properties in the search schema. The process is:

1. In the SharePoint Admin Center Search, check the existing crawled properties that appear after the first crawl for the library.
2. Create an available RefinableStringXX property or a custom managed property and map the crawled property to it.
3. Trigger a reindex of the library and wait for the crawl to complete.
4. Use the new managed property as a variable in the PnP Search template.

A detailed explanation of this process can be found in the article Make SharePoint columns searchable: Crawled properties, managed properties, and refiners.

Thumbnail or document preview

PnP Modern Search can display a preview for documents if the search source provides a thumbnail URL. For SharePoint documents, the property PictureThumbnailURL is evaluated for this purpose, but it is not populated for all file types and not in all configurations. As an alternative, you can derive the file format icon from FileExtension in the template, which works more reliably and depends less on index status and permissions.

Card layout with meaningful fields instead of overloaded templates

The card layout in PnP Search is defined by a Handlebars template. The default card layout of the web part is a good starting point. It shows the title, author, modification date, and a link to the document.

What a good card shows

A helpful document card includes:

• Title: The document title, linked to the document.
• File format: An icon or a brief note on the type (PDF, DOCX, XLSX).
• Last modified: The date of the last modification to assess freshness.
• Author or owner: Who last edited the document or is responsible for it.
• At most one or two custom fields: For example, project name, category, or validity date.

What a card does not need:

• Full path display,
• technical metadata such as ContentTypeId or UniqueId,
• more than four to five fields at the same time.

Customizing the handlebars template

The default template can be customized in the Webpart edit mode via the "Layout" section. A simple customization for a two-column layout with file format detection:

<div class="card">
  <div class="card-icon">
    {{#if (eq FileExtension "pdf")}}PDF{{else if (eq FileExtension "docx")}}DOCX{{else}}DATEI{{/if}}
  </div>
  <div class="card-body">
    <a href="{{Path}}">{{Title}}</a>
    <small>{{Author}} · {{getDate LastModifiedTime "DD.MM.YYYY"}}</small>
    {{#if RefinableString01}}<span>{{RefinableString01}}</span>{{/if}}
  </div>
</div>

The field name RefinableString01 serves as an example for a self-assigned Managed Property.

Responsive layout and number of cards

The number of results displayed per page should be set to a value that makes sense for the target audience. For card views, twelve to eighteen hits per page is a good starting point. Pagination or a "Load More" link prevents the page from becoming sluggish with many results.

Typical errors: paths too broad, empty cards, missing properties

Path too broad or too inaccurate

If the path in the KQL query is the site URL instead of the library URL, all documents of the entire site are displayed. Even a typo in the path leads to empty results. The path should always be copied directly from the library URL in the browser, not typed manually.

Cards show empty fields

If a custom column on the card remains empty even though the documents contain the value, this is usually due to a missing or faulty property assignment in the search schema. The most common causes:

• The Crawled Property has not yet been created because no crawl took place after the column was created.
• The Crawled Property exists but has not yet been assigned to a Managed Property.
• The Managed Property is assigned, but the library has not been reindexed.
• The field name in the template does not match the Managed Property name exactly (pay attention to capitalization).

Wrong content type for folder hits

If folders appear instead of documents in search results, this is because folders are also indexed by SharePoint. With a KQL condition like IsDocument:1, folders can be excluded from the hits:

{searchTerms} Path:"..." IsDocument:1

Template shows no preview thumbnails

As mentioned, PictureThumbnailURL is not available for all document types. Falling back to a type-specific icon is more stable. If thumbnails are important, the permissions on the library and the settings for Office document preview in the tenant should be checked.

How to keep source filters, layout, and query controllable long-term

KQL queries in PnP Search are stored directly in the Webpart and are not centrally versioned. If library paths, content types, or folder structures change, the queries must be adjusted manually. The following measures help minimize this effort:

• Stable Path: Library names should not be renamed afterward. Renaming changes the path in the URL and makes existing queries invalid.
• Content Type as Stability Anchor: If a content type is used as a filter condition instead of a path, the query survives library restructuring. Content types have a stable ID.
• Document the Template: The customized Handlebars template should be documented outside the Webpart configuration, for example on a SharePoint page or in a OneNote notebook for SharePoint administration.
• Multi-language Content: If documents are available in multiple languages, it should be checked whether the Language Managed Property is used in the template to display document languages in the card layout.

The article Configure PnP Search Filters with Refiners and KQL explains the necessary steps to configure filters that are part of document search.