andy1

Query Templates in Share and the Public API

Blog Post created by andy1 Employee on Jun 28, 2017

Introduction

 

Some of this week's questions have been related to query templates. Specifically, how can I use my custom properties in Share live search and standard search to find stuff. To do this you need to change some query templates.

 

What is a query template?

 

A query template is a way of taking a user query and generating a more complex query. Somewhat like the dismax parsers in SOLR. The Share template for live search looks like this:

 

%(cm:name cm:title cm:description TEXT TAG)

 

The % identifies something to replace and is followed by a field or, in this case, a group of fields to use for the replacement.  Whatever query a user enters for the template is applied to those fields. For groups of fields they are ORed together.

 

So for example, if you search for alfresco in the live search it will generate:

 

(cm:name:alfresco OR cm:title:alfresco OR cm:description:alfresco OR TEXT:alfresco OR TAG:alfresco)

 

If you search for =Alfresco in the live search it will generate:

 

(=cm:name:Alfresco OR =cm:title:Alfresco OR =cm:description:Alfresco OR =TEXT:Alfresco OR =TAG:Alfresco)

 

For multiple words they are ANDed together(by default), So for one two you get:

 

(cm:name:(one AND two) OR  cm:title:(one AND two) OR cm:description:(one AND two) OR TEXT:(one AND two) OR TAG:(one AND two))

 

If you search for the phrase "alfresco is great":

 

(cm:name:"alfresco is great" OR cm:title:"alfresco is great" OR cm:description:"alfresco is great" OR TEXT:"alfresco is great" OR TAG"alfresco is great")

 

Here, the template is simply defining the fields used for search. You can also add different importance to each term if you specify each field rather than a replacement group. For example:

 

(%cm:name^10 OR  %cm:title^2  OR %cm:description^1.5 OR %TEXT OR %TAG)

 

Here we are ranking name matches higher then title, title over description and all over TEXT (content) and TAGs.

 

Query templates can contain any query element - so we could limit the results to certain types.....but this would be better as a filter query .....

(%cm:name^10 OR  %cm:title^2  OR %cm:description^1.5 OR %TEXT OR %TAG) AND TYPE:content

 

You could split your template into two parts - one for content and one for folders  - if you want to change the balance of relevance between them.

 

Customizing Share Templates

 

There are two templates for share: one for live search and one for standard search. The configuration of advanced search is discussed elsewhere. In

<tomcat>\shared\classes\alfresco\extension\templates\webscripts\org\alfresco\slingshot\search

 

You will need two files with the following default content

  • search.get.config.xml

    <search>
       <default-operator>AND</default-operator>
       <default-query-template>%(cm:name cm:title cm:description ia:whatEvent ia:descriptionEvent lnk:title lnk:description TEXT TAG)</default-query-template>
    </search>

  • live-search-docs.get.config.xml

    <search>
      <default-operator>AND</default-operator>
      <default-query-template>%(cm:name cm:title cm:description TEXT TAG)</default-query-template>
    </search>

You will probably want to change them so they do not use field groups and you can add boosting as described above.

It is then easy to add your own properties and boosting to one or both of the templates.

 

Search public API

 

The search public API in ACS 5.2 and later supports templates (as has the Java API for some time). Each template is mapped to a field. 

{
    "query": {
        "language": "afts",
        "query": "WOOF:alfresco"
    },
    "include": ["properties"],
    "templates": [
        {
            "name": "WOOF",
            "template": "(%cm:name OR %cm:content^200 OR %cm:title OR %cm:description) AND TYPE:content"
        }
    ]
}

 

A template is assigned to a name which can be used in the query language just like any other field. If the name of a template is set as the default field any part of the query that does not specify a field will go to the template. That is how Share maps the user query to the template and exposes a default Google like query but also allows advanced users to execute any AFTS query. Most of the time it uses the default field and the template above.

 

As of 5.2.1, templates can also be used in the CMIS QL CONTAINS() expression

{
    "query": {
      "language": "cmis",
      "query": "select * from cmis:document where CONTAINS('alfresco')"
  },
  "include": ["properties"],
   "templates": [
    {
      "name": "TEXT",
      "template": "%cmis:name OR %cmis:description^200"
    }
  ]
}

CMIS CONTAINS() defines TEXT as the default field. This normally goes to cm:content but can be redefined, as we do here.

 

Summary

 

Query templates are a great way to hide query mapping from the end user. The Share templates allow you to add your own properties to Share queries and tweak the weight given to each field - perhaps giving name matches greater prominence.

Outcomes