Run federated queries on Snowflake (PEM private key)

This page describes how to set up Lakehouse Federation to run federated queries on Snowflake data that is not managed by Databricks. To learn more about Lakehouse Federation, see What is Lakehouse Federation?

To connect to your Snowflake database using Lakehouse Federation, you must create the following in your Databricks Unity Catalog metastore:

A connection to your Snowflake database.
A foreign catalog that mirrors your Snowflake database in Unity Catalog so that you can use Unity Catalog query syntax and data governance tools to manage Databricks user access to the database.

This page covers connecting to Snowflake using a PEM private key. For other authentication methods, see the following pages:

Before you begin

Workspace requirements:

Workspace enabled for Unity Catalog.

Compute requirements:

Network connectivity from your compute resource to the target database systems. See Networking recommendations for Lakehouse Federation.
Databricks compute must use Databricks Runtime 13.3 LTS or above and Standard or Dedicated access mode.
SQL warehouses must be pro or serverless and must use 2023.40 or above.

Permissions required:

To create a connection, you must be a metastore admin or a user with the CREATE CONNECTION privilege on the Unity Catalog metastore attached to the workspace.
To create a foreign catalog, you must have the CREATE CATALOG permission on the metastore and be either the owner of the connection or have the CREATE FOREIGN CATALOG privilege on the connection.

Additional permission requirements are specified in each task-based section that follows.

Create a connection

A connection specifies a path and credentials for accessing an external database system. To create a connection, you can use Catalog Explorer or the CREATE CONNECTION SQL command in a Databricks notebook or the Databricks SQL query editor.

note

You can also use the Databricks REST API or the Databricks CLI to create a connection. See POST /api/2.1/unity-catalog/connections and Unity Catalog commands.

Permissions required: Metastore admin or user with the CREATE CONNECTION privilege.

Catalog Explorer
SQL

In your Databricks workspace, click Catalog.
At the top of the Catalog pane, click the Add icon and select Add a connection from the menu.

Alternatively, from the Quick access page, click the External data > button, go to the Connections tab, and click Create connection.
On the Connection basics page of the Set up connection wizard, enter a user-friendly Connection name.
Select a Connection type of Snowflake.
For Auth type, PEM Private Key from the drop-down menu.
(Optional) Add a comment.
Click Next.
Enter the following authentication and connection details for your Snowflake warehouse.
- Host: For example, snowflake-demo.east-us-2.azure.snowflakecomputing.com
- Port: For example, 443
- User: For example, snowflake-user
- PEM private key: Private key from RSA key par in HEX64 format.
- Expires in secs: The expiration time (in seconds) for the connection made with a private key.
Click Next.
On the Connection details page, specify the following:
- Snowflake warehouse: For example, my-snowflake-warehouse
- (Optional) Proxy host: Host of the proxy used to connect to Snowflake. You must also select Use proxy and specify Proxy port.
- (Optional) Use proxy: Whether to connect to Snowflake using a proxy server.
- (Optional) Proxy port: Port of the proxy used to connect to Snowflake. You must also select Use proxy and specify Proxy host.
- (Optional) Snowflake role: The default security role to use for the session after connecting.
Click Next.
On the Catalog basics page, enter a name for the foreign catalog. A foreign catalog mirrors a database in an external data system so that you can query and manage access to data in that database using Databricks and Unity Catalog.
(Optional) Click Test connection to confirm that it works.
Click Create catalog.
On the Access page, select the workspaces in which users can access the catalog you created. You can select All workspaces have access, or click Assign to workspaces, select the workspaces, and then click Assign.
Change the Owner who will be able to manage access to all objects in the catalog. Start typing a principal in the text box, and then click the principal in the returned results.
Grant Privileges on the catalog. Click Grant:
1. Specify the Principals who will have access to objects in the catalog. Start typing a principal in the text box, and then click the principal in the returned results.
2. Select the Privilege presets to grant to each principal. All account users are granted BROWSE by default.
  - Select Data Reader from the drop-down menu to grant read privileges on objects in the catalog.
  - Select Data Editor from the drop-down menu to grant read and modify privileges on objects in the catalog.
  - Manually select the privileges to grant.
3. Click Grant.
Click Next.
On the Metadata page, specify tags key-value pairs. For more information, see Apply tags to Unity Catalog securable objects.
(Optional) Add a comment.
Click Save.

Run the following command in a notebook or the Databricks SQL query editor.

SQL
CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user '<user>',
  password '<password>'
);

We recommend that you use Databricks secrets instead of plaintext strings for sensitive values like credentials. For example:

SQL
CREATE CONNECTION <connection-name> TYPE snowflake
OPTIONS (
  host '<hostname>',
  port '<port>',
  sfWarehouse '<warehouse-name>',
  user secret ('<secret-scope>','<secret-key-user>'),
  password secret ('<secret-scope>','<secret-key-password>')
)

For information about setting up secrets, see Secret management.

Case-sensitive database identifiers

The database field of the foreign catalog maps to a Snowflake database identifier. If the Snowflake database identifier is not case-sensitive, the casing you use in the foreign catalog <database-name> is preserved. However, if the Snowflake database identifier is case-sensitive, you must wrap the foreign catalog <database-name> in double quotes to preserve the case.

For example:

database is converted to DATABASE
"database" is converted to database
"database""" is converted to database"

To escape a double quote, use another double quote.
"database"" results in an error because the double quote is not escaped correctly.

For more information, see Identifier requirements in the Snowflake documentation.

Supported pushdowns

The following pushdowns are supported:

Filters
Projections
Limit
Joins
Aggregates (Average, Corr, CovPopulation, CovSample, Count, Max, Min, StddevPop, StddevSamp, Sum, VariancePop, VarianceSamp)
Functions (String functions, Mathematical functions, Data, Time and Timestamp functions, and other miscellaneous functions, such as Alias, Cast, SortOrder)
Windows functions (DenseRank, Rank, RowNumber)
Sorting

Data type mappings

When you read from Snowflake to Spark, data types map as follows:

Snowflake type	Spark type
decimal, number, numeric	DecimalType
bigint, byteint, int, integer, smallint, tinyint	IntegerType
float, float4, float8	FloatType
double, double precision, real	DoubleType
char, character, string, text, time, varchar	StringType
binary	BinaryType
boolean	BooleanType
date	DateType
datetime, timestamp, timestamp_ltz, timestamp_ntz, timestamp_tz	TimestampType

Limitations

The Snowflake JDBC driver does not support authentication with encrypted private keys. To avoid errors, generate a key with -nocrypt option added, as follows:
```
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out rsa_key.p8 -nocrypt
```

Additional resources

Snowflake: Key-pair authentication and key-pair rotation in the Snowflake documentation

Before you begin​

Create a connection​

Case-sensitive database identifiers​

Supported pushdowns​

Data type mappings​

Limitations​

Additional resources​