#influxdb API reference

An InfluxDB client over http for both major API generations: write measurements as line-protocol points and run queries, getting back a parsed result. The push counterpart to a scrape.

Two selectable backends under one Client (stance 1: one module, one version discriminator). A 1.x client (client / clientWith) writes to /write?db=... with optional Basic auth and queries InfluxQL over /query (query). A 2.x / 3.x client (client2) writes to /api/v2/write?org=...&bucket=... with Authorization: Token <token> auth and queries Flux over /api/v2/query (queryFlux). write dispatches on the client's version, so the same call serves both; the line protocol is identical across versions, so line is reused verbatim.

A Point is built with value-semantic builders (point / tag / field / intField / stringField / boolField / at), each returning a fresh Point, then rendered to a line-protocol line by line (or sent by write). Field types are carried as pre-rendered fragments, so one point can mix float / int / string / bool fields despite Jennifer's homogeneous maps. Needs the default jennifer binary (http over net); a failed request throws Error{kind: "influxdb"} (a 2.x client's token is redacted from it).

Import with import "influxdb.j" as influxdb;. See the influxdb guide for prose and examples.

#Functions

#influxdb.at(p as Point, unixNanos as int)

Set an explicit timestamp in nanoseconds since the Unix epoch. Returns a fresh point.

Parameters

• p {Point} - the point
• unixNanos {int} - the timestamp in nanoseconds

Returns {Point} - a timestamped point

#influxdb.atTime(p as Point, t as time.Time)

Set the timestamp from a time.Time. Returns a fresh point.

Parameters

• p {Point} - the point
• t {time.Time} - the timestamp

Returns {Point} - a timestamped point

#influxdb.boolField(p as Point, key as string, value as bool)

Add a boolean field. Returns a fresh point.

Parameters

• p {Point} - the point
• key {string} - the field key
• value {bool} - the field value

Returns {Point} - a point with the field added

#influxdb.client(url as string, db as string)

Open a client to a database with no authentication.

Parameters

• url {string} - the base URL (e.g. "http://localhost:8086")
• db {string} - the database name

Returns {Client} - a ready client

#influxdb.client2(url as string, org as string, bucket as string, token as string)

Open an InfluxDB 2.x / 3.x client: token auth, addressing data by organization + bucket. write posts to /api/v2/write and queryFlux runs Flux over /api/v2/query.

Parameters

• url {string} - the base URL (e.g. "http://localhost:8086")
• org {string} - the organization
• bucket {string} - the target bucket
• token {string} - the API token (sent as Authorization: Token <token>)

Returns {Client} - a ready 2.x client

#influxdb.clientWith(url as string, db as string, user as string, password as string)

Open a 1.x client with HTTP Basic-auth credentials.

Parameters

• url {string} - the base URL
• db {string} - the database name
• user {string} - the username
• password {string} - the password

Returns {Client} - a ready client

#influxdb.field(p as Point, key as string, value as float)

Add a float field. Returns a fresh point.

Parameters

• p {Point} - the point
• key {string} - the field key
• value {float} - the field value

Returns {Point} - a point with the field added

#influxdb.intField(p as Point, key as string, value as int)

Add an integer field (rendered with the line-protocol i suffix). Returns a fresh point.

Parameters

• p {Point} - the point
• key {string} - the field key
• value {int} - the field value

Returns {Point} - a point with the field added

#influxdb.line(p as Point)

Render a point to one line-protocol line.

Parameters

• p {Point} - the point

Returns {string} - the line-protocol line

Throws

• {Error} - kind "influxdb" if the point has no fields

#influxdb.point(measurement as string)

Start a point for a measurement (no tags or fields yet).

Parameters

• measurement {string} - the measurement name

Returns {Point} - a fresh point

#influxdb.query(c as Client, influxql as string)

Run an InfluxQL statement against a 1.x client's database and parse the result. (The 2.x query language is Flux - see queryFlux.)

Parameters

• c {Client} - the client
• influxql {string} - the InfluxQL statement (e.g. SELECT * FROM cpu)

Returns {Result} - the parsed series

Throws

• {Error} - kind "influxdb" on a request failure or a query error

#influxdb.queryFlux(c as Client, flux as string)

Run a Flux query against a 2.x client's organization and return the raw response body: InfluxDB answers a Flux query with annotated CSV (RFC 4180 with #datatype / #group / #default header rows), not JSON, so this returns it verbatim - parse it with the csv module. Posts the script to /api/v2/query?org=... under application/vnd.flux.

Parameters

• c {Client} - a 2.x client (from client2)
• flux {string} - the Flux script

Returns {string} - the annotated-CSV response body

Throws

• {Error} - kind "influxdb" on a non-2xx response (token redacted)

#influxdb.stringField(p as Point, key as string, value as string)

Add a string field (double-quoted, escaped). Returns a fresh point.

Parameters

• p {Point} - the point
• key {string} - the field key
• value {string} - the field value

Returns {Point} - a point with the field added

#influxdb.tag(p as Point, key as string, value as string)

Add a tag (indexed string metadata). Returns a fresh point.

Parameters

• p {Point} - the point
• key {string} - the tag key
• value {string} - the tag value

Returns {Point} - a point with the tag added

#influxdb.write(c as Client, points as list of Point)

Write points to the client's target (line protocol, nanosecond precision). Dispatches on the client's version: a 1.x client posts to /write?db=..., a 2.x client to /api/v2/write?org=...&bucket=....

Parameters

• c {Client} - the client
• points {list of Point} - the points to write

Throws

• {Error} - kind "influxdb" on a non-2xx response (2.x token redacted)

#Structs

#influxdb.Client

A client for either API generation. A 1.x client carries db and optional Basic-auth user / password; a 2.x client carries org / bucket and a token. version selects which set is used (unused fields stay "").

#influxdb.Point

A line-protocol point under construction. Tags and fields are held as pre-rendered, escaped key=value fragments so a point can mix field types.

#influxdb.Result

A parsed query result: the flattened series across every statement.

#influxdb.Series

One result series: its measurement name, its GROUP BY tag set, the column names, and the rows (each cell stringified).

#Enums

#influxdb.Version

The API generation a Client targets: influxdb.Version.V1 (InfluxDB 1.x - /write?db=... + InfluxQL, optional Basic auth) or influxdb.Version.V2 (InfluxDB 2.x / 3.x - /api/v2/write?org=...&bucket=... + Flux, token auth). The backend selector write dispatches on; the zero value is V1.