From 5c837f47b6b4cb18d824ff855ec6a86c6216c440 Mon Sep 17 00:00:00 2001 From: Emil Sadek Date: Fri, 7 Nov 2025 13:28:06 -0800 Subject: [PATCH 1/4] docs: add python notebooks guide --- docs/guides/index.md | 1 + docs/guides/python_notebooks.md | 61 +++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 63 insertions(+) create mode 100644 docs/guides/python_notebooks.md diff --git a/docs/guides/index.md b/docs/guides/index.md index 18b13e6..8b11d22 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -22,3 +22,4 @@ For detailed guides on using dbc, see the following pages: - [Finding Drivers](./finding_drivers.md) - [Using a Driver List](./driver_list.md) - [Installing a Driver Manager](./driver_manager.md) +- [Python Notebooks](./python_notebooks.md) diff --git a/docs/guides/python_notebooks.md b/docs/guides/python_notebooks.md new file mode 100644 index 0000000..77d07bf --- /dev/null +++ b/docs/guides/python_notebooks.md @@ -0,0 +1,61 @@ + + +# Python Notebooks + +dbc can be installed and used directly in Python notebooks (such as Jupyter or Google Colab). +Each of the following code blocks is designed to be executed as an individual cell in your notebook. + +Install the `dbc`, `adbc-driver-manager`, and `pyarrow` packages: + +```python +%pip install dbc adbc_driver_manager pyarrow +``` + +Install the `duckdb` driver: + +```python +!dbc install duckdb +``` + +!!! note + + This guide uses the DuckDB driver for simplicity. + To list all available drivers, run `!dbc search`. + +Import the `dbapi` module: + +```python +from adbc_driver_manager import dbapi +``` + +Connect to a database via ADBC, create a cursor, execute queries, and fetch the result as a PyArrow Table: + +```python +with ( + dbapi.connect(driver="duckdb", db_kwargs={"path": "penguins.duckdb"}) as con, + con.cursor() as cursor, +): + cursor.execute("CREATE TABLE IF NOT EXISTS penguins AS FROM 'http://blobs.duckdb.org/data/penguins.csv'") + cursor.execute("SELECT * FROM penguins") + table = cursor.fetch_arrow_table() +``` + +Print the table: + +```python +print(table) +``` diff --git a/mkdocs.yml b/mkdocs.yml index 6e27451..ce7f7a5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: - Finding Drivers: guides/finding_drivers.md - Using a Driver List: guides/driver_list.md - Driver Managers: guides/driver_manager.md + - Python Notebooks: guides/python_notebooks.md - Concepts: - concepts/index.md - Driver: concepts/driver.md From 9c54562d8625adbe0b4fb8024ac0b3a1e36eab49 Mon Sep 17 00:00:00 2001 From: Emil Sadek Date: Tue, 11 Nov 2025 14:03:19 -0800 Subject: [PATCH 2/4] docs: add links to jupyter and colab Co-authored-by: Bryce Mecum --- docs/guides/python_notebooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/python_notebooks.md b/docs/guides/python_notebooks.md index 77d07bf..c256320 100644 --- a/docs/guides/python_notebooks.md +++ b/docs/guides/python_notebooks.md @@ -16,7 +16,7 @@ limitations under the License. # Python Notebooks -dbc can be installed and used directly in Python notebooks (such as Jupyter or Google Colab). +dbc can be installed and used directly in Python notebooks (such as [Jupyter](https://jupyter.org) or [Google Colab](https://colab.google)). Each of the following code blocks is designed to be executed as an individual cell in your notebook. Install the `dbc`, `adbc-driver-manager`, and `pyarrow` packages: From cef9aad03809e5de6e893b8695b931da57eaed50 Mon Sep 17 00:00:00 2001 From: Emil Sadek Date: Tue, 11 Nov 2025 14:05:42 -0800 Subject: [PATCH 3/4] docs: use in-memory database in notebooks guide Co-authored-by: Bryce Mecum --- docs/guides/python_notebooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/python_notebooks.md b/docs/guides/python_notebooks.md index c256320..98c189b 100644 --- a/docs/guides/python_notebooks.md +++ b/docs/guides/python_notebooks.md @@ -46,7 +46,7 @@ Connect to a database via ADBC, create a cursor, execute queries, and fetch the ```python with ( - dbapi.connect(driver="duckdb", db_kwargs={"path": "penguins.duckdb"}) as con, + dbapi.connect(driver="duckdb") as con, con.cursor() as cursor, ): cursor.execute("CREATE TABLE IF NOT EXISTS penguins AS FROM 'http://blobs.duckdb.org/data/penguins.csv'") From 42a1c8b477e3960d6037db01466a1871b7cbcc2b Mon Sep 17 00:00:00 2001 From: Emil Sadek Date: Tue, 11 Nov 2025 14:08:40 -0800 Subject: [PATCH 4/4] docs: use https for data url in notebooks guide Co-authored-by: Bryce Mecum --- docs/guides/python_notebooks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/python_notebooks.md b/docs/guides/python_notebooks.md index 98c189b..ddcc135 100644 --- a/docs/guides/python_notebooks.md +++ b/docs/guides/python_notebooks.md @@ -49,7 +49,7 @@ with ( dbapi.connect(driver="duckdb") as con, con.cursor() as cursor, ): - cursor.execute("CREATE TABLE IF NOT EXISTS penguins AS FROM 'http://blobs.duckdb.org/data/penguins.csv'") + cursor.execute("CREATE TABLE IF NOT EXISTS penguins AS FROM 'https://blobs.duckdb.org/data/penguins.csv'") cursor.execute("SELECT * FROM penguins") table = cursor.fetch_arrow_table() ```