query-unevaluable

• Routes: run-eventql-query and write-events
• Description: query cannot be evaluated: <message>, with the message of the evaluator, such as division by zero or cannot cast '978-0756906788' of type STRING to INTEGER: invalid format. For the query of a precondition, the text starts with /preconditions/<index>: , with the place of the precondition in its list, counting from 0.
• Details: When running a query, start and end, each with a line and a column, counting from 1: the first character of the part of the query that fails and the position after its last character. Where that part is not known, details is an empty object. For a precondition, precondition, the place of the precondition in its list, counting from 0.

Why It Happens#

A query that parses can still fail on the values it meets while it runs: a function that gets a value it does not take, such as UPPER on a field that an event lacks, a type conversion of a value that does not fit, a division by zero, an operator that its operands do not take, such as > between a number and a string, which fails with unknown operator: INTEGER > STRING, a value of SKIP or TOP that the query computes and that the clause does not take, as in TOP 1 - 1, which fails with TOP must be at least 1, a function named without being called, such as LEN in PROJECT INTO LEN, which fails with function must be called: LEN, as in LEN(...) before the query reads an event, an unknown function or source, a number that JSON cannot represent, such as the result of SQRT(-1), a string longer than 1 MiB that the query would build, by joining with + or with REPLACE, UPPER, or LOWER, which fails with string is too long: a query may build strings of at most 1 MiB before the string is built, or more rows or values than a query may hold at once, which fails with query result exceeds limit of 1000000 concurrently loaded items, or more than 1 GiB of them at once, which fails with query result exceeds limit of 1 GiB of concurrently loaded data, see Rows Held in Memory.

Such a mistake may show only at some of the events, so a query can fail after it has sent rows, and those rows are not the whole result. A failure from outside the query, such as the server shutting down, is reported by its own code, such as server-shutting-down.

How to Fix It#

Change the query so that it can be evaluated on every event it reads, for example by restricting it with WHERE to the events that have the field, as WHERE e.type == 'io.eventsourcingdb.library.book-acquired' does. Since events never change, sending the same query again fails again as long as it reads the same events.

Example#

To run the query FROM e IN events PROJECT INTO UPPER(e.data.title), which meets an event without a title, EventSourcingDB answers with this error after the rows it has sent so far, as a line of the stream, and then ends the stream with its end item:

{
  "type": "error",
  "data": {
    "code": "https://docs.eventsourcingdb.io/errors/query-unevaluable",
    "description": "query cannot be evaluated: unsupported argument type to `upper` at position 0, got NULL, expected STRING",
    "details": {
      "end": {
        "column": 50,
        "line": 1
      },
      "start": {
        "column": 31,
        "line": 1
      }
    }
  }
}