Configuring Global Environment Variables

AtScale admins can define global environment variables that can be used as values in SML files. Unlike repository-level environment variables, which only apply to the repository they're defined in, global-level environment variables apply to the entire environment.

Important

Environment variables defined at the repository level (i.e., those defined in .env files) override those defined at the global level.

You can use global environment variables to ensure your organization's models can be easily deployed across multiple environments. For example, if your organization uses different database and schema names in their development and production environments, you can set these values as global environment variables so that they stay consistent across both environments.

Note

Environment variables can only be used in connection and dataset files.

Define global environment variables

You define global environment variables in your global settings file, using the sml.environment.variables setting. Variables are defined using the following syntax:

VARIABLE=value

For example, to define a variable for a database connection label, you would add the following to your settings file:

object_type: global_settings
overrides:
  sml.environment.variables:
    LABEL=Postgres

Your global environment variables take effect once you apply your global settings file.

Reference global environment variables

Users can reference global environment variables in SML object files, using the syntax ${variable-name}.

To continue with our example, a model designer could add the following to a connection file. This would set the label property to Postgres.

label: ${LABEL}

Note

You cannot use environment variables in object_type or unique_name SML properties.

Environment variables can also be used to partially define properties. For example, if your database connection names all use the same base followed by numbers, you could define the base as an environment variable:

object_type: global_settings
overrides:
  sml.environment.variables:
    CONNECTION=db_con

And then use the variable in your connection files to partially define the connection name:

as_connection: ${CONNECTION}01

Examples

Connection example

The following is an example of a global settings file defining variables for a connection file:

object_type: global_settings
overrides:
  sml.environment.variables:
    CONNECTION=Postgres
    DB_NAME=atscale_tutorial_data
    DB_SCHEMA=as_adventure
    LABEL=Postgres

And below is a sample connection file using the variables defined above:

unique_name: Postgres
object_type: connection
as_connection: ${CONNECTION}
label: ${LABEL}
database: ${DB_NAME}
schema: ${DB_SCHEMA}

Dataset example

The following is an example of a global settings file defining variables for a dataset file:

object_type: global_settings
overrides:
  sml.environment.variables:
    DATABASE=connection1
    SCHEMA=schema1

And below is a sample from a dataset file, using the variables defined above in the dialects property:

dialects:
  - dialect: Postgresql
    sql: >-
      SELECT * FROM "${DATABASE}"."${SCHEMA}"."dataset"