Skip to main content

User Attributes

User attributes provide a way to customise Lightdash charts, dashboards, and other behaviour depending on the user that is logged in. For example, you could only show your sales team members data that are relevant to their region.

User attributes are defined for your whole Organization and can only be a text value (not a date or number). Some examples of user attributes are:

  • Sales region
  • Department
  • Can view PII
  • Can view financial data

To start user attributes you need to follow 2 steps:

  1. Define the user attribute, users can only have user attributes that are explicitly created by admins
  2. Set the user attribute value per user.

User attributes can only be managed by admins.

Managing user attributes​

Creating user attributes​

User attributes can be created by navigating to Organization Settings > User Attributes and clicking on the Add attribute button. This will create a new user attribute but it will not be assigned to any user.

Assigning user attributes to users​

User attributes can be assigned to users by navigating to Organization Settings > User Attributes and clicking on the user attribute you'd like to assign. Select a user by email address and set their value.

Setting a default value for your user attribute​

You can add a default attribute that will be applied to all users who don't have their own value defined in this user attribute.

If a user has an attribute defined, we will ignore the default for that user.

Using user attributes in Lightdash​

There are several places in Lightdash where you can customise behaviour based on user attributes.

When referencing user attributes in SQL you can use the following SQL variables:

  • ${lightdash.attributes.my_attr_1} - a user attribute called my_attr_1
    • (optional) ld as an alias for lightdash
    • (optional) attribute or attr as an alias for attributes

1. Row filtering with sql_filter​

You can use user attributes to filter the rows returned by a query. This is useful if you want to restrict the data based on the user's attributes. To reference a user attribute in your sql, use the special lightdash reference ${lightdash.attributes.<attribute_name> }. For example, if you have a user attribute called sales_region you can use it in your sql like this:

models:
  - name: my_model
    meta:
      sql_filter: ${TABLE}.sales_region = ${lightdash.attributes.sales_region}

2. Filtering joins with sql_on​

If you're joining a table, you can also customise the rows that are returned

You can use user attributes to filter the rows returned by a join. This is useful if you want to restrict the data returned from the joined table. To reference a user attribute in your sql, use the special lightdash reference ${ lightdash.attributes.<attribute_name> }. For example, if you have a user attribute called sales_region you can use it in your sql like this:

models:
  - name: base
    meta:
      joins:
        - join: joined
          sql_on: >
            ${base}.id = ${joined}.id
            AND ${joined}.sales_region = ${lightdash.attributes.sales_region}

Demo: filtering a chart based on user attributes

The following video gives you a full demo for how to use user attributes to filter chart results.