# 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: ```ini [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](http://jinja.pocoo.org) 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** ```text 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](../../data-loading/connectors/one-click/microsoft-sharepoint.md#sharepoint-acl).