User Guide Getting Started Help Center Documentation Community Training
Looker
User Attributes

User attributes provide a customized experience for each Looker user. A Looker admin defines a user attribute and then applies a user attribute value to a user group or to individual users.

Admins can also define user attributes for which the users themselves provide values, such as passwords or contact information. Various places throughout Looker can reference the user attributes to provide a custom experience for each user.

Looker automatically includes some user attributes, such as email, first name, last name, full name, ID, and time zone (if configured).

Viewing User Attributes

To see your list of user attributes, go to the User Attributes page in the Admin section of Looker:

The table of user attributes gives the name, label, and type for each user attribute (see below for more information). In addition, the table provides a button for actions you can take for the user attribute. Some attributes show “System Default” instead of a button for actions, which means that Looker automatically creates those attributes for each user. The system default user attributes cannot be edited.

Creating User Attributes

New in Looker 5.20, you must specify a domain whitelist when you hide a user attribute’s values.

To define a user attribute, click the Create User Attribute button at the upper left of the screen. Each user attribute has the following settings:

Once you define a user attribute, you can assign values to individual users or to user groups by clicking the User Values and Group Values tabs at the top of the page:

Assigning Values to Individual Users

After defining a user attribute, you can assign a value for it to an individual user:

  1. Click on User Values.
  2. Choose the user to which you want to assign a value in the drop-down menu. This will reveal a table of values that apply to that user.
  3. Click the Set Value for User button.
  4. Enter the value that you want the user to have in the New Value field.
  5. Click Save.

When a value is assigned to an individual user, that value will always take precedence over any values assigned to that user’s groups. The User Values tab shows when a custom value has been assigned to a user attribute that overrides a group value:

If you want to assign a Looker admin or other user all possible values, use a wildcard value in the user attribute:

Assigning Values to User Groups

After defining a user attribute, you can assign a value for it to a user group:

  1. Click on Group Values.
  2. Click the + Add Group button.
  3. Choose the group to which you want to assign a value in the drop-down menu.
  4. Enter the value that you want the group to have in the Value field.
  5. Click Save.

When a value is assigned to multiple groups you’ll need to decide which group should take precedence, in case a user belongs to multiple groups. To do so, drag the groups into the order that should apply; each group takes precedence over the groups listed below it.

For instance, in the example above, there are Executive Team and Management Team groups. Executives are also managers, so they are members of both groups. Dragging the Executive Team group to the top of the list will ensure that its members are assigned the Executive value instead of the Manager value.

Where Can User Attributes Be Used?

User attributes have the following functions:

Database Connections

The host, port, database, username, password, and schema of a connection can each be given the value of a user attribute. (The connection host field will not accept a user attribute that has a User Access level set to Editable.)

This makes the connection specific to the user who runs a query. User attributes can also be referenced in the Additional Params field, which customizes the JDBC connection string. When a user runs a query using the connection, the user attribute values assigned to the user will be applied, allowing the connection to be customized based on the user.

If you set one or more connection parameters to a user attribute, you must define separate persistent derived table (PDT) credentials to use PDTs in your LookML model. (One exception: BigQuery’s “Max Billing Gigabytes” can be set to a user attribute without requiring a separate PDT user.)

Configuration

Any connection can be configured to use user attributes from the Connections page in the Admin section of Looker. (See this documentation page for information on the Connections page.) To create a new connection, click New Connection. To configure an existing connection, click Edit next to the connection.

In the New Connection and Edit Connection pages, each of the inputs that can be set to a user attribute has a button attached to its right side with the user attribute icon:

Click the user attribute button to display a drop-down menu that lets you choose the desired user attribute:

For example, here is a user attribute called Database Name that is used to parameterize the database of the connection. The value for the Database Name user attribute for the current user, demo_db, is shown in parentheses:

To reference a user attribute in the Additional Params field, use the same Liquid templating syntax available in LookML. User attributes are made available through the _user_attributes Liquid variable. For example, to reference a user attribute named my_jdbc_param_attribute, use the following syntax:

my_jdbc_param={{ _user_attributes['name_of_attribute'] }}

Here’s how it might look in the Additional Params field in Looker:

Use Case: Applying Database-Level Permissions in Looker

If your database has different accounts with various access restrictions, you can leverage your database permissions in Looker. Parameterize the user name and password of a connection so each user connects with the appropriate credentials for their database access level. While this will ensure that users do not see data to which they shouldn’t have access, this will not affect which Explores, dimensions, and measures are shown to them in Looker.

For example, if a user is configured to connect to the database with an account that prevents them from seeing a credit_card_number column in the user table, any dimension using that database column will still be shown to them in Looker. They will simply receive an error from the database if they attempt to run a query that includes that dimension.

Use Case: Using One Model for Multiple Identical Databases

Let’s say you have multiple databases with the exact same schema, such as when each customer’s data is siloed into its own database for data security measures (such as HIPAA compliance). Or perhaps you would like your LookML developers to run queries against a development copy of a production database.

If these databases live on the same database server, you don’t need to set up separate connections and models. Instead, set the database of a connection to a user attribute and each user will be pointed to the database specified in their value for the Database Name user attribute.

Using user attributes on a connection will disable persistent derived tables for that connection.

Data Actions

Data actions can be configured to include certain user attributes with their JSON payload. Use this to send user-specific information along with the data, such as their credentials to perform an operation against a particular service.

Configuration

To include a user attribute in a data action, add a user_attribute_param block to the action definition. Each of these blocks takes two parameters:

