Vizzly Query Engine
Environment variables

Environment variables

Connection variables


Set this environment variable value to "bigquery".


Set the Big Query project ID to use in the connection to your BigQuery database.


Set the region in which your BigQuery database is deployed in


The recommended approach to providing your BigQuery credentials. The value should be a JSON stringified and base 64 encoded string of your Google Cloud Service Account JSON object.


Optionally override the location of your key file. The default location is /etc/vizzly/bq/service-account.json.

The preferred option is to use the VIZZLY_BIGQUERY_CREDENTIALS variable, as this will avoid additionally needing to mount your credentials file onto the file system.

Cloud provider variables


Load secret environment variables from AWS Secrets Manager (opens in a new tab).

Provide the ID of the secret stored within the same region as the running Vizzly Query Engine, to load secret environment variables at runtime.

The secret should be in a JSON-formatted string, for example, a secret storing a postgres database password will be;


Be certain that the container has permission to fetch the secret from AWS Secrets Manager.

Static Vizzly Configs


To load your config directly from GitHub, use this environment variable to provide the GitHub repository.

For example; my-organisation/my-repo


To load your config directly from GitHub, use this environment variable to provide the path to the vizzly.config.json file in the repository.

For example; folder/subfolder/vizzly-config.json


To load your Vizzly config file directly from GitHub, use this environment variable to authenticate the request for the vizzly.config.json file.

You will need to generate this token value on GitHub.


The default port the query engine runs on is port 8000. You can change this using the PORT environment variable.


This changes the base path of the Vizzly query engine. For example, you might have a routing layer that matches requests for /vizzly-query-engine/*, and forwards them to the query engine. In which case, you'd set this value to /vizzly-query-engine so the requests match the path matchers in the query engine.

If you need to support dynamic base paths, this is supported by using path matchers and indexes starting at 1. For example, a base path of;


will match requests sent to all of the following;


This environment variable is not required and defaults to ''.


Change the log level from the default warning level. Valid logging levels are "debug", "info", "warning" and "error".


Set the minimum connection pool size. The value must be an integer.


Set the minimum connection pool size. The value must be an integer.


Provide your Vizzly public key through an environment variable, rather than the publicKeyCertificates field of the Vizzly config.

The value should be formatted as a JSON array. For example, if you had the following public key;

-----END PUBLIC KEY-----

then it would be exported in this format as an environment variable.

export VIZZLY_PUBLIC_KEYS='["-----BEGIN PUBLIC KEY-----\r\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEQJqQ1P+MyW4E/32pXvkxQiOVT0IW\r\n1CwdEzN2D5+KtIK1qyUpMFiH2oBc8BIo8w3AvID0cOrD5+KEKXSIbw9Nig==\r\n-----END PUBLIC KEY-----\r\n"]'

The Vizzly CLI command vizzly format-public-pem-for-env will convert your public PEM file into the format required for the VIZZLY_PUBLIC_KEYS environment variable.


Changes the path at which the config file resides inside the running container.

This environment variable is not required, and defaults to /etc/vizzly/vizzly.config.json.


In seconds, how long should we serve a stale result before removing it from the cache?


In seconds, how long should we serve a result from the cache before considering it stale?


How many results should we store in the cache?


In seconds, how long should we store a config in the cache, before considering it stale?


In seconds, how long should we use a stale config before removing it from the cache?


Hash to verify an API key used for the Vizzly Query Engine.

To generate this value along with the API key, run the command vizzly dynamic-api-key.


Limit the max cache item size of results. This number is calculated by multiplying number of rows, by number of fields in each row.


API Key used to access resources for a Vizzly project. This value is created on the projects page on the Vizzly app, and will only be shown to you once when generated!

This value should be stored securely.


Encryption key to enable various Query Engine features such as direct sign-in and storing the config on the Vizzly API. This can be generated using the vizzly encryption-secret CLI command.

This value should be unique per project, and stored securely.


This is your Vizzly Project ID! It can be found on your project settings page on the Vizzly app (opens in a new tab), and begins with prj_.


Disable the sign-in feature by setting this value to DISABLED.

This will block all sign-in requests through the CLI and username/password combinations to sign in to the query engine, even if they are valid.


Control the Access-Control-Allow-Origin response header by providing a comma-separated list of origins to allow.

By default, the value is "*".


Use this environment variable to disable the dashboard encryption feature.

By default, encryption is enabled. To disable it, set the value to DISABLED


Set an absolute URL where we can load Dynamic Query Engine configs from.

To learn more about its usage, follow the documentation for remote configs.