Using Variables

Birst spaces support two types of variables, based on when their values are updated:

  • Repository variables: Variables that are refreshed when data is processed. Birst provides built-in repository variables related to data loading, such as LoadDate, LoadStartTime, LoadDateSFDC, LoadCompletionTime, and LoadNumber.
  • Session variables: Variables that are refreshed with each new user session. Birst provides two session variables, USER and UserLocale. USER can help drive data level security for a space by dictating what data a specific user is able to see. UserLocale is determined by the Birst User Settings page Language option. These are not valid for ETL scripts.

Space Administrators can create new variables of either type.

Personalizing Content with Session Variables

Session variables provide a convenient way to personalizing content for each user. Session variables are populated when a user logs into Birst.

Important: Birst refreshes session variables at the start of each session for each user login. The more session variables there are, the longer a session may take to initialize when the user logs in. Configure a variable as a session variable only when it needs to be run per user. If the value will be the same for all users, then it should be configured as a repository variable.

Using Repository Variables

Repository variables get refreshed when data is processed. They are data-specific rather than user-specific. They are driven off of data that has just been processed. For example, use a repository variable to get the current date from data that has just been processed.

Built-in Repository Variables for Loads

The pre-defined repository variables hold information about when data was last uploaded and processed into Birst. These are shown in the Admin - Process New Data tab.

  • LoadDate: The last time the data was loaded. For example, 08/29/2015.
  • LoadDateSFDC: The last data and time that Salesforce data was loaded. For example, 2015-08-29T00:00:00-05.00.
  • LoadNumber: The incremented load number, or load ID. For example, 3.
  • LoadStartTime: The start data and time of the last load into the space. For example, 2015-08-29T11:46:45-05:00.
  • LoadCompletionTime: The end data and time of the last load into the space. For example, 2015-08-29T11:46:45-05:00.

Variables in Packages

Packages for managed data mashups can include variables. See Managed Data Mashups.

Variables that are imported as part of a package appear grayed out and italicized on the Variables tab. You can use them in the child space, however you cannot modify them in the child space.

Referencing Variables

When referencing a variable in BQL, for example in a report expression or an ETL script, use the GETVARIABLE function:

GETVARIABLE('variable_name')

Example:

GETVARIABLE('LoadDate')

In non-BQL situations, such as when referencing a variable in a Birst Connect query, Query (opaque view) Live Access source, Salesforce SOQL query, application connector data source object queries, or in a report schedule, use the following syntax:

V{variable_name}

Example:

V{LAST_UPDATE_DATE}

Tip: When referencing DATE or DATETIME variables in queries for some application connectors, the entire call must be surrounded with single quotes. For example: 'V{LAST_UPDATE_DATE}'. When applicable, this is noted in the documentation for the connector.