In the example below, we have two user attributes—salesforce_username and salesforce_password—used to hold each user’s Salesforce credentials in Looker. When a user performs the Update in Salesforce data action, Looker sends their Salesforce credentials with the JSON payload, which the receiving server can use in authenticating to Salesforce.

dimension: stage_name { type: string sql: ${TABLE}.stage_name;; action: { label: "Update in Salesforce" url: "https://example.com/my_salesforce_url" user_attribute_param: { user_attribute: salesforce_username name: "username" } user_attribute_param: { user_attribute: salesforce_password name: "password" } form_param: { name: "new_stage_name" type: string required: yes } } }

Filters

Filters on Explores, Looks, and dashboards can be set to a user attribute to customize the query based on the user running it.

For example, you could create a user attribute called Salesforce Username and configure each Looker user so that their value for it is their Salesforce username. Then you could set a filter on a dashboard to the Salesforce Username user attribute and each user would see that dashboard filtered for their particular Salesforce username.

Configuration

In the FILTERS section of the Explore, Look, or dashboard:

  1. Select the matches a user attribute option on the desired filter.

    The select box to the right automatically updates with a list of user attributes that have the same type as the filter’s field, such as number, string (text), date, and so forth. Looker displays your value for each user attribute in parentheses.

  2. Select the desired user attribute.

Advanced Filter Syntax

If you’d like to do something more complex than a simple equality check for the filter, select matches (advanced) and reference the user attribute using a Liquid variable:

{{ _user_attributes['name_of_attribute'] }}

For example, suppose you need to apply a sf_ prefix to the value of the Salesforce Username user attribute because that is how the values are stored in your database. To add the prefix to the user attribute value, use the Liquid variable syntax:

Scheduled Dashboards and Looks

Dashboard and Look filters can be set on a per-schedule basis, including the option to use a user attribute. This lets you customize the data delivery results for each email recipient. You can customize data delivery results both for scheduled data deliveries and for data deliveries sent without a schedule.

For example, you could create a user attribute called Salesforce Username and set the value to each user’s Salesforce username. Set a filter on a dashboard or Look schedule to the Salesforce Username user attribute so each recipient gets that dashboard filtered by their Salesforce username.

Prerequisites

Configuration

Open the Schedule or Send window for the dashboard or Look:

  1. In the Filters section, select the matches a user attribute option on the desired filter.

    The select box to the right automatically updates with a list of user attributes that are the same type as the filter. Your own value for each user attribute will be shown in parentheses.

  2. Select the desired user attribute.

  3. Check the run schedule as recipient checkbox next to the Email options field.

Access Filters

You can limit the data a user can access with access filters, which provide row-level security. Although you can use the access_filter parameter, access filters are more easily implemented and maintained with user attributes.

Access filters provide a secure way to apply user-specific data restrictions. Defining one or more access filters for a LookML Explore enforces that the data returned from an Explore is filtered based on the user running the query. Thus, access filters provide an extra layer of restriction, ensuring the user can only see specific subsets of the data from a database connection.

SQL Note: Access filters provide row-level security by inserting conditions in the SQL WHERE clause. User attributes can be leveraged in LookML in another way to provide column-level security as described in the Masking Sensitive Fields for Certain Users article.

Configuration

  1. Create a user attribute:
    • Configure with User Access set to None (recommended) or View. (A user attribute configured to be editable by users cannot be used for an access filter.)
    • Assign user attribute values to groups or individual users.
  2. In the LookML definition for the Explore where you want the access filter, add an access_filter block with the following parameters:
    • field: The name of the LookML field on which to filter
    • user_attribute: The name of the user attribute that stores the value you want to use to filter the data
  3. Run a query against that Explore.
  4. Check the WHERE clause of the query’s SQL to verify that the data is filtered according to your value for the user attribute.

This LookML ensures queries about orders are filtered by brand, with the particular brand being based on the user’s assigned value for a user attribute named company:

explore: orders { view_name: orders access_filter: { field: products.brand_name user_attribute: company } join: products { foreign_key: orders.product_id } }

Connecting to Git Providers

For LookML projects, you can configure Git authentication over HTTPS. Projects that use HTTPS Git authentication have the option of leveraging user attributes to log in to individual developer’s Git accounts when performing Git operations for the developer.

Controlling Access with Access Grants

You can create access grants that limit access of a LookML Explore, join, view, or field using user attribute values, the access_grant parameter, and the required_access_grants parameter.

Access grants work like this:

  1. You define an access grant using the access_grant parameter. As part of the definition, you associate the access grant with a user attribute. You also specify which user attribute values provide access to the access grant.
  2. Next, you use the required_access_grants parameter at the Explore, join, view, or field level to restrict that structure to only users who have access to every access grant listed.

For example, you could use an access grant to limit access to the “salary” dimension to only those users who have the value payroll in their department user attribute.

For more information about how to define access grants, see the access_grant documentation page.

Liquid Variables

LookML enables the use of several different Liquid variables, which can be useful for more complex types of customized output. A user’s attribute values can now be included in Liquid.

You can see an example in the Connection section of this documentation page.

Google BigQuery Data Limits

If you use Google BigQuery as your database, then Google charges you for each query based on the size of the query. To help prevent users from accidentally running too expensive a query, you can apply a user attribute in the Max Billing Gigabytes setting in your BigQuery connection. The values that you supply in the user attribute should be the number of gigabytes that a user is allowed to pull in a single query.

Embedded Dashboards

You can limit the data displayed in embedded Looks and dashboards by basing filter values on user attribute values. For more information, see this Community topic.

Top