mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-16 08:42:29 +00:00
Brendan Clement
06aa526ae1
This PR is part of the documentation revamp. Once the full set of PRs is merged, we’ll publish the combined site to staging for review before updating docs.lancedb.com. The curation, SQL and operations pages contain outdated claims and examples that do not reliably work as written. This corrects those pages against the reviewed SDK and local server evidence, including prepared statements, background jobs, cleanup and monitoring. Integration guides are grouped with their examples in #4533. Function and Secret-object documentation stays unpublished until its release. The two Function pages are listed in `.mintignore` and left out of the navigation, and the sections about them on other pages are MDX comments. Stacked on #4533. Each MDX file has one PR owner. Rebase onto main after #4533 is squash-merged. Local assembly, Mint validation and link checks pass, and the assembled site shows no Function or Secret-object content. A local release rehearsal that uncomments the drafts and restores the navigation also passes. Hold publication until this PR and lancedb/sophon#8688 are on `main`.
101 lines
2.7 KiB
Plaintext
101 lines
2.7 KiB
Plaintext
---
|
|
title: "Window functions"
|
|
sidebarTitle: "Window Functions"
|
|
description: "Compute over a set of rows related to the current one, without collapsing them."
|
|
icon: chart-simple
|
|
keywords: ["window", "over", "partition by", "row_number", "rank", "lag", "lead"]
|
|
---
|
|
|
|
<Badge color="red">Enterprise</Badge> [SQL runs in LanceDB Enterprise.](/sql)
|
|
|
|
A window function computes across a set of rows related to the current one and
|
|
returns a value **per row**. That is the difference from
|
|
[aggregation](/sql/dql/aggregation), which collapses the rows it covers.
|
|
|
|
```sql
|
|
SELECT
|
|
title,
|
|
score,
|
|
row_number() OVER (PARTITION BY category ORDER BY score DESC) AS rank
|
|
FROM documents
|
|
```
|
|
|
|
Every row survives; each one gains its rank within its category.
|
|
|
|
## The window {#window}
|
|
|
|
```sql
|
|
OVER (
|
|
[PARTITION BY expr [, ...]]
|
|
[ORDER BY expr [, ...]]
|
|
[ROWS | RANGE BETWEEN frame_start AND frame_end]
|
|
)
|
|
```
|
|
|
|
`PARTITION BY` splits the rows into independent groups. `ORDER BY` orders them
|
|
inside each partition. Supply an ordering for useful ranks, and a stable
|
|
tie-breaker when selecting one row from several equal values. The frame clause narrows the window further, which is
|
|
how running totals and moving averages are expressed:
|
|
|
|
```sql
|
|
SELECT
|
|
created_at,
|
|
sum(amount) OVER (ORDER BY created_at ROWS UNBOUNDED PRECEDING) AS running_total,
|
|
avg(amount) OVER (ORDER BY created_at ROWS BETWEEN 6 PRECEDING AND CURRENT ROW) AS trailing_7
|
|
FROM transactions
|
|
```
|
|
|
|
A `WINDOW` clause names a definition when several functions share one:
|
|
|
|
```sql
|
|
SELECT
|
|
row_number() OVER w,
|
|
lag(score) OVER w
|
|
FROM documents
|
|
WINDOW w AS (PARTITION BY category ORDER BY score DESC)
|
|
```
|
|
|
|
## The functions {#functions}
|
|
|
|
Registered in DataFusion 54.
|
|
|
|
**Ranking**
|
|
|
|
```text
|
|
row_number rank dense_rank percent_rank cume_dist ntile
|
|
```
|
|
|
|
**Offset and positional**
|
|
|
|
```text
|
|
lag lead first_value last_value nth_value
|
|
```
|
|
|
|
**Aggregates**
|
|
|
|
Any [aggregate function](/sql/dql/aggregation#functions) used with `OVER` becomes a
|
|
window function. This is how running totals and moving averages are written.
|
|
|
|
## Deduplicating with a window {#dedup}
|
|
|
|
The common practical use: keep one row per key, chosen by some ordering. A
|
|
window ranks, and an outer query filters:
|
|
|
|
```sql
|
|
WITH ranked AS (
|
|
SELECT *, row_number() OVER (PARTITION BY doc_id ORDER BY version DESC) AS rn
|
|
FROM revisions
|
|
)
|
|
SELECT * FROM ranked WHERE rn = 1
|
|
```
|
|
|
|
The outer query is needed because a window function cannot appear in `WHERE` --
|
|
windows are computed after filtering, so the predicate would have nothing to
|
|
read.
|
|
|
|
<Note>
|
|
Window functions sort within each partition, so on a large table they are among
|
|
the more expensive things you can ask for. Filter first, and check the cost with
|
|
[Explain Analyze](/search/explain).
|
|
</Note>
|