Metadata-Version: 2.1
Name: asqlcell
Version: 0.2.2
Summary: Analytical sql cell for Jupyter
Home-page: https://github.com/datarho/asqlcell
Author: qizh
Author-email: qizh@datarho.tech
License: BSD
Keywords: Jupyter,Widgets,IPython
Platform: Linux
Platform: Mac OS X
Platform: Windows
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Framework :: Jupyter
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: altair >=5.0.1
Requires-Dist: duckdb >=0.8.1
Requires-Dist: duckdb-engine >=0.9.2
Requires-Dist: fastparquet >=2023.4.0
Requires-Dist: ipywidgets >=8.0.0
Requires-Dist: jinja2 >=3.1.2
Requires-Dist: pandas >=2.0.3
Requires-Dist: StrEnum >=0.4.15
Requires-Dist: sqlparse >=0.4.3
Requires-Dist: sqlalchemy >=2.0.19
Requires-Dist: openai >=0.27.8
Requires-Dist: requests >=2.28.1
Provides-Extra: docs
Requires-Dist: jupyter-sphinx ; extra == 'docs'
Requires-Dist: nbsphinx ; extra == 'docs'
Requires-Dist: nbsphinx-link ; extra == 'docs'
Requires-Dist: pytest-check-links ; extra == 'docs'
Requires-Dist: pypandoc ; extra == 'docs'
Requires-Dist: recommonmark ; extra == 'docs'
Requires-Dist: sphinx >=1.5 ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
Provides-Extra: examples
Provides-Extra: test
Requires-Dist: pytest >=4.6 ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: nbval ; extra == 'test'

# Analytical SQL Cell

Analytical SQL cell for Jupyter.

## Installation

You can install using `pip`:

```bash
pip install asqlcell
```

## Quick Start

Here's a quick example to get you started with Analytical SQL Cell in Jupyter:

```%%sql result_set

SELECT
    *
FROM 'data.csv'
LIMIT 10
```

In the above sample, `%%sql` is a cell magic indicating that the cell block will be executed as a SQL statement. The following `result_set` is required to be the name of Pandas dataframe holding the result set.

### Data Load

You can query from Pandas DataFrame, CSV files, compressed (e.g. compressed with gzip) CSV files, as well as Parquet files.

### SQL

DuckDB is the default engine of Analytical SQL Cell. Please find more details at the [SQL Introduction](https://duckdb.org/docs/sql/introduction) of DuckDB.

### Result Table

With the SQL query being executed in an Analytical SQL Cell, the result set is presented as a table.

In case of multiple SQL statements being executed in an Analytical SQL Cell, only the result set of the last SQL statement will be presented.

If the last SQL statement didn't have any result set, then only the count of executed data rows is shown.

![sample result table](screenshot.jpg)

### Tutorial

- [Introduction](examples/introduction.ipynb)
- [World Development in Numbers](examples/gapminder.ipynb)

## Development

This widget is developed with conda to ensure a consistent developer experience. The project is developed in both
Mac OS and Windows Subsystem for Linux.

Please run the following commands to create a conda environment:

```bash
conda create -n asqlcell -c conda-forge nodejs=18.15 python=3.8 jupyterlab=3.6 jupyter_packaging=0.12
conda activate asqlcell
```

### Python

Install the python. This will also build the TypeScript package.

```bash
pip install -e ".[test, examples, docs]"
```

### Jupyter

When developing your extensions, you need to manually enable your extensions with the notebook / lab frontend.

For lab, this is done by the command:

```
jupyter labextension develop --overwrite .
jlpm run build
```

#### Typescript

You must start watching the change of the widget:

```bash
jlpm run watch
```

Then in another terminal you can run Jupyter Lab (without launching a browser):

```bash
jupyter lab --no-browser
```

Now you can open Google Chrome and navigate to [http://localhost:8888](http://localhost:8888) to play with the widget.
After a change wait for the build to finish and then refresh your browser and the changes should take effect.

If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
