rayforce 1.0.1

Convenient, high-performance Rust bindings for RayforceDB v2
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

<table style="border-collapse:collapse;border:0;">
  <tr>
    <td style="border:0;padding:0;">
      <a href="https://rs.rayforcedb.com">
        <picture>
            <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RayforceDB/rayforce-rs/refs/heads/master/docs/docs/assets/logo_light_full.svg">
            <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/RayforceDB/rayforce-rs/refs/heads/master/docs/docs/assets/logo_dark_full.svg">
            <img src="https://raw.githubusercontent.com/RayforceDB/rayforce-rs/refs/heads/master/docs/docs/assets/logo_dark_full.svg" width="200">
        </picture>
      </a>
    </td>
    <td style="border:0;padding:0;">
      <h1>High-Performance, Zero-Copy Rust bindings for <a href="https://core.rayforcedb.com"><picture>
            <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/RayforceDB/rayforce-rs/refs/heads/master/docs/docs/assets/logo_light_full.svg">
            <img src="https://raw.githubusercontent.com/RayforceDB/rayforce-rs/refs/heads/master/docs/docs/assets/logo_dark_full.svg" alt="RayforceDB" height="40" style="vertical-align: bottom;">
        </picture></a></h1>
    </td>
  </tr>
</table>

[![CI](https://github.com/RayforceDB/rayforce-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/RayforceDB/rayforce-rs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/rayforce.svg)](https://crates.io/crates/rayforce)
[![Docs.rs](https://img.shields.io/docsrs/rayforce)](https://docs.rs/rayforce)
[![License: MIT](https://img.shields.io/badge/License-MIT-e5601f.svg)](LICENCE)
![Rust Version](https://img.shields.io/badge/rustc-1.74%2B-orange.svg)

Rust bindings for [RayforceDB](https://core.rayforcedb.com), a high-performance columnar
database designed for analytics and data operations. The core is written in pure C with
minimal overhead — combining columnar storage with SIMD vectorization for lightning-fast
analytics on time-series and big-data workloads.

The bindings call the core's C API **directly** (no marshalling shim), so reads are
zero-copy where it counts: a numeric column is exposed as a `&[T]` slice rather than
copied element by element.

**Full Documentation:** https://rs.rayforcedb.com/

## Features

- **Fluent API** — chainable, intuitive query builders that read like the operation; real
  operator overloads for arithmetic, methods for comparisons.
- **Zero-Copy & High Performance** — build a column in a single `memcpy`, read it back as a
  borrow; minimal overhead between Rust and the RayforceDB runtime via the C API.
- **Type-Safe** — a full value model (atoms, vectors, lists, dicts, tables) with
  `ToValue`/`FromValue` conversions and optional `chrono` temporals.
- **Lightweight** — the core is less than a 1 MB footprint.
- **Batteries included** — CSV & splayed I/O, binary serialization, and a TCP/IPC client.

## Quick Start

```rust
use rayforce::{col, Runtime, Table, Value};

let _rt = Runtime::new()?;                       // one live runtime per process

let quotes = Table::new(
    &["symbol", "bid", "ask"],
    &[
        Value::sym_vec(&["AAPL", "AAPL", "AAPL", "GOOG", "GOOG", "GOOG"]),
        Value::vec(&[100.0f64, 101.0, 102.0, 200.0, 201.0, 202.0]),
        Value::vec(&[110.0f64, 111.0, 112.0, 210.0, 211.0, 212.0]),
    ],
)?;

let result = quotes
    .select()
    .agg("max_bid", col("bid").max())
    .agg("min_bid", col("bid").min())
    .agg("avg_ask", col("ask").avg())
    .agg("count",   col("bid").count())
    .filter(col("bid").ge(110.0).and(col("ask").gt(100.0)))
    .by("symbol")
    .execute()?;

println!("{result}");
```

```text
┌────────┬─────────┬─────────┬─────────┬───────┐
│ symbol │ max_bid │ min_bid │ avg_ask │ count │
│  SYM   │   F64   │   F64   │   F64   │  I64  │
├────────┼─────────┼─────────┼─────────┼───────┤
│ GOOG   │ 202.0   │ 200.0   │ 211.0   │ 3     │
├────────┴─────────┴─────────┴─────────┴───────┤
│ 1 rows (1 shown) 5 columns (5 shown)         │
└──────────────────────────────────────────────┘
```

## Installation

The crate links two local checkouts: the RayforceDB **core** (`RAYFORCE_SRC`) and the
**rayforce-q** IPC client (`RAYFORCE_Q_SRC`). The build script compiles both and statically
links `librayforce.a`.

```toml
# Cargo.toml
[dependencies]
rayforce = { git = "https://github.com/RayforceDB/rayforce-rs" }
```

```sh
git clone https://github.com/RayforceDB/rayforce   ~/rayforce      # core
git clone https://github.com/RayforceDB/rayforce-q ~/rayforce-q    # Q IPC client

export RAYFORCE_SRC=/path/to/rayforce       # default: ~/rayforce
export RAYFORCE_Q_SRC=/path/to/rayforce-q   # default: ~/rayforce-q

cargo build
cargo test
```

Requirements: a C toolchain (`make`, `clang`) and `libclang` for `bindgen`.

`bindgen` locates `libclang` via `LIBCLANG_PATH`. This is deliberately **not** set in the
repo's `.cargo/config.toml`. If bindgen can't auto-detect libclang, set it yourself:

```sh
# macOS (CTL):
export LIBCLANG_PATH="/Library/Developer/CommandLineTools/usr/lib"
# Linux:
export LIBCLANG_PATH="$(dirname "$(find /usr/lib -name 'libclang*.so*' | head -1)")"
```

The `chrono` is on by default for date/time/timestamp conversions.

---

**Built with ❤️ for high-performance data processing | <a href="https://rs.rayforcedb.com/content/license.html">MIT Licensed</a> | RayforceDB**