fix: address all P0-P2 issues from dogfooding audit

P0 fixes (blockers):
- Add whereNotNull()/whereNull() with is_null/is_not_null filter ops
- Fix join() signature in docs (positional → object keys)
- Fix install instructions (git clone, not pnpm add)
- Document Zig requirement for WASM rebuild

P1 fixes (friction):
- Fix compute() → computed() in docs
- Fix unionAll() → union(df, true) in docs
- Fix head() return type in docs (QueryResult → Row[])
- Validate negative offset() values

P2 fixes (paper cuts):
- Add orderBy() alias for sort()
- Add drop() method (inverse of select)
- Add rename() method for column aliasing
- Expand error codes: SCHEMA_MISMATCH, MEMORY_EXCEEDED,
  NETWORK_TIMEOUT, QUERY_TIMEOUT, INVALID_FILTER, INVALID_AGGREGATE
- Add test:quick script (~2s vs ~8min full suite)
- Update query-schema.ts to accept new filter ops
- Fix example/local-quickstart.ts to use QueryMode API

All 176 tests pass.

Author: teamchong

README.md

@@ -5,7 +5,9 @@
 ## Quickstart
 
 ```bash
-pnpm add querymode
+# Clone and use from source (not yet published to npm)
+git clone https://github.com/teamchong/querymode.git
+cd querymode && pnpm install
 ```
 
 ```typescript
@@ -238,7 +240,8 @@ npx tsx examples/nextjs-api-route.ts
 
 - No deployed instance
 - No browser mode
-- No npm package published
+- No npm package published (install from source via git clone)
+- No SQL mode (planned — SQL frontend compiling to operator pipeline)
 
 ## Architecture
 ![querymode-architecture](docs/architecture/querymode-architecture.svg)
@@ -247,11 +250,14 @@ npx tsx examples/nextjs-api-route.ts
 
 ```bash
 pnpm install          # install dependencies
-pnpm build            # typecheck (tsc)
-pnpm test             # run vitest
+pnpm build:ts         # typecheck only (no WASM rebuild needed — pre-built WASM included)
+pnpm test:node        # run node tests (~2 min)
+pnpm test:workers     # run workerd tests
+pnpm test             # run all tests (~8 min)
 pnpm dev              # local dev with wrangler
 
-# build WASM from Zig source (requires zig)
+# Rebuild WASM from Zig source (requires zig toolchain)
+# Install: https://ziglang.org/download/
 pnpm wasm             # cd wasm && zig build wasm && cp to src/wasm/
 ```
 

docs/src/content/docs/dataframe-api.mdx

@@ -12,6 +12,7 @@ df.filter("age", "gt", 25)
 df.filter("status", "eq", "active")
 df.filter("id", "in", [1, 2, 3])
 df.whereNotNull("email")
+df.whereNull("deleted_at")
 ```
 
 | Operator | Description |
@@ -23,18 +24,22 @@ df.whereNotNull("email")
 | `lt` | Less than |
 | `lte` | Less than or equal |
 | `in` | Membership in array |
+| `is_null` | Value is null |
+| `is_not_null` | Value is not null |
 
 ## Projection
 
 ```typescript
 df.select("id", "name", "email")
+df.drop("internal_id", "debug_flag")     // exclude columns
+df.rename({ user_id: "userId", created_at: "createdAt" })
 ```
 
 ## Sorting
 
 ```typescript
 df.sort("amount", "desc")
-df.sort("name", "asc")
+df.orderBy("name", "asc")   // alias for sort()
 ```
 
 ## Limiting
@@ -62,8 +67,8 @@ Supported functions: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`, `std
 const orders = qm.table("orders")
 const users = qm.table("users")
 
-orders.join(users, "user_id", "id", "inner")
-orders.join(users, "user_id", "id", "left")
+orders.join(users, { left: "user_id", right: "id" }, "inner")
+orders.join(users, { left: "user_id", right: "id" }, "left")
 ```
 
 Join types: `inner`, `left`, `right`, `full`, `cross`.
@@ -86,14 +91,14 @@ Supported: `row_number`, `rank`, `dense_rank`, `lag`, `lead`, rolling `sum`/`avg
 ## Computed columns
 
 ```typescript
-df.compute("total", (row) => (row.price as number) * (row.qty as number))
+df.computed("total", (row) => (row.price as number) * (row.qty as number))
 ```
 
 ## Set operations
 
 ```typescript
-df1.union(df2)
-df1.unionAll(df2)
+df1.union(df2)           // UNION (deduplicates)
+df1.union(df2, true)     // UNION ALL (keeps duplicates)
 df1.intersect(df2)
 df1.except(df2)
 ```
@@ -117,7 +122,7 @@ These execute the query and return results:
 | `exists()` | `boolean` | Check if any rows match |
 | `explain()` | `ExplainResult` | Show execution plan without running |
 | `describe()` | Table schema | Column names, types, row counts |
-| `head(n)` | `QueryResult` | First N rows (shorthand for limit + collect) |
+| `head(n)` | `Row[]` | First N rows (shorthand for limit + collect) |
 
 ## Progress tracking
 

