Query Templates

Query Templates#

Query Templates are appended to an incoming Squirro query. This functionality is typically used to implement access control logic.

Configuration#

To enable query templates, the /etc/squirro/topic.ini configuration is modified to contain a [query_templates] section:

[query_templates]
# Which projects should use a query template (space-separated)
project_ids = IgnLQDYqSta1dQUtOZh0xg I6JAxCjeRTWts8mwI3AA6A


# Where are the templates stored
directory = /etc/squirro/query_templates

Make sure, the specified directory exists. For reach project that was specified in the project_ids a template file with the tmpl extension should exists. In the example above, the following two templates are used on the disk:

  • /etc/squirro/query_templates/IgnLQDYqSta1dQUtOZh0xg.tmpl

  • /etc/squirro/query_templates/I6JAxCjeRTWts8mwI3AA6A.tmpl

If a template doesn’t exist, even though the project is listed in the query templates project IDs, then all queries in that project will return an error.

Template#

The query template is written as a Jinja template. A number of arguments are provided to the template.

In addition, all values passed into the user_information dictionary in the extauth service are available as top level attributes.

Authorization Example#

A typical use case for query templates is to combine them with authorization facets (see the auth option in data loader labels. For example, a facet can be calculated or loaded, that flags each item with the user IDs that are allowed to see that item. In that case, the query template may look like this:

example.tmpl

user:{{user}}

In this example, the original query may be something like “salary”, but this will be expanded by this template to (depending on the user ID) the larger query “salary AND user:WXt6zm_wSKqW3J8S-aDAwA” - thus ensuring, that only results are returned, where the user facet is set to the current user’s identifier.

Passing Permissions in SharePoint#

Query templates can be used to pass permissions from third-party applications through to Squirro using query templates using the following template:

(acl_users:{{msAzureUserId[0]}} {%- for item in user_values['microsoft_user_groups'] %} OR acl_groups:{{item}} {%- endfor %}) AND source_type:"Microsoft SharePoint" OR NOT source_type:"Microsoft SharePoint"

To learn more about how query templates can be used to pass permissions from Microsoft SharePoint via Microsoft Azure Active Directory, see ACL Configuration via Microsoft Azure Active Directory.

Contents