Skip to content

feat(zql): add Cap operator for EXISTS pipelines #5661

Open
tantaman wants to merge 1 commit intomainfrom
mlaw/cap-2
Open

feat(zql): add Cap operator for EXISTS pipelines #5661
tantaman wants to merge 1 commit intomainfrom
mlaw/cap-2

Conversation

@tantaman
Copy link
Contributor

@tantaman tantaman commented Mar 17, 2026

Introduces the Cap operator, an alternative to Take for EXISTS subquery pipelines.

This eliminates SQLite's need to create temporary B-trees for ORDER BY in EXISTS child pipelines, where only row existence matters — not order.

Key changes:

  • Cap operator (cap.ts): Count-based limiter that tracks membership by primary key set rather than sorted bounds. No comparator, no start/reverse fetch support needed.
  • Unordered source connections: Source.connect() now accepts sort: undefined. MemorySource falls back to primary key ordering internally while exposing schema.sort = undefined to downstream operators.
  • Unordered overlay generators: New generateWithOverlayUnordered variants in both memory-source.ts,
    table-source.ts, and join-utils.ts that inject/suppress rows by PK match without requiring sorted iteration.
  • Builder integration (builder.ts): EXISTS child pipelines now pass isExistsChild flag, connecting sources without ordering and using Cap instead of Take.
  • Schema change: SourceSchema.sort is now optional (Ordering | undefined), reflecting that not all pipelines are ordered.
  • Guard rails: Take, Skip, and UnionFanIn now assert that their input is sorted, catching misuse early.
  • Query builder (query-builder.ts): buildSelectQuery omits ORDER BY when no ordering is specified.

Tests:

  • cap.push.test.ts
  • join-utils unordered overlay tests (join-utils.test.ts)
  • Unordered MemorySource tests
  • Integration tests (cap.pg.test.ts) testing various overlay configurations

@vercel
Copy link

vercel bot commented Mar 17, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
replicache-docs Ready Ready Preview, Comment Mar 19, 2026 7:17pm
zbugs Ready Ready Preview, Comment Mar 19, 2026 7:17pm

Request Review

@github-actions
Copy link

github-actions bot commented Mar 17, 2026

🐰 Bencher Report

Branchmlaw/cap-2
TestbedLinux
Click to view all benchmark results
BenchmarkFile SizeBenchmark Result
kilobytes (KB)
(Result Δ%)
Upper Boundary
kilobytes (KB)
(Limit %)
zero-package.tgz📈 view plot
🚷 view threshold
1,933.89 KB
(+0.51%)Baseline: 1,924.12 KB
1,962.61 KB
(98.54%)
zero.js📈 view plot
🚷 view threshold
282.60 KB
(+1.43%)Baseline: 278.62 KB
284.20 KB
(99.44%)
zero.js.br📈 view plot
🚷 view threshold
74.56 KB
(+0.80%)Baseline: 73.97 KB
75.45 KB
(98.82%)
🐰 View full continuous benchmarking report in Bencher

@github-actions
Copy link

github-actions bot commented Mar 17, 2026

🐰 Bencher Report

Branchmlaw/cap-2
Testbedself-hosted

🚨 2 Alerts

BenchmarkMeasure
Units
ViewBenchmark Result
(Result Δ%)
Lower Boundary
(Limit %)
src/client/custom.bench.ts > big schemaThroughput
operations / second (ops/s) x 1e3
📈 plot
🚷 threshold
🚨 alert (🔔)
109.56 ops/s x 1e3
(-15.30%)Baseline: 129.35 ops/s x 1e3
114.54 ops/s x 1e3
(104.54%)

src/client/zero.bench.ts > pk compare > pk = NThroughput
operations / second (ops/s) x 1e3
📈 plot
🚷 threshold
🚨 alert (🔔)
49.82 ops/s x 1e3
(-14.39%)Baseline: 58.19 ops/s x 1e3
54.57 ops/s x 1e3
(109.54%)

Click to view all benchmark results
BenchmarkThroughputBenchmark Result
operations / second (ops/s) x 1e3
(Result Δ%)
Lower Boundary
operations / second (ops/s) x 1e3
(Limit %)
src/client/custom.bench.ts > big schema📈 view plot
🚷 view threshold
🚨 view alert (🔔)
109.56 ops/s x 1e3
(-15.30%)Baseline: 129.35 ops/s x 1e3
114.54 ops/s x 1e3
(104.54%)

src/client/zero.bench.ts > basics > All 1000 rows x 10 columns (numbers)📈 view plot
🚷 view threshold
1.93 ops/s x 1e3
(-7.52%)Baseline: 2.09 ops/s x 1e3
1.16 ops/s x 1e3
(60.28%)
src/client/zero.bench.ts > pk compare > pk = N📈 view plot
🚷 view threshold
🚨 view alert (🔔)
49.82 ops/s x 1e3
(-14.39%)Baseline: 58.19 ops/s x 1e3
54.57 ops/s x 1e3
(109.54%)

src/client/zero.bench.ts > with filter > Lower rows 500 x 10 columns (numbers)📈 view plot
🚷 view threshold
2.94 ops/s x 1e3
(-11.37%)Baseline: 3.32 ops/s x 1e3
2.42 ops/s x 1e3
(82.24%)
🐰 View full continuous benchmarking report in Bencher

@github-actions
Copy link

github-actions bot commented Mar 17, 2026

🐰 Bencher Report

Branchmlaw/cap-2
Testbedself-hosted

⚠️ WARNING: Truncated view!

The full continuous benchmarking report exceeds the maximum length allowed on this platform.

🚨 27 Alerts

🐰 View full continuous benchmarking report in Bencher

@tantaman tantaman changed the title Mlaw/cap 2 feat(zql): add Cap operator for EXISTS pipelines Mar 18, 2026
@tantaman tantaman marked this pull request as ready for review March 19, 2026 13:35
@tantaman tantaman requested a review from grgbkr March 19, 2026 13:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant