Tau (τ) - τ (tau) Documentation

The Tau (written as τ, the Greek letter for Tau) is the most fundamental primitive in τ. It represents a single, immutable, time-stamped event or piece of data.

Think of a Tau not as a static value, but as a delta that is valid over a specific range of time.

The Structure of a Tau

A Tau is defined by three essential properties:

data: The actual value of the event. This is stored as an opaque byte array ([]const u8), allowing you to store anything from simple numbers to complex JSON objects.
valid_ns: A u64 nanosecond timestamp indicating the beginning of the Tau's validity.
expiry_ns: A u64 nanosecond timestamp indicating the end of the Tau's validity.

libtau/primitives/tau.zig (Simplified)

1pub const Tau = struct {
2    data: []const u8,
3    valid_ns: u64,
4    expiry_ns: u64,
5
6    // ... methods
7};

Key Concepts

Immutability

Once a Tau is created and appended to a Schedule, it cannot be changed. This is a core design principle of τ. Any modification is recorded as a new Tau, preserving a complete and auditable history of all changes. This immutability guarantees:

A full, tamper-proof audit trail.
Deterministic and repeatable queries.
No accidental data loss from overwrites.

Time Range Validity

Every Tau exists within a precise time range, defined by valid_ns and expiry_ns. This is the foundation of τ's bitemporal capabilities. It allows you to ask not just "what is the value now?" but also "what was the value at this specific point in the past?"

Delta Storage

τ is optimized for storing data that changes over time. Instead of repeatedly storing the full state of an entity, you only store what changed, when it changed.

Efficient Time-Series Storage

For many time-series workloads (like IoT sensor data or financial tickers), values are often stable for periods of time. A traditional database might record a value at every interval, leading to massive data duplication.

With τ, you only need to append a new Tau when the value actually changes. This can lead to significant storage savings and performance gains.

Working with Taus

You rarely create Taus directly. Instead, you create them implicitly by using the append command, which adds a new Tau to a specified Schedule.

REPL

1# This command creates a Tau with the value "25.5",
2# valid from t=1s to t=5s, and appends it to "sensor_1".
3τ> append sensor_1 25.5 1000000000 5000000000
4OK

When you query the database using commands like at or range, the server returns the data from the relevant Tau(s).