oneiriq-surql 0.2.2

Code-first database toolkit for SurrealDB - schema definitions, migrations, query building, and typed CRUD (Rust port of oneiriq-surql). Published as the `oneiriq-surql` crate; imported as `use surql::...`.
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

# Query Hints

Hints are SurrealQL comment annotations that the query planner consumes.
They are strongly typed so builder chains can dedup + validate them before
rendering.

## Kinds

| Hint            | Rendering                                 |
|-----------------|-------------------------------------------|
| `IndexHint`     | `/* USE INDEX table.index */` or `/* FORCE INDEX … */` |
| `ParallelHint`  | `/* PARALLEL ON */` / `OFF` / `/* PARALLEL N */`       |
| `TimeoutHint`   | `/* TIMEOUT Ns */`                        |
| `FetchHint`     | `/* FETCH EAGER */` / `LAZY` / `/* FETCH BATCH N */`   |
| `ExplainHint`   | `/* EXPLAIN */` or `/* EXPLAIN FULL */`   |

## Construction

```rust
use surql::query::hints::{
    ExplainHint, FetchHint, IndexHint, ParallelHint, TimeoutHint, QueryHint,
};

let idx = QueryHint::Index(IndexHint::new("user", "email_idx").force(true));
let par = QueryHint::Parallel(ParallelHint::with_workers(4)?);
let tmo = QueryHint::Timeout(TimeoutHint::new(30.0)?);
let fch = QueryHint::Fetch(FetchHint::batch(100)?);
let xpn = QueryHint::Explain(ExplainHint::full());
```

## Composition

Multiple hints can coexist; `merge_hints` collapses duplicates of the
same kind to the latest value (preserving insertion order of unique
kinds).

```rust
use surql::query::hints::{merge_hints, render_hints};

let hints = vec![tmo_a, par, tmo_b];       // two Timeout hints
let merged = merge_hints(hints);            // tmo_b wins
println!("{}", render_hints(&merged));      // space-joined comment string
```

## Validation

```rust
use surql::query::hints::validate_hint;

let errors = validate_hint(&idx, Some("user"));
assert!(errors.is_empty());

let errors = validate_hint(&idx, Some("post"));
assert_eq!(errors.len(), 1); // wrong table
```

## What's next

- **[Query Builder](queries.md)** -- chaining hints onto queries.