Line protocol parser for InfluxElixir.Client.Local.
Turns a line-protocol payload into point maps, honouring the escaping rules of the format (escaped spaces, commas, equals signs, backslashes and quotes) and the write precision. Each line is parsed on its own so a caller can store the good lines and report the bad ones, which is what InfluxDB 3 does ("partial write of line protocol occurred").
Per-line rules verified against InfluxDB 3 Core: an integer must fit in
64 bits (u marks an unsigned one), time is a reserved column, and a
key cannot be both a tag and a field on one line.
Summary
Types
Whose rules apply. InfluxDB 3 refuses a key that is
both tag and field (and, in the store, time as a column); InfluxDB 2
drops a time field silently and lets a
tag and a field share a name.
One rejected line, in the shape InfluxDB 3's partial-write response lists (the original line is truncated to 20 characters, as the engine does).
A line's outcome: the point with its line number and text, or the error.
A parsed point: fields and tags as string-keyed maps, timestamp in ns.
The unit numeric timestamps are in; :auto guesses it from the magnitude.
Functions
The engine's name for a column kind: iox::column_type::tag or
iox::column_type::field::<integer | uinteger | float | string | boolean>.
Builds a line_error/0 the way InfluxDB 3 reports one. The full line
is kept under :line for InfluxDB 2's report, which quotes it whole.
Parses a line-protocol payload line by line.
Builds the line_error/0 for a schema error. InfluxDB 3 does not echo
the raw line for those but the line as it parsed it (verified): single
spaces, floats printed shortest and without an exponent (2.0 → 2,
1e3 → 1000), strings unquoted, then cut to 20 characters. Parse
errors keep the raw line (line_error/3).
Undoes line-protocol escaping in a measurement name (\, \,, \\).
InfluxDB 2's name for a field type (integer, unsigned, float, string, boolean).
Types
@type dialect() :: :v3 | :v2
Whose rules apply. InfluxDB 3 refuses a key that is
both tag and field (and, in the store, time as a column); InfluxDB 2
drops a time field silently and lets a
tag and a field share a name.
@type line_error() :: %{ error_message: binary(), line_number: pos_integer(), original_line: binary(), line: binary() }
One rejected line, in the shape InfluxDB 3's partial-write response lists (the original line is truncated to 20 characters, as the engine does).
@type line_result() :: {:ok, point(), pos_integer(), binary()} | {:error, line_error()}
A line's outcome: the point with its line number and text, or the error.
@type point() :: %{ measurement: binary(), tags: %{required(binary()) => binary()}, fields: %{required(binary()) => term()}, timestamp: integer() | nil }
A parsed point: fields and tags as string-keyed maps, timestamp in ns.
@type precision() :: :nanosecond | :microsecond | :millisecond | :second | :auto
The unit numeric timestamps are in; :auto guesses it from the magnitude.
Functions
The engine's name for a column kind: iox::column_type::tag or
iox::column_type::field::<integer | uinteger | float | string | boolean>.
@spec line_error(binary(), pos_integer(), binary()) :: line_error()
Builds a line_error/0 the way InfluxDB 3 reports one. The full line
is kept under :line for InfluxDB 2's report, which quotes it whole.
@spec parse_lines(binary(), precision(), dialect()) :: {:ok, [line_result()]} | {:error, map()}
Parses a line-protocol payload line by line.
Blank lines and # comments are skipped. precision is a precision/0:
a unit scales numeric timestamps to nanoseconds and :auto guesses the unit
from the magnitude as InfluxDB 3 does. A point without a timestamp keeps nil; the
caller assigns the server time. A newline inside a quoted string field
value is part of the value, as the engine reads it.
Returns {:error, ...} only for a payload with no lines at all ("incoming
write was empty" on the engine); every other problem is a per-line
{:error, line_error} in the list, numbered as the engine numbers it.
@spec schema_error(binary(), pos_integer(), binary()) :: line_error()
Builds the line_error/0 for a schema error. InfluxDB 3 does not echo
the raw line for those but the line as it parsed it (verified): single
spaces, floats printed shortest and without an exponent (2.0 → 2,
1e3 → 1000), strings unquoted, then cut to 20 characters. Parse
errors keep the raw line (line_error/3).
Undoes line-protocol escaping in a measurement name (\, \,, \\).
InfluxDB 2's name for a field type (integer, unsigned, float, string, boolean).