README

OCaml bindings for TrailDB

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

Pre-requisites

• OCaml

• TrailDB

• uuidm OCaml module for UUIDs.

To build from source.

• jbuilder OCaml build system.

Install

From source:

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

Or using directly jbuilder:

$ jbuilder build @install$ jbuilder runtest$ jbuilder install

Documentation

ATrailDB 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 inlib/trailDB.mli.

Usage

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 TrailDB.Cursor.next cursor with    | None -> ()    | Some event ->      let [measure;value] =        event.TrailDB.values        |> List.map (TrailDB.get_item_value db)      in      Printf.printf "(%Ld,%s,%s)\n" event.TrailDB.timestamp measure value      |> loop  in  loop ()

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

1. ounitwith-test

None

None