> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REFRESH COLUMN

> Fill computed outputs and select rows to recompute.

**Applies to:** Embedded ❌, Enterprise ✅

A LanceDB extension with no DataFusion equivalent. It is what makes
[feature engineering](https://docs.lancedb.com/feature-engineering.md) reachable from SQL: a column
declared by [DDL](https://docs.lancedb.com/sql/ddl/table.md#computed-column) starts empty, and a refresh fills it.

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
REFRESH COLUMN <column> ON [TABLE] <table>
  [WHERE <predicate>]
  [WITH (<option> = <value> [, ...])]
```

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
REFRESH COLUMN doubled ON my_table
REFRESH COLUMN embedding ON documents WHERE created_at > '2026-01-01'
```

Without `WHERE`, a refresh fills unassigned rows and recomputes values whose
inputs changed, leaving other current values alone. A retry after a failure
can still repeat work that was not committed.

With `WHERE`, a refresh **recomputes every matching live row**, including rows
that already have current values. Repeating a predicate can repeat the Function
calls and their cost. To select only null outputs within a slice:

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
REFRESH COLUMN embedding ON documents
  WHERE created_at > '2026-01-01' AND embedding IS NULL
```

This skips non-null outputs even if their inputs changed. It also selects
outputs that were successfully computed as `NULL`. Use an unfiltered refresh
to let LanceDB track which outputs need updating.

## Options

| Option | Meaning |
| - | - |
| `num_workers` | fixed worker count for SQL-expression columns; rejected for registered Function columns |
| `cpu_millis` | aggregate CPU ceiling across the refresh's Function workers, in thousandths of a CPU |
| `memory_bytes` | aggregate memory ceiling across the refresh's Function workers, in bytes |
| `gpu_count` | aggregate GPU budget across the refresh's workers. Function columns only |
| `gpu_class` | GPU class name for the refresh's workers. Function columns only |
| `batch_size` | maximum rows passed to one Function call; actual calls can be smaller. Function columns only |
| `max_executor_processes_per_worker` | cap on executor processes per worker. Function columns only |
| `row_timeout_seconds` | deadline for one Function call. Function columns only |
| `error_policy` | `'fail'` (default) stops on a row error; `'skip'` writes null outputs and records row errors, subject to failure limits. Function columns only |
| `max_failed_fraction` | fail the job once more than this share of rows has failed. Function columns only |
| `max_failed_rows` | fail the job once more than this many rows has failed. Function columns only |

```sql SQL icon="database" theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
REFRESH COLUMN embedding ON documents
  WITH (cpu_millis = 8000, memory_bytes = 17179869184, gpu_count = 2)
```

The example allows up to 8 CPUs, 16 GiB of memory, and 2 GPUs across the
Function workers together. It does not reserve those resources per worker or
guarantee a worker count. When setting CPU or memory, provide all three budget
fields. A complete CPU-only budget uses `gpu_count = 0`.

Set `error_policy` on the refresh, not on the Function definition. With `skip`,
inspect failures with `SHOW ERRORS` or `table.function_errors()` and retry the
affected rows after fixing the cause. Initialization, infrastructure, and
publication failures can still fail the job.

> [!NOTE]
>
> `num_workers` is refused for a column filled by a registered
> [function](https://docs.lancedb.com/management/function.md), which sizes its own workers from the CPU,
> memory and GPU options instead. `error_policy` (and the Function-only options
> above it in the table) is the reverse: it's refused for a plain SQL-expression
> column, which has no per-row failures to skip -- it's accepted only for a
> Function column.

## Watching a refresh

A refresh submits work that outlives the call. Track it with
[`SHOW JOBS`](https://docs.lancedb.com/sql/ddl/job#show), and diagnose failures with
[`SHOW ERRORS`](https://docs.lancedb.com/sql/ddl/job#errors). For per-split progress, worker fleet
detail, and a `DESCRIBE JOB` example, see [Watching a refresh](https://docs.lancedb.com/sql/dml/refresh.md#watching).

## See also

> [card] [Refresh a computed column](https://docs.lancedb.com/feature-engineering/refresh-column.md)
>
> The same operation from the SDKs, and what a refresh guarantees.

> [card] [Table](https://docs.lancedb.com/sql/ddl/table.md#alter)
>
> Declaring the columns this fills.

> [card] [REFRESH MATERIALIZED VIEW](https://docs.lancedb.com/sql/dml/refresh-materialized-view.md)
>
> Bringing a view's stored result up to date, instead of a column.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.