Skip to main content

Dynamic reports

Insights is the fastest way to get answers about your platform: you describe what you want in the AI dashboard builder and it assembles the widgets and queries for you.

Sometimes you want more control. When you need a report with a specific input form, exact queries, and a shape you define yourself, you can build it by hand as a dynamic report. Once published, it surfaces in Insights alongside the AI-generated dashboards, so your readers get to it the same way.

A dynamic report combines three things you define yourself:

  • A JSON Schema that defines the report's input fields.
  • A UI Schema that controls how those fields render as a form.
  • A set of queries that pull data and can populate field options.

Because reports use the same schema engine as the rest of nullplatform, you can reuse everything you already know from JSON UI Schema to design the form.

tip

If you just want a quick dashboard, start with the AI dashboard builder. Reach for dynamic reports when you need to hand-craft the form and queries.

What a report contains​

Besides the schema, the UI Schema, and the queries, a report has a name (the only required field), an optional slug and description, and a visibility setting that controls who can see it. The Reports API documents the full shape.

Queries​

The queries field maps a query ID to a query definition. A query runs a SQL SELECT and can populate a form field's options with the results.

Each query supports:

  • source: the SQL SELECT statement. It can include {name:Type} placeholders.
  • params: binds each placeholder to a form field. Each param has a scope, a JSON Pointer to the field (for example #/properties/environment).
  • target: a JSON Pointer to the schema property the query populates.
  • mapping: how results map onto the target field. Use enum to turn query results into the field's selectable options.

This is what makes reports dynamic: a query can read a value the user picked in one field and use it to populate the options of another.

{
  "environments": {
    "source": "SELECT name FROM environments WHERE account = {account:String}",
    "params": {
      "account": { "scope": "#/properties/account" }
    },
    "target": "#/properties/environment",
    "mapping": "enum"
  }
}

Visibility and access​

A report's visibility controls who can work with it. user reports are private: only the owner can see and edit them, within their own organization. organization reports are shared: everyone in the organization can see and edit them.

Next steps​