Visualisation

The Visualisation is where your team works with a finished analytic app. It is built from widgets on a grid, tables, charts, text, and inputs, that turn the results of your pipeline into something people can actually use. It is more than a report to read: from the Visualisation your team can run the app, see the latest run results, filter the data, type values back into a table, and download what they need. An app can hold more than one page of widgets, so a single app can cover several related topics.

How the Visualisation is built

You build it in the editor, on the Visualisation tab. Add widgets, arrange them on the grid by dragging and resizing, and give each data widget a data source: the pipeline step (called a node) whose results it should show.

A Table, Chart, Pivot or Figure widget can read any node that holds data, and so can a parameter whose dropdown options load from a node: a dataset, a SQL node, and the two nodes that import data from elsewhere, indicator data from one of your indicator apps and analytic app data from another analytic app. You can show imported figures directly, without a SQL node in between. An imported node gets its columns from the pipeline's last successful run, so run the pipeline once after adding one: until then the widget's column settings ask you to run it first.

For data to appear, the pipeline must have run at least once. If a widget prompts you to run the pipeline, switch to the Data Pipeline, click Run, and the widget fills with fresh results. See the Pipeline overview for how running works.

While you work, all of this lives in your private draft. Click Publish to hand the new layout to your team; until you do, they keep seeing the previous one. See Draft and publish.

When the Visualisation shows nothing

An app your team opens shows results from the latest published run. When there is no such run, the widgets are empty and a notice at the top of the page says which of three things is missing, and what fills it:

If there is no notice and a widget is still empty, the app IS populated and the question is the data itself: the filter or query matched no rows.

The Run button appears only for people who may run apps. Everyone else sees the same notice ending in "Ask a workspace administrator...", because the run would be refused for them.

When a widget names a column that no longer exists

A chart or pivot that groups its data names the columns it groups by and the columns it adds up, and how it adds each one up. If one of those columns is not in the widget's data source any more - it was renamed or removed in the pipeline, or Vera or an import created the widget with a column that was never there - or a summary names a function other than sum, count, avg, min or max, the widget does not guess. It shows a short message instead of data:

There is no Try again: asking again gives the same answer until the widget changes.

To fix it, open the widget's settings in the editor. The column that no longer exists shows as an empty choice: pick one of the data source's columns there, or remove that row with its X. The widget reads its data again and draws as soon as the answer arrives. People reading the published app see the message until you publish the corrected version.

When a widget uses an unsupported feature

A widget whose saved settings use a feature Ovidens no longer supports shows "This widget uses a feature that is no longer supported" in its own space. The other widgets on the page keep working. The same notice appears wherever a report or printout places that widget. Vera and connected AI clients receive the notice as a note, with no data for that widget.

An unsupported widget does not stop you editing the rest of the Visualisation: the editors keep saving your other changes and leave that widget exactly as it was saved. To clear the notice, remove the widget or replace it with a new one. If an edit leaves a widget with a setting its type does not accept, a persistent banner names the widget and its page, and changes are not saved until you correct or remove it.

Each widget accepts only the settings for its own type. When Vera, a connected AI client or an app import supplies an invalid setting, Ovidens refuses the write and names the widget and the field. Choosing a different type in the editor starts with that type's settings.

Widget settings for AI clients

The tool schema describes nine authored widget types selected by type. All share id, type, title, description, descriptionAsTooltip, width and height. Widths are full, half, third or quarter; heights are steps 1 through 4 or auto. Each alternative adds only these fields:

Nested entries also have their own schemas. Filters use id, column, operator and value; aggregates use id, column, function and an optional label (a chart aggregate can also have color). Aggregate functions are sum, count, avg, min and max. A table has no grouping settings: use a pivot to summarise rows. The tool schema states which fields can be omitted. Omitted settings on an existing widget are kept; a new widget starts with its type's defaults.

