Errors and corrections

Every failure is JSON with one shape, and the class tells you whose fault it is: the envelope, the key, the spec, or the model. Successful responses may also carry a corrections array when a misspelled field was silently matched. This page lists both so your application can act on them.

The envelope

{"error": {"class": "Semantic::NotFound", "message": "No field named 'revenu' in this model. Did you mean: Revenue, Net Paid?"}}

class is stable and meant for code; message is for people and may name fields from the model.

Classes and statuses

400 means fix the request envelope; 401/403 means fix the key or its grants; 422 means fix the spec or the model; 5xx is ours.

Messages you will meet

Envelope and auth

Field references

Spec shape (Query::Spec::InvalidSpecError)

Validation (ActiveRecord::RecordInvalid)

All prefixed Validation failed: .

A bad calculation data_type (outside string, integer, decimal, date, date_time, boolean, bigint, binary) and a window size, offset or buckets below 1 are rejected in the same class.

Planner

Shorthand (Shorthand, 400)

The corrections array

A field reference that matches nothing exactly is scored against every field of the wanted kind by trigram overlap of the normalized text (lower-cased, runs of non-alphanumerics collapsed to one space) against the field’s name, uid and synonyms. Three constants decide what happens:

When both hold the candidate is used silently and the response reports it:

{"sql": "...", "datasource": "Warehouse", "datasource_uid": "warehouse", "adapter": "postgres",
 "corrections": [{"term": "departmnt", "field_uid": "department", "field_name": "Department", "score": 0.8}]}

corrections is omitted when empty. When the floor or the margin is not met, the request fails with Semantic::NotFound and up to three candidates scoring at least 0.25 in Did you mean: A, B, C?.

zsql prints corrections to stderr before the SQL, one per line:

departmnt → Department (~0.8)

Treat a correction as a warning in an interactive tool (show the user what was substituted) and as an error in a pipeline, where a silently substituted field is a bug waiting to be noticed.

Handling errors in your app

async function plan(body) {
  const res = await fetch(`https://app.0sql.io/projects/tpcds/branches/main/sql`, {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  const json = await res.json();

  if (!res.ok) {
    const { class: cls, message } = json.error;
    switch (cls) {
      case "Semantic::NotFound":
      case "Semantic::Ambiguous":
      case "Query::Spec::InvalidSpecError":
      case "ActiveRecord::RecordInvalid":
      case "Shorthand":
        throw new UserFixable(message);        // show it; the request can be edited
      case "Planner::ResolutionError":
      case "Planner::SecurityPolicyError":
      case "Unimplemented":
        throw new ModelProblem(message);       // the model or the policy needs a change
      case "ContextRequired":
      case "Invalid":
      case "Unauthorized":
      case "Forbidden":
      case "NotFound":
        throw new IntegrationBug(cls, message); // your code built the request or key wrong
      default:
        throw new Error(`${cls}: ${message}`);  // 5xx: retry later, then report it
    }
  }

  if (json.corrections?.length) {
    log.warn("0sql corrected fields", json.corrections);
  }
  return json; // { sql, datasource, datasource_uid, adapter, ... }
}

Three habits that pay off:

• Branch on class, never on message. Messages name fields and may change wording.
• Surface Semantic::NotFound with its Did you mean candidates and Semantic::Ambiguous with its @d/@m hint directly to whoever is building the query; they are written to be shown.
• Log corrections with the request. A rename in the model can turn an exact match into a fuzzy one without any error.

Next steps

• The query spec
• Field references
• Troubleshooting