KQL Tips & Tricks (Keyword Query Language)

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.

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
  • Excluding current page
  • Excluding template pages
  • Matching results to common Atlas tags
  • Matching core terms against the tagging of the current page
  • Personalize content for the user
• 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.

1. Edit the page with the In Focus web part you want to apply KQL to, then edit the specific In Focus web part
2. Go to page 2 of the configuration panel
3. Paste your KQL into the Query template box, ensuring you leave a space between anything else in the box and your additional KQL
   
4. 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

Getting child items through KQL

{searchTerms} cp{FieldName}TaxID:"GPP|{GUID}", for example for the Subject field:

{searchTerms} cpSubjectTaxID:"GPP|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 common Atlas tags

cpReference:{Page.CPReference}

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