Skip to content

Commit a63f7a4

Browse files
committed
docs: catalog query pushdown design, marked proposed
Adds the design for executing a whole eligible read query at a catalog provider -- optional read-query preparation and streaming, the Python provider API, DuckDB 1.5 explicit execution and DuckDB 2.0 automatic pushdown -- and registers it in the protocol index, the proposed-changes list and the nav. Labelled **informative, proposed** in all three places on purpose. It is not an extension of the filter-v2 contract and nothing implements it; filing it as a design without that label would let a reader mistake it for a spec that ports are behind on.
1 parent cced485 commit a63f7a4

5 files changed

Lines changed: 908 additions & 0 deletions

File tree

‎PROTOCOL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ The canonical protocol documents live in [`docs/protocol/`](docs/protocol/index.
66
- [VGI Filter Encoding v2 — normative proposed specification](docs/protocol/vgi-filter-encoding-v2-spec.md)
77
- [Runtime-filter artifacts — proposed optional extension](docs/protocol/vgi-runtime-filter-artifacts.md)
88
- [DuckDB filter adapter — informative implementation guide](docs/protocol/vgi-duckdb-filter-adapter.md)
9+
- [Catalog query pushdown — proposed implementation design](docs/protocol/vgi-catalog-query-pushdown-design.md)
910
- [DuckDB 2.0 protocol design/audit report — informative](docs/protocol/vgi-protocol-proposed-changes.md)
1011

1112
The executable language-neutral conformance corpus and retargetable worker runner are in

‎docs/protocol/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Each document declares its own status; “proposed” means the contract is stil
88
| [VGI Filter Encoding v2](vgi-filter-encoding-v2-spec.md) | **Normative, proposed** | Engine-neutral wire format, semantics, validation, and conformance requirements for `vgi.filters.v2`. |
99
| [VGI Runtime-Filter Artifacts](vgi-runtime-filter-artifacts.md) | **Normative optional extension, proposed** | Additional requirements for capability-gated advisory runtime-pruning artifacts. Base filter-v2 conformance does not require this extension. |
1010
| [VGI DuckDB Filter Adapter](vgi-duckdb-filter-adapter.md) | **Informative implementation guide, proposed** | DuckDB 1.5 and 2.0 mappings into the normative filter-v2 wire contract. |
11+
| [VGI catalog query pushdown](vgi-catalog-query-pushdown-design.md) | **Informative implementation design, proposed** | Optional read-query preparation and streaming, Python provider API, DuckDB 1.5 explicit execution, and DuckDB 2.0 automatic pushdown. |
1112
| [Proposed VGI protocol changes for DuckDB 2.0](vgi-protocol-proposed-changes.md) | **Informative design/audit report** | Rationale, migration inventory, implementation status, and deferred protocol decisions. It is not an implementation specification. |
1213

1314
## Reading order
@@ -16,6 +17,10 @@ Protocol implementers should begin with the normative [Filter Encoding v2](vgi-f
1617
runtime-artifact extension only when implementing one of its negotiated algorithms. Engine adapters should then use
1718
the relevant implementation guide without treating engine-private classes as wire types.
1819

20+
The [catalog query pushdown design](vgi-catalog-query-pushdown-design.md) describes a separate optional
21+
capability for executing whole eligible read queries at a catalog provider. It is a proposal, not
22+
an implemented extension of the filter-v2 contract.
23+
1924
The language-neutral filter corpus at `conformance/filter-v2/` contains structural JSON cases and executable Arrow
2025
IPC vectors. Its worker runner sends the portable cases through the public VGI client and can target any SDK's
2126
standard example worker.

0 commit comments

Comments
 (0)