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.

Configuration Service#

As an alternative to storing templates on disk, the query template can be set per project via the configuration service using the topic.query-template configuration key. When a value is found in the configuration service for a given project, it takes precedence over the file-based template; otherwise, Squirro falls back to reading the template from disk as described above.

This is useful for managing query templates centrally without requiring filesystem access on the server.

Template#

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

Parameter

Description

query

The original query, for which the user is requesting information.

Deprecated as of Squirro 3.3.9. The template gets merged with an incoming query.

user

The user ID of the user executing the query.

tenant

The tenant domain of the current user. Tenant is the Squirro concept for running multiple organisations on the same Squirro cluster - used especially in the cloud environment.

email

The user’s email address.

is_admin

The boolean flag indicating if the user has admin permissions.

project_id

The project ID on which the query is executed.

project_title

The name of the project on which the query is executed.

external_request_params

The contents of the template_params dict in the query options. This can be used to pass custom data into the query template from custom widgets.

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:

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

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

Contents