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';

Kvery detects $status and $from_date, 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.)

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 binds 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.