Concepts → Internal Session Variable

About an internal session variable

An internal session variable is a tenant object that defines an internal query expression. An internal query expression typically queries a physical schema table or runtime business view. “Internal” refers to the physical schemas and business schemas within a given tenant.

When a user signs in to the Analytics Service, the Analytics Service, as a web application — creates a session (HTTPsession in Apache Tomcat) for the user. A session maintains state information between requests for a particular user of a web application.

The first time a user invokes an internal session variable, usually by means of a calling expression such as a formula expression, the Analytics Services creates an instance of the variable for the user, executes the internal query expression, and then assigns the query result as the variable value for the given user's session. The value can be a scalar value of type string or an array of values of the type string. Throughout the duration of the user's session, the variable value exists solely in the scope of this user's session and this value is immutable.

You can use the Schema Manager to create and test an internal session variable. Using the Formula Builder, a schema developer or a similar user can define an internal query expression.

You can reference an internal session variable in specific expression contexts such as a formula expression. You can also assign access rights to an internal session variable.

Note

Starting with 2023.7.0, you can use the Schema Manager to view the data lineage of internal session variables that you own or have access rights to. You can track entities referenced in an internal session variable, that is, its source or upstream lineage and entities that reference the internal session variable, that is, downstream lineage. For more details, refer to Tools → Data Lineage Viewer.

The Name of an internal session variable:

  • must be between 1 and 250 characters in length
  • must begin with an alpha character (lower or upper case) or an underscore (_)
  • after the first character, can contain zero or more alphanumeric characters in lower, upper, or mixed case
  • besides underscores (_), cannot contain special characters, symbols, or spaces
  • must be unique
  • is case-sensitive

Properties of an internal session variable

Here are the properties of an internal session variable.

PropertyControlDescription
Nametext boxEnter the name of the internal session variable
Descriptiontext boxOptional description of the internal session variable.
QueryFormula BuilderConstruct an internal query expression using the Formula Builder. The internal query expression result is the value of the internal session variable.

Example of the Query property for an internal session variable

Here is an example of an internal session variable that queries the value of the $yearAgo date system variable.

query(
formatDate(
if(
mod(year($yearAgo),4) = 0,
addDays($yearAgo,-366),
addDays($yearAgo,-365)
),
"yyyy-MM-dd"
)
)

In this example, the internal session variable stores the date as a string. Even though the formatDate() built-in function returns a scalar date, the internal session variable always store the value as a string.

Access rights for an internal session variable

A Super User (tenant administrator) or a user that belongs to a group assigned the SuperRole or the Schema Manager role can create, view, and edit the internal session variables in a given tenant.

Note: Super User and SuperRole access rights
  • When the Cluster Management Console (CMC) admin turns the Enable Super User Mode option on, the Super User and users with the SuperRole can manage all session variables regardless of the access rights.

  • Only the Super User tenant administrator can view all session variables regardless of the access rights and the Enable Super User mode option.

The following are the available access rights for an internal session variable:

PropertyIconDescription
Can VieweyeThe user can view the internal session variable, for example, in the Formula Builder.
Can Sharenode treeThe user can view and share the internal session variable with other users.
Can Editpen and paperThe user can view, edit, delete, and share the internal session variable.

Test an internal session variable

If you have edit access rights to an internal session variable and belong to a group with the Schema Manager role, you can test the variable as follows:

Test As: By default, this tests how the variable will display information for the current user. You can also select a different user to test the variable’s result. This is useful when testing if permissions are configured properly or the output of the variable is dependent on the selected user.

Note

The result of a test on an internal session variable is independent of the current user’s session. As such, if the internal query expression’s source schema is updated during your session, the test result will reflect the change. However, your session’s captured value of the internal session variable will not express this update. You must sign out and start a new session to have your internal session variable value updated.

Steps to test an internal session variable

Here are the steps to test an internal session variable:

  • Sign in to the Incorta Direct Data Platform.
  • In the Navigation bar, select Schema.
  • In the Schema Manager, select the Session Variables tab.
  • In the list view, select an internal session variable.
  • In the Internal Variable dialog, select Test As to view the results for the current user, or you can select another user to view the results as that user, and then select Test As.
  • Select Cancel.

Additional considerations for an internal session variable

Here are some additional considerations for working with an internal session variable:

Conversion

Regardless of the source data type, an internal session variable stores a scalar value as a string or an array of scalar values as strings. When you use an internal session variable in a formula expression or filter expression, you may need to convert the string value to another data type using a built-in conversion function.

Modifications

If the owner or a user that belongs to a group with Edit access rights to an internal session variable alters the query expression for the variable object and saves the modifications, the Analytics Service deletes the session variable for all other active users. For this reason, schema developers should be wary of altering internal session variables in production while not in the maintenance window. When a user invokes the internal session variable again, the Analytics Services creates a new instance of the variable for this user.

Owner of scheduled job

The owner of a scheduled job for a dashboard's email delivery defines the user session for the emailed dashboard. If the dashboard or dashboard insights contain references to an internal session variable, the value of the internal session variable is defined by the user session of the scheduled job.