1. Cloud
  2. Guides
  3. Tours
  4. Concepts
    1. Aggregate filter
    2. Alias
    3. Apache Avro™
    4. Apache Kafka™
    5. Applied filter
    6. Base table
    7. Bookmark
    8. Business schema
    9. Business schema view
    10. Business schema view column
    11. Business schema view formula column
    12. Column
    13. Connector
    14. Dashboard filter
    15. Dashboard folder
    16. Dashboard runtime filter
    17. Data agent
    18. Data alert
    19. Data destination
    20. Date system variable
    21. Distinct filter
    22. Dynamic Field
    23. Expression
    24. External data source
    25. External session variable
    26. Filter expression
    27. Filter expression session variable
    28. Filter option
    29. Formula column
    30. Formula expression
    31. Full load
    32. Global variable
    33. Incorta Analyzer Table
    34. Incorta Analyzer Table column
    35. Incorta Analyzer Table formula column
    36. Incorta Analyzer View
    37. Incorta Analyzer View formula column
    38. Incorta SQL Table
    39. Incorta SQL View
    40. Individual filter
    41. Insight filter
    42. Internal query expression
    43. Internal session variable
    44. Join
    45. Join condition
    46. Join condition column
    47. Join filter
    48. Join filter column
    49. Level based measure
    50. Load filter
    51. Local data file
    52. Local data folder
    53. Materialized View
    54. Materialized View Column
    55. Materialized View Formula Column
    56. Measure filter
    57. Miscellaneous system variable
    58. Multi-Source table
    59. Physical schema
    60. Physical schema table
    61. Physical schema table column
    62. Physical schema table formula column
    63. Physical schema table runtime security filter
    64. Presentation variable
    65. Prompt
    66. Query system variable
    67. Runtime business view
    68. Runtime business view formula column
    69. Runtime security filter
    70. Session variable
    71. Shared Storage
    72. Upgrade Readiness
    73. Variable
    74. Visualization
  5. Tools
  6. References
  7. Integrations
  8. Data applications
  9. Releases

Concepts → External Session Variable

About an external session variable

An external session variable is a tenant object that defines a SELECT command for an SQL statement to an external data source. “External” describes a reference to the external data sources defined 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 external 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 SELECT query for the external data source, and then assigns the query result as the variable value for the given user's session. From the results of the SELECT query, the value can be a scalar value of type string or an array of values of the type string. The value for an external session variable is mutable.

You can use the Schema Manager to create and test an external session variable. You can reference an external session variable in specific expression contexts such as a formula expression or filter expression. You can also assign access rights to an external session variable.

Note

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

The Name of an external 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 external session variable

The following are the properties of an external session variable:

PropertyControlDescription
Nametext boxEnter the name of the external session variable
Descriptiontext boxOptional description of the external session variable.
Data Sourcedrop down listSelect the data source to query data for use in the external session variable.
Querytext boxConstruct the query to request data from a data source. Query result will be the external session variable value.

Example of the Query property for an external session variable

In the following example, the WHERE clause references the $user miscellaneous system variable.

SELECT ID FROM USER WHERE LOGINNAME = $user

Even though ID is of the type INT in the above example, the external session variable stores the scalar value as string or as an array of scalar values as strings.

Access rights for an external 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 external 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 external session variable:

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

Test an external session variable

If you have edit access rights to an external session variable and belong to a group with the necessary role access permission such as Schema Manager or SuperRole, 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 the permissions are configured properly or the output of the variable is dependent on the selected user.

Note

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

Steps to test an external session variable

Here are the steps to test an external 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 external session variable.
  • In the External 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 external session variable

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

Conversion

Regardless of the source data type, an external session variable stores a scalar value as a string or an array of scalar values as strings. When you use an external 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 external 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 external session variables in production while not in the maintenance window. When a user invokes the external session variable again, the Analytics Services creates a new instance of the variable for this user.

Owner of a 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 external session variable, the value of the variable is defined by the user session of the scheduled job.