Skip to main content
Snowflake is a popular cloud-based data platform.

​
Prerequisites

In order to connect Cube to Snowflake, you need to grant certain permissions to the Snowflake role used by Cube. Cube requires the role to have USAGE on databases and schemas and SELECT on tables. An example configuration:
GRANT USAGE ON DATABASE ABC TO ROLE XYZ;
GRANT USAGE ON ALL SCHEMAS IN DATABASE ABC TO ROLE XYZ;
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE ABC TO ROLE XYZ;
GRANT SELECT ON ALL TABLES IN DATABASE ABC TO ROLE XYZ;
GRANT SELECT ON FUTURE TABLES IN DATABASE ABC TO ROLE XYZ;
  • Account/Server URL for Snowflake.
  • User name and password or an RSA private key for the Snowflake account. In Cube Cloud, you can authenticate with OIDC workload identity instead — the same role grants apply to the mapped service user.
  • Optionally, the warehouse name, the user role, and the database name.

​
Setup

If you’re having Network error and Snowflake can’t be reached please make sure you tried format 2 for an account id.

​
Manual

Add the following to a .env file in your Cube project: 
CUBEJS_DB_TYPE=snowflake
CUBEJS_DB_SNOWFLAKE_ACCOUNT=XXXXXXXXX.us-east-1
CUBEJS_DB_SNOWFLAKE_WAREHOUSE=MY_SNOWFLAKE_WAREHOUSE
CUBEJS_DB_NAME=my_snowflake_database
CUBEJS_DB_USER=snowflake_user
CUBEJS_DB_PASS=**********

​
Cube Cloud

In some cases you’ll need to allow connections from your Cube Cloud deployment IP address to your database. You can copy the IP address from either the Database Setup step in deployment creation, or from Settings → Configuration in your deployment.
The following fields are required when creating a Snowflake connection:
Cube Cloud Snowflake Configuration Screen

​
OIDC workload identity

Instead of a password or key pair, Cube Cloud deployments can authenticate to Snowflake with OIDC workload identity: a Snowflake External OAuth integration trusts Cube’s OIDC issuer, and the driver presents a short-lived Cube-minted JWT — no long-lived secrets to provision or rotate. Snowflake validates each connection’s token against your tenant’s public JWKS, maps the token’s sub claim to a Snowflake user, and authorizes the session role through the token’s scp claim. Start with the OIDC overview for the concepts (issuer, token configs, custom claims, target env var) and to enable OIDC for your tenant, then:
1

Create the token config

In Admin → OIDC, click Add Config and create a config with:
FieldValue
Audience TypeCustom
Namesnowflake
Custom Audiencehttps://<account-identifier>.snowflakecomputing.com
Subject Claim FormatKeep the default, or pick a richer template — the rendered sub must match the Snowflake user’s LOGIN_NAME below
Custom ClaimsClaim scp with value session:role-any
Target Env VarCUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH
Edit OIDC Token Config dialog in Cube Cloud for Snowflake: Custom audience type, the Snowflake account URL as the custom audience, a Target Env Var of CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH, and a custom claim scp set to session:role-any.
The scp claim is the part that’s easy to miss: Snowflake grants session roles exclusively through it — a token without scp authenticates but fails role authorization. session:role-any lets the driver request any role granted to the mapped user; to pin the role inside the token instead, use session:role:<role-name> and EXTERNAL_OAUTH_ANY_ROLE_MODE = 'DISABLE' below. The Target Env Var is how the driver finds the token: Cube sets that env var to the token file path in every execution context (deployed pods, dev mode, and test connection each keep the file in a different place), so the path is never written by hand.
2

Create the External OAuth security integration

In a Snowflake worksheet, as ACCOUNTADMIN:
CREATE SECURITY INTEGRATION CUBE_CLOUD_EXTERNAL_OAUTH
  TYPE = EXTERNAL_OAUTH
  ENABLED = TRUE
  EXTERNAL_OAUTH_TYPE = CUSTOM
  EXTERNAL_OAUTH_ISSUER = 'https://<tenant-name>.cubecloud.dev'
  EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://<tenant-name>.cubecloud.dev/.well-known/jwks.json'
  EXTERNAL_OAUTH_AUDIENCE_LIST = ('https://<account-identifier>.snowflakecomputing.com')
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'LOGIN_NAME'
  EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';
The issuer and audience must match the token config exactly. Snowflake fetches the JWKS from your tenant’s public endpoint, so no key material changes hands.
3

Create the service user and role

