Directives
Directives are special instructions you add to a query to control how Kvery responds when the query runs — its error message, its HTTP status code, and any webhooks it should fire. They are most useful for queries published as an API, where the response and status code matter to the caller.
The editor suggests each directive as an autocomplete item, so you can insert the correct syntax without memorising it.
ON ERROR RETURN
Return a custom message when the query fails, instead of the raw database error.
SELECT * FROM orders WHERE id = :id;
ON ERROR RETURN 'Order not found or could not be loaded'
This gives API consumers a clean, controlled error message.
SET HTTPCODE
Set the HTTP status code of the response. This lets an API endpoint return a
meaningful status (for example 404 for "not found" or 422 for a validation
problem) rather than a generic one.
SET HTTPCODE '404'
Combine it with ON ERROR RETURN to pair a message with a status code.
ON SUCCESS POST '...' TO '...'
Fire a webhook after the query succeeds. Kvery sends an HTTP request to the URL you specify, carrying the text/JSON payload you provide.
ON SUCCESS POST 'text, json' TO 'https://example.com/webhook'
POST is the usual method, but Kvery accepts any of GET, POST, PUT,
PATCH or DELETE in this position — use whichever the receiving endpoint
expects:
ON SUCCESS PUT 'text, json' TO 'https://example.com/resource'
Use this to notify another system when a query completes — for example to trigger
a downstream job after an INSERT.
ON ERROR POST '...' TO '...'
Fire a webhook when the query fails. Same shape as the success variant
(any of GET, POST, PUT, PATCH, DELETE), but triggered on error —
ideal for alerting.
ON ERROR POST 'text, json' TO 'https://example.com/alert'
See Webhooks for payload details and patterns.
Helpers: return(); and returnk();
The editor also offers return(); and returnk(); helpers for controlling query
output flow. Insert them from autocomplete where you need to short-circuit or
shape the returned result.
Putting it together
A robust API query often combines several directives:
INSERT INTO signups (email) VALUES (:email);
ON ERROR RETURN 'Could not register that email'
ON SUCCESS POST 'text, json' TO 'https://hooks.example.com/new-signup'
ON ERROR POST 'text, json' TO 'https://hooks.example.com/signup-failed'
This returns a clean error message, notifies a webhook on success, and alerts a different webhook on failure — all without any backend code.