An unsupported widget is a read-only fallback, outside the tool schema. A write that leaves it as it is - sending it back as exactly its id and type, or not naming it in an edit - keeps it exactly as stored, so it never blocks a change to another widget. Sending it back with all its stored settings is refused. A write that changes it without making it valid is refused, naming the widget and its settings: remove it, or change its type to rebuild it. Changing a widget's type keeps its title, description and size and, when the new type reads data, its node, fixed filters and parameter opt-out; every other setting starts from the new type's defaults.

An AI write is limited in length for what it adds or changes: a new page or widget id is at most 64 characters, a widget title 200, a page name 120 and a widget description 2,000. A value sent back unchanged is not limited, so a longer name someone typed in the editor stays. A text widget's content has no limit.

The widgets

Every widget is added in the editor and positioned on the grid. Table, Chart, Pivot and Figure widgets use a pipeline node as their data source; the other types have the settings described below.

Text

The Text widget puts formatted text on the page: headings, short notes, and instructions. Use it to give the page structure and to explain what people are looking at, for example a title, a note on where the data comes from, or how to use a filter. It shows no data, so it needs no data source.

Table

The Table widget shows your data as rows and columns, straight from a node. You choose which columns appear. To summarise rows by group, use a pivot. A table works in one of two ways:

• Read-only tables display data and cannot be changed, the usual choice for a report.
• Data-entry tables let people type values directly into the table from the app. Edits are saved when the pipeline runs. This is how a Visualisation becomes a place to enter data, not just read it. Only a data-entry table offers Import for loading a file into it, and in the editor its header carries an Editable label so you can tell it apart from a read-only table at a glance. A table with fixed filters is always read-only: its settings show a short note saying why instead of the Editable switch. Adding fixed filters also switches Editable off, and removing them later leaves it off, so switch it back on if the table should take entries again.

Anyone whose role lets them enter data in the app - Contributor, App builder or Admin - can edit the rows of a data-entry table: change a value, add a row, or delete one. Each change is recorded in the audit trail under the name of the person who made it. Import, loading a file into the table, stays with workspace administrators, so other members do not see it.

Tables respect your parameters: with a region filter set to "North", the table shows only North rows, and a small label shows which filter is active.

A table keeps the rows it holds in view. With an automatic height it grows with its rows, and while someone is editing it (Edit) it grows a little more to make room for the Save and Cancel buttons and the New row strip, so a table filtered to the one or two rows being corrected keeps them on screen. With a fixed height the card keeps its size; if it is too small for the table, the table scrolls inside the card, under the widget's title, so every row, the page controls and Save and Cancel can still be reached.

With an automatic height, a table is never taller than the window it is read in. It shows as many whole rows as fit below its title, together with its page controls and its Show all button, and always at least five rows, so in a very small window the page scrolls instead. A pivot with an automatic height does the same. Resize the window or zoom the browser and the table follows, showing more or fewer rows, without reloading anything. Show all shows up to 100 rows at once, and the page scrolls to reach them.

If a table's data cannot be loaded, the table says so in its own space, where the column names and rows would be, with a Try again button that asks again. The message stays while the request is repeated; then the rows come back, or the message shows again if the data still cannot be loaded. Search, sort and filter stay available, because changing any of them asks for the data again. Edit and + Row are unavailable until the data loads, and anything typed but not yet saved is kept.

A table can be downloaded from the widget itself. You choose CSV or Excel - the Excel file keeps the column types and the percent and currency formatting the table shows on screen, so it opens ready to sort and total. See Download the data.

Which rows the file holds depends on where the table is. A table in the Audit Analytics app, or on a survey's Results page, downloads the rows it shows: its filters (including the ones a link set when it opened the page already narrowed to one resource), the page's parameters and the search all apply, so a table showing 312 rows downloads 312. The file carries every column of the table's data source, not only the ones on screen, and its rows come in the table's own default order rather than one you sorted them into. A table in any other app downloads its whole data source, whatever is filtered on screen. A spreadsheet holds about a million rows, so Excel is refused for a bigger table, with a message saying so - choose CSV for it.

Files in a table

