QuackDB.Explorer (quackdb v0.3.0)

Optional Explorer integration for QuackDB results.

This module requires the optional :explorer dependency at runtime. It materializes QuackDB query results in Elixir and then builds an Explorer.DataFrame. It is not a zero-copy Arrow IPC path.

Summary

Types

dataframe_option()

insert_dataframe_option()

Functions

dataframe(connection, statement_or_query, params \\ [], options \\ [])

Runs a QuackDB query and returns an Explorer.DataFrame.

dataframe!(connection, statement, params \\ [], options \\ [])

Runs a QuackDB query and returns an Explorer.DataFrame, raising on error.

from_columns(columns, options \\ [])

Converts a QuackDB.Columns struct into an Explorer.DataFrame.

from_columns!(columns, options \\ [])

Converts a QuackDB.Columns struct into an Explorer.DataFrame, raising on error.

from_result(result, options \\ [])

Converts a QuackDB.Result into an Explorer.DataFrame.

from_result!(result, options \\ [])

Converts a QuackDB.Result into an Explorer.DataFrame, raising on error.

insert_dataframe(connection, table, dataframe, options \\ [])

Appends an Explorer.DataFrame to a DuckDB table through Quack's native append protocol.

insert_dataframe!(connection, table, dataframe, options \\ [])

Appends an Explorer.DataFrame to a DuckDB table, raising on error.

Types

dataframe_option()

@type dataframe_option() :: {:dataframe, Keyword.t()} | {:query, Keyword.t()}

insert_dataframe_option()

@type insert_dataframe_option() ::
  {:columns, list()} | {:batch_size, pos_integer()} | {:schema, String.t()}

Functions

dataframe(connection, statement_or_query, params \\ [], options \\ [])

@spec dataframe(DBConnection.conn(), iodata() | term(), [term()] | Keyword.t(), [
  dataframe_option()
]) ::
  {:ok, Explorer.DataFrame.t()} | {:error, Exception.t()}

Runs a QuackDB query and returns an Explorer.DataFrame.

The query can be raw SQL iodata or an Ecto query. Use :query to pass QuackDB query options and :dataframe to pass options to Explorer.DataFrame.new/2.

dataframe!(connection, statement, params \\ [], options \\ [])

@spec dataframe!(DBConnection.conn(), iodata(), [term()], [dataframe_option()]) ::
  Explorer.DataFrame.t()

Runs a QuackDB query and returns an Explorer.DataFrame, raising on error.

from_columns(columns, options \\ [])

@spec from_columns(QuackDB.Columns.t(), Keyword.t()) ::
  {:ok, Explorer.DataFrame.t()} | {:error, Exception.t()}

Converts a QuackDB.Columns struct into an Explorer.DataFrame.

Options are passed to Explorer.DataFrame.new/2.

from_columns!(columns, options \\ [])

@spec from_columns!(QuackDB.Columns.t(), Keyword.t()) :: Explorer.DataFrame.t()

Converts a QuackDB.Columns struct into an Explorer.DataFrame, raising on error.

from_result(result, options \\ [])

@spec from_result(QuackDB.Result.t(), Keyword.t()) ::
  {:ok, Explorer.DataFrame.t()} | {:error, Exception.t()}

Converts a QuackDB.Result into an Explorer.DataFrame.

from_result!(result, options \\ [])

@spec from_result!(QuackDB.Result.t(), Keyword.t()) :: Explorer.DataFrame.t()

Converts a QuackDB.Result into an Explorer.DataFrame, raising on error.

insert_dataframe(connection, table, dataframe, options \\ [])

@spec insert_dataframe(
  DBConnection.conn(),
  String.t() | atom(),
  Explorer.DataFrame.t(),
  Keyword.t()
) ::
  {:ok, QuackDB.Result.t()} | {:error, Exception.t()}

Appends an Explorer.DataFrame to a DuckDB table through Quack's native append protocol.

This uses QuackDB.insert_columns/4 to preserve Explorer's columnar shape and avoid row materialization. Pass :columns to override inferred DuckDB types. :batch_size and :schema are forwarded to QuackDB.insert_columns/4.

insert_dataframe!(connection, table, dataframe, options \\ [])

@spec insert_dataframe!(
  DBConnection.conn(),
  String.t() | atom(),
  Explorer.DataFrame.t(),
  Keyword.t()
) ::
  QuackDB.Result.t()

Appends an Explorer.DataFrame to a DuckDB table, raising on error.