ExArrow.Flight.Client (ex_arrow v0.4.0)

Arrow Flight client: connect to a Flight server and exchange Arrow data.

Delegates to the configured implementation (see :flight_client_impl in application config). The default implementation uses NIFs backed by arrow-flight + tonic.

Connection

{:ok, client} = ExArrow.Flight.Client.connect("localhost", 9999, [])

Options accepted by connect/3:

:connect_timeout_ms — TCP connection timeout in milliseconds (default: 0, no timeout).
:tls — transport security (see below).

TLS

Transport security is controlled by the :tls option and defaults to a secure setting for non-loopback hosts:

`:tls` value	behaviour
not set, loopback host	plaintext HTTP/2 (auto; localhost / 127.x / ::1)
not set, remote host	TLS with native OS certificate store (auto, secure default)
`false`	plaintext HTTP/2 regardless of host
`true`	TLS with native OS certificate store
`[ca_cert_pem: pem]`	TLS verified against the given PEM-encoded CA certificate

Using tls: false for a non-loopback host is permitted but exposes traffic on untrusted networks — prefer the default or an explicit tls: true.

Examples

# Remote server — TLS enabled automatically
{:ok, client} = ExArrow.Flight.Client.connect("flight.example.com", 9999, [])

# Explicit TLS with a custom CA certificate
pem = File.read!("/etc/ssl/my-ca.pem")
{:ok, client} = ExArrow.Flight.Client.connect("internal.svc", 9999, tls: [ca_cert_pem: pem])

# Explicit plaintext (loopback only, development)
{:ok, client} = ExArrow.Flight.Client.connect("localhost", 9999, tls: false)

Timeouts and cancellation

Use :connect_timeout_ms to bound the initial connection. Per-call timeouts and retry policies are not yet exposed through the public API; see the Flight guide in docs/flight_guide.md for patterns to implement these at the call site.

Summary

Types

t()

Functions

connect(host, port, opts \\ [])

Connects to a Flight server at host:port.

do_action(client, action_type, action_body \\ <<>>)

Executes the named action on the server with an optional binary body.

do_get(client, ticket)

Retrieves data for ticket as a stream of record batches.

do_put(client, schema, batches, opts \\ [])

Uploads batches to the server under the given schema.

get_flight_info(client, descriptor)

Returns metadata for the flight identified by descriptor.

get_schema(client, descriptor)

Returns the Arrow schema for the flight identified by descriptor.

list_actions(client)

Lists the action types supported by the server.

list_flights(client, criteria \\ <<>>)

Lists available flights matching criteria (empty binary = all).

Types

t()

@opaque t()

Functions

connect(host, port, opts \\ [])

@spec connect(String.t(), non_neg_integer(), keyword()) ::
  {:ok, t()} | {:error, term()}

Connects to a Flight server at host:port.

Options:

:connect_timeout_ms — connection timeout in milliseconds (0 = no limit).
:tls — true | false | [ca_cert_pem: pem]; see module doc for details. Defaults to :system_certs for non-loopback hosts and plaintext for loopback.

do_action(client, action_type, action_body \\ <<>>)

@spec do_action(t(), String.t(), binary()) :: {:ok, [binary()]} | {:error, term()}

Executes the named action on the server with an optional binary body.

Returns {:ok, results} where results is a list of binary response bodies, or {:error, reason} on failure.

Examples

{:ok, ["pong"]} = ExArrow.Flight.Client.do_action(client, "ping", <<>>)
{:ok, []}       = ExArrow.Flight.Client.do_action(client, "clear", <<>>)

do_get(client, ticket)

@spec do_get(t(), term()) :: {:ok, ExArrow.Stream.t()} | {:error, term()}

Retrieves data for ticket as a stream of record batches.

do_put(client, schema, batches, opts \\ [])

@spec do_put(t(), ExArrow.Schema.t(), Enumerable.t(), keyword()) ::
  :ok | {:error, term()}

Uploads batches to the server under the given schema.

Options

:descriptor — {:cmd, binary()} or {:path, [String.t()]} to route the dataset to a named ticket on the server. Defaults to :none which causes the server to use the legacy "echo" ticket.

Examples

# Store under ticket "sales_2024"
:ok = ExArrow.Flight.Client.do_put(client, schema, batches,
        descriptor: {:cmd, "sales_2024"})

# Store under path ["datasets", "metrics"]
:ok = ExArrow.Flight.Client.do_put(client, schema, batches,
        descriptor: {:path, ["datasets", "metrics"]})

get_flight_info(client, descriptor)

@spec get_flight_info(t(), ExArrow.Flight.ClientBehaviour.descriptor()) ::
  {:ok, ExArrow.Flight.FlightInfo.t()} | {:error, term()}

Returns metadata for the flight identified by descriptor.

descriptor is {:cmd, binary()} or {:path, [String.t()]}.

get_schema(client, descriptor)

@spec get_schema(t(), ExArrow.Flight.ClientBehaviour.descriptor()) ::
  {:ok, ExArrow.Schema.t()} | {:error, term()}

Returns the Arrow schema for the flight identified by descriptor.

list_actions(client)

@spec list_actions(t()) :: {:ok, [ExArrow.Flight.ActionType.t()]} | {:error, term()}

Lists the action types supported by the server.

Returns a list of ExArrow.Flight.ActionType structs.

list_flights(client, criteria \\ <<>>)

@spec list_flights(t(), binary()) ::
  {:ok, [ExArrow.Flight.FlightInfo.t()]} | {:error, term()}

Lists available flights matching criteria (empty binary = all).

Returns a list of ExArrow.Flight.FlightInfo structs.