Connect to TiDB Cloud Lake with Jupyter Notebook

Jupyter Notebook is an interactive environment for running code, querying data, and creating visualizations. You can connect a notebook to TiDB Cloud Lake through the TiDB Cloud Lake dialect for SQLAlchemy.

Prerequisites

Before you begin, make sure that you have the following:

• Python 3.8 or later
• A TiDB Cloud Lake account, database, and warehouse
• The host, username, password, database, and warehouse name for your connection

For information about obtaining connection information, see Connect to a Warehouse.

Install Jupyter Notebook and the SQLAlchemy dialect

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install Jupyter Notebook, the SQLAlchemy dialect, and the visualization dependencies:

python3 -m pip install notebook tidbcloudlake-sqlalchemy pandas matplotlib

The tidbcloudlake-sqlalchemy package installs SQLAlchemy and the required TiDB Cloud Lake Python driver.

Start Jupyter Notebook:

jupyter notebook

In the Jupyter interface, create a Python notebook.

Connect to TiDB Cloud Lake

The SQLAlchemy connection URI uses the following format:

lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>

To avoid storing credentials in the notebook, set the connection URI in an environment variable before starting Jupyter Notebook:

export LAKE_SQLALCHEMY_URI='lake://<username>:<password>@<host>:443/<database>?warehouse=<warehouse>'

In the notebook, create a SQLAlchemy engine:

import os

from sqlalchemy import create_engine, text

engine = create_engine(os.environ["LAKE_SQLALCHEMY_URI"])

Query and visualize data

Run the following cell to create a sample table and query it:

with engine.connect() as connection:
    connection.execute(text("DROP TABLE IF EXISTS jupyter_sales"))
    connection.execute(
        text(
            """
            CREATE TABLE jupyter_sales (
                sale_date DATE,
                quantity INT
            )
            """
        )
    )
    connection.execute(
        text(
            """
            INSERT INTO jupyter_sales VALUES
                ('2026-08-01', 5),
                ('2026-08-01', 3),
                ('2026-08-02', 4),
                ('2026-08-03', 10)
            """
        )
    )
    result = connection.execute(
        text(
            """
            SELECT sale_date, SUM(quantity) AS total_quantity
            FROM jupyter_sales
            GROUP BY sale_date
            ORDER BY sale_date
            """
        )
    )
    rows = result.fetchall()
    columns = list(result.keys())

Convert the query result to a pandas DataFrame and create a bar chart:

import matplotlib.pyplot as plt
import pandas as pd

df = pd.DataFrame(rows, columns=columns)
df.plot.bar(x="sale_date", y="total_quantity", legend=False)
plt.ylabel("Quantity")
plt.tight_layout()
plt.show()

When you finish the tutorial, remove the sample table:

with engine.connect() as connection:
    connection.execute(text("DROP TABLE IF EXISTS jupyter_sales"))

Related resources

• tidbcloudlake-sqlalchemy on PyPI
• Connect to TiDB Cloud Lake using Python