Skip to content
datarelix.ai docs

Writing Queries

Writing Queries

datarelix.ai turns natural-language questions into validated SQL/KQL plus optional Python analysis. This guide shows the moves that get good answers fast.

Start with a connection

Every conversation is bound to one connection. Pick a connection from the sidebar selector before you ask. Switching connections mid-conversation prompts a confirmation and starts a fresh chat — your queries never run against the wrong database.

Schema discovery makes asking easier

The first time you connect, datarelix.ai introspects the schema and (optionally) uses an LLM to enrich each table with a short description. The descriptions show up in the planner prompt — better descriptions mean better queries.

If a table is poorly named, edit its description in the connection’s discovery view. You can also mark or unmark primary-key and foreign-key columns there. Key edits override database and LLM hints for planning, but never change the source database or the raw introspection snapshot.

When you rerun Analyze, add optional notes about the database, important tables, or main key columns. These hints help the discovery LLM produce better descriptions and relationship hints.

Question patterns that work well

  • Aggregate questions: “What was monthly revenue last quarter?”
  • Top-N questions: “Top 10 customers by lifetime value.”
  • Comparative questions: “How does conversion compare between the US and EU?”
  • Trend questions: “Show signups per week for the last 6 months.”

Be specific about the time window and the grain (day/week/month). Specific questions get specific queries.

@-mentions: pin tables and columns

Type @ to insert a table or column directly into your question. Useful when:

  • A schema has many similarly-named tables and you want to be exact.
  • You want to scope an analysis to a specific column.

The mention shows up as a pill in your prompt and in the planner’s context.

Filter pills

Below the input you’ll see chips for the tables in scope. You can:

  • Toggle individual tables on or off.
  • Toggle individual columns within a table.
  • Click “Clear” to reset.

Narrower scope = faster, cheaper, and more accurate planning.

Chart toggle

The chart toggle next to the input switches between text-only answers and chart-augmented answers. Charts come from a sandboxed Python step that runs after the SQL step — adds a few seconds but produces visual results you can pin to dashboards.

Reading the answer

Every assistant message has these parts:

  1. Answer text — the LLM’s natural-language summary.
  2. Artifact — table or chart, depending on the question.
  3. Evidence row — tables used, row count, runtime. Always visible.
  4. Trace toggles — the exact SQL/KQL and the step-by-step execution log are one click away.

If something looks off, expand the SQL. If the SQL looks right but the data doesn’t, the issue is upstream of datarelix.ai.

When things go wrong

datarelix.ai sorts errors into five classes. Each has its own recovery UI:

  • No results — broaden the question.
  • Timeout — narrow the scope or shorten the window.
  • Plan failure — the LLM couldn’t produce a valid plan; edit the question and retry.
  • Connection failure — re-test the connection from the sidebar.
  • Permission/validation — your auth is rejected at the database; check your credentials.

See Error Codes for the full taxonomy.

Pinning to a dashboard

Any chart can be pinned to a dashboard from the chart’s overflow menu. Dashboards refresh on demand or on a schedule (Cloud / Enterprise).

Sharing a conversation

Every conversation has a deep link at /c/<id>. Copy and paste — anyone with access to the connection can replay the trace.