Your module collects data. A dataset lets people use it: on dashboards, in reports, and in the assistant's answers ("how many jobs did we close last month, by crew?"). You describe your data once, and every reporting tool on the platform can use it, for each person within their permissions.
What a dataset is
A dataset is a description of one of your tables in business words:
| Part | What it means | Example |
|---|---|---|
| Dimensions | Things to group by | Status, crew, month created |
| Metrics | Numbers to add up | Count of jobs, total hours, average days open |
| Filters | Ways to narrow it | Date range, status |
| Permission | Who may see it | One of your module's view permissions |
Nobody writes database queries. People pick jobs by crew, last 90 days, and the platform works out the rest.
Who can see it
Only people whose role holds the dataset's permission can see or query it. They see every row in it: there is no "only my own rows" option yet. So:
- If your screens show people only their own records (their time, their tasks), publish the dataset behind a permission that already means "see everyone's".
- Money (rates, costs) goes behind the permission that already shows money in your module.
- Rows hidden from everyone (private or restricted records) can be left out of the dataset entirely.
Joining with other modules' data
A dataset can say "my asset column points to the Assets module's assets". Dashboards can then show work orders by asset type across both modules. The other module decides what it publishes, and a person needs permission for both datasets to see the combined numbers.
How the assistant uses datasets
The Dashboards & Reports agent, and Claude or ChatGPT with the Data Visions connector, can list the datasets a person may see, read what's in them and query them. Every number they quote comes from your dataset, as that person. Good names and short descriptions make better answers, so describe each dimension and metric the way your users talk.
The same dataset can also draw charts on your own screens. See Charts, maps and 3D.
Datasets you create while running
Some modules create tables as they go: an uploaded spreadsheet, a copy of another system's data. Your module can publish a dataset for those too, for one workspace, while it runs. These take plain columns and simple totals (count, sum, average, minimum, maximum, distinct count and ratios). They appear in dashboards, reports and the assistant within about 20 seconds; a workspace can have up to 200.
Ask the Module Builder
For developers
{"name": "jobs", "display_name": "Jobs", "source_table": "jobs",
"permission_code": "JOBS.VIEW_ALL",
"dimensions": [{"name": "status", "type": "string", "column": "status"},
{"name": "month", "type": "date_trunc:month", "column": "created_at"}],
"metrics": [{"name": "jobs", "agg": "count"},
{"name": "hours", "agg": "sum", "column": "hours"}],
"filters": [{"name": "created", "type": "date_range", "column": "created_at"}]}It lives in ai/skills/dataset-jobs/dataset.json, next to a short SKILL.md.
Good to know
- Publishing is the default. A module with tables and no dataset gets a recommendation from the module check.
- The Marketplace requires it. A listed module needs at least one dataset, each behind one of its own permissions.
- Printable reports build on the same data: see Report templates.