ask

Invocation#

echo-cli ask --question <text> --max-rows <count>

Inputs and output#

{ question, route, statement, explanation, total, rows }: the question as asked, the Brama route that wrote the statement, the one SELECT statement that was run, what it computes in one sentence, how many rows it gives, and the first --max-rows of them as JSON objects.

State effect#

The command calls Echo Web's POST /api/ask with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the dashboard's Ask screen, the Ask Echo's data section of Echo Desktop's GEO screen and echo-mcp (echo_ask) call the same operation. The route ECHO_ASK_ROUTE declares is shown the tables a question may read — web_analytics_events, mobile_analytics_events, products, blog_posts, creator_contacts, crm_campaigns, crm_campaign_recipients, geo_runs, geo_answers, automation_audit and approval_requests — with their columns as the database describes them now, and answers by one call of record_statement. Before the statement runs, Echo Web hands the database role ask_reader SELECT on exactly those tables and nothing else (ask_grant), and the statement runs as that role: the database plans it first, and a plan that writes, or reads any other table, is refused and nothing runs; a table the plan check could not see, read through a view or a function, is refused by the role's own privileges. The rest runs in a read-only transaction as a subquery; total counts every row it gives and rows holds the first --max-rows. Nothing is stored.

Refusals#

• A wrong invocation is refused before anything is sent: "ask does not take <flag>; it takes --question, --max-rows", "<flag> needs a value", "ask needs --question <text>: what to ask of Echo's data", "ask needs --max-rows <count>: the most rows the answer shows" and "--max-rows must be a whole number; got <text>".
• Echo Web's refusal is printed as "Echo Web refused POST /api/ask with HTTP <status>: <its answer>": a bad request with "question is required: what to ask of Echo's data, in words" or "max_rows must be a positive whole number: the most rows the answer shows; got <value>"; an unprocessable request with "the statement written for the question holds more than one statement, so it was not run: <statement>" or "the statement written for the question was not run: <why>. The statement: <statement>", where why is "the statement writes (<operations>); a question runs only statements that read", "the statement reads <tables>, which questions may not read; they read <tables>", the role's "permission denied for <table>", or the database's own refusal of the statement (a syntax error, an unknown column). When the role cannot be given the declared tables Echo Web fails with "the role questions run as could not be given the declared tables (<tables>): <the database's message>".
• Without ECHO_ASK_ROUTE Echo Web answers that it is required. A route that declines or answers without the one call answers "the question could not be answered: the route <route> …" naming what it did, and a route that calls record_statement without a statement or an explanation is named the same way.