InfluxElixir.Client.Local.SQLFunctions (InfluxElixir v0.1.40)

Copy Markdown View Source

The scalar math functions Client.Local evaluates in SQL expressions, wherever an expression stands (WHERE, the select list, ORDER BY, an aggregate's argument), as InfluxDB 3 does (verified against Core):

  • abs(x) — the magnitude, in the argument's type
  • round(x), round(x, n) — half away from zero (round(-2.5) is -3.0), to n decimal places (negative n rounds left of the point: round(1234.5678, -2) is 1200.0); always a float, and a zero result keeps the sign of its argument (round(-0.3) is -0.0)
  • trunc(x) — toward zero (trunc(-2.75) is -2.0), always a float; a zero it leaves keeps the sign of a fraction (trunc(-0.4) is -0.0) but not of a zero (trunc(-0.0) is 0.0). trunc(x, n) is round(x, n): the engine rounds there (trunc(1234.5678, 2) is 1234.57)
  • floor(x), ceil(x) — always a float

An argument that is a decimal (an Int64 with a UInt64) is read as a double, except by abs, which keeps it. An infinity or a NaN is passed on (round(inf) is infinity); round(x, n) that overflows is null on the engine, and here (see InfluxElixir.Client.Local.SQLNumber).

A null argument makes the result null. Names are case-insensitive.

The engine checks the arguments' types when it plans the query, so a wrong one fails the query even when no row would reach the call (check/3). The message depends on where the call stands: in WHERE it carries the type_coercion prefix, in ORDER BY it is cut after its first sentence, and in the select list it has neither. A call in WHERE under a CAST, IS [NOT] NULL, BETWEEN, LIKE, IN or NOT is cut after its first sentence too (:where_cut; see InfluxElixir.Client.Local.SQLPlan for the order the engine reports them in). floor and ceil with a second argument are the engine's 405.

Summary

Functions

Evaluates a call the planner has accepted (check/3), its arguments already evaluated: numbers (see InfluxElixir.Client.Local.SQLNumber), or nil, which makes the result nil.

The engine's planning error for a call, given its arguments' Arrow types (nil where unknown, which is never refused), or :ok.

Whether an Arrow type name is one of the engine's numeric types.

The function a name (any case) calls, or nil for any other name.

DataFusion's NativeType for an Arrow type, as its messages name it.

The Arrow type an expression has, given the columns' types, or nil when it cannot be known.

Types

context()

@type context() :: :where | :where_cut | :select | :order_by

name()

@type name() :: :abs | :round | :trunc | :floor | :ceil

Functions

call(name, args)

Evaluates a call the planner has accepted (check/3), its arguments already evaluated: numbers (see InfluxElixir.Client.Local.SQLNumber), or nil, which makes the result nil.

check(name, types, context)

@spec check(name(), [binary() | nil], context()) :: :ok | {:error, map()}

The engine's planning error for a call, given its arguments' Arrow types (nil where unknown, which is never refused), or :ok.

is_numeric_type(type)

(macro)

Whether an Arrow type name is one of the engine's numeric types.

lookup(name)

@spec lookup(binary()) :: name() | nil

The function a name (any case) calls, or nil for any other name.

native(type)

@spec native(binary()) :: binary()

DataFusion's NativeType for an Arrow type, as its messages name it.

type_of(arg1, columns)

@spec type_of(InfluxElixir.Client.Local.SQLParser.expr(), %{
  required(binary()) => binary()
}) ::
  binary() | nil

The Arrow type an expression has, given the columns' types, or nil when it cannot be known.