A table over a dataset with an Attachment column shows each row's files exactly as the dataset's own data view does. Click the file icon in a cell to see the files with their names and sizes, download one (you are asked what to name it first) or see an image in a larger view. Downloading works on every table, read-only ones included, for anyone who can read the app.

On a data-entry table, administrators can also add and remove files while editing (Edit): choose Add file on an empty cell or the paperclip on a filled one, then pick files or drag them onto the upload dialog. Each file can be up to 10 MB; a bigger one is refused in the dialog and nothing else you changed is lost. To replace a file, remove it and add the new one. A file is uploaded when you confirm the dialog, but it becomes part of the row only when you choose Save; Cancel drops it with the rest of the unsaved changes. Other readers of the app can download files but not add or remove them. See Files in an attachment column for what happens to a file that is removed.

Context columns

Context columns put facts from other datasets beside each row, so the people correcting a table see what they need without leaving it. A table over a dataset, read-only or data-entry, can carry up to 10 of them in total, shown after its own columns with a lock in the header that names the dataset each one comes from.

Context columns come from context from a dataset: you choose a dataset of the same app, and how its rows match this table's rows, once, and then pick as many of its columns as you need. Every column of one context reads the same matching rows. Each column is one of:

• Value shows a column of that dataset from the first matching row: each order's product category from your products dataset, for example.
• A function counts or adds up all the matching rows: how many customers bought each product, or the revenue of all its orders, for example. The functions are Count, Count distinct, Sum, Average, Minimum and Maximum, and that list is complete: a calculation beyond them, such as a ratio or a count of only some rows, belongs in a SQL node.

One context can mix both: from your orders dataset, the first customer, the number of customers and the revenue, all matched on the product.

To add context, open the table's settings and find Context columns in the Data group, under the columns. Click Add context from a dataset. Choose From dataset, then Match rows where a column of this table equals a column of that dataset (Match another column adds a second or third pair). Then, for each column, choose its Column and its Function - Value or one of the functions - and give it a Name; Add column adds another column from the same dataset. The editor offers only the functions the dataset has a column for and, per function, only the columns it can use. Renaming a column, or changing its function, keeps it the same column. If you later switch a context to another dataset, the columns that dataset also has stay - found by the same column, or by a column of the same name - and the others go; removing a context's last column removes the context. One context is open for editing at a time.

How values match. A dropdown is compared by the label you see. A number and a text are compared as numbers, so 1 matches "1", "1.0" and "1.00", while a text that is not a number matches nothing - that includes a number written with a decimal comma, such as 1,5. A date and a timestamp are compared by the calendar day, so the date 5 January 2024 matches every timestamp on that day. A text and a date or a timestamp are compared as that date or timestamp: 2024-01-05 matches the date 5 January 2024, and against timestamps it matches only midnight of that day. Two timestamps must be exactly equal. Rows of the other dataset whose match value is empty, or does not read as the type it is compared as, are left out.

What a column shows. A row with no match shows 0 for a count and stays empty otherwise. A row whose own match value is empty shows empty in every column, counts included, because "no customer" is not "no orders". Count without a column counts the matching rows, and with a column counts its non-empty values. Average is the mean of the non-empty values. Minimum and Maximum of a text compare by character code, so Zebra comes before apple, and a dropdown compares by its label, not by the order of its options. A sum keeps its column's type: a sum of a currency column shows that currency, a sum of a percent column a percent, and a sum of whole numbers a whole number; an average keeps a currency or a percent and is otherwise a decimal. A Value, a minimum and a maximum of a currency or percent column show its format too.

What is refused. Sum and Average take a number, currency or percent column, but not a year: the sum of years is not a number anyone reads. A multi-select column holds several options in one cell, so it cannot be a match column, and Count distinct, Minimum and Maximum cannot read it; Count and Value can.

Context columns sort, filter and search like any column, but they are never edited: they are not part of Edit, the new-row form or the record panel, and the text filter suggests no values for them. They always show, since hiding and pinning apply to the table's own columns. Their values come from the same data as the rows - your draft in the editor, the published version for your team - and follow an edit the next time the table loads, with no pipeline run. A download carries the table's own columns only.