docs/src/content/docs/getting-started.mdx

@@ -6,7 +6,8 @@ description: Install querymode and run your first query.
 ## Installation
 
 ```bash
-pnpm add querymode
+git clone https://github.com/teamchong/querymode.git
+cd querymode && pnpm install
 ```
 
 ## Zero-config demo

examples/local-quickstart.ts

@@ -4,15 +4,13 @@
  * Reads a Lance or Parquet file from disk, applies filter + sort + limit,
  * and prints the result. Replace the path with your own data file.
  */
-import { LocalExecutor } from "../src/local-executor.js";
-import { DataFrame } from "../src/client.js";
+import { QueryMode } from "../src/local.js";
 
-const executor = new LocalExecutor();
 const TABLE = process.argv[2] ?? "./data/events.parquet";
 
-const df = new DataFrame(TABLE, executor);
-
-const result = await df
+const qm = QueryMode.local();
+const result = await qm
+  .table(TABLE)
   .filter("amount", "gt", 100)
   .whereNotNull("region")
   .select("id", "amount", "region")

package.json

@@ -24,6 +24,7 @@
     "test": "vitest run -c vitest.workers.config.ts && vitest run",
     "test:workers": "vitest run -c vitest.workers.config.ts",
     "test:node": "vitest run",
+    "test:quick": "vitest run -c vitest.workers.config.ts src/convenience.test.ts src/format.test.ts src/footer.test.ts src/decode.test.ts src/merge.test.ts src/partial-agg.test.ts src/vip-cache.test.ts src/page-processor.test.ts",
     "test:watch": "vitest",
     "deploy": "pnpm run build && wrangler deploy",
     "wasm": "pnpm run build:wasm",

src/client.ts

@@ -163,16 +163,61 @@ export class DataFrame<T extends Row = Row> {
     return this.where(column, op, value);
   }
 
+  /** Filter rows where a column is not null. */
+  whereNotNull(column: string): DataFrame<T> {
+    return this.derive({ filters: [...this._filters, { column, op: "is_not_null", value: 0 }] });
+  }
+
+  /** Filter rows where a column is null. */
+  whereNull(column: string): DataFrame<T> {
+    return this.derive({ filters: [...this._filters, { column, op: "is_null", value: 0 }] });
+  }
+
   /** Select specific columns. Only these byte ranges are fetched from R2. */
   select(...columns: string[]): DataFrame {
     return this.derive({ projections: columns }) as DataFrame;
   }
 
+  /** Exclude specific columns (inverse of select). */
+  drop(...columns: string[]): DataFrame<T> {
+    const dropSet = new Set(columns);
+    const remaining = this._projections.length > 0
+      ? this._projections.filter(c => !dropSet.has(c))
+      : []; // If no projections set, drop will be applied at collect time via computed exclusion
+    // Store dropped columns as a negative projection marker
+    return this.derive({
+      projections: remaining,
+      computedColumns: [
+        ...this._computedColumns,
+        ...columns.map(c => ({ alias: `__drop__${c}`, fn: () => undefined })),
+      ],
+    });
+  }
+
+  /** Rename columns. Returns a new DataFrame with renamed output columns. */
+  rename(mapping: Record<string, string>): DataFrame {
+    const renames = Object.entries(mapping);
+    return this.derive({
+      computedColumns: [
+        ...this._computedColumns,
+        ...renames.map(([from, to]) => ({
+          alias: to,
+          fn: (row: Row) => row[from],
+        })),
+      ],
+    }) as DataFrame;
+  }
+
   /** Sort results by a column. With .limit(), uses a top-K heap (O(K) memory). */
   sort(column: string, direction: "asc" | "desc" = "asc"): DataFrame<T> {
     return this.derive({ sortColumn: column, sortDirection: direction });
   }
 
