# Examples

The examples directory shows QuackDB as an Elixir-native bridge to DuckDB analytics.

Examples start a local DuckDB Quack server with `QuackDB.Server` unless `QUACKDB_URI` is set. This keeps the examples runnable without asking you to manually start DuckDB.

## Query observability

[`examples/query_observability.exs`](https://github.com/elixir-vibe/quackdb/blob/master/examples/query_observability.exs) attaches telemetry handlers and prints query, append, and fetch timings.

```sh
cd /tmp
elixir /path/to/quackdb/examples/query_observability.exs
```

## Source sampling

[`examples/source_sampling.exs`](https://github.com/elixir-vibe/quackdb/blob/master/examples/source_sampling.exs) scans newline-delimited JSON with `QuackDB.Source`, wraps it in `USING SAMPLE`, queries it through Ecto, and profiles the sampled source with DuckDB `SUMMARIZE`.

```sh
cd /tmp
elixir /path/to/quackdb/examples/source_sampling.exs
```

## Dataframe analytics

[`examples/dataframe_analytics.exs`](https://github.com/elixir-vibe/quackdb/blob/master/examples/dataframe_analytics.exs) demonstrates:

1. deriving DuckDB DDL from an Ecto schema
2. appending an `Explorer.DataFrame` through native column append
3. querying with Ecto DSL
4. returning an Explorer dataframe

```sh
cd /tmp
elixir /path/to/quackdb/examples/dataframe_analytics.exs
```

## Append benchmark

[`examples/append_benchmark.exs`](https://github.com/elixir-vibe/quackdb/blob/master/examples/append_benchmark.exs) compares SQL inserts, native row/column append, Explorer dataframe append, and Ecto insert paths.

```sh
cd /tmp
SMOKE=1 ROWS=10 BATCH_SIZE=5 elixir /path/to/quackdb/examples/append_benchmark.exs
```

Remove `SMOKE=1` and increase `ROWS` for benchmark runs.

## Full-text search

[`examples/full_text_search.exs`](https://github.com/elixir-vibe/quackdb/blob/master/examples/full_text_search.exs) creates a DuckDB FTS index, runs direct SQL BM25 search, and runs the same search through Ecto fragments.

```sh
cd /tmp
elixir /path/to/quackdb/examples/full_text_search.exs
```

## Livebook analytics

[`examples/livebook_analytics.livemd`](https://github.com/elixir-vibe/quackdb/blob/master/examples/livebook_analytics.livemd) is an interactive notebook using Explorer, Table.Reader, VegaLite, telemetry, and a local `QuackDB.Server`.

## Spatial WMS

[`examples/spatial_wms/`](https://github.com/elixir-vibe/quackdb/tree/master/examples/spatial_wms) is a minimal Ash + Ecto + Plug/Bandit application serving DuckDB Spatial rows through a WMS-like GeoJSON endpoint.

```sh
cd examples/spatial_wms
mix run --no-halt
```

## Existing servers

To use an existing DuckDB Quack server instead of `QuackDB.Server`, set:

```sh
QUACKDB_URI='http://[::1]:9494'
QUACKDB_TOKEN=super_secret
```