When a match value appears more than once in a context's dataset, a Value column shows the first row's value and an amber ! in its header says how many values repeat; a function reads every matching row and shows no warning. A column that cannot be read - its dataset or column was deleted, or it asks for something refused above - stays empty with a red ! in the header saying why, while the rest of the table loads as usual. Vera can add context columns too; one that names something that does not exist, or asks for something refused above, is refused with the reason.

Chart

The Chart widget draws your data as a bar, line, area, scatter, pie or donut chart, so a trend or a ranking is obvious at a glance. Bar compares values across categories, line and area show change over time, pie and donut show how a whole splits into parts, and scatter plots two number columns against each other, to show how one measure moves with another. A chart needs a data source plus the column that labels each point or bar, the column that supplies the values, and optionally more than one series to compare. You can group by a category, and the chart redraws to match your parameters.

A scatter's horizontal axis and each of its series must be number columns: over a text or date column there is nothing to plot, so the chart says so instead of drawing an empty plot. A scatter can carry several series, each plotted at its own values. A chart saved with a type Ovidens does not draw, by another tool for example, names that type in place of a drawing until an editor picks a chart type in its settings.

A pie, a donut, or a grouped bar, line or area chart whose label or value column is no longer in its data source shows a message instead of a drawing, and an editor fixes it in the chart's settings. See When a widget names a column that no longer exists.

Each series can also carry its own label: open the pencil on the series row to type one (or clear it back to the column name with Reset), and the legend and the tooltip both use it - handy when two series aggregate the same column in different ways.

Five settings control how a chart reads:

• Stacked (bar and area) places the series on top of one another instead of side by side, so each bar shows a total that is split into parts rather than several values to compare.
• Bars (bar only) chooses vertical columns or horizontal bars. Horizontal is the one to reach for when your category names are long: they are read down the side, where there is room, instead of packed across the bottom.
• Label angle (vertical columns only) turns the category labels flat, at an angle, or upright. Turning them fits far more categories across the bottom. When there are still more labels than will fit legibly, the chart shows every second or third one rather than overlapping them.
• Category order decides the order the categories are drawn in, and it changes what the chart says: left to right as the data came back, A to Z, highest value first, or lowest first. Highest-first turns a chart into a ranking. Line and area charts offer only the first two, because their horizontal axis usually runs in time and sorting those points by value would destroy the trend they exist to show.
• Legend (every chart type) shows or hides the colour key naming each series under the chart. It is on by default; switch it off when the tile is tight and the series are obvious - pie and donut charts included, whose legend is how their categories are read.

Pivot

The Pivot widget groups rows together and shows a summary for each group. An editor sets it up in the pivot's settings: one or more group-by columns (such as region) and one or more summary columns, each a sum, count, average, minimum or maximum of a column (such as the sum of revenue). A year column offers count, minimum and maximum only, because a sum or average of years is not a number anyone reads. People reading the page see the result, one row per group. Use a table when people need the detail, and a pivot when they need the totals.

A new pivot starts on a default so it shows something straight away: it groups by the first column that is not a number and adds up the first number column that is not a year. The default only fills a part you have left empty. A column you chose is always used as you chose it and never quietly swapped for another, so if it is no longer in the data source the pivot shows a message instead of a grid, and an editor fixes it in the pivot's settings. See When a widget names a column that no longer exists.

Formats. A pivot shows its figures the way the data source defines them. A sum of a currency column is shown in that currency with its decimal places, and a sum of a percent column with its decimal places and a % sign. A count is always a whole number, because it counts rows. An average of whole or decimal numbers is rounded to two decimal places. The earliest or latest date of a date column is shown as a date, and a year is shown as a year (2023, never 2,023). A group-by over a dropdown column shows the option's name and colour.

Every group, page by page. A pivot shows every group its data has, a page at a time, and its pager says how many groups there are.

