query-malformed

• Routes: run-eventql-query, write-events, and format-eventql-query
• Description: query is malformed at line <line>, column <column>: <message>, with the position where the parser stops, counting from 1, and the message of the parser, which says what it expected and what it got instead. For the query of a precondition, the text starts with /preconditions/<index>: , with the place of the precondition in its list, counting from 0. Where the parser names no position, the text leaves out the line and the column.
• Details: When running or formatting a query, start and end, each with a line and a column, counting from 1: the first character of the part that does not parse and the position after its last character. Where the parser names no position, details is an empty object. For a precondition, precondition, the place of the precondition in its list, counting from 0.

Why It Happens#

EventSourcingDB parses a query before it runs it, and refuses one that does not follow the syntax of EventQL, such as one with a misspelled keyword, as in PROJEKT INTO, one that does not end with PROJECT INTO, or one with a string that lacks its closing quote. A query of nothing but whitespace is refused this way as well, while an empty one is query-missing.

A query that nests more than 256 levels or holds a chain of more than 10,000 operands is refused before it is parsed, with query-too-deep instead, also where it would not parse either, such as one with more than 256 parentheses that are never closed.

The parser also refuses a number that does not fit its type, with the message integer <number> is out of range or float <number> is out of range: an integer with more than 1,000 digits, leading zeros aside, and a decimal beyond the range of a 64-bit floating-point number.

It refuses a value of SKIP or TOP that the clause does not take as well, where the query writes it as a literal: one that is not an integer, such as TOP 1.5, with TOP must be an integer or SKIP must be an integer, and one below the least the clause takes, such as TOP 0 or SKIP -1, with TOP must be at least 1 or SKIP must be at least 0. A value that the query computes, as in TOP 1 - 1, is checked only when the query runs, and fails it with query-unevaluable.

For a precondition, the query is parsed only when the write evaluates it, after the preconditions on subjects. So if one of those does not hold, the write reports precondition-violated first.

The route format-eventql-query belongs to the management UI, which formats the queries of its EventQL editor through it. It exists only while the management UI is enabled, with --with-ui, is not part of the stable API, and answers with a single envelope, the error itself, rather than a stream.

How to Fix It#

Correct the query at the position that the description and the details name; the EventQL editor of the management UI marks it for you. Sending the same query again fails the same way, since the error depends on the query alone.

Example#

To run the query FROM e IN events PROJEKT INTO e, EventSourcingDB answers with this error, 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-malformed",
    "description": "query is malformed at line 1, column 18: expected next token to be one of ['FROM' 'GROUP' 'ORDER' 'PROJECT' 'SKIP' 'TOP' 'WHERE'], got PROJEKT instead",
    "details": {
      "end": {
        "column": 25,
        "line": 1
      },
      "start": {
        "column": 18,
        "line": 1
      }
    }
  }
}