{"canonical_url":"https://engineer.company/glossary/query/","content_markdown":"# Query\n\n## What it is\n\nA query is a request for data, written in a language the database understands,\nthat comes back with a result: usually a set of rows, sometimes a single number.\nPostgreSQL's manual defines it in one line: retrieving data from a database, or\nthe command that does the retrieving, is called a query, and in SQL that command\nis SELECT. Everyday usage stretches the word further, and engineers call almost\nany statement they send to a database a query, including the ones that change\ndata and hand something back. Both senses appear below, and the plural, queries,\nusually means all the traffic an application sends.\n\nAsking which invoices have waited longest for payment reads close to how the\nquestion would be put aloud:\n\n```sql\nSELECT i.number, c.name, i.amount, i.due_on\nFROM invoices AS i\nJOIN customers AS c ON c.id = i.customer_id\nWHERE i.paid_on IS NULL\n  AND i.due_on \u003c current_date\nORDER BY i.due_on\nLIMIT 20;\n```\n\nThe text names what it wants and leaves the method open. Between receiving it\nand returning the first row, PostgreSQL's planner lists the ways it could get\nthe answer, such as reading the whole invoices table or walking an index on\n`due_on`, estimates a cost for each, and runs the cheapest. Those costs are in\narbitrary units, conventionally anchored to reading one page from disk. Two\nqueries that look alike on screen can therefore differ by a factor of a\nthousand once the data under them grows, and the plan is the only place that\ndifference shows.\n\nThe clauses do not run in the order they are written. The manual describes the\nprocessing of SELECT as WITH first, then FROM, WHERE, grouping and HAVING, then\nthe output list, and only after that ORDER BY and LIMIT. That order explains a\nrule that surprises most people once: a name given to a column in the select\nlist works in ORDER BY and GROUP BY, while WHERE runs before the name exists, so\nthere the expression has to be written out again. The result of every query is\nitself a table, which is why queries nest, with a subquery or a WITH clause\nfeeding its rows into a larger one.\n\n## Why it matters\n\nIn an application backed by a relational database, the queries decide much of\nhow fast a page feels and how much hardware the system needs. Which queries\nmatter is arithmetic rather than instinct: a query's cost to the system is its\nduration multiplied by how often it runs. A 2 ms lookup run a million times an\nhour adds up to more than half an hour of database time every hour, while a\nreport that takes two seconds and runs twice a day barely registers.\n\nPostgreSQL keeps that tally in the pg_stat_statements extension. It folds\nstatements that differ only in their literal values into one entry and records\nhow many times each ran and the total time it took. Sorting by the total rather\nthan the average is the habit that pays off first in query work, because it\npoints at the statement worth fixing instead of the one that only looks slow.\n\nEvery query also costs a round trip. The application sends text, the server\nparses, plans and runs it, and rows travel back. For a quick lookup on an\nindex, the trip can outweigh the work. So the shape of the conversation matters\nas much as any single statement: one UPDATE that touches a hundred rows makes\none trip, and a loop that reads a hundred rows and updates each in turn makes a\nhundred and one.\n\nThen there is the question of who writes the queries. An ORM or a query builder\ngenerates them from application code, which is quick for simple reads and\nwrites and keeps the code in one language. It also hides how many statements a\nrequest sends and what they look like, until a page turns slow. Hand-written\nSQL shows both, at the price of someone owning it like any other code. A\nworkable split lets the ORM handle routine records, writes the hot paths by\nhand, and reads the generated SQL of anything that climbs to the top of the\ntotals.\n\n## What it looks like in practice\n\nThe method for a slow database in\n[Optimise the database before you shard it](/notes/optimise-before-you-shard/)\nstarts with queries, before anyone prices more machines. The first step asks\nPostgreSQL which statements cost the most in total, using pg_stat_statements\nsorted by total execution time. The second runs EXPLAIN (ANALYZE, BUFFERS) on\nthe statement at the top, to see the plan the database chose, the rows each\nstep really returned against the rows the planner expected, and how many pages\nit read. The note's rule of thumb is that a scan of a million rows to return\nten, or an estimate a hundred times off, usually explains the slowness on its\nown. It counts round trips too, and draws the line this article draws above:\nwhatever has to see the data moves into the database, and business rules stay\nin the application.\n\nA query can also do the work of a lock. In\n[Selling the last ticket exactly once](/notes/selling-limited-stock-without-overselling/)\na flash sale goes wrong in one of two ways. Reading the stock level, deciding in\nthe application and writing the new number back lets two buyers both take the\nlast unit; holding a row lock across that application logic makes every buyer\nwait behind it. The fix folds the check and the decrement into one conditional\nUPDATE that subtracts the quantity only where enough stock remains and returns\nthe new level. One row back means the unit is reserved, and zero rows means sold\nout. At READ COMMITTED, PostgreSQL's default isolation level, a second buyer who\nreaches the row while the first holds it waits, then evaluates the WHERE clause\nagain against the committed row, so the last unit goes to exactly one of them. A\nCHECK constraint that keeps stock at zero or above stands behind the query.\n\n## Where it goes wrong\n\n**A cheap query that dominates the load.** The database runs hot, yet the\nslow-query log stays quiet, because each call finishes in a few milliseconds.\nThe cause is frequency: one fast query called on every request, often from a\nloop or from a component that appears on every page. Rank statements by total\nexecution time in pg_stat_statements, then cache the result, batch the calls,\nor make the query cheaper with an index that matches its filter.\n\n**A page that sends hundreds of queries.** Each query in the trace takes a\nmillisecond, and the page still takes seconds. An ORM loading related records\nlazily, one query per parent row, is the usual cause, known as the N+1 pattern.\nLoad the related rows in one query, with a join or with `WHERE id = ANY($1)`\nand an array of keys, and watch the count of statements per request as closely\nas the duration of any one.\n\n**The last unit sold twice.** Two requests read the same stock level, both\ndecide there is enough, and both write. Reading and writing in separate\nstatements leaves a gap between the check and the action, and concurrent\ntraffic finds it. Close the gap inside the query, with a conditional UPDATE and\nRETURNING as above, or with SELECT ... FOR UPDATE held as briefly as possible\nand with no network call between the lock and the commit.\n\n**A diagnosis that changed the data.** Someone runs EXPLAIN ANALYZE on a slow\nDELETE to look at its plan, and the rows are gone. ANALYZE executes the\nstatement for real and discards only its output, so every side effect happens.\nWrap any data-modifying statement in BEGIN and ROLLBACK before analysing it, or\nuse plain EXPLAIN, which plans without executing, when estimates are enough.\n\n## Further reading\n\n- [SELECT](https://www.postgresql.org/docs/current/sql-select.html)\n  — the full syntax of a query in PostgreSQL, including the order in which its\n  clauses are processed.\n- [7.1. Overview](https://www.postgresql.org/docs/current/queries-overview.html)\n  — the start of the manual's chapter on queries, with the definition of the\n  word.\n- [51.1. The Path of a Query](https://www.postgresql.org/docs/current/query-path.html)\n  — the trip from the client's text through parser, rewriter and planner to the\n  executor.\n- [14.1. Using EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html)\n  — how to read a plan, what the cost units mean, and why ANALYZE runs the\n  statement.\n- [F.32. pg_stat_statements — track statistics of SQL planning and execution](https://www.postgresql.org/docs/current/pgstatstatements.html)\n  — the extension that ranks queries by what they cost in total.\n- [13.2. Transaction Isolation](https://www.postgresql.org/docs/current/transaction-iso.html)\n  — what a second writer sees under READ COMMITTED, and why the WHERE clause is\n  checked again.\n\n\u003chttps://engineer.company/glossary/query/\u003e\n","date_modified":"2026-10-18T22:40:12Z","description":"What a query is, how the database turns one into a plan, why how often it runs matters more than how slow it looks, and the mistakes that cost most.","formats":{"gemtext":"https://engineer.company/glossary/query/index.gmi","gopher":"https://engineer.company/glossary/query/gophermap","html":"https://engineer.company/glossary/query/","json":"https://engineer.company/glossary/query/index.json","markdown":"https://engineer.company/glossary/query/index.md","pdf":"https://engineer.company/glossary/query/index.pdf"},"kind":"page","language":"en","title":"What is a query?","url":"https://engineer.company/glossary/query/","version":1}