What a time comparand is, as InfluxDB 3 reads it (verified against Core):
- a quoted string is read as Arrow reads a timestamp:
YYYY-MM-DD, then optionallyT,tor a space,HH:MM:SS(:60is the next minute), a fraction (digits past the ninth are dropped) and a zone —Z,z, a fixed offset (+01:00,+0100,+01, after any blanks) or a name of the time zone database, which is case sensitive: the ones that are UTC (UTC,GMT,Zulu,UCT,Universal,Greenwich,GMT0,GMT+0,GMT-0and the same underEtc/),Etc/GMT+1toEtc/GMT+12(the sign is inverted: UTC minus that many hours) andEtc/GMT-1toEtc/GMT-14, and the fixed offsetsEST,MSTandHST. A string it cannot read is the optimizer's 500 naming why (timestamp must contain at least 10 characters,error parsing date,invalid timestamp separator,error parsing time,Invalid timezone "..."), and an instant outside theInt64nanoseconds is its overflow error now(), offset by+/-INTERVAL 'N unit'terms- a
$name, bound byInfluxElixir.Client.Local.SQLBind: a string is read as above, a null is unknown, a number or boolean is the planner's type error NULL, which compares as unknown- a bare number is the planner's type error, worded by the caller
The optimizer folds a constant after the planner has typed the whole
query, so an unreadable string is kept in the parsed query as
{:invalid_time, error} and raised by first_invalid/1 once the type
checks have passed. What the double cannot model — a time zone whose offset
changes with the date — is the same marker carrying a Client.Local:
refusal.
Summary
Types
A time comparand: nanoseconds since the epoch, now() plus an offset,
null, a $name still to bind, a bare number of the given type (an error
once the clause is known) or an unreadable string.
What comparand/1 returns.
Functions
A time BETWEEN once its bounds are known: a bare number fails it, naming
the first bound that has one.
A comparand as a bound: a bare number stays {:number, type} and an
unreadable one becomes {:invalid_time, error}, for the clause to settle.
Reads the text of a time comparand. {:error, {:number, type}} is a bare
number of that type, for the caller to word as its clause does.
The engine's type error for time compared with something that is not a
timestamp.
The first unreadable string among the time comparands of a WHERE, in
the order written, as the optimizer's error; :ok when there is none.
The first type error kept in a WHERE (a time compared with a number,
see InfluxElixir.Client.Local.SQLWhere.deferred_clause/1), in the order
written; :ok when there is none. A statement that is not planned
against a schema raises it as soon as it is parsed.
A time IN list once its items are known: a bare number fails the whole
list, which the engine words with every item's type, a string being Utf8.
An interval as nanoseconds: "N unit" with the unit one of second,
minute, hour or day (plural or not).
What a bound parameter is as a time comparand.
Whether the bound is a $name still to bind.
Types
@type bound() :: integer() | {:now, integer()} | nil | {:param, binary()} | {:param, binary(), :left} | {:number, binary()} | {:invalid_time, InfluxElixir.Client.Local.SQLError.t()}
A time comparand: nanoseconds since the epoch, now() plus an offset,
null, a $name still to bind, a bare number of the given type (an error
once the clause is known) or an unreadable string.
@type comparand() :: {:ok, bound()} | {:error, {:number, binary()} | InfluxElixir.Client.Local.SQLError.t()}
What comparand/1 returns.
Functions
@spec between(:between | :not_between, bound(), bound()) :: {:ok, {atom(), binary(), {bound(), bound()}}} | {:error, InfluxElixir.Client.Local.SQLError.t()}
A time BETWEEN once its bounds are known: a bare number fails it, naming
the first bound that has one.
A comparand as a bound: a bare number stays {:number, type} and an
unreadable one becomes {:invalid_time, error}, for the clause to settle.
Reads the text of a time comparand. {:error, {:number, type}} is a bare
number of that type, for the caller to word as its clause does.
@spec comparison_type_error(binary(), binary(), binary()) :: InfluxElixir.Client.Local.SQLError.t()
The engine's type error for time compared with something that is not a
timestamp.
@spec first_invalid([term()]) :: :ok | {:error, InfluxElixir.Client.Local.SQLError.t()}
The first unreadable string among the time comparands of a WHERE, in
the order written, as the optimizer's error; :ok when there is none.
@spec first_type_error([term()]) :: :ok | {:error, InfluxElixir.Client.Local.SQLError.t()}
The first type error kept in a WHERE (a time compared with a number,
see InfluxElixir.Client.Local.SQLWhere.deferred_clause/1), in the order
written; :ok when there is none. A statement that is not planned
against a schema raises it as soon as it is parsed.
@spec in_list([bound()]) :: {:ok, [bound()]} | {:error, InfluxElixir.Client.Local.SQLError.t()}
A time IN list once its items are known: a bare number fails the whole
list, which the engine words with every item's type, a string being Utf8.
@spec interval(binary()) :: {:ok, pos_integer()} | {:error, InfluxElixir.Client.Local.SQLError.t()}
An interval as nanoseconds: "N unit" with the unit one of second,
minute, hour or day (plural or not).
What a bound parameter is as a time comparand.
Whether the bound is a $name still to bind.