Dokumente mit PnP Search filtern: Bibliotheken eingrenzen und Kartenansichten bauen

Wie lassen sich Dokumente mit PnP Search filtern, wenn nur bestimmte SharePoint-Bibliotheken oder Ordner als Kartenansicht erscheinen sollen? Das ist eine der häufigsten konkreten Einrichtungsfragen rund um PnP Modern Search. Die Antwort liegt in der richtigen KQL-Abfrage für die Suchquelle, in den passenden Managed Properties für die Darstellung und in einem Layout, das die relevanten Dokumentmetadaten lesbar auf der Karte zeigt.

Ohne eine bewusste Eingrenzung zeigt PnP Search Results standardmäßig Treffer aus dem gesamten Tenant oder dem gesamten Site-Suchbereich. Das ist für eine Dokumentbibliothek mit spezifischem Fokus selten das, was gebraucht wird. Ein Vertrag aus der Rechtsabteilung soll nicht in einem Suchbereich für technische Anleitungen erscheinen, und Fotos aus dem Pressearchiv sollen nicht Platz in einer Materialliste beanspruchen. Dieser Ratgeber zeigt, wie Sie Dokumente mit PnP Search filtern, den richtigen Pfad oder die richtige Bibliothek eingrenzen und das Ergebnis als strukturiertes Kartenlayout darstellen.

Dokumente mit PnP Search filtern: passende Suchquelle wählen

PnP Modern Search bietet mehrere Datenquellen für das Search-Results-Webpart. Für Dokumente aus SharePoint-Bibliotheken kommt in den meisten Fällen SharePoint Search als Datenquelle in Frage. Microsoft Search ist eine weitere Option, liefert jedoch nicht immer dieselben Filterparameter und ist für engere Bibliotheksabfragen oft weniger flexibel. Falls die Suchseite selbst noch nicht steht, hilft zuerst die Grundkonfiguration im Beitrag PnP Such-Webpart konfigurieren.

SharePoint Search als Ausgangspunkt

SharePoint Search indexiert alle Inhalte im Tenant, auf die die suchende Person Zugriff hat. Das ist gleichzeitig eine Stärke und ein Risiko: Ohne eine Basisabfrage, die den Suchbereich eingrenzt, erscheinen Dokumente aus dem gesamten Tenant. Die Abfrage bestimmt, welcher Teil dieses Index tatsächlich ausgewertet wird.

Für eine Dokumentbibliothek gibt es zwei Hauptansätze zur Eingrenzung:

• Pfadbasiert: Die Abfrage enthält den SharePoint-Pfad der Bibliothek oder des Ordners.
• Eigenschaftsbasiert: Die Abfrage filtert nach einem Inhaltstyp, einer Spalte oder einer Managed Property, die nur die gewünschten Dokumente tragen.

Beide Ansätze können kombiniert werden. In den meisten Fällen ist eine Kombination aus Pfad und Inhaltstyp robuster als eine rein pfadbasierte Abfrage, weil sich Ordnerstrukturen ändern können, während Inhaltstypen stabiler bleiben.

Microsoft Graph als Datenquelle

Microsoft Graph als Suchquelle eignet sich vor allem für Szenarien, in denen Teams-Dateien, OneDrive-Inhalte und SharePoint-Dokumente gemeinsam durchsucht werden sollen. Die Filterlogik ist in diesem Fall weniger präzise auf einzelne Bibliothekspfade auszurichten, und die verfügbaren Managed Properties entsprechen nicht exakt denen des klassischen SharePoint-Suchschemas. Für eng definierte Dokumentbibliotheken ist SharePoint Search die zuverlässigere Wahl.

KQL für Bibliotheken, Ordnerpfade und Freigabestatus

KQL (Keyword Query Language) ist die Abfragesprache, mit der SharePoint Search die Treffermenge eingrenzt. Das Query Template des Search-Results-Webparts kombiniert die Basisabfrage mit dem Suchtext des Benutzers.

Grundstruktur einer Basisabfrage

Eine typische Basisabfrage für eine Dokumentbibliothek sieht so aus:

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

Der Platzhalter {searchTerms} wird durch den eingegebenen Suchbegriff ersetzt. Gibt der Benutzer keinen Begriff ein, sucht die Abfrage innerhalb des angegebenen Pfades nach allen Dokumenten.

Pfad auf Ordnerebene eingrenzen

Wenn nur ein bestimmter Ordner innerhalb einer Bibliothek durchsucht werden soll, wird der Pfad entsprechend verlängert:

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

Wichtig: Der Pfad in der KQL-Abfrage ist case-sensitive. Groß- und Kleinschreibung muss exakt dem tatsächlichen Bibliotheks- oder Ordnernamen entsprechen, wie er in der URL angezeigt wird. Leerzeichen im Pfad werden durch %20 oder durch Anführungszeichen um den gesamten Wert behandelt.