Searching, filtering and sorting. The search box finds groups by the values of the group-by columns, and a dropdown group-by by the option names you see. A filter on a group-by column narrows the rows before the summaries are taken, so the totals follow the filter. A filter on a summary column keeps the groups whose summary passes it, such as the regions whose revenue is above 10,000. Sorting by a summary column puts the groups in order of their summary. The pivot's Fixed filters (its settings' Data group) and the page's parameters narrow the rows before the summaries are taken too.

Full screen and download. Open a pivot in full screen from its header (in the editor, from the buttons over the tile); your search stays as it was. The download holds every group the pivot shows under its current search, filters and sort, under the same column headers. Figures are written as plain numbers so a spreadsheet can calculate with them; an Excel file keeps a currency or percent column's format, and a date is written as a date (2024-01-01).

If a pivot cannot read its data, for example because the query took too long, it says so in place of the grid and offers Try again. A report block shows a pivot exactly as the tile does, formats, years and dropdown names included.

Naming a summary column

Each summary column of a pivot can have its own header. In the widget's settings, open the pencil button next to the summary and type the header into Column header, for example "Revenue in EUR". The header is shown above that column on the page, in full screen, in reports and in a downloaded file; the small badge with the summary (SUM, AVG, ...) stays beside it. Leave the field empty, or choose Reset, and the column takes its data source column's name again. A report and a download have no badge, so there an unnamed summary column is headed by the column's name and its summary, such as "Amount (sum)" beside "Amount (max)", and a filter on it reads the same way above the page.

Parameters

A Parameter widget adds input controls, a dropdown, text box, number field, date picker, or range, that let people filter or adjust the page without changing anything you built. Rather than build one page per region, you add a region parameter: people pick a region and every table and chart updates to match. One page serves everyone.

Connect a parameter to the column it filters on, and provide a dropdown's options either as a fixed list or loaded live from a pipeline node. A parameter filters every widget that uses the matching column, so one control can drive the whole page. A widget that should always show everything (for example a grand total) can be set to ignore parameters.

SQL

The SQL widget puts a query box on the page so someone comfortable with SQL can ask ad-hoc questions of the pipeline output. Pick a node as the source and it fills in a starter query to adjust. A query can name a dataset or a SQL node, but not an imported node (indicator data or analytic app data): to query imported data, add a SQL node after the import in the pipeline and query that. If you are not comfortable with SQL you do not need this widget: describe your question to Vera instead, or use the other widgets, which cover most needs without a single query.

A query here reads only this app's own nodes, named directly by their id: a name with a prefix, another app's table, a system table, a file path or a table function in FROM is refused with a message saying what to change, and so is a function that reads settings or the catalog, runs SQL given as text, or changes something. The full rule is in What the Run button can read.

Writing and running a query of your own is a permission of its own, separate from reading the app. It comes with the Contributor, Analyst, App builder and Admin roles on the whole workspace - a role on a single space or app does not give it - and you always hold it in your own personal space. Someone who may only view an app sees each SQL widget's results - the rows of the query saved on the widget - without the query box, so they read what the page's author wrote and cannot change it. In the editor, someone who may change the app but not run queries edits the saved query with no Run button, and a short note says why.

AI

The AI widget runs a curated AI skill and shows the answer right on the page. Its only setting is which skill it runs; the widget takes the skill's name as its title. If the skill asks for something, for example a region or a date range, the widget shows one labelled box per question, so the reader fills those in and clicks Run.

While it works you see what Vera is doing, how long it has been running, and how far it may go. When it finishes you get the answer, with a foldout showing how Vera arrived at it. It needs no data source: the skill already knows which data to look at. A reader whose account is not allowed to use AI sees the widget explain that instead of a Run button.

Knowledge Base

The Knowledge base widget embeds a single page from the app's Knowledge Base on the Visualisation, rendered read-only. Use it to keep guidance next to the numbers: what the data means, how the app is meant to be used, or the rules behind a figure, so people do not have to leave the page to find it. It shows no pipeline data, so it needs no data source; you simply pick which page it displays.