sochdb-query 0.4.2

SochDB query engine (sync-first execution and vector query planning)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# sochdb-query

Query planning and execution engine for SochDB.

## Overview

`sochdb-query` provides the query layer for SochDB, featuring:

- **Query Builder**: Fluent API for constructing queries
- **Query Optimizer**: Cost-based optimization for efficient execution
- **Projection Pushdown**: Only read columns you need
- **Filter Pushdown**: Apply filters at storage layer
- **TOON Output**: Token-optimized format (40-66% fewer tokens than JSON)

## Features

- **SQL-like Queries**: Familiar query patterns without SQL parsing overhead
- **Path-based Access**: O(|path|) resolution independent of data size
- **Aggregations**: COUNT, SUM, AVG, MIN, MAX with efficient execution
- **Sorting & Pagination**: ORDER BY, LIMIT, OFFSET support
- **Join Support**: Nested loop and hash joins

## Installation

```toml
[dependencies]
sochdb-query = "0.2.5"
```

## Usage

Most users should use the high-level [`sochdb`](https://crates.io/crates/sochdb) crate:

```rust
use sochdb::{Database, Query};

let db = Database::open("./my_data")?;

// Query with builder pattern
let results = db.query("users")
    .filter("age", ">", 21)
    .select(&["name", "email"])
    .order_by("name")
    .limit(10)
    .execute()?;

// Results in token-efficient TOON format
println!("{}", results.to_toon()); 
// users[3]{name,email}: Alice,alice@...|Bob,bob@...|Carol,carol@...
```

## Query Execution Pipeline

```
┌──────────────┐
│    Query     │  User query (builder or path)
└──────┬───────┘
       │
       ▼
┌──────────────┐
│    Parse     │  Validate and normalize
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Optimize   │  Pushdown filters, projections
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Execute    │  Scan, filter, project, sort
└──────┬───────┘
       │
       ▼
┌──────────────┐
│   Format     │  TOON or JSON output
└──────────────┘
```

## Crate Structure

| Crate | Purpose |
|-------|---------|
| [`sochdb`](https://crates.io/crates/sochdb) | High-level client API (start here) |
| [`sochdb-core`](https://crates.io/crates/sochdb-core) | Core types and traits |
| [`sochdb-storage`](https://crates.io/crates/sochdb-storage) | Storage engine with WAL |
| [`sochdb-index`](https://crates.io/crates/sochdb-index) | HNSW vector indexing |
| `sochdb-query` | Query execution (this crate) |

## License

Apache-2.0 - see [LICENSE](../LICENSE) for details.