package traildb

  1. Overview
  2. Docs


TrailDB is a file format for time-series.

Published: 15 Feb 2018


OCaml bindings for TrailDB

Here are OCaml bindings for TrailDB, an efficient tool for storing and querying series of events.


To build from source.


From source:

$ make            # use jbuilder
$ make test
$ make install    # use opam

Or using directly jbuilder:

$ jbuilder build @install
$ jbuilder runtest
$ jbuilder install


A TrailDB file is a read only collection of trails, i.e. keyed series of event records with a timestamp and sharing a common set of fields.

The API is documented in lib/trailDB.mli.


A TrailDB file is created after a series of event records with

  • a trail identifier,

  • a timestamp

  • and a shared set of fields.

  (* Start the creation of a new traildb file to record events
     with two fields (measure kind and value) plus an implicit timestamp *)
  let db = TrailDB.Cons.open_w "/tmp/foo" ["measure";"value"] in

  (* Make some trail identifiers *)
  let uuid_0 = Uuidm.(v5 ns_oid "trail_0") in
  let uuid_1 = Uuidm.(v5 ns_oid "trail_1") in

  (* Insert events with a string value for each field *)
  TrailDB.Cons.add db uuid_0  123456L ["temperature";"22"];
  TrailDB.Cons.add db uuid_1  123456L ["temperature";"12"];
  TrailDB.Cons.add db uuid_1  123457L ["temperature";"13"];
  TrailDB.Cons.add db uuid_0  123457L ["temperature";"23"];
  TrailDB.Cons.add db uuid_0  123458L ["temperature";"24"];
  TrailDB.Cons.add db uuid_1  123458L ["temperature";"14"];
  TrailDB.Cons.add db uuid_1  123459L ["temperature";"13"];

  (* Dump on disk the TrailDB file *)
  TrailDB.Cons.finalize db

Once build a TrailDB database is read only file.

  (* Open a read only TrailDB file *)
  let db = TrailDB.open_r "/tmp/foo.tdb" in

  (* Get some meta data *)
  assert (TrailDB.num_trails db = 2L);
  assert (TrailDB.num_events db = 7L);
  assert (TrailDB.num_fields db = 3L); (* timestamp, measure, value *)

  (* Get the identifier of a trail given its UUIDs *)
  let trail_uuid = Uuidm.(v5 ns_oid "trail_1") in
  let (Some trail_id) = TrailDB.get_trail_id db trail_uuid in

  (* Extract the events of a trail using a cursor *)
  let cursor = TrailDB.Cursor.create db in
  TrailDB.Cursor.get_trail cursor trail_id;

  let rec loop () =
    match cursor with
    | None -> ()
    | Some event ->
      let [measure;value] =
        |> (TrailDB.get_item_value db)
      Printf.printf "(%Ld,%s,%s)\n" event.TrailDB.timestamp measure value
      |> loop
  loop ()

Dependencies (3)

  1. jbuilder >= "1.0+beta7"
  2. uuidm
  3. ocaml

Dev Dependencies (1)

  1. ounit with-test

Used by