Holistics Docs - End-to-End Business Intelligence Platform

Holistics Documentation

Welcome to the Holistics Documentation page. You'll find comprehensive guides and documentation to help you start working with Holistics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Permission System

There are several methods to manage permission in User Management:

  • Roles & Groups: control which groups can access which data, making it easier for users to navigate through reports and improving data security. All users are assigned a role, and can then be added into user groups.
  • Report/Dashboard Level Permissions: share reports/dashboards to specific users or groups.
  • Filter Permissions (Row-level permission): apply permission rights in the filters that you created.
  • Column-level permission: show certain columns basing on who views the report.
  • Sharing data sources to analysts: allows admin to set a specific data source permission to analysts.
  • Locking Objects: allows admins or analysts to lock a specific report or dashboard. Once locked, only admins or the owner can modify or delete it.

Roles & Groups


There are 3 possible roles on Holistics platform. Each user will belong to one role.

  • Admin: can manage users, reports, dashboards and billing, etc.
  • Analyst: can create and edit reports and dashboards whose data source is shared with them. Analyst cannot manage users, or connect new data sources.
  • Business User: can only view reports and dashboards that are shared with them


Groups can be created by admins, and they are used to organize users into different categories. Each user can belong to multiple groups. Examples of user groups:

  • Marketing
  • Engineering
  • Asia
  • Europe
  • Management
  • ...

Report/Dashboard Level Permissions

  • You can share reports, dashboards, or KPI metric sheets to specific users or groups.
  • This works for folders as well. Sharing a folder will automatically share all items inside.

Filter Permissions

Sometimes you need to share a dashboard to many groups/users and want to filter permission on each group/user, for examples:

  • If the user is in group Marketing, it will show the marketing data (Customer engagement, Conversion rates...) only.
  • If the user is in group Sales, it will show the sales data (Sales lead, Sales won...) only.
  • If the user is in group Director or the email is admin@company.com, it will show both marketing and sales data.
  • If the user is in group Investor, it will show marketing and sales data in the last 6 months only.

In Holistics, user/group permissions can be included into Text Input, Date and Dropdown filters. To do this, expand the Permissions field when creating or editing a filter, and then add your permission code into the field.

Syntax References

  • Condition variables

    • if_group: Group name
    • if_user: User email
    • else: No value is needed. This applies to anyone who does not belong to its above condition
  • Outcome variables

    • then_value: Value manually added
    • then_sql [ds_id, query]: Value extracted through a SQL. ds_id is the datasource id
    • then_date_min: Min date value
    • then_date_max: Max date value
  • Optional variables

    • expression: Allows more control over permissions filter. This field defaults to Group1 union Group2 union Group3, where Group1, Group2 and Group3 are added in as in_group. This field could be customized to: Group1 union (Group2 intersect Group3)

Note: Please refer to Legacy Filter Permission Syntax if you need to use the old syntax version.

Example input code:

- if_group: GroupA
  then_value: valueA
- if_group: GroupB
  then_value: [valueB, valueC]
- if_group: GroupC
      ds_id: 25
      query: select val from tableC
expression: Group1 union (Group2 intersect Group3)

Example code using else:

- if_group: GroupA
  then_value: valueA
- if_group: GroupB
  then_value: [valueB, valueC]
- else:
  then_value: valueD


  • Each permission must contains at least one Condition variable and one Outcome variable
  • expression is usable only in Dropdown Filter
  • then_date_min, then_date_max are usable only in Date Filter
  • else syntax can only be used for filter that returns a single value

Add Variable In Filter Permission


  • We have a company where 50 managers manage 100 different stores
  • Each manager can only see the stores' reports he/she manages.

Previously, when managers switch stores, the admins will need to update the changes in their own system and update the permissions in Holistics system.

With this feature, they only need to update the tables in their own system, and Holistics will refer to those tables with a query using the {{ $user.email }} variable.

Consider these tables. By providing a mapping table to match two key tables together (such as employees table with stores table), when employees login to the Holistics platform with their emails, the {{ $user.email }} variable will get passed into the filter query, and pull out the subset of stores that the employee manages.