The integration maps the token’s sub claim to a Snowflake user via LOGIN_NAME. With the default subject claim format the rendered sub is cube:deployment:<deployment-id> — the deployment ID is the number in your deployment’s console URL. If you chose a different template, use the token-config dialog’s live preview to see the exact rendered value.
CREATE ROLE CUBE_ROLE;

CREATE USER CUBE_SVC
  TYPE = SERVICE
  LOGIN_NAME = 'cube:deployment:<deployment-id>'
  DEFAULT_ROLE = CUBE_ROLE
  DEFAULT_WAREHOUSE = <warehouse>;

GRANT ROLE CUBE_ROLE TO USER CUBE_SVC;
GRANT USAGE ON WAREHOUSE <warehouse> TO ROLE CUBE_ROLE;

-- Grant the role read access to the data Cube serves, e.g.:
GRANT USAGE ON DATABASE <database> TO ROLE CUBE_ROLE;
GRANT USAGE ON ALL SCHEMAS IN DATABASE <database> TO ROLE CUBE_ROLE;
GRANT SELECT ON ALL TABLES IN DATABASE <database> TO ROLE CUBE_ROLE;
TYPE = SERVICE blocks password logins for this user entirely — it can only authenticate through the federation.
4

Configure the deployment

Set the OAUTH authenticator and omit CUBEJS_DB_USER / CUBEJS_DB_PASS:
CUBEJS_DB_TYPE=snowflake
CUBEJS_DB_SNOWFLAKE_ACCOUNT=<account-identifier>
CUBEJS_DB_SNOWFLAKE_WAREHOUSE=<warehouse>
CUBEJS_DB_NAME=<database>
CUBEJS_DB_SNOWFLAKE_ROLE=CUBE_ROLE
CUBEJS_DB_SNOWFLAKE_AUTHENTICATOR=OAUTH
CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH is not set here — Cube populates it automatically thanks to the Target Env Var from the token config. The driver re-reads the file on every new connection, so the broker’s automatic refresh is picked up without restarts.
To verify, run any query against the Snowflake data source. On the Snowflake side, a successful federation shows up in the login history with OAUTH_ACCESS_TOKEN as the authentication factor: 
SELECT event_timestamp, user_name, first_authentication_factor, is_success
FROM TABLE(SNOWFLAKE.INFORMATION_SCHEMA.LOGIN_HISTORY_BY_USER(USER_NAME => 'CUBE_SVC'))
ORDER BY event_timestamp DESC;
Common failure modes:
ErrorCause
Invalid OAuth access tokenIssuer or audience mismatch between the token config and the security integration, or the JWKS URL is unreachable.
The role … is not listed in the Access Token or was filteredThe scp custom claim is missing from the token config, or the role isn’t granted to the mapped user.
User … not found / mapping errorsThe rendered sub doesn’t match the Snowflake user’s LOGIN_NAME — compare against the dialog’s live preview.
File … provided by CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH does not existThe Target Env Var isn’t set on the token config (or a stale hand-written path is configured), or the deployment is still starting up.
Cube Cloud also supports connecting to data sources within private VPCs if single-tenant infrastructure is used. Check out the VPC connectivity guide for details.

​
Environment Variables

Environment VariableDescriptionPossible ValuesRequired
CUBEJS_DB_SNOWFLAKE_ACCOUNTThe Snowflake account identifier to use when connecting to the databaseA valid Snowflake account ID✅
CUBEJS_DB_SNOWFLAKE_REGIONThe Snowflake region to use when connecting to the databaseA valid Snowflake region❌
CUBEJS_DB_SNOWFLAKE_WAREHOUSEThe Snowflake warehouse to use when connecting to the databaseA valid Snowflake warehouse in the account✅
CUBEJS_DB_SNOWFLAKE_ROLEThe Snowflake role to use when connecting to the databaseA valid Snowflake role in the account❌
CUBEJS_DB_SNOWFLAKE_CLIENT_SESSION_KEEP_ALIVEIf true, keep the Snowflake connection alive indefinitelytrue, false❌
CUBEJS_DB_NAMEThe name of the database to connect toA valid database name✅
CUBEJS_DB_USERThe username used to connect to the databaseA valid database username✅1
CUBEJS_DB_PASSThe password used to connect to the databaseA valid database password✅1
CUBEJS_DB_SNOWFLAKE_AUTHENTICATORThe type of authenticator to use with Snowflake. Use SNOWFLAKE with username/password, or SNOWFLAKE_JWT with key pairs. Defaults to SNOWFLAKESNOWFLAKE, SNOWFLAKE_JWT, OAUTH❌
CUBEJS_DB_SNOWFLAKE_PRIVATE_KEYThe content of the private RSA keyContent of the private RSA key (encrypted or not)❌
CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PATHThe path to the private RSA keyA valid path to the private RSA key❌
CUBEJS_DB_SNOWFLAKE_PRIVATE_KEY_PASSThe password for the private RSA key. Only required for encrypted keysA valid password for the encrypted private RSA key❌
CUBEJS_DB_SNOWFLAKE_OAUTH_TOKENThe OAuth tokenA valid OAuth token (string)❌
CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATHThe path to the valid oauth toket fileA valid path for the oauth token file❌
CUBEJS_DB_SNOWFLAKE_HOSTHost address to which the driver should connectA valid hostname❌
CUBEJS_DB_SNOWFLAKE_QUOTED_IDENTIFIERS_IGNORE_CASEWhether or not quoted identifiers should be case insensitive. Default is falsetrue, false❌
CUBEJS_DB_MAX_POOLThe maximum number of concurrent database connections to pool. Default is 20A valid number❌
CUBEJS_CONCURRENCYThe number of concurrent queries to the data sourceA valid number❌
1 Required when using password-based authentication. Not required with SNOWFLAKE_JWT (key pair) or with OAUTH — including OIDC workload identity in Cube Cloud, where the driver reads a Cube-minted token from CUBEJS_DB_SNOWFLAKE_OAUTH_TOKEN_PATH.

