@spec column_names(t()) :: [String.t()]

Returns the column names of this batch.

Derived from the batch's schema. Equivalent to ExArrow.Schema.field_names(ExArrow.RecordBatch.schema(batch)).

Examples

{:ok, ipc_bin} = ExArrow.Native.ipc_test_fixture_binary()
{:ok, stream}  = ExArrow.IPC.Reader.from_binary(ipc_bin)
batch = ExArrow.Stream.next(stream)

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

Concatenate a list of record batches that share the same schema into one batch.

Returns {:ok, batch} or {:error, message} (e.g. empty list or schema mismatch).

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

Create a RecordBatch from column-oriented binary data.

Each column is provided as a raw binary paired with an Arrow dtype string and a shared row count. This constructor builds parameter batches for Flight SQL prepared statement binding.

Parameters

• names: list of column name strings
• binaries: list of column data binaries (one per column). See the supported dtypes table in the moduledoc for the wire format of each dtype.
• dtypes: list of Arrow dtype strings, one per column
• length: number of rows (must be the same for every column)

All four lists must have the same length and at least one entry.

Returns

• {:ok, %ExArrow.RecordBatch{}} on success
• {:error, message} if the inputs are inconsistent (mismatched list lengths, malformed binary, unknown dtype, invalid UTF-8 in a "utf8"/"large_utf8" column, etc.)

Examples

# Single int64 column with one row
{:ok, batch} = ExArrow.RecordBatch.from_columns(
  ["id"],
  [<<42::little-signed-64>>],
  ["s64"],
  1
)

# Mixed primitives
{:ok, batch} = ExArrow.RecordBatch.from_columns(
  ["id", "score"],
  [<<1::little-signed-64>>, <<3.14::little-float-64>>],
  ["s64", "f64"],
  1
)

# utf8 column with two rows ("hello", "world") using length-prefixed
# records: <<len::little-32, bytes::binary-size(len)>>
utf8 = <<5::little-32, "hello", 5::little-32, "world">>
{:ok, batch} = ExArrow.RecordBatch.from_columns(["s"], [utf8], ["utf8"], 2)

# timestamp_micros column
ts = <<1_700_000_000_000_000::little-signed-64>>
{:ok, batch} =
  ExArrow.RecordBatch.from_columns(["t"], [ts], ["timestamp_micros"], 1)

@spec from_lists([{String.t() | atom(), atom() | String.t(), list()}]) ::
  {:ok, t()} | {:error, String.t()}

Create a RecordBatch from named columns of Elixir lists.

Each column is a {name, dtype, values} triple. name may be a string or atom. dtype may be a from_columns/4 dtype string ("s64", "utf8", …) or the matching atom (:s64, :utf8, …). values is a list of scalar cells; all columns must have the same length.

Supports every dtype accepted by from_columns/4. Temporal and integer dtypes expect integer cells (days/ticks as in the wire format). Float dtypes accept integers or floats. Boolean expects true/false. Utf8 expects valid UTF-8 binaries; binary / large_binary accept any binary.

nil cells are rejected in 0.9 (no null-bitmap encoding yet). Nested lists, maps, and tuples as cells are rejected.

Packs into the from_columns/4 wire format and reuses that NIF path.

Examples

{:ok, batch} =
  ExArrow.RecordBatch.from_lists([
    {"id", :s64, [1, 2, 3]},
    {"name", :utf8, ["a", "b", "c"]}
  ])

{:error, _} =
  ExArrow.RecordBatch.from_lists([{"x", :s64, [1, nil]}])

@spec from_map(%{optional(String.t() | atom()) => list()}) ::
  {:ok, t()} | {:error, String.t()}

Create a RecordBatch from a map of column name => value list.

Keys are sorted lexicographically (after converting atom keys to strings) so the resulting schema order is stable. Value lists must all have the same length.

Dtypes are inferred from the cells of each column:

Empty columns and mixed incompatible cell types return {:error, message}. For explicit dtypes use from_lists/1.

Examples

{:ok, batch} =
  ExArrow.RecordBatch.from_map(%{"id" => [1, 2], "name" => ["a", "b"]})

@spec num_columns(t()) :: non_neg_integer()

Returns the number of columns in this batch.

Derived from the batch's schema; no separate NIF call is needed.

Examples

{:ok, ipc_bin} = ExArrow.Native.ipc_test_fixture_binary()
{:ok, stream}  = ExArrow.IPC.Reader.from_binary(ipc_bin)
batch = ExArrow.Stream.next(stream)
ExArrow.RecordBatch.num_columns(batch)  #=> 2

@spec num_rows(t()) :: non_neg_integer()

Returns the number of rows in this batch.

@spec schema(t()) :: ExArrow.Schema.t()

Returns the schema of this record batch.