Mehrere Bibliotheken kombinieren

Wenn Dokumente aus mehreren Bibliotheken in einer einzigen Ansicht zusammengefasst werden sollen, lassen sich Pfade mit dem KQL-Operator OR verknüpfen:

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

Diese Variante ist bei kleinen Mengen von Bibliotheken praktikabel. Wenn die Zahl der Quellen wächst, ist ein eigenständiger Inhaltstyp oder ein gemeinsames Metadatenfeld als Filterbedingung einfacher zu pflegen.

Freigabestatus als Filterbedingung

Wenn nur genehmigte oder veröffentlichte Dokumente erscheinen sollen, kann der Genehmigungsstatus in die Abfrage aufgenommen werden. SharePoint indexiert den Moderationsstatus über die Crawled Property _ModerationStatus. Der Wert 0 steht für genehmigt:

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

Damit diese Einschränkung funktioniert, muss auf der Bibliothek die Inhaltsgenehmigung aktiviert sein.

Dateityp einschränken

Um nur bestimmte Dateitypen anzuzeigen, eignet sich die Property FileExtension:

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

Für eine reine Dokumentbibliothek sind solche Einschränkungen oft nicht nötig, können aber in gemischten Bibliotheken sinnvoll sein.

Managed Properties für Kartenansicht und Metadatenanzeige

Das Kartenlayout in PnP Search zeigt für jedes Dokument einen Satz von Feldern. Welche Felder erscheinen, hängt davon ab, welche Managed Properties im Ergebnis-Template verknüpft sind. Nur Felder, die im SharePoint-Suchschema als Managed Property verfügbar und auf die entsprechende Crawled Property gemappt sind, können im Layout dargestellt werden.

Standardmäßig verfügbare Eigenschaften für Dokumente

Folgende Managed Properties sind für SharePoint-Dokumente standardmäßig verfügbar und müssen nicht manuell angelegt werden:

Managed Property: Title

Inhalt: Dokumenttitel (Titelfeld des Dokuments)

Managed Property: Author

Inhalt: Ersteller des Dokuments

Managed Property: LastModifiedTime

Inhalt: Zuletzt geändert (Zeitstempel)

Managed Property: FileExtension

Inhalt: Dateiformat

Managed Property: Path

Inhalt: URL des Dokuments

Managed Property: SiteName

Inhalt: Name der Site

Managed Property: SPWebUrl

Inhalt: URL der Site

Managed Property: ContentType

Inhalt: Inhaltstyp

Diese Eigenschaften sind direkt im Handlebars-Template des Kartenlayouts verwendbar, ohne zusätzliche Konfiguration im Suchschema.

Benutzerdefinierte Spalten im Kartenlayout anzeigen

Wenn eine Dokumentbibliothek eigene Spalten hat, die auf der Karte erscheinen sollen, etwa „Projektname“, „Gültig bis“ oder „Dokumentklasse“, müssen diese Spalten als Managed Properties im Suchschema abgebildet sein. Der Prozess dafür ist:

1. In der SharePoint Admin Center Search die vorhandenen Crawled Properties prüfen, die nach dem ersten Crawl für die Bibliothek erscheinen.
2. Eine verfügbare RefinableStringXX-Property oder eine benutzerdefinierte Managed Property erstellen und die Crawled Property zuordnen.
3. Reindexierung der Bibliothek auslösen und den Crawl abwarten.
4. Im PnP-Search-Template die neue Managed Property als Variable verwenden.

Eine ausführliche Erklärung dieses Prozesses findet sich im Artikel SharePoint-Spalten durchsuchbar machen: Crawled Properties, Managed Properties und Refiners.

Thumbnail oder Dokumentvorschau

PnP Modern Search kann für Dokumente eine Vorschau anzeigen, wenn die Suchquelle eine Thumbnail-URL liefert. Für SharePoint-Dokumente wird dafür die Property PictureThumbnailURL ausgewertet, die jedoch nicht für alle Dateitypen und nicht in allen Konfigurationen befüllt ist. Als Alternative lässt sich im Template das Dateiformat-Icon aus FileExtension ableiten, was zuverlässiger funktioniert und weniger von Index-Zustand und Berechtigungen abhängt.

Kartenlayout mit sinnvollen Feldern statt überladener Templates

Das Kartenlayout in PnP Search wird über ein Handlebars-Template definiert. Das Standard-Kartenlayout des Webparts ist ein guter Startpunkt. Es zeigt Titel, Autor, Änderungsdatum und einen Link zum Dokument.

Was eine gute Karte zeigt

Eine hilfreiche Dokumentkarte enthält:

