sqlframe

library4.3.0pypypiunverified

SQLFrame is a Python library that translates PySpark DataFrame API calls into SQL queries for multiple database engines (BigQuery, DuckDB, Postgres, Snowflake, Spark, etc.). Version 4.1.0 requires Python >=3.10 and uses sqlglot for SQL generation. Release cadence is approximately bi-weekly.

data database

pip install sqlframe

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SQLFRAME

sqlframe

datapythonv4.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 10

Env Coverage0 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

3/6 runs

5/6 runs

py 3.11

3/6 runs

5/6 runs

py 3.12

3/6 runs

5/6 runs

py 3.13

3/6 runs

5/6 runs

py 3.9

3/6 runs

5/6 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session

✓ from sqlframe import Session

✗ from sqlframe import Session

Quickstart using DuckDB engine (no external database needed). Set up a session, create a DataFrame, apply filters, and inspect generated SQL.

import os from sqlframe import Session # Create a session for DuckDB (no external DB needed) engine = "duckdb" os.environ["SQLFRAME_ENGINE"] = engine # optional session = Session.builder.config("extension", engine).getOrCreate() # Create a DataFrame from a list of tuples df = session.createDataFrame([(1, "Alice"), (2, "Bob")], schema=["id", "name"]) df.show() # Apply transformations df_filtered = df.filter(df.name == "Alice").select(df.id) print(df_filtered.sql()) # print generated SQL

Debug

Known issues

breakingIn version 4.0.0, the engine configuration changed. Previously you might have set an environment variable or used a different builder pattern. Now use Session.builder.config("extension", "engine_name").getOrCreate(). The old pattern with spark = SQLFrame(engine='duckdb') is removed.

fix

Upgrade to 4.0.0+ and use Session.builder.config("extension", "duckdb") (or other engine).

affects: <4.0.0

gotchaSQLFrame does not execute queries by default. Use .show() or .collect() to actually run the query against the engine. Calling .sql() only returns the generated SQL string.

fix

Use .show() to preview results, .collect() to get a list of Row objects, or .toPandas() to get a Pandas DataFrame.

affects: all

deprecatedThe old import path from sqlframe.sql import DataFrame is deprecated as of version 4.0.0. Use from sqlframe import DataFrame instead.

fix

Change imports to from sqlframe import DataFrame, Session, functions as F.

affects: >=4.0.0

gotchaWhen using multiple engines in the same project, you must create a separate Session for each engine. Sharing sessions across different engine types will lead to errors.

fix

Create one session per engine: session_duckdb = Session.builder.config("extension", "duckdb").getOrCreate() and session_bq = Session.builder.config("extension", "bigquery").getOrCreate().

affects: all

Upgrade

Version history

4.3.0latest on PyPI · released Jun 12, 2026

Audit

Dependencies

sqlglotrequiredSQL generation engine

duckdboptionalRequired for DuckDB engine

snowflake-connector-pythonoptionalRequired for Snowflake engine

psycopg2-binaryoptionalRequired for Postgres engine

google-cloud-bigqueryoptionalRequired for BigQuery engine

pysparkoptionalRequired for Spark engine