examples · errors · 3 / 19

3. 400 - unknown column

what this error means

The table resolved fine, but a column referenced in the SELECT, WHERE, JOIN ON, or GROUP BY clause is not declared on that table's manifest. The translator stops before planning.

what triggers it

Selecting a column that isn't in the schema.

POST /v1/tenants/:t/sql

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT bogus_col FROM shop.customers LIMIT 1"}'

the canonical response body

{
  "error": "unknown_column",
  "message": "column 'bogus_col' is not declared on table 'shop.customers'",
  "retry": false
}

how to recover

Fetch the manifest: GET /v1/tenants/:t/schemas/shop.customers - the declared columns are listed at the top.
Fix the typo, or add the column with an online-schema-change if it should exist.
Column names are case-sensitive. CustomerID and customerid are different references.
retry: false - same query will keep failing.

common upstream causes

Typo in the column name.
SQL written against a newer schema version than the one currently registered.
Aliasing in a JOIN where the alias scope was lost.
SELECT * works, then a specific column was added - check spelling against the manifest.
Confusing a JSON sub-field with a top-level column (sub-fields require json_extract(...)).