Skip to content

Commit 606e5d0

Browse files
committed
docs: update error-handling page for expanded QueryModeError coverage
- INVALID_FORMAT now covers decompression failures + bad binary formats - SCHEMA_MISMATCH includes unsupported dtype errors - New "DataFrame validation errors" section documents QUERY_FAILED from client.ts (limit/offset/after/append) and MEMORY_EXCEEDED from WASM OOM
1 parent 1baff5e commit 606e5d0

File tree

1 file changed

+24
-2
lines changed

1 file changed

+24
-2
lines changed

docs/src/content/docs/error-handling.mdx

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ All errors thrown by QueryMode are `QueryModeError` instances with a structured
1111
|------|------|----------------|
1212
| `TABLE_NOT_FOUND` | File doesn't exist, R2 key missing | "Table not found: events.lance" |
1313
| `COLUMN_NOT_FOUND` | Column name not in schema | "Column not found: foo" |
14-
| `INVALID_FORMAT` | File can't be parsed as any supported format | "Invalid table format: data.xyz. Supported formats: .lance, .parquet, .csv, ..." |
15-
| `SCHEMA_MISMATCH` | Column exists but type doesn't match operation | "Column not found in events: age" |
14+
| `INVALID_FORMAT` | File can't be parsed, decompression fails, bad binary format | "Invalid table format: data.xyz. Supported formats: .lance, .parquet, .csv, ..." |
15+
| `SCHEMA_MISMATCH` | Column type doesn't match operation, unsupported dtype | "Column not found in events: age" |
1616
| `INVALID_FILTER` | Bad filter op or value type | "Invalid filter: unknown op 'regex'" |
1717
| `INVALID_AGGREGATE` | Bad aggregate function or missing column | "Invalid aggregate: sum requires numeric column" |
1818
| `MEMORY_EXCEEDED` | Operator exceeds memory budget | "Memory budget exceeded querying events" |
@@ -86,6 +86,28 @@ The response body always includes `{ error: string }` and, for `QueryModeError`,
8686
{ "error": "Column not found in events: foo", "code": "SCHEMA_MISMATCH" }
8787
```
8888

89+
## DataFrame validation errors
90+
91+
The DataFrame API validates arguments eagerly and throws `QueryModeError` with `QUERY_FAILED`:
92+
93+
```typescript
94+
qm.table("events").limit(-1)
95+
// QueryModeError: QUERY_FAILED — "limit() must be non-negative"
96+
97+
qm.table("events").after(100)
98+
// QueryModeError: QUERY_FAILED — "after() requires sort()"
99+
100+
await qm.table("events").append(rows)
101+
// QueryModeError: QUERY_FAILED — "append() requires an executor with write support"
102+
// (when using a read-only executor)
103+
```
104+
105+
WASM out-of-memory errors throw `MEMORY_EXCEEDED`:
106+
107+
```typescript
108+
// QueryModeError: MEMORY_EXCEEDED — "WASM OOM allocating zstd output"
109+
```
110+
89111
## SQL errors
90112

91113
SQL syntax errors throw `SqlParseError` or `SqlLexerError` (not `QueryModeError`) with a `position` field indicating where the error occurred:

0 commit comments

Comments
 (0)