Struct LineProtocolBuilder

pub struct LineProtocolBuilder<B, S = BeforeMeasurement>
where
    B: BufMut,
{ /* private fields */ }

Implements a line protocol builder.

A LineProtocolBuilder is a statically-typed InfluxDB line protocol builder. It writes one or more lines of line protocol to a bytes::BufMut.

use influxdb_line_protocol::LineProtocolBuilder;
let lp = LineProtocolBuilder::new()
    .measurement("foo")
    .tag("bar", "baz")
    .field("qux", 42.0)
    .close_line();

assert_eq!(lp.build(), b"foo,bar=baz qux=42\n");

LineProtocolBuilder never returns runtime errors. Instead, it employs a type-level state machine to guarantee that users can’t build a syntactically-malformed line protocol batch.

This builder does not check for semantic errors. In particular, it does not check for duplicate tag and field names, nor it does enforce naming restrictions on keys.

Attempts to consume the line protocol before closing a line yield compile-time errors:

let lp = LineProtocolBuilder::new()
    .measurement("foo")
    .tag("bar", "baz")

assert_eq!(lp.build(), b"foo,bar=baz qux=42\n");

and attempts to close_line the line without at least one field also yield compile-time errors:

let lp = LineProtocolBuilder::new()
    .measurement("foo")
    .tag("bar", "baz")
    .close_line();

Tags, if any, must be emitted before fields. This will fail to compile:

let lp = LineProtocolBuilder::new()
    .measurement("foo")
    .field("qux", 42.0);
    .tag("bar", "baz")
    .close_line();

and timestamps, if any, must be specified last before closing the line:

let lp = LineProtocolBuilder::new()
    .measurement("foo")
    .timestamp(1234)
    .field("qux", 42.0);
    .close_line();

(the negative examples part of the documentation is so verbose because it’s the only way to test compilation failures)

Implementations

impl LineProtocolBuilder<Vec<u8>, BeforeMeasurement>

pub fn new() -> Self

Creates a new LineProtocolBuilder with an empty buffer.

impl<B> LineProtocolBuilder<B, BeforeMeasurement>

where B: BufMut,

pub fn new_with(buf: B) -> Self

Like new but appending to an existing BufMut.

pub fn measurement( self, measurement: &str, ) -> LineProtocolBuilder<B, AfterMeasurement>

Provide the measurement name.

It returns a new builder whose type allows only setting tags and fields.

pub fn build(self) -> B

Finish building the line protocol and return the inner buffer.

impl<B> LineProtocolBuilder<B, AfterMeasurement>

where B: BufMut,

pub fn tag(self, tag_key: &str, tag_value: &str) -> Self

Add a tag (key + value).

Tag keys and tag values will be escaped according to the rules defined in [the special characters documentation].

pub fn field<F>( self, field_key: &str, field_value: F, ) -> LineProtocolBuilder<B, AfterField>

where F: FieldValue,

Add a field (key + value).

Field keys will be escaped according to the rules defined in [the special characters documentation].

Field values will encoded according to the rules defined in [the data types and formats documentation].

This function is called for the first field only. It returns a new builder whose type no longer allows adding tags.

impl<B> LineProtocolBuilder<B, AfterField>

where B: BufMut,

pub fn field<F: FieldValue>(self, field_key: &str, field_value: F) -> Self

Add a field (key + value).

This function is called for the second and subsequent fields.

pub fn timestamp(self, ts: i64) -> LineProtocolBuilder<B, AfterTimestamp>

Provide a timestamp.

It returns a builder whose type allows only closing the line.

The precision of the timestamp is by default nanoseconds (ns) but the unit can be changed when performing the request that carries the line protocol body. Setting the unit is outside of the scope of a line protocol builder.

pub fn close_line(self) -> LineProtocolBuilder<B, BeforeMeasurement>

Closing a line is required before starting a new one or finishing building the batch.

impl<B> LineProtocolBuilder<B, AfterTimestamp>

where B: BufMut,

pub fn close_line(self) -> LineProtocolBuilder<B, BeforeMeasurement>

Closing a line is required before starting a new one or finishing building the batch.

Trait Implementations

impl<B, S: Debug> Debug for LineProtocolBuilder<B, S>

where B: BufMut + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B, S: Default> Default for LineProtocolBuilder<B, S>

where B: BufMut + Default,

fn default() -> LineProtocolBuilder<B, S>

Returns the “default value” for a type.