Skip to main content

Form Variables

Form variables turn a static query into an interactive one. Anywhere you write a $-prefixed variable in your SQL, Kvery renders an input field for it — so the same query can be re-run with different values without editing the SQL.

Declaring a variable​

Use a $-prefixed name (a dollar sign followed by a name) anywhere in your query:

SELECT *
FROM orders
WHERE status = '$status'
  AND created_at >= '$from_date'
  AND id IN ($ids);

Kvery detects $status, $from_date and $ids, shows an input for each, and substitutes the values you enter when the query runs. The values come from the request (the form fields, or the matching URL/body parameters when the query is called as an API).

Form variables vs. internal variables

A $-prefixed name ($status) is a form variable — it creates an input field and is filled from the request. A :-prefixed name (:log) is an internal variable that you declare or that Kvery provides; it is not a form field. (Note: :: — a double colon — is a PostgreSQL type cast, e.g. value::int, not a variable.)

How values are inserted​

The value replaces its parameter in the SQL text:

  • Inside quotes ('$status') apostrophes in the value are escaped, so the value stays inside the quoted text. Put text, dates and anything else that is not a plain number in quotes.
  • Without quotes ($id, IN ($ids), ORDER BY $column) the value is inserted as it is. Use this for numbers, comma-separated lists of numbers and column names.

The same rules apply in the editor, on shared links, in the API and through the MCP server.

Why use them​

  • Reusable reports. One query serves many cases — pick a date range, a status, a customer id.
  • Safe sharing. When you share or publish a query as an API, the form variables become the inputs/parameters the consumer supplies.
  • Dashboards. A dashboard tile can prompt for the variable so viewers drive the report themselves.

Using variables in the API​

When a query with form variables is published as an API endpoint, each variable becomes a request parameter. The caller passes values and the query uses them exactly as the form does in the editor.

Tips​

  • Give variables clear names — they become field labels and API parameter names.
  • Combine with internal variables (like the current user) to scope results automatically.
  • Provide sensible defaults in your WHERE logic so the query still returns something useful before the user changes a value.