Cloud9QL Assistant - AI-powered query authoring

Cloud9QL Assistant turns plain English into validated Cloud9QL. Describe what you want in everyday language ("top 5 customers by revenue last month") and the assistant generates a Cloud9QL query, runs it against your actual data to confirm it works, and lets you apply it to the editor with one click.

Every query the assistant returns has been validated against your dataset - if validation fails, the assistant tries to repair it automatically before showing you anything, so you never see Cloud9QL that's broken.

Where to find it

The AI button (ai-icon appears in two places:

  1. Widget editor - inside the Add Cloud9QL modal, in the toolbar above the Cloud9QL Transformations editor.
  2. Queries page - in the toolbar above each per-source Cloud9QL Transformations block, when editing a saved or new query.

Click it to open the assistant chat panel.

What you can ask

The assistant supports three modes:

  • Generate (default) - turn a natural-language prompt into Cloud9QL. Example: "top 5 invoice statuses by total amount"select invoice_status, sum(amount) as total group by invoice_status order by total desc limit 5
  • Fix - paste broken Cloud9QL or a query that returned a runtime error, and the assistant will repair it. Useful when a preview fails and you want help diagnosing. The most recent editor error is auto-attached.
  • Explain - paste any Cloud9QL and get a plain-English explanation of what it does. Useful for understanding queries written by colleagues or copied from older widgets.

Choosing the AI model

The Cloud9QL Assistant uses your account's configured AI Agents model (User Settings → AI Settings → AI Agents). By default this is Knowi's on-prem model. If you have provider credentials configured (OpenAI, Anthropic, Google), you can switch to a stronger model for better Cloud9QL accuracy.

You can also override the model on a per-conversation basis from the dropdown at the top of the chat panel.

Permissions

To use the Cloud9QL Assistant, your role must have all three of:

  • AI — Use AI Agent Assistant for queries (AI_USE_AGENT_ASSISTANT_QUERIES)
  • Query — Edit (QUERY_EDIT)
  • Query — Create (QUERY_CREATE)

Without these, the AI button is hidden.

Outside the UI: MCP

The Cloud9QL Assistant is also available as an MCP tool (cloud9ql_assist) for Claude, Cursor, ChatGPT, Codex, and VS Code. Once your MCP client is connected to Knowi, the assistant works as a tool call alongside get_data, create_query, and the rest of the Knowi MCP toolkit. See the MCP server docs for the tool spec.

Tips

  • Be specific about field names - the assistant can only use fields that exist in your dataset, so use names that match (or are close to) the schema.
  • Ask for one thing at a time - "top customers by revenue, grouped by region, with month-over-month change" can confuse the model. Build it up across a few prompts.
  • Use Refine instead of starting over - clicking Refine on an existing answer keeps the context, so the assistant remembers what you've already asked.
  • Examine the field chips - the assistant lists which fields the generated query references. If a chip surprises you, the model probably mis-mapped your prompt.
  • The chat history clears when you switch queries or widgets - intentional, so old turns don't pollute a new context.