# ApexBase Documentation
Complete documentation for ApexBase — a high-performance HTAP embedded database with Rust core and Python API.
## Quick Links
| [Quick Start](QUICK_START.md) | Get started in 5 minutes |
| [API Reference](API_REFERENCE.md) | Complete Python API documentation (100% coverage) |
| [Rust Embedded API](RUST_EMBEDDED_API.md) | Rust native API — all types, methods, examples, concurrency |
| [Examples](EXAMPLES.md) | Code examples and use cases |
| [FTS Guide](FTS_GUIDE.md) | Full-text search SQL reference and examples |
| [Float16 Vector Guide](FLOAT16_VECTOR_GUIDE.md) | f16 embedding storage and SIMD distance kernels |
| [Storage Architecture](STORAGE_ARCHITECTURE.md) | V4 Row Group format, engine internals |
| [HTAP Roadmap](HTAP_ROADMAP.md) | Roadmap and current status |
| [Root README](../README.md) | Project overview, benchmarks, installation |
### Server Quick Reference
| `apexbase-serve` | pg=5432, flight=50051 | **Start both servers simultaneously** |
| `apexbase-server` | 5432 | PostgreSQL Wire only |
| `apexbase-flight` | 50051 | Arrow Flight gRPC only |
## Installation
```bash
# From PyPI (Linux, macOS, Windows — Python 3.9–3.13)
pip install apexbase
```
Or build from source:
```bash
conda activate dev
maturin develop --release
```
## Usage Overview
```python
from apexbase import ApexClient
# Create client
client = ApexClient("./data")
# Create a table (required before any data operations)
client.create_table("users")
# Store data (columnar batch — fastest path)
client.store({
"name": ["Alice", "Bob", "Charlie"],
"age": [30, 25, 35],
"city": ["Beijing", "Shanghai", "Beijing"],
})
# SQL query (use your table name in FROM clause)
results = client.execute("SELECT * FROM users WHERE age > 25")
# Convert to DataFrame (zero-copy Arrow IPC)
df = results.to_pandas()
# Close
client.close()
```
## Key Features
- **HTAP architecture** — columnar V4 Row Group storage + delta writes for fast inserts
- **Multi-database support** — multiple isolated databases; cross-database queries with `db.table` SQL syntax
- **Single-file storage** — custom `.apex` format, no server, no external dependencies
- **Full SQL support** — DDL, DML, aggregations, GROUP BY, HAVING, ORDER BY, JOINs, cross-db queries
- **DataFrame integration** — native Pandas / Polars / PyArrow support via zero-copy Arrow IPC
- **Full-text search** — SQL-native NanoFTS (`MATCH` / `FUZZY_MATCH` in `WHERE`; `CREATE / DROP / SHOW FTS INDEX`); works over PG Wire and Arrow Flight
- **JIT compilation** — Cranelift-based JIT for predicate evaluation
- **Durability** — configurable `fast` / `safe` / `max` with WAL support
- **PostgreSQL wire protocol** — connect DBeaver, psql, DataGrip, pgAdmin, Navicat, and any libpq client
- **Arrow Flight gRPC** — 4–7× faster than PG wire for large result sets; native pyarrow.flight / Go / Java support
- **Cross-platform** — Linux, macOS, Windows (x86_64 & ARM64)
## API Coverage
This documentation covers 100% of the public Python API:
- **ApexClient** — all 50+ public methods including `use_database()`, `use()`, `list_databases()`
- **ResultView** — all conversion and access methods
- **Constants** — module-level exports
- **SQL syntax** — supported SQL operations including cross-database `db.table` syntax
See [API_REFERENCE.md](API_REFERENCE.md) for complete details.
## Documentation Structure
```
docs/
├── README.md # This file — documentation index
├── QUICK_START.md # 5-minute quick start guide (Python)
├── API_REFERENCE.md # Complete Python API reference (100% coverage)
├── RUST_EMBEDDED_API.md # Rust native API — types, methods, examples, concurrency
├── EXAMPLES.md # Real-world usage examples
├── FTS_GUIDE.md # Full-text search SQL reference and guide
├── FLOAT16_VECTOR_GUIDE.md # f16 vector storage, SIMD kernels, benchmarks
├── STORAGE_ARCHITECTURE.md # V4 Row Group format, engine design
└── HTAP_ROADMAP.md # Roadmap and status
benchmarks/
├── bench_vs_sqlite_duckdb.py # Engine vs SQLite vs DuckDB
├── bench_pg_wire.py # PG Wire protocol performance
└── bench_flight.py # Arrow Flight vs PG Wire vs Direct API
```
## Server Launch
```bash
# Both servers simultaneously (recommended)
apexbase-serve --dir /path/to/data
apexbase-serve --dir /path/to/data --pg-port 5432 --flight-port 50051
# Individual servers
apexbase-server --dir /path/to/data --port 5432
apexbase-flight --dir /path/to/data --port 50051
# Connect (PG Wire)
psql -h 127.0.0.1 -p 5432 -d apexbase
python -c "import psycopg2; conn = psycopg2.connect(host='127.0.0.1', port=5432)"
# Connect (Arrow Flight)
python -c "
import pyarrow.flight as fl
client = fl.connect('grpc://127.0.0.1:50051')
df = client.do_get(fl.Ticket(b'SELECT * FROM t LIMIT 100')).read_all().to_pandas()
print(df)
"
```
## Development
```bash
conda activate dev
# Build + install (includes both server and flight features)
maturin develop --release
# Run tests
pytest test/ -q
# Benchmark: engine vs SQLite vs DuckDB
python benchmarks/bench_vs_sqlite_duckdb.py --rows 1000000
# Benchmark: Arrow Flight vs PG Wire vs Direct API
python benchmarks/bench_flight.py --rows 200000
# Benchmark: PG Wire protocol deep-dive
python benchmarks/bench_pg_wire.py --rows 200000
```
## Version Info
| Python | 3.9+ |
| PyArrow | 10.0+ |
| pandas | 2.0+ |
| polars | 0.15+ |
## Notes
- Primary API entry: `apexbase.ApexClient`
- Multi-database: use `use_database(name)` or `use(database=name, table=name)` to switch context
- Cross-database SQL: `SELECT * FROM db.table`, `JOIN db.table ON ...`, `INSERT INTO db.table ...`
- Storage layout: `root_dir/<table>.apex` for default db; `root_dir/<db>/<table>.apex` for named dbs
- Data persistence: single `.apex` file per table per database directory
- Internal ID: records have auto-increment `_id` field
- Query preference: use `execute(sql)` for full SQL, `query(where)` for simple filters
- **Server choice**: use `apexbase-serve` for the simplest deployment (both protocols at once); use individual commands for single-protocol deployments
- **Arrow Flight** requires `pyarrow>=10.0.0` (already a package dependency); no extra install needed
- **PG Wire auth**: authentication is disabled — all connections are accepted without credentials
## License
Apache-2.0