::: info Also known as timeout (with or without @ prefix) :::

Set the query execution timeout for the endpoint.

@timeout <interval>
@command_timeout <interval>

Or using custom parameter syntax:

@timeout = <interval>
@command_timeout = <interval>

The value uses the interval format. Common examples:

::: warning Single Token Requirement The @timeout annotation reads only the first token after the keyword. Use formats without spaces to avoid parsing issues. Numbers without a unit default to seconds. :::

The default timeout is configured via NpgsqlRest.CommandTimeout in configuration. If not set, defaults to 30 seconds.

create function quick_lookup(_id int)
returns json
language sql
begin atomic;
select row_to_json(t) from table t where id = _id;
end;

comment on function quick_lookup(int) is
'HTTP GET
@timeout 5s';

Equivalent as a SQL file endpoint (sql/quick-lookup.sql):

/*
HTTP GET
@timeout 5s
@param $1 id
*/
select row_to_json(t) from items t where t.id = $1;

create function generate_report(_year int)
returns json
language sql
begin atomic;
...complex aggregation...;
end;

comment on function generate_report(int) is
'HTTP GET
@timeout 2min
@authorize';

comment on function slow_process() is
'HTTP POST
@command_timeout 90s';

• Overrides the global NpgsqlRest.CommandTimeout configuration for this endpoint.
• Query is cancelled if it exceeds the timeout.
• On timeout, returns the response configured in ErrorHandlingOptions.TimeoutErrorMapping.

When a command times out, the response is determined by the TimeoutErrorMapping configuration:

{
  "ErrorHandlingOptions": {
    "TimeoutErrorMapping": {
      "StatusCode": 504,
      "Title": "Command execution timed out",
      "Details": null,
      "Type": null
    }
  }
}

Default timeout response: HTTP 504 Gateway Timeout

See Error Handling for customizing timeout responses.

• Interval Format - Complete interval format reference
• NpgsqlRest Options configuration - Set global CommandTimeout default
• Error Handling configuration - Configure TimeoutErrorMapping response
• Comment Annotations Guide - How annotations work
• Configuration Guide - How configuration works

• BUFFER_ROWS - Control row buffering
• RETRY_STRATEGY - Retry on failure

• NpgsqlRest Options - Default timeout setting