InfluxElixir.Flight.Client (InfluxElixir v0.1.17)

Arrow Flight gRPC client for high-throughput query transport.

Connects to an InfluxDB v3 Flight endpoint, encodes SQL queries as JSON-bearing Ticket messages, streams back FlightData chunks via the DoGet RPC, and delegates binary decoding to InfluxElixir.Flight.Reader.

Transport

InfluxDB v3 exposes its Flight service on the same host as the HTTP API, typically port 443 (TLS). The host in the connection map must be the plain hostname (no scheme); TLS is configured via the :tls option.

Authentication

Bearer-token auth is passed as gRPC metadata on every call:

Authorization: Bearer <token>

Example

conn = %{host: "us-east-1.influxdb.io", token: "my-token",
         database: "mydb", port: 443}

{:ok, rows} = InfluxElixir.Flight.Client.query(conn, "SELECT * FROM cpu LIMIT 10")

Options

:timeout — per-call timeout in milliseconds (default: 30_000)
:connect_timeout — bound on the gRPC channel establishment phase (default: same value as :timeout). Without this bound, a stuck TLS handshake against an unresponsive host can hang far longer than the in-stream :timeout would suggest.
:tls — true to use TLS (default: true when port is 443)

Summary

Types

connection()

A connection map with the keys used by this client.

Functions

build_ticket(database, sql)

Builds a Ticket struct for the given database and SQL query.

build_ticket_payload(database, sql)

Builds the JSON-encoded ticket payload for an InfluxDB v3 SQL query.

query(connection, sql, opts \\ [])

Executes a SQL query against InfluxDB v3 via Arrow Flight DoGet.

Types

connection()

@type connection() :: %{
  :host => binary(),
  :token => binary(),
  :database => binary(),
  optional(:port) => non_neg_integer()
}

A connection map with the keys used by this client.

:host — hostname of the InfluxDB Flight endpoint (required)
:token — bearer token for authentication (required)
:database — InfluxDB database / bucket name (required)
:port — gRPC port (default: 443)

Functions

build_ticket(database, sql)

@spec build_ticket(binary(), binary()) :: InfluxElixir.Flight.Proto.Ticket.t()

Builds a Ticket struct for the given database and SQL query.

Useful for constructing tickets before calling do_get directly or for inspecting the wire format in tests.

Parameters

database — target InfluxDB database name
sql — SQL query string

Example

iex> t = InfluxElixir.Flight.Client.build_ticket("mydb", "SELECT 1")
iex> t.ticket |> Jason.decode!() |> Map.fetch!("database")
"mydb"

build_ticket_payload(database, sql)

@spec build_ticket_payload(binary(), binary()) :: binary()

Builds the JSON-encoded ticket payload for an InfluxDB v3 SQL query.

Exposed for testing and introspection purposes.

Parameters

database — target InfluxDB database name
sql — SQL query string

Example

iex> payload = InfluxElixir.Flight.Client.build_ticket_payload("mydb", "SELECT 1")
iex> Jason.decode!(payload)
%{"database" => "mydb", "sql_query" => "SELECT 1", "query_type" => "sql"}

query(connection, sql, opts \\ [])

@spec query(connection(), binary(), keyword()) :: {:ok, [map()]} | {:error, term()}

Executes a SQL query against InfluxDB v3 via Arrow Flight DoGet.

Builds a Ticket with a JSON payload understood by InfluxDB v3, opens a gRPC channel, streams FlightData messages, and decodes them into a list of row maps.

Parameters

connection — map with :host, :token, :database, and optional :port
sql — SQL query string
opts — keyword options

Options

:timeout — milliseconds to wait for the full stream (default: 30_000)
:tls — force TLS on/off; inferred from port when omitted

Returns

{:ok, [map()]} — list of row maps (column name → value)
{:error, term()} — gRPC or decode error

Example

conn = %{host: "cloud2.influxdata.com", token: "my-tok", database: "sensors"}
{:ok, rows} = InfluxElixir.Flight.Client.query(conn, "SELECT * FROM cpu LIMIT 5")