• Titel: Der Dokumenttitel, verlinkt auf das Dokument.
• Dateiformat: Ein Icon oder ein kurzer Hinweis auf den Typ (PDF, DOCX, XLSX).
• Letzte Änderung: Das Datum der letzten Änderung, um die Aktualität einschätzen zu können.
• Autor oder Verantwortlicher: Wer hat das Dokument zuletzt bearbeitet oder ist dafür zuständig.
• Maximal ein oder zwei benutzerdefinierte Felder: Beispielsweise Projektname, Kategorie oder Gültigkeitsdatum.

Was eine Karte nicht braucht:

• Pfadanzeige in voller Länge,
• technische Metadaten wie ContentTypeId oder UniqueId,
• mehr als vier bis fünf Felder gleichzeitig.

Anpassung des Handlebars-Templates

Das Standard-Template lässt sich im Webpart-Editiermodus über den Bereich „Layout“ anpassen. Eine einfache Anpassung für ein Zwei-Spalten-Layout mit Dateiformat-Erkennung:

<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>

Der Feldname RefinableString01 steht hier beispielhaft für eine selbst zugeordnete Managed Property.

Responsive Layout und Anzahl Karten

Die Anzahl der angezeigten Ergebnisse pro Seite sollte auf einen für die Zielgruppe sinnvollen Wert gesetzt werden. Für Kartenansichten sind zwölf bis achtzehn Treffer pro Seite ein guter Ausgangspunkt. Paginierung oder ein „Mehr laden“-Link verhindern, dass die Seite bei vielen Ergebnissen träge wird.

Typische Fehler: zu breite Pfade, leere Karten, fehlende Properties

Pfad zu breit oder zu ungenau

Wenn der Pfad in der KQL-Abfrage die Site-URL ist statt die Bibliotheks-URL, werden alle Dokumente der gesamten Site angezeigt. Auch ein Tippfehler im Pfad führt zu leeren Ergebnissen. Der Pfad sollte immer direkt aus der URL der Bibliothek im Browser kopiert werden, nicht manuell eingetippt.

Karten zeigen leere Felder

Wenn eine benutzerdefinierte Spalte auf der Karte immer leer bleibt, obwohl die Dokumente den Wert enthalten, liegt das meist an einer fehlenden oder fehlerhaften Property-Zuordnung im Suchschema. Die häufigsten Ursachen:

• Die Crawled Property wurde noch nicht erstellt, weil kein Crawl nach dem Anlegen der Spalte stattgefunden hat.
• Die Crawled Property ist vorhanden, aber noch keiner Managed Property zugeordnet.
• Die Managed Property ist zugeordnet, aber die Bibliothek wurde nicht reindiziert.
• Der Feldname im Template entspricht nicht exakt dem Managed-Property-Namen (Groß-/Kleinschreibung beachten).

Falscher Inhaltstyp bei Ordnertreffern

Wenn in Suchergebnissen Ordner statt Dokumente erscheinen, liegt das daran, dass auch Ordner vom SharePoint-Index erfasst werden. Mit einer KQL-Bedingung wie IsDocument:1 lassen sich Ordner aus den Treffern ausschließen:

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

Template zeigt keine Vorschau-Thumbnails

Wie erwähnt ist PictureThumbnailURL nicht für alle Dokumenttypen verfügbar. Ein Fallback auf ein typbezogenes Icon ist stabiler. Falls Thumbnails wichtig sind, sollten die Berechtigungen auf der Bibliothek und die Einstellungen für die Office-Dokumentvorschau im Tenant geprüft werden.

So bleiben Quellfilter, Layout und Query langfristig beherrschbar

KQL-Abfragen in PnP Search sind direkt im Webpart gespeichert und nicht zentral versioniert. Wenn Bibliothekspfade, Inhaltstypen oder Ordnerstrukturen sich ändern, müssen die Abfragen manuell angepasst werden. Folgende Maßnahmen helfen, diesen Aufwand zu minimieren:

• Stabiler Pfad: Bibliotheksnamen sollten nicht nachträglich umbenannt werden. Umbenennung ändert den Pfad in der URL und macht bestehende Abfragen ungültig.
• Inhaltstyp als Stabilitätsanker: Wenn statt eines Pfades ein Inhaltstyp als Filterbedingung verwendet wird, übersteht die Abfrage Umstrukturierungen der Bibliothek. Inhaltstypen haben eine stabile ID.
• Template dokumentieren: Das angepasste Handlebars-Template sollte außerhalb der Webpart-Konfiguration dokumentiert werden, zum Beispiel in einer SharePoint-Seite oder einem OneNote-Notizbuch für die SharePoint-Administration.
• Mehrsprachige Inhalte: Wenn Dokumente in mehreren Sprachen vorhanden sind, sollte geprüft werden, ob die Language Managed Property im Template genutzt wird, um Dokumentsprachen im Kartenlayout anzuzeigen.

Für die Konfiguration von Filtern, die zur Dokumentsuche gehören, erklärt der Artikel PnP Search Filter mit Verfeinerern und KQL konfigurieren die notwendigen Suchschema-Schritte.