docs: show the Python filtered refresh next to the SQL form (#4923)

Adds Python where= examples next to the SQL ones.

Also fixes two examples that fail:
- Date filters now use date '2026-01-01'. A bare string fails on DATE
and TIMESTAMP columns (see [Dates, Timestamps,
Decimals](https://docs.lancedb.com/search/filtering#dates-timestamps-decimals)).
- The first example reads results with table.search().to_arrow(),
because table.to_arrow() raises on Enterprise.

where= needs lancedb 0.42.0 or later.
This commit is contained in:
Brendan Clement
2026-11-09 09:51:48 -08:00
committed by GitHub
parent 1157a0709d
commit 94f366a11a
2 changed files with 29 additions and 12 deletions
+27 -10
View File
@@ -22,7 +22,7 @@ Computed columns require LanceDB Enterprise.
job = table.refresh_column_async("doubled")
job.wait()
table.to_arrow().sort_by("x").to_pandas()
table.search().to_arrow().sort_by("x").to_pandas()
# x doubled
# 0 1 2
# 1 2 4
@@ -77,13 +77,21 @@ catch-up works when it's re-enabled after being off.
## Refreshing part of a table {#partial}
<Badge color="red">Enterprise</Badge> In SQL a refresh can be scoped to a
predicate, which is useful for filling a slice first and checking it before
committing to the whole table:
<Badge color="red">Enterprise</Badge> A refresh can be scoped to a predicate,
with `where=` in Python or `WHERE` in SQL, which is useful for filling a slice
first and checking it before committing to the whole table:
<CodeGroup>
```python Python icon="python"
job = table.refresh_column_async(
"embedding",
where="created_at > date '2026-01-01'",
)
job.wait()
```
```sql SQL icon="database"
REFRESH COLUMN embedding ON documents WHERE created_at > '2026-01-01'
REFRESH COLUMN embedding ON documents WHERE created_at > date '2026-01-01'
```
</CodeGroup>
@@ -92,9 +100,17 @@ whose outputs are already current. Repeating the same predicate repeats those
Function calls and their cost. To select only null outputs within a slice:
<CodeGroup>
```python Python icon="python"
job = table.refresh_column_async(
"embedding",
where="created_at > date '2026-01-01' AND embedding IS NULL",
)
job.wait()
```
```sql SQL icon="database"
REFRESH COLUMN embedding ON documents
WHERE created_at > '2026-01-01' AND embedding IS NULL
WHERE created_at > date '2026-01-01' AND embedding IS NULL
```
</CodeGroup>
@@ -247,13 +263,14 @@ and `gpuCount` in the `refreshColumnAsync` options.
The job APIs also take the row filter and failure handling of the SQL
`REFRESH COLUMN ... WHERE ... WITH (...)` form, so a refresh can be narrowed
to new rows and told to skip rows whose Function call fails:
to new rows (see [what a filter recomputes](#partial)) and told to skip rows
whose Function call fails:
<CodeGroup>
```python
job = table.refresh_column_async(
"embedding",
where="published_at > '2026-01-01'",
where="created_at > date '2026-01-01'",
error_policy="skip",
max_failed_fraction=0.01,
row_timeout_seconds=30,
@@ -262,7 +279,7 @@ job = table.refresh_column_async(
```typescript
const job = await table.refreshColumnAsync("embedding", {
where: "published_at > '2026-01-01'",
where: "created_at > date '2026-01-01'",
errorPolicy: "skip",
maxFailedFraction: 0.01,
rowTimeoutSeconds: 30,
@@ -276,7 +293,7 @@ let _job = table
.refresh_column_async_with_options(
"embedding",
RefreshColumnOptions::default()
.where_clause("published_at > '2026-01-01'")
.where_clause("created_at > date '2026-01-01'")
.error_policy(FunctionErrorPolicy::Skip)
.max_failed_fraction(0.01)
.row_timeout_seconds(30.0),
+2 -2
View File
@@ -24,7 +24,7 @@ REFRESH COLUMN <column> ON [TABLE] <table>
<CodeGroup>
```sql SQL icon="database"
REFRESH COLUMN doubled ON my_table
REFRESH COLUMN embedding ON documents WHERE created_at > '2026-01-01'
REFRESH COLUMN embedding ON documents WHERE created_at > date '2026-01-01'
```
</CodeGroup>
@@ -39,7 +39,7 @@ calls and their cost. To select only null outputs within a slice:
<CodeGroup>
```sql SQL icon="database"
REFRESH COLUMN embedding ON documents
WHERE created_at > '2026-01-01' AND embedding IS NULL
WHERE created_at > date '2026-01-01' AND embedding IS NULL
```
</CodeGroup>