# `Dux.Remote.Worker`
[🔗](https://github.com/elixir-dux/dux/blob/v0.3.0/lib/dux/remote/worker.ex#L1)

A DuckDB worker node in a distributed Dux cluster.

Each worker owns a DuckDB connection, registers in the `:dux_workers`
process group via `:pg`, and executes pipelines on behalf of the
coordinator.

## Starting workers

Workers are started automatically by the application supervisor if distributed
mode is enabled, or manually:

    {:ok, pid} = Dux.Remote.Worker.start_link([])

## Discovery

The coordinator discovers workers via `:pg`:

    workers = Dux.Remote.Worker.list()

## Execution

Workers receive `%Dux{}` pipelines (plain data), compile to SQL locally,
execute against their local DuckDB, and return results as Arrow IPC.

    {:ok, ipc_binary} = Dux.Remote.Worker.execute(worker_pid, pipeline)

# `append_chunk`

Append an Arrow IPC chunk to a named temp table. Creates the table if
it doesn't exist. Used during shuffle exchange.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `drop_table`

Drop a named temporary table on the worker.

# `execute`

Execute a `%Dux{}` pipeline on a worker. Returns `{:ok, ipc_binary}` or `{:error, reason}`.

The pipeline is compiled to SQL on the worker node and executed against
the worker's local DuckDB. The result is serialized as Arrow IPC.

# `hash_partition`

Hash-partition a pipeline's results into `n_buckets` buckets by join key(s).

`on` can be a single column (atom/string) or a list of columns.
Returns `%{bucket_id => ipc_binary}` — each bucket contains the rows
whose `hash(join_keys) % n_buckets == bucket_id`.

# `info`

Get worker info (node, connection status).

# `insert_into`

Execute a pipeline and insert the results into a table.

`setup_sqls` is a list of SQL statements to run before the insert
(e.g., INSTALL/LOAD extensions, ATTACH databases). The worker compiles
the pipeline, then runs INSERT INTO or CREATE TABLE AS.

Returns `{:ok, table}` or `{:error, reason}`.

# `list`

List all registered workers across the cluster.

# `list`

List workers on a specific node.

# `register_table`

Register an Arrow IPC binary as a named temporary table on the worker.
Used for broadcast joins — the coordinator sends a small table to all workers.

# `setup`

Run a setup function on the worker's node.

The function runs in the worker's GenServer process. Use this to configure
the worker's DuckDB (e.g. create S3 secrets, load extensions).

    Worker.setup(worker, fn ->
      Dux.create_secret(:s3, type: :s3, region: "us-west-2")
    end)

# `start_link`

Start a worker and register it in the `:dux_workers` process group.

# `write`

Execute a pipeline and write the results directly to a file.

The worker compiles the pipeline to SQL, then runs
`COPY (query) TO 'path' (format_opts)`. Returns `{:ok, path}` or
`{:error, reason}`.

---

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