User attributes are arbitrary values that you can assign to a user, or a user can assign to themselves, that can then be used in other parts of Looker to provide custom experiences for each user.
Looker automatically includes some user attributes for you, including their 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 contains the following values:
|Name||The name of the user attribute, as you’ll reference it in text-based areas of Looker like LookML|
|Label||The user-friendly name of the user attribute, as you’ll see it in parts of the Looker interface|
|Type||The type of the user attribute (string, number, date, yes/no, zipcode)|
|Actions||Any actions you can take for the user attribute. Note that some attributes will say “System Default”, which is the set of attributes that Looker automatically creates for each user.|
Creating User Attributes
To define a user attribute, click the Create User Attribute button at the upper left of the screen. Creating a user attribute requires two steps:
- Define the user attribute’s settings
- Assign values to the user attribute for sets of users or user groups
Defining a User Attribute
Each user attribute has the following settings:
- Name: The name of the user attribute, for use in text-based environments such as LookML (can only use lowercase letters, numbers, and underscores).
- Label: The user-friendly version of the name. By default this will be the Name of the attribute, with underscores replaced with spaces, and each word capitalized. However, it can be modified as desired.
- Data Type: The type of the user attribute can be a string (words), number, datetime, yesno, or zipcode. This setting is used to check that valid values are being assigned to users for this user attribute.
- User Access: You can choose the level of visiblity and editing users have to a user attribute:
- Hidden: Will not appear on users’ account pages.
- Viewable: Will appear on users’ account pages, but will not be editable.
- Editable: Will appear on users’ account pages and can be set by the user.
- Hide Values: Even if user attributes are visible to users, they can still be masked, which is useful for passwords or other sensitive information. Keep in mind that once this value is set to “Yes”, it can never be changed back to “No”.
- Default Value: You can optionally set a default value to fall back on if a user has not had another value assigned to them.
Assigning Values to Groups and Users
Once a user attribute has been defined, values can be assigned to user groups and/or individual users using the Group Values and User Values tabs at the top of the page:
Assigning Values to Individual Users
To assign a value to an individual user, follow these steps:
- Click on User Values.
- Choose the user to which you want to assign a value in the dropdown menu. This will reveal a table of values that apply to that user.
- Click the Set Value for User button.
- Enter the value that you want the user to have in the New Value field.
- Click Save.
When a value is assigned to an individual user the 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:
To give access to all values of a string field, use a
To give access to all values of a number field, use
Assigning Values to User Groups
To assign a value to a user group, follow these steps:
- Click on Group Values.
- Click the + Add Group button.
- Choose the group to which you want to assign a value in the dropdown menu.
- Enter the value that you want the group to have in the Value field.
- 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 is both an “Executive Team” and “Management Team” group. Executives are also managers, so they are a member of both groups. Dragging the “Executive Team” 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:
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. 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 field 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 Database Name user attribute’s value 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:
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 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 which includes that dimension.
Using One Model for Multiple Identical Databases
If 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 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 of these blocks takes two parameters:
user_attribute— The name of the user attribute
name— The name to use in the JSON payload
In the example below, we have two user attributes—
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.
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.
In the Filters section of the Explore, Look, or dashboard:
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.
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:
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.
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.
For each email recipient’s own user attribute to be applied to a filter specified on a schedule, the Run a schedule as each of its recipients Labs feature must be enabled. This Labs feature can be turned on from the Labs page in the Admin section of Looker:
If you don’t have access to this panel, ask your Looker admin to enable it for you.
Open the Schedule or Send page for the dashboard or Look:
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 which are applicable, based on the type of the filter’s field matching the type of the user attribute. Your own value for each user attribute will be shown in parentheses.
Select the desired user attribute.
Check the Run a schedule as each of its recipients checkbox next to the Email Address field.
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
WHEREclause. User attributes can be leveraged in LookML in another way to provide column-level security as described in the Masking Sensitive Fields for Some Users article.
- 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.
- In the LookML definition for the Explore where you want the access filter, add an
access_filterblock 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.
- Run a query against that Explore.
- Check the
WHEREclause 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
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 on this 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.
You can limit the data displayed in embedded Looks and dashboards by basing filter values on user attribute values. For more information, see this User Forum topic.