Registry / database / databricks-labs-lsql

databricks-labs-lsql

JSON →
library0.17.0pypypi✓ verified 25d ago

Databricks-labs-lsql is a Python library that provides lightweight, stateless SQL execution capabilities for Databricks, built on top of the Databricks SDK. It's designed for serverless or containerized short-lived applications where minimal dependencies and faster startup times are critical, fetching results in JSON format through presigned external links. The current version is 0.17.0, and it appears to have an active release cadence with regular updates.

pip install databricks-labs-lsql
INSTALL
IMPORT
SIG · DATABRICKS-LABS-LS
D
databricks-labs-lsql
databasepythonv0.17.0
Install
5.6s avg
Import
5619ms
Disk
67MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.17.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
✓ —
✓ 5.9s
py 3.11
✓ —
✓ 5.5s
py 3.12
✓ —
✓ 5.5s
py 3.13
✓ —
✓ 5.7s
py 3.9
✕ build_error
✕ build_error
67MB installed
● package 67MB
Code
Verified usage

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

StatementExecutionExt
from databricks.labs.lsql.core import StatementExecutionExt
escape_name
from databricks.labs.lsql.escapes import escape_name
Introduced in v0.13.0 for SQL identifier escaping.
escape_full_name
from databricks.labs.lsql.escapes import escape_full_name
Introduced in v0.13.0 for SQL fully qualified identifier escaping.

This quickstart demonstrates how to initialize the `StatementExecutionExt` client using the `databricks-sdk` `WorkspaceClient` and execute SQL queries. It shows how to fetch results by iterating over them and how to execute DDL/DML statements. Authentication relies on environment variables (`DATABRICKS_HOST`, `DATABRICKS_TOKEN`) for the `WorkspaceClient`.

import os from databricks.sdk import WorkspaceClient from databricks.labs.lsql.core import StatementExecutionExt # Ensure DATABRICKS_HOST and DATABRICKS_TOKEN environment variables are set # For local testing, you might need to export them (e.g., in bash:) # export DATABRICKS_HOST="https://<your-databricks-workspace-url>" # export DATABRICKS_TOKEN="<your-personal-access-token>" w = WorkspaceClient() # The warehouse_id can be optional if implicitly configured or running within DBR see = StatementExecutionExt(w, warehouse_id=os.environ.get("TEST_DEFAULT_WAREHOUSE_ID", "")) # Execute a query and iterate over results print("Fetching results:") for pickup_zip, dropoff_zip in see.fetch_all("SELECT pickup_zip, dropoff_zip FROM samples.nyctaxi.trips LIMIT 5"): print(f' pickup_zip={pickup_zip}, dropoff_zip={dropoff_zip}') # Execute a DDL/DML statement (e.g., create a temporary view) print("\nExecuting a DDL statement:") see.execute("CREATE OR REPLACE TEMPORARY VIEW my_temp_view AS SELECT 'hello' as greeting, 1 as number") # Fetch from the temporary view print("\nFetching from temporary view:") for greeting, number in see.fetch_all("SELECT greeting, number FROM my_temp_view"): print(f" greeting='{greeting}', number={number}")
Debug
Known issues
breakingResource name validation was introduced and refined in versions v0.15.0, v0.15.1, and v0.16.0. Resource names are now restricted to alphanumeric characters, hyphens, and underscores. Older code generating resource names with other special characters may break.
fix
Ensure all generated resource names adhere to the new validation rules (alphanumeric, hyphens, underscores). Review and update resource naming conventions in your application.
affects: >=0.15.0
gotchaThe `databricks-labs-lsql` library is explicitly designed for lightweight, stateless SQL execution via REST APIs, best suited for serverless functions or short-lived applications. For traditional SQL Python APIs, cursors, efficient large data transfers (Apache Arrow), and low latency, use the `Databricks SQL Connector for Python` instead.
fix
Choose the appropriate Databricks SQL client based on your application's requirements: `lsql` for stateless, REST-driven, short-lived tasks; `databricks-sql-connector` for stateful, high-throughput, traditional SQL workloads.
affects: all
deprecatedThe downstream `ucx` check was disabled in v0.17.0 due to compatibility issues with the latest Databricks SDK. While this resolves immediate failures, users relying on these checks should be aware they are no longer active.
fix
Review your application's reliance on `ucx` checks. If critical, consider implementing custom validation logic or monitoring for potential issues that the disabled check previously covered.
affects: >=0.17.0
breakingSQL name escaping functions (`escape_name`, `escape_full_name`) were added in v0.13.0. If your application dynamically constructs SQL queries with identifiers that might contain special characters, older versions of the library would not have provided built-in escaping, potentially leading to SQL injection vulnerabilities or syntax errors.
fix
Upgrade to v0.13.0 or later and utilize the `escape_name` and `escape_full_name` functions from `databricks.labs.lsql.escapes` to properly escape SQL identifiers, especially when dealing with user-generated or dynamic names.
affects: <0.13.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'databricks_labs'
This error occurs when the `databricks-labs-lsql` package, or its parent `databricks-labs` namespace package, is not installed or is not accessible in the Python environment.
fix
Ensure the library is installed using pip: `pip install databricks-labs-lsql`
ValueError: default auth: cannot configure default credentials
This error indicates that the Databricks SDK, which `databricks-labs-lsql` relies on, could not find valid credentials (e.g., Databricks host, token, or other authentication methods) in the environment or configuration.
fix
Configure Databricks authentication by setting environment variables (e.g., `DATABRICKS_HOST`, `DATABRICKS_TOKEN`), using a Databricks CLI configuration profile, or explicitly passing a `Config` object to the `LSQLClient`.
[TABLE_OR_VIEW_NOT_FOUND] The table or view `your_table_name` cannot be found
This is a common Databricks SQL error indicating that the specified table or view in your SQL query does not exist in the current catalog and schema, or you lack the necessary permissions to access it.
fix
Verify the spelling and correctness of the table or view name, including its catalog and schema if necessary (e.g., `catalog.schema.your_table_name`). Ensure the user or service principal has `SELECT` permissions on the table/view.
pyspark.sql.Row is being returned instead of databricks.labs.lsql.core.Row
This issue arises when `databricks-labs-lsql` might incorrectly return `pyspark.sql.Row` objects instead of its own `databricks.labs.lsql.core.Row` objects, potentially leading to unexpected type mismatches in downstream processing.
fix
This often indicates a known bug or an interaction issue between `lsql` and the underlying PySpark environment. Check the `databricks-labs-lsql` GitHub issues or documentation for updates, workarounds, or ensure compatibility with the PySpark version in use. You might need to explicitly cast or convert the `pyspark.sql.Row` objects if the library doesn't handle it automatically.
Upgrade
Version history
0.17.0latest on PyPI · released Mar 23, 2026
Audit
Dependencies
databricks-sdkrequiredCore dependency for interacting with Databricks APIs.
Agent activity
17 hits · last 30 days
node
14
Google (search)
1
OpenAI (training)
1
Resources
databricks-labs-lsql — pip install databricks-labs-lsql · libregistry