NpgsqlRest

Appearance

Comments
Written with Claude

RESULT_NAME ​

Rename the default result keys (result1, result2, ...) in multi-command SQL file endpoints. This makes the response JSON more descriptive and easier to consume.

This annotation only applies to multi-command SQL file endpoints (files with multiple SQL statements separated by ;).

Available since version 3.12.0.

Syntax ​

code
@result <name>
@result is <name>

The @result annotation is positional. It can be placed in two ways:

  1. Before the statement (on a separate line) — applies to the next statement below it
  2. Inline after the semicolon (on the same line) — applies to the statement on that line

This same placement rule applies to all positional annotations: @result, @single, and @skip.

Examples ​

Before Statement (Separate Line) ​

Place @result name on a line before the statement it applies to:

sql
sql
-- sql/dashboard.sql
-- HTTP GET
-- @result users
SELECT id, name FROM users;
-- @result orders
SELECT id, total FROM orders;

Response:

json
json
{
  "users": [{"id": 1, "name": "Alice"}, ...],
  "orders": [{"id": 1, "total": 99.99}, ...]
}

Inline After Semicolon (Same Line) ​

Place @result name after the semicolon on the same line as the statement:

sql
sql
-- sql/dashboard.sql
-- HTTP GET
SELECT id, name FROM users; -- @result users
SELECT id, total FROM orders; -- @result orders

Produces the same result as the previous example.

"is" Style Syntax ​

The is keyword is optional:

sql
sql
-- These are equivalent:
-- @result validate
-- @result is validate

Naming Some Results ​

Commands without a @result annotation keep their default auto-generated key:

sql
sql
-- sql/process_order.sql
-- HTTP POST
-- @param $1 order_id
-- @result validate
select count(*) from orders where id = $1;
update orders set status = 'processing' where id = $1;
-- @result confirm
select id, status from orders where id = $1;

POST /api/process-order with {"order_id": 42} returns:

json
json
{
  "validate": [1],
  "result2": 1,
  "confirm": [{"id": 42, "status": "processing"}]
}
  • First command renamed to validate
  • Second command keeps its default name result2 (no annotation)
  • Third command renamed to confirm

Naming All Results ​

sql
sql
-- sql/dashboard_data.sql
-- HTTP GET
-- @result users
select count(*) from users;
-- @result orders
select count(*) from orders where created_at > now() - interval '24 hours';
-- @result revenue
select sum(total) from orders where created_at > now() - interval '24 hours';

Response:

json
json
{
  "users": [{"count": 150}],
  "orders": [{"count": 42}],
  "revenue": [{"sum": 12500.00}]
}

Behavior ​

  • Default result keys use the format result1, result2, result3, etc.
  • The prefix (result) is configurable via the ResultPrefix setting in SqlFileSource configuration
  • Commands returning rows produce a JSON array of row objects
  • Void commands (INSERT/UPDATE/DELETE without RETURNING) produce an integer (rows affected count)
  • Only results with a @result annotation are renamed; others keep their default key
  • This annotation has no effect on single-command SQL file endpoints (they return a plain array, not a keyed object)

Comments