+  /** Alias for .sort() — common in SQL-style APIs. */
+  orderBy(column: string, direction: "asc" | "desc" = "asc"): DataFrame<T> {
+    return this.sort(column, direction);
+  }
+
   /** Limit the number of returned rows. Enables early termination. */
   limit(n: number): DataFrame<T> {
     if (n < 0) throw new Error("limit() must be non-negative");
@@ -181,6 +226,7 @@ export class DataFrame<T extends Row = Row> {
 
   /** Skip the first N rows. Enables offset-based pagination. */
   offset(n: number): DataFrame<T> {
+    if (n < 0) throw new Error("offset() must be non-negative");
     return this.derive({ offset: n });
   }
 
@@ -617,6 +663,8 @@ export class MaterializedExecutor implements QueryExecutor {
     for (const f of query.filters) {
       rows = rows.filter(row => {
         const v = row[f.column];
+        if (f.op === "is_null") return v === null || v === undefined;
+        if (f.op === "is_not_null") return v !== null && v !== undefined;
         if (v === null) return false;
         const fv = f.value;
         switch (f.op) {

src/decode.ts

@@ -8,6 +8,7 @@ import { decodeLanceV2Utf8 } from "./lance-v2.js";
 export function canSkipPage(page: PageInfo, filters: QueryDescriptor["filters"], columnName: string): boolean {
   for (const filter of filters) {
     if (filter.column !== columnName) continue;
+    if (filter.op === "is_null" || filter.op === "is_not_null") continue;
     if (page.minValue === undefined || page.maxValue === undefined) continue;
 
     let { minValue: min, maxValue: max } = page;
@@ -370,6 +371,8 @@ export function matchesFilter(
   val: number | bigint | string | boolean | Float32Array | null,
   filter: QueryDescriptor["filters"][0],
 ): boolean {
+  if (filter.op === "is_null") return val === null;
+  if (filter.op === "is_not_null") return val !== null;
   if (val === null) return false;
   const t = filter.value;
   switch (filter.op) {

src/errors.ts

@@ -3,10 +3,22 @@
  *
  * Wraps low-level errors (ENOENT, parse failures) into actionable messages.
  */
+
+export type ErrorCode =
+  | "TABLE_NOT_FOUND"
+  | "INVALID_FORMAT"
+  | "SCHEMA_MISMATCH"
+  | "INVALID_FILTER"
+  | "INVALID_AGGREGATE"
+  | "MEMORY_EXCEEDED"
+  | "NETWORK_TIMEOUT"
+  | "QUERY_TIMEOUT"
+  | "QUERY_FAILED";
+
 export class QueryModeError extends Error {
-  readonly code: string;
+  readonly code: ErrorCode;
 
-  constructor(code: string, message: string, cause?: unknown) {
+  constructor(code: ErrorCode, message: string, cause?: unknown) {
     super(message);
     this.name = "QueryModeError";
     this.code = code;
@@ -19,6 +31,7 @@ export class QueryModeError extends Error {
 
     const raw = err instanceof Error ? err : new Error(String(err));
     const { table, operation } = context;
+    const msg = raw.message;
 
     // ENOENT — table/file not found
     if ("code" in raw && (raw as NodeJS.ErrnoException).code === "ENOENT") {
@@ -30,18 +43,46 @@ export class QueryModeError extends Error {
     }
 
     // Parse failures
-    if (raw.message.includes("footer") || raw.message.includes("Invalid file")) {
+    if (msg.includes("footer") || msg.includes("Invalid file") || msg.includes("Failed to parse")) {
       return new QueryModeError(
         "INVALID_FORMAT",
         `Invalid table format${table ? `: ${table}` : ""}. Supported formats: .lance, .parquet, .csv, .tsv, .json, .ndjson, .jsonl, .arrow, .ipc, .feather`,
         raw,
       );
     }
 
+    // Column/schema mismatches
+    if (msg.includes("column") && (msg.includes("not found") || msg.includes("does not exist"))) {
+      return new QueryModeError(
+        "SCHEMA_MISMATCH",
+        `Column not found${table ? ` in ${table}` : ""}: ${msg}`,
+        raw,
+      );
+    }
+
+    // Memory exceeded
+    if (msg.includes("OOM") || msg.includes("memory") || msg.includes("budget")) {
+      return new QueryModeError(
+        "MEMORY_EXCEEDED",
+        `Memory budget exceeded${table ? ` querying ${table}` : ""}. Try adding filters, reducing projections, or increasing memoryBudgetBytes.`,
+        raw,
+      );
+    }
+
+    // Timeouts
+    if (msg.includes("timeout") || msg.includes("timed out") || msg.includes("TIMEOUT")) {
+      const code = msg.includes("network") || msg.includes("R2") ? "NETWORK_TIMEOUT" : "QUERY_TIMEOUT";
+      return new QueryModeError(
+        code,
+        `${code === "NETWORK_TIMEOUT" ? "Network" : "Query"} timeout${table ? ` on ${table}` : ""}: ${msg}`,
+        raw,
+      );
+    }
+
     // Generic wrapper
     return new QueryModeError(
       "QUERY_FAILED",
-      `${operation ?? "Query"} failed${table ? ` on ${table}` : ""}: ${raw.message}`,
+      `${operation ?? "Query"} failed${table ? ` on ${table}` : ""}: ${msg}`,
       raw,
     );
   }

src/index.ts

@@ -15,6 +15,7 @@ export type { FormatReader, DataSource } from "./reader.js";
 export { DataFrame, TableQuery, MaterializedExecutor } from "./client.js";
 export { LazyResultHandle } from "./client.js";
 export { QueryModeError } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
 export { LocalExecutor } from "./local-executor.js";
 export { bigIntReplacer } from "./decode.js";
 export { createFromJSON, createFromCSV, createDemo } from "./convenience.js";

src/local.ts

@@ -61,6 +61,7 @@ export class QueryMode {
 export { LocalExecutor } from "./local-executor.js";
 export { DataFrame, TableQuery, MaterializedExecutor } from "./client.js";
 export { QueryModeError } from "./errors.js";
+export type { ErrorCode } from "./errors.js";
 export { bigIntReplacer } from "./decode.js";
 export { createFromJSON, createFromCSV, createDemo } from "./convenience.js";
 export { formatResultSummary, formatExplain, formatBytes } from "./format.js";