Aster Web Data / Operate

Limits

The caps on what one request may cost, their defaults, and what a client receives when a request goes over one.

One careless request, such as a sort on a column of another database over a large table, should not be able to exhaust the server's memory or hold a database connection for minutes. Aster Web Data caps the work a single request can cause, refuses a request that would go over a cap before it loads the database, and names the limit in the error. Every cap has a default that suits a typical service, and you can change most of them per service.

Request cost limits

Aster does not filter or sort a large table in memory. It sends a request's filter, sort and paging to the database, and refuses a request that would make the engine hold more rows than a cap allows. The cost limits set those caps.

Set the limits under limits, and a service can set its own under services.<name>.limits. A service's keys override the top-level ones, and the keys it leaves out keep the top-level value:

limits:
  residual_rows: 50000
  max_body_bytes: 4194304

services:
  reports:
    root: /reports
    datasources: [model/reports]
    limits:
      residual_rows: 100000

The limits come from three places, in this order: the built-in defaults, then the environment variables ASTER_WEBDATA_RESIDUAL_ROWS, ASTER_WEBDATA_MAX_INSERT_ROWS and ASTER_WEBDATA_MAX_QUEUE_OPS (which sets max_batch_size), then the configuration file. The file wins.

Three further limits are set in the engine and do not appear in the configuration file: an expression may nest 64 levels deep, a plan 256, and a hierarchy function may reach 50,000 keys and output 50,000 rows.

Nesting limits are checked as the request is parsed, so an over-deep expression or $expand is refused before it is planned.

Reads that would run in memory

A $skip or $count that the database cannot apply runs in the engine over every row the database returns. By default the server runs it and logs a warning, and counts it in aster_webdata_unbounded_residual_total. Set limits.unbounded_residual: refuse to refuse these requests instead.

Under refuse, the request fails with 501 NotImplemented, names the option and the set, and asks the client to leave that option out or use one the set can apply itself. The message does not say where the set is stored.

Timeouts

Two timeouts apply to every request:

A request that runs past either timeout fails with 503 and the code Timeout. The engine checks the request deadline every 256 rows.

A $batch is one request: the deadline covers all of its members. A member that starts within it has what is left of it, and a member that would start after it is answered with 503 and the code Timeout without running.

The request deadline also bounds the client's side of a request. A body that has not fully arrived within it is refused with 408 and the code RequestTimeout. A client that stops reading a streamed response is cut off at the deadline: the server stops producing rows, and the body ends without completing.

Connections have timeouts of their own, which no setting changes:

The database stops a statement that runs past statement_timeout_ms: PostgreSQL through its statement_timeout, set for each transaction, and MariaDB through max_statement_time on each write and each SELECT. SQLite and DuckDB interrupt the statement. A timed-out statement answers without a Retry-After header.

Page sizes

A service can cap the size of every page it returns:

• max_page_size is the largest page the server returns, 1,000 rows unless you set it. A client can ask for a smaller page with Prefer: odata.maxpagesize.
• A $top larger than the server's largest page is clamped to it, not rejected.
• A set that declares keysetOrder pages by cursor over one field. Its pages end with an @odata.nextLink, and $skip is refused on it.

Large reads

A read streams its rows. Aster builds the first page before it sends the status, so an error in the first page still answers with its proper status code. A failure after that point ends the response without its closing, so a client cannot mistake it for a complete answer, and the server logs the failure with the request's trace ID.

Counts

$count=true is always exact. The server reads the top page and runs COUNT(*) in one snapshot, so the count and the rows agree. On a very large set, a restrictive $filter keeps the count cheap, and an index on the filtered column lets the database answer it quickly.

What a refusal looks like

A refusal is an OData error object with a stable code, a message for people, and a target where one applies. This request sorts the invoices by their customer's name, which are stored on another database, with residual_rows set to 50 so that the engine would hold more rows than the limit allows:

HTTP 400
content-language: en
content-type: application/json;odata.metadata=minimal
odata-version: 4.01

{
  "error": {
    "code": "QueryTooExpensive",
    "message": "the request would hold more than 50 rows in memory to answer it. Filter, sort or page it so the database does the work, narrow the request, or raise `limits.residual_rows`"
  }
}

The codes a limit produces:

For QueryTooExpensive, the client can push the filter, sort or page down to the database, or narrow the request. Filters, sorts and paging that the database applies keep rows out of the engine. The Error codes reference has every code. What runs on your database shows the SQL each request sends, so you can see which part of it the database runs.