KQL (Keyword Query Language) is a powerful way to enhance the queries that feed our "In Focus" / search experiences. A lot of power is built into search, which KQL helps you access with a little bit of creativity. Atlas Platform Administrators should be well rehearsed in using KQL to deliver slick and efficient experiences for users, with a bit of extra effort in the backend configuration.
It is worth having this page open as a reference if you want to follow the examples using RefinableString or RefinableDate values - Atlas Managed Properties for Search
In this article:
- How to apply KQL to In Focus web parts
- Querying based on tagging
- Dynamic queries based on the properties of the current loaded page
- Queries with dates
How to apply KQL to In Focus web parts
Once you have a KQL query based on the advice throughout this article, you'll need to know how to apply it to an In Focus web part.
- Edit the page with the In Focus web part you want to apply KQL to, then edit the specific In Focus web part
- Go to page 2 of the configuration panel
- Paste your KQL into the Query template box, ensuring you leave a space between anything else in the box and your additional KQL
- Bear in mind that if you already have additional filters set this will affect the results. Make sure you save the page as a draft and test that your configuration returns the information you're expecting.
Querying based on tagging
In the below examples, wherever something is in bold, you should replace it by the correct value. It is also important to understand all the options because some are not very intuitive. For example depending whether you write your query using the label or the GUID may actually effect whether results with child tags are returned even though the syntax is almost identical.
Getting all child items
This can be useful if for example you had a "Projects" parent term with all your projects listed as children, you could get all results for all projects (but not the parent "Projects" itself) only by knowing the GUID for the parent, and avoid listing and updating many project tags in the query.
{searchTerms} cp{FieldName}TaxID:"GPP|GUID", for example for the Subject field:
{searchTerms} cpSubjectTaxID:"GPP|5cd93ad5-97db-45fc-ad97-cfa15fc2e694"
Getting results for parent and all children
{searchTerms} RefinableStringXXX:GUID, for example for the Subject field:
{searchTerms} RefinableString137:5cd93ad5-97db-45fc-ad97-cfa15fc2e694
Getting results for ONLY the specific tag
{searchTerms} RefinableStringXXX:"TermLabel", for example for the Subject field:
{searchTerms} RefinableString137:"Annual Leave"
or you can use the unique GUID (unique identifier) for the term, found within the term store, but use an equal sign instead of a ':' colon.
{searchTerms} RefinableString137=5cd93ad5-97db-45fc-ad97-cfa15fc2e694
Dynamic queries based on the properties of the current loaded page:
When creating a query, it is often useful to be able to dynamically compare queried properties against the properties set in the page details.
Excluding current page
This KQL is useful to *exclude* the current page from search results (i.e. you really don't want to see the page you are standing on when listing items):
This returns items where their path is different to the current page's URL: Path<>{Page.Url}
As above, but in this case comparing on the URL of the Web (i.e. the root of the site collection, aka the home page): Path<>{Web.Url}
Excluding template pages
Here we are asking to "not" (the minus in front) get pages where the ParentLink is the templates folder.
-ParentLink:/SitePages/Templates
Matching results to specific Page tags
If you want to match using all the page tags you can just use the default configuration, but if you only want to filter based on a specific page tag you can use the following or similar:
CPReference:{Page.CPReference}
CPDepartment:{Page.CPDepartment}
Matching core terms against the tagging of the current page
In this example we want Landing Page results where the Entity on the Landing Page content matches the Entity on the Page itself and also where the Activity on the Landing Page content matches or is a child of a specific Term (in this case "Bids" using its GUID from the term store). The # at the front of the GUID specifies to also include any children.
In the example below, we are searching for items where CPEntityTaxId match against the current page's CPEntity (and it's child terms):
- Entity = {|CPEntityTaxId:{Page.CPEntity.IDWithChildren}}
Other Atlas managed metadata options are:
- Location = {|CPLocationGeographyTaxId:{Page.CPLocationGeography.IDWithChildren}}
- Department = {|CPDepartmentsTaxId:{Page.CPDepartments.IDWithChildren}}
- Activity = {|CPActivityTaxId:{Page.CPActivity.IDWithChildren}}
- Subject = {|CPSubjectTaxId:{Page.CPSubject.IDWithChildren}}
- Information Type = {|CPDocumentType:{Page.CPDocumentType.IDWithChildren}}
Personalize content for the user
If you want to tailor content based on the user preferences (My Preferences under the My Atlas in the header) you can do that by using the term User.NameOfProperty in a similar way to how it's done with pages above.
In this example, the user will be presented with items that are matching at least one Department (contains) on their preferences:
CPDepartment:{User.CPDepartment}
Queries with dates
Credit: Miguel Angel Garcia
A common scenario involves getting content based on dates. E.g. recently added, added during a date range, or reviewed in next 30 days.
Imagine a contract renewal date stored in the Atlas Date field (CPDate), and you want to know which contracts are up for renewal in the next 90 days. This would be done as follows, where RefinableDate18 corresponds to CPDate:
{searchTerms} (RefinableDate18<={Today+90})
Comments
0 comments
Please sign in to leave a comment.