Skip to main content

Query Federation

You'll create a foreign catalog to run pushdown queries against an external data source in ~10 min.

Prereqs: Create connection

What you'll build​

A foreign catalog in Unity Catalog that lets you query an external system (PostgreSQL, MySQL, Snowflake, etc.) directly from Databricks. Queries are pushed down to the source — no data is copied into Databricks.

Prerequisites​

  • A Unity Catalog connection to the target system (see Create connection).
  • The connected system must support pushdown queries via Lakehouse Federation.
tip

A foreign catalog is only needed if you want to run pushdown queries from Databricks. If your goal is to ingest data into UC tables, skip this page and go to Create ingestion pipeline instead.

Steps​

1. Create a foreign catalog​

Follow the official guide to create a foreign catalog from your connection:

Create a Foreign Catalog — Databricks docs

The foreign catalog maps to the external system's schema structure. Once created, you can query its tables using standard SQL from any Databricks notebook or SQL warehouse.

2. Video walkthrough (optional)​

Verify​

  1. In the Databricks workspace, navigate to Catalog.
  2. Confirm the foreign catalog appears in the catalog list.
  3. Expand it and run a SELECT query against one of its tables to confirm pushdown works.

Troubleshoot​

Foreign catalog creation fails

Verify the underlying connection is still active by testing it in External Data > Connections. The external system must be reachable and the connection credentials must be valid.

Query returns an error or no results

Pushdown queries run on the source system. If the source user does not have read access to the target schemas or tables, the query will fail. Check the permissions on the source system.

Next​