# `QuackDB.Explorer`
[🔗](https://github.com/elixir-vibe/quackdb/blob/main/lib/quack_db/explorer.ex#L2)

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.

# `dataframe_option`

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

# `insert_dataframe_option`

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

# `dataframe`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

```elixir
@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`

```elixir
@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!`

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

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

# `insert_dataframe`

```elixir
@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 by streaming binary vectors into an `INSERT`.

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!`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*