The params: of a SQL query, as both clients send and read them.
Client.HTTP sends the parameters as the JSON object of the request body;
Client.Local binds what the engine would read from that object. Both
start from normalize/1, so a value either client refuses is refused with
the same error tuple, and the JSON Client.HTTP sends is the JSON
Client.Local reads back with engine_values/1.
params: is a map or a keyword list, or nil for none (the engine accepts
"params": null). A parameter is a nil, boolean, number, string, atom
(sent as its name), Date, Time, NaiveDateTime, DateTime (sent as
ISO-8601 strings) or a Decimal, which is sent as a JSON number: Jason
encodes a Decimal as a string, which the engine would compare as text. A
map or a list encodes but is refused by the engine (Client.HTTP returns
its 400, Client.Local the same body), and so is a number its JSON parser
cannot read (1e400, Integer.pow(10, 400)): number out of range.
Errors
{:invalid_param, name, :non_finite_decimal}— aDecimalthat is NaN or an infinity, which has no JSON number{:invalid_param, name, :unsupported_type}— a valueJasoncannot encode (a tuple, a pid, a function){:invalid_param, name, :unsupported_key}— a name that is not a string, an atom or a number (a tuple){:invalid_param, name, :unsupported_params}—params:itself is neither a map nor a keyword list
name is the parameter's name as a string, or the inspected term for an
unsupported key or params: value.
Summary
Types
The error normalize/1 returns: the parameter's name and why it is refused.
What the engine's JSON parser finds wrong with one parameter, if anything.
Why a parameter cannot be sent.
The parameters as the request body carries them: string keys, JSON-encodable values.
Functions
What the engine reads from the parameters: the request body's JSON read
as its parser reads it. A number is read as serde_json reads it: an
integer in the Int64/UInt64 range stays one, any other is a float. The
parameters must be free of problem/1s.
Validates the parameters (a map, a keyword list or nil) and returns them
with string keys, each value ready for Jason.
What the engine's JSON parser refuses in one parameter: an object, an array
or a number it cannot read; nil when it reads it.
The JSON body Client.HTTP posts to /api/v3/query_sql: db (left out
when database is nil), format (left out when it is nil, as for a
statement run with execute_sql), params and q, written in that order
(Jason writes a small map's keys sorted). The engine's JSON parser reports
an error by its byte position in this body, so Client.Local and the
contract tests that pin the position read it from here.
Types
The error normalize/1 returns: the parameter's name and why it is refused.
@type problem() :: :object | :array | :out_of_range
What the engine's JSON parser finds wrong with one parameter, if anything.
@type reason() ::
:non_finite_decimal
| :unsupported_type
| :unsupported_key
| :unsupported_params
Why a parameter cannot be sent.
The parameters as the request body carries them: string keys, JSON-encodable values.
Functions
What the engine reads from the parameters: the request body's JSON read
as its parser reads it. A number is read as serde_json reads it: an
integer in the Int64/UInt64 range stays one, any other is a float. The
parameters must be free of problem/1s.
Validates the parameters (a map, a keyword list or nil) and returns them
with string keys, each value ready for Jason.
What the engine's JSON parser refuses in one parameter: an object, an array
or a number it cannot read; nil when it reads it.
The JSON body Client.HTTP posts to /api/v3/query_sql: db (left out
when database is nil), format (left out when it is nil, as for a
statement run with execute_sql), params and q, written in that order
(Jason writes a small map's keys sorted). The engine's JSON parser reports
an error by its byte position in this body, so Client.Local and the
contract tests that pin the position read it from here.