What is a query? (and why does your agent say it failed)

What it actually is

A query is a question or instruction you send to a database: fetch these rows, count how many match, update this field, delete that record. The database reads the instruction, does the work, and hands back either the data you asked for or an error explaining why it couldn’t.

Think of it like a request slip at a library counter. You don’t wander the stacks yourself. You write down exactly what you want, hand the slip to the librarian, and either get the shelf you asked for or an answer for why it’s not there. A SQL query works the same way: SELECT name, email FROM users WHERE id = 1; asks the database to hand back one row from a table named users. Swap SELECT for UPDATE or DELETE and the same word covers changing data instead of reading it.

The word also names two things that have nothing to do with SQL. A URL query string is the part of a web address after the ?: on https://example.com/products?category=shoes&sort=price, ?category=shoes&sort=price is the query string, which MDN defines as “a string containing a ’?’ followed by the parameters of the URL.” TanStack Query (still widely called React Query) is a JavaScript library your frontend uses to fetch and cache data, where its docs define a query as “a declarative dependency on an asynchronous source of data that is tied to a unique key.” If your agent writes useQuery in a .tsx file, that’s this library, with no SQL involved.

All three describe asking for something, but that’s the only thing they share.

Why your AI just did this

When you ask your agent for something like “show me all my orders,” it builds a database query behind the scenes, sometimes hand-written SQL, more often generated through an ORM like Prisma or Drizzle, or through Supabase’s client library. Lovable and Bolt connect straight to a Supabase Postgres database and issue a query on every screen load or form submit. Cursor and Claude Code do the same when wiring up your own backend, or when they open Supabase’s SQL Editor directly.

“Query failed” shows up because the instruction reached the database but didn’t complete. Common causes are a table or column name that doesn’t match your actual schema, a permission the database refused, or a plain typo in the SQL your agent generated. Whichever it is, the database’s own error message names the real problem far more precisely than “failed” does.

When you’ll run into it

Two error shapes cover most of what you’ll see. A malformed instruction produces ERROR: syntax error at or near "FROM", meaning the SQL text itself isn’t valid, often a missing comma, quote, or keyword. A reference to something missing produces ERROR: relation "users" does not exist, meaning the SQL is valid but names a table (or column) your database doesn’t actually have, usually a typo or a table your agent assumed exists but never created.

You’ll also meet a broken URL query string doing something unrelated: a page not changing when you edit ?page=2 in the address bar. That’s a frontend routing problem, not a database one, even though your agent may describe both as “the query isn’t working.”

What to check

• Read the exact error text your agent shows you, in the terminal or in Supabase’s SQL Editor, instead of settling for “query failed”; the table or column name in a relation ... does not exist error is your typo.
• Confirm the table and column names in the failing query match your schema exactly, including case.
• If the problem involves a URL, check your browser’s address bar or Network tab against what your frontend code expects to read there, separately from anything the database is doing.
• If your agent mentions useQuery, you’re in TanStack Query territory: the fix belongs in a React component, not in SQL.
• Before letting an agent run a query that writes or deletes data, ask it to show you the exact SQL or ORM call first, especially anything past a plain read in CRUD.
• Never let a query build its SQL by pasting raw user input straight into the string; that pattern is how SQL injection happens.

Say it like a dev

Instead of: “the query failed, just fix it” Say: “Show me the exact SQL you ran and the exact error message underneath it, I want to see which table or column it’s complaining about.”

Instead of: “the data isn’t showing up” Say: “Is this a database query returning the wrong rows, or a URL query string not being read correctly on the frontend?”

Instead of: “make the filter work” Say: “Add a WHERE clause to the query that filters by the category coming from the URL’s query string.”