Metadata-Version: 2.4
Name: csvsearch
Version: 0.5.0
Summary: Search and rank terms in CSV files using DuckDB
Author: Mehdi.A
License-Expression: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: duckdb
Requires-Dist: click
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# csvsearch

Search tool for CSV files powered by DuckDB. Supports two modes: fast in-memory substring/regex search, and persistent BM25 full-text ranking via an index.

## Installation

```bash
pip install csvsearch
```

## Usage

### Substring search

```bash
# Search for one or more terms
csvsearch search data.csv "john" "doe"

# Case-sensitive, whole word only, specific columns
csvsearch search data.csv "Tom" --case-sensitive --word --columns "name,email"

# Count matching rows only
csvsearch search data.csv "error" --count

# Export results to a CSV file
csvsearch search data.csv "paris" --output results.csv
```

### File info

```bash
csvsearch info data.csv
```

### BM25 full-text ranking

Build an index once, then rank any number of queries against it:

```bash
# Build index (lean mode: index + parquet side by side)
csvsearch index data.csv

# Search by relevance
csvsearch rank data.csv "machine learning tutorial" --top 5
```

The lean index stores only the id and text columns in a `.duckdb` file, and the full data in a `.parquet` file. Both are generated automatically next to the source.

```bash
# Alternative: fat mode (everything in .duckdb, simpler but larger)
csvsearch index data.csv --fat
csvsearch rank data.duckdb "query" --fat
```

### Python API

```python
from csvsearch import CSVSearch, CSVIndex

# Substring search
with CSVSearch("data.csv") as s:
    rows = s.search(["john", "doe"], case_sensitive=False)
    print(s.get_column_names())

# BM25 ranking
with CSVIndex("data.duckdb") as idx:
    idx.build_lean("data.csv")
    rows, headers = idx.search_bm25_lean("machine learning", top_n=10)
```

## License

Copyright (c) 2026 Mehdi.A — MIT
