ExArrow.FlightSQL.Result (ex_arrow v0.6.0)

View Source

Materialized result from a Flight SQL query.

A Result is returned by ExArrow.FlightSQL.Client.query/2 after all record batches have been collected from the server. For large result sets, prefer ExArrow.FlightSQL.Client.stream_query/2, which returns a lazy ExArrow.Stream instead.

Fields

  • :schema — the Arrow schema (ExArrow.Schema.t()) describing column names and types.
  • :batches — the list of ExArrow.RecordBatch.t() that make up the result. Each batch holds data in native Arrow memory; nothing is copied to the Elixir heap.
  • :num_rows — total row count across all batches.

Examples

{:ok, result} = ExArrow.FlightSQL.Client.query(client, "SELECT id, name FROM users")
result.num_rows  #=> 42
result.schema    #=> %ExArrow.Schema{...}
result.batches   #=> [%ExArrow.RecordBatch{...}, ...]

Conversion

Use to_dataframe/1 to convert the result into an Explorer DataFrame (requires the optional :explorer dependency):

{:ok, df} = ExArrow.FlightSQL.Result.to_dataframe(result)

Summary

Types

t()

Functions

from_stream(stream)

Build a Result by collecting all batches from a stream.

to_dataframe(result)

Convert this result to an Explorer DataFrame.

to_tensor(result, column)

Convert a single column from this result to an Nx tensor.

Types

t()

@type t() :: %ExArrow.FlightSQL.Result{
  batches: [ExArrow.RecordBatch.t()],
  num_rows: non_neg_integer(),
  schema: ExArrow.Schema.t()
}

Functions

from_stream(stream)

@spec from_stream(ExArrow.Stream.t()) ::
  {:ok, t()} | {:error, ExArrow.FlightSQL.Error.t()}

Build a Result by collecting all batches from a stream.

This is the implementation of query/2 — iterating the Flight SQL stream to completion and assembling the result struct. Callers should not need this directly.

Returns {:error, %ExArrow.FlightSQL.Error{}} if schema inspection or any batch read fails mid-stream.

to_dataframe(result)

@spec to_dataframe(t()) :: {:ok, term()} | {:error, ExArrow.FlightSQL.Error.t()}

Convert this result to an Explorer DataFrame.

Requires the optional :explorer dependency. The conversion uses an Arrow IPC round-trip through ExArrow.IPC.Writer and ExArrow.Explorer.from_stream/1. Type support is determined by Explorer/Polars; columns with types that Polars does not support (e.g. decimal128, nested map) may cause a conversion error.

Performance note

This function serialises all batches to an in-memory IPC binary then reads them back through the Explorer bridge. For very large results consider converting the lazy stream directly with ExArrow.Explorer.from_stream/1 after stream_query/2, which avoids materialising the full result first.

Returns {:error, %ExArrow.FlightSQL.Error{code: :conversion_error}} if Explorer is not available or if conversion fails.

Examples

{:ok, df} = ExArrow.FlightSQL.Result.to_dataframe(result)

to_tensor(result, column)

@spec to_tensor(t(), String.t()) ::
  {:ok, term()} | {:error, ExArrow.FlightSQL.Error.t()}

Convert a single column from this result to an Nx tensor.

Requires the optional :nx dependency and a numeric column type.

Returns {:error, %ExArrow.FlightSQL.Error{code: :conversion_error}} if Nx is not available, the column is not found, or its type is not supported.

Only the first batch is converted. For multi-batch results use stream_query/2 and convert batch-by-batch.

Examples

{:ok, tensor} = ExArrow.FlightSQL.Result.to_tensor(result, "price")