For an example using our SQL syntax inside the filter permissions, consider these tables; a managers table, a store table and a mapping table that joins these two tables together, a store_user_permissions table.

Applying the variable $user.email would let us create a filter permission as such:

- if_group: Manager
    ds_id: 25
    query: select store_id from store_user_permissions SUP join managers M ON SUP.user_id = M.id where M.email = {{ $user.email }}


Parent Child Filters

Adding child filters to dropdown filters will impact your permission syntax. Please refer to Setting Up Parent-Child Filters and Dropdown Permissions

Restricting Content for Text Filter

You can make your Text filter read-only and have different values for different groups with filter permission. For example:

- if_group: 'Vietnam'
  then_value: 'mkt'
- if_group: 'US'
  then_value: 'sale'
- if_user: 'marketing@holistics.io'
  then_value: 'mkt'

When you apply this filter permission on any report or dashboard, it will check the user's group or email to assign the value when executing the report or dashboard. On the example above, we will limit the data for each department depends on the group and email.

The result would be like this:

Notes: There is only one value can be applied for one group. If you set multiple values for a group, the first one will be selected.

Restricting Date Selection for Date Filter

Sometimes when working with the Date filter, you want to restrict date range access to specific user groups.
For example: since Singapore site only launches in May, business users from Singapore should not be able to select dates earlier than that.

To do this, apply the following permission syntax to the date filter:

- if_group: Singapore
  then_date_min: '2016-05-01'

This will restrict the user's date selection options:


  • You can also use then_date_max to restrict the maximum date selectable.
  • Right now, only exact date values are supported (i.e. no text values such as 3 months ago).
  • If the user belongs to multiple groups that are defined in the permissions section, the first matching group will be selected.

Restricting Selections for Dropdown Filter

Consider a multi-national organization where employees are based in Singapore, Malaysia, Vietnam etc... with headquarter in Malaysia. We would want to have these permissions:

  • Users in Malaysia can view data from all countries
  • Users in branch countries can only view data from their countries

Here is the sample code for your Country filter:

- if_group: Malaysia
	then_value: [my, vn, sg]
- if_group: Vietnam
	then_value: vn
- if_group: Singapore
	then_value: sg

Then add the Country filter to your SQL query:

WHERE [[ country IN ({{countries}}) ]]


  • country is the name of a field in the table
  • countries is the name of the report filter

Our permission syntax allows even more complex use cases. For example, in a merchant report, you want to make sure a business user in a country can only see merchants from their own country. However, as your business grows, the list of merchants constantly changes.

Assume that we have connected different data sources containing separated merchant lists for different countries. (For example, Malaysia's data source ID is 101, Singapore is 201, Vietnam is 301...). You can find your data sources' IDs in Data Sources.

Here is a sample code to implement said restriction on your Merchants filter:

- if_group: Singapore
    ds_id: 201
    query: SELECT DISTINCT id from merchants
- if_group: Vietnam
    ds_id: 301
    query: SELECT DISTINCT id from merchants

This will map the merchant ID from the country database to the current database. Then add the Merchants filter to your SQL query:

WHERE [[ merchant_name IN ({{merchants}}) ]]


  • merchant_name is is a field in the table you are querying from
  • merchants is the name of the report filter

With this setup, the merchant lists unique to each country will always be up-to-date - No need to manually add merchant IDs every time a new merchant is added to the database!

Sharing Data Sources to Analysts

Administrator can share the data source to specific analysts by going to Manage Data Sources page and click on the Share With column.

Note that even if a data source is shared to an analyst, s/he cannot view or modify database credentials information of that data source.

They can only build queries from the schemas and tables they can access, such as those associated with the database user for the shared data source.

Locking Objects

Analysts can only lock their own objects, while admins can lock every lockable objects.
When an object is locked, it can only be edited by its owner or admins.

Current lockable objects are:

  • Dashboards
  • Query reports
  • Query templates
  • Shared filters

Verify the permission

When the permission is applied and you want to make sure it worked as your expectation. You could use the View and Edit as feature in Holistics. This feature allows admin to use Holistics using the chosen user role.

Permission System

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.