Metadata-Version: 2.4
Name: google-colabsqlviz
Version: 0.4.0
Summary: Interactive DataFrame visualization widget powered by the Google Data Studio charting engine with anywidget.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: ipython>=7.34.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: protobuf>=4.24.0
Requires-Dist: pyarrow>=10.0.1
Requires-Dist: anywidget>=0.9.3
Requires-Dist: packaging>=20.0
Requires-Dist: traitlets>=5.0.0

# google-colabsqlviz

Interactive DataFrame visualization widget powered by the Google Data Studio
charting engine.

Built on [`anywidget`](https://anywidget.dev/), `google-colabsqlviz` renders an
interactive visualization and data exploration interface inside any notebook
environment that supports IPyWidgets, including Google Colab, VS Code,
JupyterLab, and more.

Embeds the Data Studio Charting Engine UI hosted on Google's CDN; however, none
of your data is ever sent to Google. All aggregation logic is run in your Python
kernel, and all visualizations are rendered strictly in the browser.

## Features

-   **Interactive no-code charting**: Configure chart types (bar, line, scatter,
    histogram, pie, pivot tables, geo charts, etc.), dimensions, metrics,
    aggregations, sorting, and filters directly in the notebook cell output.
-   **Multi-engine DataFrame support**:
    -   **`pandas.DataFrame`**
    -   **`bigframes.pandas.DataFrame`**
    -   **`pyspark.sql.DataFrame`**, including Spark Connect
-   **Lightweight footprint**: Optional distributed engines (`bigframes`,
    `pyspark`) are detected at runtime and never force-installed or upgraded
    over your existing cluster/runtime environment.

## Installation

Install on the command line in an active virtual environment:

```bash
pip install google-colabsqlviz
```

Or directly in a notebook cell:

```
%pip install google-colabsqlviz
```

## Quick Start

Pass any supported DataFrame to `display` (also available as
`explore_dataframe`):

```py
import pandas as pd
from google.colabsqlviz.explore_dataframe import display

df = pd.DataFrame({
    "category": ["A", "B", "A", "C", "B", "A"],
    "value": [10, 25, 15, 40, 30, 20],
})

display(df)
```

If `bigframes` (`>= 2.35.0`) or `pyspark` is installed in your kernel, you can
pass a `bigframes.pandas.DataFrame` or `pyspark.sql.DataFrame` directly to
`explore_dataframe.explore_dataframe(...)` and aggregations will be executed by
that engine.

## Documentation & Resources

-   [Data Studio Chart References](https://docs.cloud.google.com/data-studio/types-of-charts)
    — Documentation on the chart types and aggregations supported by the
    embedded Data Studio engine.
