Skip to content

Commit c2b36f9

Browse files
PowershellScriptsPowershellScripts
authored
Create pnpsearchqueryexamples.md
1 parent 1077e9b commit c2b36f9

File tree

1 file changed

+163
-0
lines changed

1 file changed

+163
-0
lines changed

‎articles/en/SharePointOnline/pnpsearchqueryexamples.md

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
2+
# Intro
3+
4+
In SharePoint Search, especially when using the PnP (Patterns and Practices) Search Web Part, you can use the KQL (Keyword Query Language) query template to build dynamic queries. The query template allows for conditional logic using tokens and variables, but it's not as straightforward as using traditional programming "if" statements. Instead, you can achieve conditional logic by leveraging tokens like `{?{ }}` to include or exclude parts of the query based on conditions.
5+
6+
Here are a few examples of how you can use conditional logic in a query template.
7+
8+
### Example Scenario:
9+
You want to modify the search query based on whether a user has provided a specific filter or not.
10+
11+
### Step-by-Step Process:
12+
13+
1. **Open the PnP Search Web Part**:
14+
- Go to the SharePoint page where you want to configure the web part.
15+
- Edit the page and add or configure the "PnP - Search Results" web part.
16+
17+
2. **Edit the Query Template**:
18+
- In the web part properties, locate the "Search Query" or "Query Template" field.
19+
20+
3. **Use Conditional Logic in KQL**:
21+
- Use the `{?{ }}` syntax to conditionally include parts of the query based on the presence of a token or variable.
22+
23+
### Sample Query Template:
24+
```kql
25+
{searchTerms} {?{QueryString.FilterCategory}Category:{QueryString.FilterCategory}}
26+
```
27+
28+
#### Explanation:
29+
- `{searchTerms}`: This placeholder is replaced by the user's search query.
30+
- `{?{QueryString.FilterCategory}Category:{QueryString.FilterCategory}}`: This conditional logic checks if `QueryString.FilterCategory` is present. If it is, it appends `Category:{QueryString.FilterCategory}` to the query.
31+
32+
### Detailed Breakdown:
33+
- `QueryString.FilterCategory`: This is a token that gets replaced by the value of a query string parameter named `FilterCategory` if it exists.
34+
- `Category:{QueryString.FilterCategory}`: This part of the query is added only if `QueryString.FilterCategory` is present.
35+
36+
### Additional Example with Multiple Conditions:
37+
If you have multiple conditions, you can chain them using similar syntax:
38+
39+
```kql
40+
{searchTerms} {?{QueryString.FilterCategory}Category:{QueryString.FilterCategory}} {?{QueryString.FilterDate}Date:{QueryString.FilterDate}}
41+
```
42+
43+
### Explanation:
44+
- This query template checks for both `FilterCategory` and `FilterDate` query string parameters.
45+
- It appends the respective conditions to the search query if the parameters are present.
46+
47+
### Applying Tokens and Variables:
48+
Tokens and variables can be retrieved from:
49+
- Query string parameters
50+
- Current user's properties
51+
- Page properties
52+
53+
### Using Tokens:
54+
Here are some common tokens you might use in a query template:
55+
- `{searchTerms}`: The search terms entered by the user.
56+
- `{User.Name}`: The current user's name.
57+
- `{User.Email}`: The current user's email.
58+
- `{Page.Title}`: The title of the current page.
59+
- `{Today}`: The current date.
60+
61+
### Putting It All Together:
62+
Here’s how a more complex query template with multiple conditions might look:
63+
64+
```kql
65+
{searchTerms} {?{QueryString.FilterCategory}Category:{QueryString.FilterCategory}} {?{QueryString.FilterDate}Date:{QueryString.FilterDate}} {?{User.Name}Author:{User.Name}}
66+
```
67+
68+
69+
By using the `{?{ }}` syntax in your PnP Search Web Part query template, you can introduce dynamic, conditional logic similar to "if" statements in programming.
70+
71+
72+
73+
74+
### Example 1: Search for Documents Modified in the Last 30 Days
75+
```kql
76+
{searchTerms} AND (FileExtension:docx OR FileExtension:pdf) AND Modified:{Today-30}..{Today}
77+
```
78+
#### Explanation:
79+
- `{searchTerms}`: Placeholder for the user's search terms.
80+
- `FileExtension:docx OR FileExtension:pdf`: Filters to show only Word documents and PDFs.
81+
- `Modified:{Today-30}..{Today}`: Filters to show documents modified in the last 30 days.
82+
83+
### Example 2: Search for Items by Current User
84+
```kql
85+
{searchTerms} AND Author:{User.Name}
86+
```
87+
#### Explanation:
88+
- `{searchTerms}`: Placeholder for the user's search terms.
89+
- `Author:{User.Name}`: Filters to show items where the author is the current user.
90+
91+
### Example 3: Search for Tasks Due Today
92+
```kql
93+
ContentType:Task AND DueDate:{Today}
94+
```
95+
#### Explanation:
96+
- `ContentType:Task`: Filters to show only items of content type Task.
97+
- `DueDate:{Today}`: Filters to show tasks that are due today.
98+
99+
### Example 4: Search Within a Specific Site Collection
100+
```kql
101+
{searchTerms} AND Path:https://yoursitecollection.sharepoint.com/sites/specificsite
102+
```
103+
#### Explanation:
104+
- `{searchTerms}`: Placeholder for the user's search terms.
105+
- `Path:https://yoursitecollection.sharepoint.com/sites/specificsite`: Limits the search to items within a specific site collection.
106+
107+
### Example 5: Search with Query String Parameters for Category and Date Range
108+
```kql
109+
{searchTerms} {?{QueryString.Category}Category:{QueryString.Category}} {?{QueryString.StartDate}Modified:{QueryString.StartDate}..{QueryString.EndDate}}
110+
```
111+
#### Explanation:
112+
- `{searchTerms}`: Placeholder for the user's search terms.
113+
- `Category:{QueryString.Category}`: Filters by a category passed in the query string.
114+
- `Modified:{QueryString.StartDate}..{QueryString.EndDate}`: Filters by a date range passed in the query string.
115+
116+
### Example 6: Search for Content with Specific Metadata
117+
```kql
118+
{searchTerms} AND Department:Finance AND ContentType:Document
119+
```
120+
#### Explanation:
121+
- `{searchTerms}`: Placeholder for the user's search terms.
122+
- `Department:Finance`: Filters to show only items where the Department metadata is set to Finance.
123+
- `ContentType:Document`: Filters to show only items of content type Document.
124+
125+
### Example 7: Search for Items Tagged with Specific Terms
126+
```kql
127+
{searchTerms} AND (Tag:ProjectX OR Tag:Important)
128+
```
129+
#### Explanation:
130+
- `{searchTerms}`: Placeholder for the user's search terms.
131+
- `Tag:ProjectX OR Tag:Important`: Filters to show items tagged with either ProjectX or Important.
132+
133+
### Example 8: Search for Recently Viewed Items by the User
134+
```kql
135+
{searchTerms} AND ViewedBy:{User.Name} AND LastViewedTime:{Today-7}..{Today}
136+
```
137+
#### Explanation:
138+
- `{searchTerms}`: Placeholder for the user's search terms.
139+
- `ViewedBy:{User.Name}`: Filters to show items viewed by the current user.
140+
- `LastViewedTime:{Today-7}..{Today}`: Filters to show items viewed in the last 7 days.
141+
142+
### Example 9: Search for Items Excluding a Specific Folder
143+
```kql
144+
{searchTerms} -Path:https://yoursitecollection.sharepoint.com/sites/specificsite/Shared%20Documents/ExcludeFolder/*
145+
```
146+
#### Explanation:
147+
- `{searchTerms}`: Placeholder for the user's search terms.
148+
- `-Path:https://yoursitecollection.sharepoint.com/sites/specificsite/Shared%20Documents/ExcludeFolder/*`: Excludes items from a specific folder.
149+
150+
### Example 10: Search for Items Created by the Current User in the Last Year
151+
```kql
152+
{searchTerms} AND CreatedBy:{User.Name} AND Created:{Today-365}..{Today}
153+
```
154+
#### Explanation:
155+
- `{searchTerms}`: Placeholder for the user's search terms.
156+
- `CreatedBy:{User.Name}`: Filters to show items created by the current user.
157+
- `Created:{Today-365}..{Today}`: Filters to show items created in the last year.
158+
159+
160+
161+
### Final Notes:
162+
- Ensure that the tokens you use match the actual parameters or variables available in your context.
163+
- Test your query templates thoroughly to confirm they behave as expected with various input conditions.

0 commit comments

Comments
 (0)