Metadata-Version: 2.4
Name: localql
Version: 1.2.0
Summary: LocalQL packages csvql, a DuckDB-powered CLI for querying local structured data with SQL.
Project-URL: Repository, https://github.com/highlordleonas/csvql
Project-URL: Issues, https://github.com/highlordleonas/csvql/issues
Project-URL: Changelog, https://github.com/highlordleonas/csvql/blob/main/CHANGELOG.md
Project-URL: Release notes, https://github.com/highlordleonas/csvql/blob/main/docs/release-notes/v1.md
Author: Richard Demke
License-Expression: MIT
License-File: LICENSE
Keywords: cli,csv,data-engineering,duckdb,excel,json,local-analytics,ndjson,parquet,sql
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Topic :: Utilities
Requires-Python: <3.15,>=3.11
Requires-Dist: duckdb<2,>=1.5.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Provides-Extra: tui
Requires-Dist: textual>=8.2.8; extra == 'tui'
Description-Content-Type: text/markdown

# LocalQL

[![CI](https://github.com/highlordleonas/csvql/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/highlordleonas/csvql/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/localql.svg)](https://pypi.org/project/localql/)
[![Python](https://img.shields.io/pypi/pyversions/localql.svg)](https://pypi.org/project/localql/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/highlordleonas/csvql/blob/main/LICENSE)

LocalQL is a DuckDB-powered tool for querying local CSV, Parquet, JSON, NDJSON,
and Excel `.xlsx` sources with SQL. Install the `localql` package to use the
`csvql` command, organize repeatable work in a `.csvql.yml` project catalog,
export results, and optionally work in the LocalQL Workbench.

![LocalQL: Query local CSVs with SQL](https://raw.githubusercontent.com/highlordleonas/csvql/main/docs/assets/localql-social-preview.jpg)

## Contents

- [Install and first query](#install-and-first-query)
- [Supported sources and outputs](#supported-sources-and-outputs)
- [Result behavior](#result-behavior)
- [Optional LocalQL Workbench](#optional-localql-workbench)
- [Compatibility and safety](#compatibility-and-safety)
- [Core workflows](#core-workflows)
- [Get help and stay current](#get-help-and-stay-current)

## Install and first query

Install the core command in your selected Python environment:

```console
python -m pip install localql
csvql --version
```

To try a query, create a small CSV in the directory where you are working:

```console
python -c "from pathlib import Path; Path('orders.csv').write_text('order_id,status\nORD-1,paid\nORD-2,pending\nORD-3,paid\n', encoding='utf-8')"
csvql query orders.csv "SELECT * FROM orders LIMIT 5"
```

The file name becomes the SQL table name, so `orders.csv` is available as
`orders`. A successful command prints a table with the CSV rows. See
[Getting started](https://github.com/highlordleonas/csvql/blob/main/docs/getting-started.md)
for other source formats, project catalogs, saved SQL, and exports.

![Terminal screenshot of a LocalQL query over a CSV file](https://raw.githubusercontent.com/highlordleonas/csvql/main/docs/assets/localql-terminal-query.svg)

## Supported sources and outputs

| Capability | Available in LocalQL 1.2.0 |
| --- | --- |
| Query sources | CSV, Parquet, JSON, NDJSON, and Excel `.xlsx` |
| Complete result exports | CSV, JSON envelope, NDJSON, Parquet, Excel `.xlsx`, Markdown, and text |
| User surfaces | CLI, `.csvql.yml` project catalogs, Python API, and LocalQL Workbench |

One query can join sources from different providers. Source selection remains
deterministic across every surface, and explicit provider options carry the
same meaning everywhere. See [Getting started](https://github.com/highlordleonas/csvql/blob/main/docs/getting-started.md#query-other-local-formats)
for a guided workflow and the [v1.2.0 benchmark snapshot](https://github.com/highlordleonas/csvql/blob/main/docs/benchmarks.md)
for measured end-to-end export evidence.

## Result behavior

LocalQL keeps interactive output responsive without changing complete-result
contracts. `csvql query` and `csvql run` table output retains up to 1,000 rows
by default; `--limit` changes that table-preview bound. Query/run JSON output,
Python API results, and `csvql export` remain complete.

The Workbench follows the same split: Results shows a bounded preview while
export and save use the preserved complete result when session capacity is
available.

## Optional LocalQL Workbench

The core CLI needs only `localql`. Install the optional Textual-based Workbench
when you want a source list, SQL editor, results, and history in one terminal
application:

```console
python -m pip install "localql[tui]"
csvql menu orders.csv
```

You can also start with `csvql menu` and run source-free SQL such as `SELECT 1`
before loading any sources. In the Sources pane, press `a` to add structured
source intent with an explicit type and provider options.

All core commands remain available without the extra. See the
[Workbench guide](https://github.com/highlordleonas/csvql/blob/main/docs/tui-guide.md)
for keys and source-management actions.

![Terminal screenshot of the LocalQL Workbench with CSV sources, SQL, History, and a complete preserved result](https://raw.githubusercontent.com/highlordleonas/csvql/main/docs/assets/localql-tui-workbench.svg)

## Compatibility and safety

LocalQL supports Python 3.11 through 3.14 on macOS, Linux, and Windows.

LocalQL treats user-authored SQL as trusted local DuckDB SQL. It does not
sandbox DuckDB or restrict filesystem access. Run only SQL you trust.

Source selection is deterministic. An explicit `--type` wins, a recognized
extension selects one provider, and an extensionless file or directory that
could match a provider requires an explicit choice. Bounded identification
produces evidence and guidance; it never silently chooses between candidates.

## Core workflows

| When you want to… | Start here |
| --- | --- |
| Query a local source or join named tables | [CLI reference](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md#query-local-sources) |
| Follow a multi-format query and export workflow | [Getting started](https://github.com/highlordleonas/csvql/blob/main/docs/getting-started.md#query-other-local-formats) |
| Reuse a project catalog and saved SQL | [Project catalogs](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md#project-catalogs) |
| Inspect, sample, or profile a source | [Inspect, sample, and profile](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md#inspect-sample-and-profile) |
| Export a result or reuse it as a CSV source | [Save and reuse results](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md#save-and-reuse-results) |
| Work interactively with sources and results | [Workbench guide](https://github.com/highlordleonas/csvql/blob/main/docs/tui-guide.md) |
| Review measured multi-format export evidence | [v1.2.0 benchmarks](https://github.com/highlordleonas/csvql/blob/main/docs/benchmarks.md) |
| Check configured data-quality rules | [Data-quality checks](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md#data-quality-checks) |

DuckDB executes SQL and relational operations; LocalQL manages deterministic
source selection, local table aliases, project configuration, output, and
explicit exports.

## Get help and stay current

- [Getting started](https://github.com/highlordleonas/csvql/blob/main/docs/getting-started.md)
- [CLI reference](https://github.com/highlordleonas/csvql/blob/main/docs/cli-reference.md)
- [v1.2.0 benchmarks](https://github.com/highlordleonas/csvql/blob/main/docs/benchmarks.md)
- [Troubleshooting](https://github.com/highlordleonas/csvql/blob/main/docs/troubleshooting.md)
- [FAQ](https://github.com/highlordleonas/csvql/blob/main/docs/faq.md)
- [Support](https://github.com/highlordleonas/csvql/blob/main/SUPPORT.md)
- [Security](https://github.com/highlordleonas/csvql/blob/main/SECURITY.md)
- [Changelog](https://github.com/highlordleonas/csvql/blob/main/CHANGELOG.md)
- [v1 release notes](https://github.com/highlordleonas/csvql/blob/main/docs/release-notes/v1.md)
- [Contributing](https://github.com/highlordleonas/csvql/blob/main/CONTRIBUTING.md)
- [Roadmap](https://github.com/highlordleonas/csvql/blob/main/docs/ROADMAP.md)
