home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
Looker documentation will be moving to cloud.google.com in mid-2022!
All the information you rely on will be migrated and all docs.looker.com URLs will be redirected to the appropriate page.
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, landing_page, last_name, full_name, ID, timezone (if configured), locale, and number_format.

The default user attributes landing_page, locale, and number_format can be edited, but should not be deleted. If you delete one of these user attributes, create a new user attribute with the same name.

Viewing user attributes

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

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 are reserved by Looker for internal use and cannot be edited.

Creating user attributes

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 assign a value in the drop-down menu. This reveals a table of values that apply to that user.
  3. Click the Set Value for User button.
  4. Enter the value for the user to have in the New Value field.
  5. Click Save.

When a value is assigned to an individual user, that value always takes 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:

To assign multiple values to a user attribute, use the data type String Filter (advanced), and input multiple values, each enclosed in single quotes and separated by commas. Make sure there are no white space between the values. For example:

To assign a Looker admin or other user all possible values, use a wildcard value in the user attribute:

For security purposes, using wildcards or a range of values in a user attribute is not supported with access grants. See the access_grant parameter documentation page for more information.

Assigning values to user groups

You can assign a value for a user attribute to a user group. From the User Attributes page of the Admin panel, select Edit to the right of the attribute you want to set. Then follow these steps:

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

When a value is assigned to multiple groups you 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.

In the previous example, 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.

If a user has set a custom value for a user attribute, the value the user set overrides any value given to a group that user belongs to.

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.)


Any connection can be configured to use user attributes from the Connections page in the Admin section of Looker. (See the Admin settings - Connections 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 input 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 username and password of a connection so that each user connects with the appropriate credentials for their database access level. While this ensures 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 still appears to them in Looker. They 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 want 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.


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

This example uses two user attributes — salesforce_username and salesforce_password— 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 } } }

Custom actions in an action hub

You can configure a custom action to include user attributes that restrict users from sending or scheduling Looker content to that action destination if they do not have a value defined for that user attribute.


The params parameter in a custom action represents the form fields that a Looker admin must configure on the action’s enablement page from the Actions list in the Admin panel. In the params parameter of your action file, include:

params = [{ description: "A description of the param.", label: "A label for the param.", name: "action_param_name", user_attribute_name: "user_attribute_name", required: true, sensitive: true, }]

where user_attribute_name is the user attribute defined in the Name field on the User Attributes page in the Users section of the Admin panel, required: true means that a user must have a non-null and valid value defined for that user attribute to see the action when delivering data, and sensitive: true means that user attribute value is encrypted and never displayed in the Looker UI once entered. You can specify multiple user attribute subparameters.

A Looker admin must configure the action’s form fields with the user attribute:

  1. Click on the Enable or the Settings button next to the action on the Actions page of the Admin panel.
  2. Click on the user attribute icon to the right of the appropriate field and select the desired user attribute.

See the Adding user attributes to custom actions section of the Sharing data through an action hub documentation page.


Filters on Explores, Looks, dashboards, and legacy dashboards can be set to a user attribute to customize the query based on the user who is 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.


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 an 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 _user_attributes Liquid variable syntax:


You can use the same pattern to insert user attributes into LookML dashboard filters and dashboard element filters.

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 deliveries for content that are sent as one-time deliveries and recurring deliveries.

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.


Only Looker users have user attribute values set, so every recipient of the data delivery must have a Looker account. User attributes are applied by running the dashboard or Look once for each recipient.


Open the Scheduler for the Look, legacy dashboard, or dashboard that uses the new dashboard experience:

  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 shows 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_grant 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.


  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.

User attributes for Git account passwords must be hidden. When creating the password attribute, select Yes under the Hide Values option and enter the Git provider URL in the Domain Allowlist field.

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 parameter documentation page.

For security purposes, using wildcards or a range of values in a user attribute is not supported with access grants. See the access_grant parameter documentation page for more information.

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 examples in the Connection section of this documentation page, and in the Using user attributes for dynamic schema and table name injection Help Center article.

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.


The user attributes locale and number_format can set the appearance of data, visualizations, and parts of the Looker user interface for specific users or user groups. See the Localizing Looker documentation page for more information.

Testing user attributes and access filters

You can test the effects of your user attributes with Looker’s sudo function. Admins (or users with both the see_users and sudo permissions) can sudo as another user to see their experience of Looker.

When you are in Development Mode, your changes are not visible to other users until you deploy your changes to production. If you haven’t deployed your changes for other users to see, you will not see your changes when you sudo as a different user.