Standard library · Databases

db/oxitsdb

Imported as import "db/oxitsdb" as oxitsdb, its names are then oxitsdb.…. Every signature below is the one the checker infers.

Functions

fn ts_connect(host: Str, port: Int) -> Result(Int, Str)

# not run
import "db/oxitsdb"
fd = ts_connect("127.0.0.1", 7411)?

fn ts_hang_up(fd: Int) -> Unit

# not run
import "db/oxitsdb"
ts_hang_up(fd)

fn ts_call(fd: Int, request: Json) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_call(fd, ts_request("stats", Nil))   # Ok(the answer), or Err(the server's message)

fn ts_request(op: Str, fields: List(Field)) -> Json

Every request names the engine as well as the command: the server mounts the time-series engine beside the document and SQL ones, and engine is what tells them apart. It is off unless the server was started with OXIDB_TSDB.

import "db/oxitsdb"
ts_request("stats", Nil)   # => JObj(Cons(Field(engine, JStr(tsdb)), Cons(Field(cmd, JStr(tsdb)), Cons(Field(op, JStr(stats)), Nil))))

fn ts_point(measurement: Str, tags: List(Field), fields: List(Field), at: Int) -> Json

A point is a measurement, a moment, any number of string tags and one or more named fields. at is epoch milliseconds.

import "db/oxitsdb"
ts_point("temp", Cons(ts_tag("room", "lab"), Nil), Cons(ts_field("c", 21.5), Nil), 1700000000000)   # => JObj(Cons(Field(measurement, JStr(temp)), Cons(Field(tags, JObj(Cons(Field(room, JStr(lab)), Nil))), Cons(Field(fields, JObj(Cons(Field(c, JNum(21.5)), Nil))), Cons(Field(ts, JInt(1700000000000)), Nil)))))

fn ts_tag(key: Str, value: Str) -> Field

import "db/oxitsdb"
ts_tag("room", "lab")   # => Field(room, JStr(lab))

fn ts_field(key: Str, value: Float) -> Field

import "db/oxitsdb"
ts_field("c", 21.5)   # => Field(c, JNum(21.5))

fn ts_count_field(key: Str, value: Int) -> Field

import "db/oxitsdb"
ts_count_field("hits", 3)   # => Field(hits, JInt(3))

fn ts_write(fd: Int, points: List(Json)) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_written(ts_write(fd, Cons(p1, Cons(p2, Nil)))?)   # 2

fn ts_write_lines(fd: Int, lines_text: Str) -> Result(Json, Str)

InfluxDB line protocol, for a feed that already speaks it. A line with no timestamp is stamped by the server as it arrives.

# not run
import "db/oxitsdb"
ts_write_lines(fd, "temp,room=lab c=21.5 1700000000000\n")   # the line protocol, as written

fn ts_query(fd: Int, measurement: Str, field_name: Str, spec: List(Field)) -> Result(Json, Str)

agg is mean, sum, min, max, count, distinct, first, last, rate, or a percentile written p95. An interval in milliseconds buckets the answer; without one the whole range collapses to a single point per series.

# not run
import "db/oxitsdb"
ts_query(fd, "temp", "c", ts_between(t0, t1) |> ts_agg("mean") |> ts_every(60000))   # a mean a minute

fn ts_between(start: Int, end: Int) -> List(Field)

import "db/oxitsdb"
ts_between(1, 2)   # => Cons(Field(start, JInt(1)), Cons(Field(end, JInt(2)), Nil))

fn ts_agg(name: Str, rest: List(Field)) -> List(Field)

import "db/oxitsdb"
ts_agg("mean", Nil)   # => Cons(Field(agg, JStr(mean)), Nil)

fn ts_every(interval: Int, rest: List(Field)) -> List(Field)

import "db/oxitsdb"
ts_every(60000, Nil)   # => Cons(Field(interval, JInt(60000)), Nil)

fn ts_where(tags: List(Field), rest: List(Field)) -> List(Field)

import "db/oxitsdb"
ts_where(Cons(ts_tag("room", "lab"), Nil), Nil)   # => Cons(Field(tags, JObj(Cons(Field(room, JStr(lab)), Nil))), Nil)

fn ts_group_by(keys: List(Str), rest: List(Field)) -> List(Field)

import "db/oxitsdb"
ts_group_by(Cons("room", Nil), Nil)   # => Cons(Field(group_by, JArr(Cons(JStr(room), Nil))), Nil)

fn ts_stats(fd: Int) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_stats(fd)   # what the engine holds

fn ts_retention(fd: Int, cutoff: Int) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_retention(fd, 1700000000000)   # drop what is older than the moment

fn ts_checkpoint(fd: Int) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_checkpoint(fd)

fn ts_rollup_add(fd: Int, measurement: Str, interval: Int, agg: Str) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_rollup_add(fd, "temp", 3600000, "mean")   # an hourly mean, kept up by the engine

fn ts_rollup_refresh(fd: Int) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_rollup_refresh(fd)

fn ts_rollups(fd: Int) -> Result(Json, Str)

# not run
import "db/oxitsdb"
ts_rollups(fd)

fn ts_series(answer: Json) -> List(Json)

A query answers an array of series, each {tags, type, points:[{ts, value}]}.

import "db/oxitsdb"
len(ts_series(JArr(Cons(JObj(Nil), Cons(JObj(Nil), Nil)))))   # => 2

fn ts_series_tags(series: Json) -> Json

import "db/oxitsdb"
ts_series_tags(JObj(Cons(Field("tags", JObj(Cons(Field("room", JStr("lab")), Nil))), Nil)))   # => JObj(Cons(Field(room, JStr(lab)), Nil))

fn ts_series_points(series: Json) -> List(Json)

import "db/oxitsdb"
series = JObj(Cons(Field("points", JArr(Cons(JObj(Cons(Field("ts", JInt(1)), Cons(Field("value", JNum(2.5)), Nil))), Nil))), Nil))
map(ts_series_points(series), ts_value)   # => Cons(2.5, Nil)

fn ts_at(point: Json) -> Int

import "db/oxitsdb"
ts_at(JObj(Cons(Field("ts", JInt(1700000000000)), Nil)))   # => 1700000000000

fn ts_value(point: Json) -> Float

import "db/oxitsdb"
ts_value(JObj(Cons(Field("value", JNum(21.5)), Nil)))   # => 21.5

fn ts_written(answer: Json) -> Int

import "db/oxitsdb"
ts_written(JObj(Cons(Field("written", JInt(3)), Nil)))   # => 3