外观
本页尚未翻译
本页内容仍为英文原文，源自官方文档 sql/dml/refresh-column。中文翻译正在分批进行中。
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 reachable from SQL: a column declared by DDL starts empty, and a refresh fills it.
sql
REFRESH COLUMN <column> ON [TABLE] <table>
[WHERE <predicate>]
[WITH (<option> = <value> [, ...])]sql
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
REFRESH COLUMN embedding ON documents
WHERE created_at > '2026-01-01' AND embedding IS NULLThis 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
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.
说明
num_workers is refused for a column filled by a registered function, 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, and diagnose failures with SHOW ERRORS. For per-split progress, worker fleet detail, and a DESCRIBE JOB example, see Watching a refresh.