@query-farm/vgi 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "TypeScript framework for extending DuckDB with user-defined functions via the Vector Gateway Interface (VGI) over Arrow IPC.",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Query Farm LLC (https://query.farm)",

package/src/catalog/descriptors.ts

@@ -60,18 +60,24 @@ export interface TableDescriptor {
    */
   statisticsCacheMaxAgeSeconds?: number | null;
   /**
-   * Dotted-path column references that MUST appear in a WHERE expression for
-   * any scan of this table. Top-level names (`"country"`) or struct subfields
-   * (`"bbox.xmin"`, `"nested.outer.inner"`). Empty/undefined (default) means
-   * no enforcement — the zero-cost fast path for every existing table.
+   * Required WHERE-filter groups in conjunctive normal form — an AND (outer
+   * list) of OR-groups (inner lists) of dotted-path column references that MUST
+   * appear in a WHERE expression for any scan of this table. A group is
+   * satisfied when any one of its paths has a filter; every group must be
+   * satisfied. So `[["accession_number"], ["ticker", "cik"]]` means
+   * "accession_number AND one of (ticker, cik)"; a single-path group
+   * `[["country"]]` is a plain mandatory filter. Paths are top-level names
+   * (`"country"`) or struct subfields (`"bbox.xmin"`, `"nested.outer.inner"`).
+   * Empty/undefined (default) means no enforcement — the zero-cost fast path
+   * for every existing table.
    *
    * Satisfaction is prefix-based: a present filter on a shorter path satisfies
    * any required path it is a prefix of. So a whole-struct filter on `bbox`
    * satisfies all of `bbox.xmin` / `.xmax` / `.ymin` / `.ymax`. The VGI DuckDB
-   * extension's optimizer pass consults this list at bind time and throws a
-   * `BinderException` listing any unsatisfied paths.
+   * extension's optimizer pass consults this at bind time and throws a
+   * `BinderException` listing any unsatisfied groups.
    */
-  requiredFieldFilterPaths?: string[];
+  requiredFilters?: string[][];
   supportsTimeTravel?: boolean;
   /**
    * Inline cardinality estimate/max surfaced through TableInfo. When set,

package/src/catalog/read-only.ts

@@ -235,26 +235,34 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
       const pkIndices = resolveIndexGroups(colSchema, t.primaryKey);
       const fkBytes = serializeForeignKeys(t.foreignKey, name);
 
-      // Validate required_field_filter_paths: the leading dotted segment of
-      // each path must be a real column on this table. Struct subfield
+      // Validate required_filters: an AND (outer list) of OR-groups (inner
+      // lists). Each OR-group must be non-empty, and the leading dotted segment
+      // of each path must be a real column on this table. Struct subfield
       // validity is not checked here — DuckDB's binder catches typos at scan
       // time, and the descriptor doesn't unpack STRUCT subfields. (Mirrors
       // vgi-python's Table descriptor validation.)
-      const requiredFieldFilterPaths = t.requiredFieldFilterPaths ?? [];
-      if (requiredFieldFilterPaths.length > 0) {
+      const requiredFilters = t.requiredFilters ?? [];
+      if (requiredFilters.length > 0) {
         const columnNames = new Set(colSchema.fields.map((f) => f.name));
-        for (const path of requiredFieldFilterPaths) {
-          if (!path) {
+        for (const group of requiredFilters) {
+          if (!group || group.length === 0) {
             throw new Error(
-              `Table '${t.name}': requiredFieldFilterPaths must not contain empty strings`
+              `Table '${t.name}': requiredFilters must not contain empty groups`
             );
           }
-          const head = path.split(".", 1)[0];
-          if (!columnNames.has(head)) {
-            throw new Error(
-              `Table '${t.name}': requiredFieldFilterPaths path '${path}' references ` +
-                `unknown column '${head}'. Available columns: ${[...columnNames].sort().join(", ")}`
-            );
+          for (const path of group) {
+            if (!path) {
+              throw new Error(
+                `Table '${t.name}': requiredFilters must not contain empty strings`
+              );
+            }
+            const head = path.split(".", 1)[0];
+            if (!columnNames.has(head)) {
+              throw new Error(
+                `Table '${t.name}': requiredFilters path '${path}' references ` +
+                  `unknown column '${head}'. Available columns: ${[...columnNames].sort().join(", ")}`
+              );
+            }
           }
         }
       }
@@ -292,7 +300,7 @@ export class ReadOnlyCatalogInterface extends CatalogInterface {
         cardinality_max: t.inlinedCardinality
           ? Number(t.inlinedCardinality.max)
           : null,
-        required_field_filter_paths: requiredFieldFilterPaths,
+        required_filters: requiredFilters,
       };
     }));
   }

package/src/generated/vgi-client.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_client. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-client v1
-// Content hash: 5ddab596625f
+// Content hash: f3ac87321a0c
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-client \
@@ -84,7 +84,7 @@ export interface TableInfo {
   cardinality_max?: number | null;
   column_statistics?: Uint8Array | null;
   bind_result?: Uint8Array | null;
-  required_field_filter_paths: string[];
+  required_filters: string[][];
 }
 
 export interface ViewInfo {

package/src/generated/vgi-protocol-schemas.ts

@@ -2,7 +2,7 @@
 // GENERATED by vgi.codegen.ts_schemas. DO NOT EDIT BY HAND.
 //
 // Generator: vgi-gen-ts-schemas v2
-// Content hash: 673bfdc9573a
+// Content hash: b3c99cc5fac8
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python vgi-gen-ts-schemas \
@@ -70,7 +70,7 @@ export const TableInfoSchema = schema([
   field("cardinality_max", int64(), false),
   field("column_statistics", binary(), false),
   field("bind_result", binary(), false),
-  field("required_field_filter_paths", list(field("item", utf8(), true)), false),
+  field("required_filters", list(field("item", list(field("item", utf8(), true)), true)), false),
 ]);
 
 // Origin: ViewInfo