​
Pre-Aggregation Feature Support

​
count_distinct_approx

Measures of type count_distinct_approx can be used in pre-aggregations when using Snowflake as a source database. To learn more about Snowflake’s support for approximate aggregate functions, click here.

​
Pre-Aggregation Build Strategies

To learn more about pre-aggregation build strategies, head here.
FeatureWorks with read-only mode?Is default?
Batching❌✅
Export Bucket❌❌
By default, Snowflake uses batching to build pre-aggregations.

​
Batching

No extra configuration is required to configure batching for Snowflake.

​
Export Bucket

Snowflake supports using both AWS S3 and Google Cloud Storage for export bucket functionality.

​
AWS S3

Ensure proper IAM privileges are configured for S3 bucket reads and writes, using either storage integration or user credentials for Snowflake and either IAM roles/IRSA or user credentials for Cube Store, with mixed configurations supported.
Using IAM user credentials for both: 
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
Using a Storage Integration to write to export buckets and user credentials to read from Cube Store: 
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_INTEGRATION=aws_int
CUBEJS_DB_EXPORT_BUCKET_AWS_KEY=<AWS_KEY>
CUBEJS_DB_EXPORT_BUCKET_AWS_SECRET=<AWS_SECRET>
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>
Using a Storage Integration to write to export bucket and IAM role/IRSA to read from Cube Store:** 
CUBEJS_DB_EXPORT_BUCKET_TYPE=s3
CUBEJS_DB_EXPORT_BUCKET=my.bucket.on.s3
CUBEJS_DB_EXPORT_INTEGRATION=aws_int
CUBEJS_DB_EXPORT_BUCKET_AWS_REGION=<AWS_REGION>

​
Google Cloud Storage

When using an export bucket, remember to assign the Storage Object Admin role to your Google Cloud credentials (CUBEJS_DB_EXPORT_GCS_CREDENTIALS).
Before configuring Cube, an integration must be created and configured in Snowflake. Take note of the integration name (gcs_int from the example link) as you’ll need it to configure Cube. Once the Snowflake integration is set up, configure Cube using the following: 
CUBEJS_DB_EXPORT_BUCKET=snowflake-export-bucket
CUBEJS_DB_EXPORT_BUCKET_TYPE=gcs
CUBEJS_DB_EXPORT_GCS_CREDENTIALS=<BASE64_ENCODED_SERVICE_CREDENTIALS_JSON>
CUBEJS_DB_EXPORT_INTEGRATION=gcs_int

​
Azure

To use Azure Blob Storage as an export bucket, follow the guide on using a Snowflake storage integration (Option 1). Take note of the integration name (azure_int from the example link) as you’ll need it to configure Cube. Retrieve the storage account access key from your Azure account. Once the Snowflake integration is set up, configure Cube using the following: 
CUBEJS_DB_EXPORT_BUCKET_TYPE=azure
CUBEJS_DB_EXPORT_BUCKET=wasbs://my-container@my-storage-account.blob.core.windows.net
CUBEJS_DB_EXPORT_BUCKET_AZURE_KEY=<AZURE_STORAGE_ACCOUNT_ACCESS_KEY>
CUBEJS_DB_EXPORT_INTEGRATION=azure_int

​
SSL

Cube does not require any additional configuration to enable SSL as Snowflake connections are made over HTTPS.