Visualisation
Type identifier:
visualisationCategory: Experience Blocks
Description
Data-visualisation block with component-specific configuration for WordCloud, BarChart, Map, Document, and Graph.
Schema Summary
A Visualisation block has type, width, height, optional states, and a component that selects the variant and its configuration.
Required:
type: "visualisation"component: "WordCloud" | "BarChart" | "Map" | "Document" | "Graph"datumReference(required forMap; required forWordCloudandBarChartunless they setentityQuery, also in state overrides that setcomponent)src(required forDocument)edges(required forGraph)
Visualisation blocks also have the shared block style, layout, and data properties.
Component Variants
Data Sources
WordCloud and BarChart show one of two data sources:
- Datum (
datumReference): an array datum, usually a block query's Records. Each item is one word or one bar, read attextPath/countPathorxAxisPath/yAxisPath. Nothing is counted or totalled: to chart counts this way, the datum must already hold one item per count. - Grouped query (
entityQuerywithbindings): the block runs a grouped query itself (Record Queries — Grouped Queries) and shows one word or bar per group. The server counts or totals the Records, so the page never loads them. See Grouped Query Source.
When entityQuery is set, the block ignores datumReference and the datum paths.
WordCloud
Optional config:
entityQuery,bindings({ text, weight }),keyDateFormat: see Grouped Query SourcetextPath,countPathpadding(0..50)rotation(horizontal|mixed|vertical)minFontSize(1..100)maxFontSize(1..200)color
BarChart
Optional config:
entityQuery,bindings({ category, series?, value }),keyDateFormat: see Grouped Query SourceyAxisPath,xAxisPathbarColor,showGrid,showTooltip,xAxisAngle,barRadiusshowXAxis,showYAxis,layoutlabelPosition,labelFontSize,labelFontWeight,labelFilluseColorRange,colorRangeStart,colorRangeEnd
Grouped Query Source
entityQuery is a grouped query in the input format of Record Queries, without spaceId, sort, offset and cursor.
Property | Notes |
|---|---|
| The Schema whose Records are grouped. |
| Optional |
| 1 or 2 group keys (Record Queries — Group Keys), with an optional date |
| Group entries and aggregates ( |
| Optional, |
bindings names the select aliases the chart shows:
Component | Bindings | Notes |
|---|---|---|
|
|
|
|
|
|
Rules, checked against the query's output types before it runs:
- Every
groupBykey must be bound, so each row is one bar or word. A word cloud has one key. - The bound value must be a number: a
count, or asum,avg,minormaxof a number property.
When the rules are not met, the Schema cannot be read, or the query fails, the block shows Chart unavailable in place of the chart. In Studio (the Experience designer and previews), the notice includes the reason; viewers of a published Experience see only Chart unavailable.
Rendering:
- Groups are shown in the query's default order: every key ascending, with the group of unset values last.
- The group of Records whose key is unset is labelled
(none). - Date keys are labelled with
keyDateFormatwhen it is set: a standard date format ({ "type": "preset", "preset": "medium" }, or{ "type": "custom", "pattern": "MMM yyyy" }), formatted in the viewer's locale and timezone. It applies to every bound date key, bucketed or not, and is ignored for other keys. A bucketed key is formatted as the first day of its period, so pick a format that shows the period, such asMMM yyyyfor months. - Without
keyDateFormat, a bucketed date key is shown as its period in the viewer's locale:Mar 2025(month),Q2 2025(quarter),2025(year),Week of Mar 3, 2025(week) orMar 3, 2025(day). The query returns the first day of the period (2025-03-01). A date key without a bucket uses its property'sdefaultFormatwhen it has one, and is otherwise shown as stored (2025-03-01). The standard propertiescreatedAtandupdatedAthave nodefaultFormat. - When there are more groups than
limit, the chart shows the first groups and the note Showing first N of M groups. With aserieskey, N and M count category and series pairs, so the last category shown may be missing some of its series bars. - Bar values in tooltips, labels and the value axis are formatted for the viewer's locale, with at most two fraction digits.
- The query runs in the browser when the block renders: server-side rendering shows nothing in its place, and the chart appears once the groups load.
useColorRangecolours bars by value when there is noseries.
The query runs as the viewer, with the same access rules as a block query. On a public Experience, the viewer is a guest, and the Space's guest role must be able to read the Schema.
In the Experience designer, select Data source → Grouped query in the Bar Chart or Word Cloud settings, then pick the Schema, the group keys and the value. The designer composes entityQuery and bindings. While a bound key is a date, Date labels sets keyDateFormat. Switching a grouped chart between Bar Chart and Word Cloud keeps its group key, value and keyDateFormat (a bar chart's series is dropped); switching to Map or Document, or to the datum source, clears the grouped query and keyDateFormat. See How to Chart Grouped Records.
Example: open Tasks per month of their due date, split by status.
{
"id": "tasks-by-month",
"type": "visualisation",
"component": "BarChart",
"entityQuery": {
"schemaId": "ckvq0p8sd0000qzrmn831i7rn",
"filter": {
"type": "property",
"path": "archived",
"operator": "eq",
"value": { "type": "literal", "value": false }
},
"groupBy": [
{ "id": "category", "alias": "category", "path": "dueDate", "bucket": "month" },
{ "id": "series", "alias": "series", "path": "status" }
],
"select": [
{ "kind": "group", "id": "category", "groupBy": "category" },
{ "kind": "group", "id": "series", "groupBy": "series" },
{ "kind": "aggregate", "id": "value", "alias": "value", "fn": "count" }
],
"limit": 100
},
"bindings": { "category": "category", "series": "series", "value": "value" }
}On Space import, entityQuery.schemaId and the relationship IDs in its filter are mapped to the imported Schema and relationships.
Map
Optional config:
zoomFilteringstyleMappingpointBlock,hoverBlockhoverStyleworldCopyJump,minZoom,maxZoom,showMinimap
Supported datum payloads:
- GeoJSON geometry, feature, or feature collection payloads
- Geography reference payloads with the following shape:
{
"mode": "geography-reference",
"rows": [
{
"id": "AU",
"sources": [
{
"type": "reference",
"geographySet": "world-country-ne-v1",
"geographyCode": "AU"
}
],
"properties": {
"regionName": "Oceania",
"displayCount": 10
},
"value": 124
}
]
}- Geography reference payloads can also define row-level custom sources when a rendered feature needs to be built from multiple standard regions, inline GeoJSON literals, or both:
{
"mode": "geography-reference",
"rows": [
{
"id": "anz-core",
"label": "ANZ Core",
"properties": {
"detailLevel": "Continental",
"displayCount": 12
},
"sources": [
{
"type": "reference",
"geographySet": "world-country-ne-v1",
"geographyCode": "AU"
},
{
"type": "reference",
"geographySet": "world-country-ne-v1",
"geographyCode": "NZ"
},
{
"type": "geojson",
"value": {
"type": "Polygon",
"coordinates": [
[
[160, -20],
[161, -20],
[161, -19],
[160, -19],
[160, -20]
]
]
}
}
]
}
]
}Reference-mode requirements:
modemust begeography-referencerows[].idis the feature identifier for the rendered row- Additional row properties, including
rows[].properties, are merged onto feature properties for styling and hover content rows[].sources[]is required and can mix standard geography references with inline GeoJSON literalsrows[].sources[].geographySetis required forreferencesources
Mode selection guidance:
- GeoJSON mode accepts custom shapes and ad hoc map geometry.
- Geography-reference mode maps rows onto a known geography set, or assembles custom regions from standard units.
Shipped geography sets:
world-country-ne-v1: countries, identified by ISO 3166-1 alpha-2 codesworld-admin1-ne-v1: global first-order subdivisions, identified by ISO 3166-2 codesworld-admin1-africa-ne-v1,world-admin1-antarctica-ne-v1,world-admin1-asia-ne-v1,world-admin1-europe-east-ne-v1,world-admin1-europe-west-ne-v1,world-admin1-north-america-ne-v1,world-admin1-oceania-ne-v1,world-admin1-south-america-ne-v1: regional admin-1 packs, described in the table below
Geography-Reference Data Shaping
Each row renders one feature.
rows[].idis a stable row identifier from your dataset. It does not need to equal the geography code.- Put one or more geometry inputs in
rows[].sources[]. type: "reference"resolves the row to a shipped geography unit from a known geography set.type: "geojson"supplies inline custom geometry for the row.- Put display or styling fields either on the row itself or under
rows[].properties; both are merged into the rendered feature properties.
A row that matches one shipped geography unit directly has this shape:
{
"mode": "geography-reference",
"rows": [
{
"id": "US",
"label": "United States",
"sources": [
{
"type": "reference",
"geographySet": "world-country-ne-v1",
"geographyCode": "US"
}
],
"properties": {
"value": 125,
"segment": "North America"
}
}
]
}For first-order subdivisions, keep the same structure but switch both the geographySet and the code format:
{
"mode": "geography-reference",
"rows": [
{
"id": "US-CA",
"label": "California",
"sources": [
{
"type": "reference",
"geographySet": "world-admin1-north-america-ne-v1",
"geographyCode": "US-CA"
}
],
"properties": {
"value": 42
}
}
]
}A custom composite region uses one output row with multiple sources:
- Multiple
referencesources from the same geography set merge into one output geometry. referencesources from different geography sets can be combined, but the output is then a custom composite feature rather than a simple boundary-pack join.- Inline
geojsonsources can be mixed withreferencesources when you need to extend or patch a region.
Choosing the Geography Set
The geography set follows the level of the identifiers in your rows, not the visual zoom level.
Data level in your rows | Expected code format | Geography set to use | When it applies |
|---|---|---|---|
Country | ISO 3166-1 alpha-2, for example |
| Each row represents a country. |
Admin-1 (first-order subdivision) | ISO 3166-2, for example |
| Rows span multiple continents or the whole world. |
| All rows are within Africa. | ||
| All rows are within Antarctica. | ||
| All rows are within Asia. | ||
| All rows are within Eastern Europe. | ||
| All rows are within Western Europe. | ||
| All rows are within North America. | ||
| All rows are within Oceania. | ||
| All rows are within South America. |
Selection rules:
- Row identifiers that are country codes use
world-country-ne-v1. - Row identifiers that are first-order subdivision codes use an admin-1 set.
- When all admin-1 rows fall inside one regional pack, that regional admin-1 set applies.
- When admin-1 rows span more than one regional pack,
world-admin1-ne-v1applies. - Country codes must not be sent to an admin-1 geography set, and admin-1 codes must not be sent to
world-country-ne-v1.
A subdivision code that resolves in one of the regional packs targets that pack for its row.
Graph
Draws a node-and-edge diagram, such as the systems in a portfolio and the integrations between them. The nodes and edges come from datums, so the diagram changes when the Records do. It is laid out automatically: edges flow in one direction, and nodes are placed in ranks along it.
Graph is available only in Spaces where it has been turned on. In other Spaces, saving an Experience that adds a Graph block fails with Graph visualisations are not enabled for this Space (block '<block id>'), and Graph is not offered under Component. A Graph already saved in an Experience still renders and can still be edited. Contact your administrator to turn Graph on for a Space.
Studio does not edit a Graph's settings yet: set them in the block's JSON, for example with ligantic experiences blocks update.
Required config:
edges: where the edges come from, and how they look:
Property | Required | Notes |
|---|---|---|
| Yes | A list of rows, one per edge. Usually a block query with output columns whose records columns list each edge's source and target Records. See How to Show Records With Their Linked Records and Totals. |
| Yes | The source node in each row: an id, a Record, or a list of Records, of which the first is used. A Record's id is read at the nodes' |
| Yes | The target node in each row, read as |
| No | A value shown in a badge on the edge, such as its number. |
| No | The edge style of every edge. See Graph Styles. |
| No | Up to 5 mappings that style each edge by its value at a path. See Graph Styles. |
Optional config:
nodes: where the nodes come from, and how they look:
Property | Notes |
|---|---|
| A list of rows, one per node. Every row is drawn, linked or not. Without it, the nodes are the sources and targets of the edges, so a node appears only when an edge links it: a Record the edge lists is labelled and styled from its fields, and an endpoint given as an id is labelled by its id, with the default style. |
| The node's id in each node row, and in each Record an edge lists. Default |
| The node's label, wrapped to at most two lines and cut with |
| The node size in pixels: |
| The node style of every node. See Graph Styles. |
| Up to 5 mappings that style each node by its value at a path. |
layout:direction: the direction edges flow:LR(left to right, the default),RL,TB(top to bottom) orBTnodeSpacing(0..500, default32): the gap between nodes in the same rankrankSpacing(0..1000, default64): the gap between ranks
legend:trueshows a legend under the diagram. It lists the values of the first node mapping that sets afill, and the values of the first edge mapping, except values that hide edges.
Graph Styles
Style | Properties |
|---|---|
Node |
|
Edge |
|
A style mapping has a path and values: an object from a value, as text, to the style to apply. A number such as 2 is matched as "2", and a list by its first item. Each item's style is the default, then style, then each mapping whose value matches, in order. Unknown style properties are rejected.
Rendering:
- An edge is not drawn when its source or target is missing or is not a node. In Studio, a note under the diagram counts these edges; viewers of a published Experience do not see it.
- The diagram scales to the block's width, up to its natural size, and keeps its proportions. With a
height, it scales to fit within it. - With no edge rows and no node rows, the block is empty. In Studio, it shows a hint to bind the edges.
- The diagram is announced to screen readers by its block name (or Graph) and how many nodes and edges it shows, for example
Integration diagram: 15 nodes and 13 edges. List the nodes and edges as text alongside it, such as the integrations list in the example, for readers who need the details. - The rows come from the datums, so a block query's access rules and limits apply: the query runs as the viewer, and a query with records columns returns at most 100 rows.
Example: integrations between applications. A block query on the Integration Schema lists each integration's source and target Applications, with columns Number, Confidence, Direction, Source and Target (records columns of the Applications' id, Label and Group):
{
"id": "integration-map",
"type": "visualisation",
"component": "Graph",
"edges": {
"datumReference": { "type": "datumReference", "referenceId": "integrations" },
"sourcePath": "Source",
"targetPath": "Target",
"labelPath": "Number",
"style": { "line": "dashed" },
"styleMapping": [
{
"path": "Confidence",
"values": {
"Confirmed": { "line": "solid", "color": "#067647" },
"Not in use": { "hidden": true }
}
},
{ "path": "Direction", "values": { "Two-way": { "arrows": "both" } } }
]
},
"nodes": {
"labelPath": "Label",
"styleMapping": [
{
"path": "Group",
"values": {
"Practice": { "fill": "#eff8ff" },
"Accounting and tax": { "fill": "#ecfdf3" }
}
}
]
},
"layout": { "direction": "LR" },
"legend": true
}Switching a block to Graph in the designer binds its edges to the block's datum, with sourcePath Source and targetPath Target. Switching a Graph to another component keeps its edges' datum as the block's datum, and clears the Graph settings.
Document
Previews a document file inside the Experience, with the same previews as file fields.
Required config:
src: the document to preview, in the same source shape as the Image, Video, and Audio blocks:- a URL string: an absolute
httporhttpsURL. A URL with another scheme, such asjavascript:ordata:, renders nothing - a static
fileReference(schemaId,entityId,fileId) to a file stored on a Record - a
datumReference(withschemaIdand apathto a file field) resolved from a datum when the block renders. For a multiple file field, the first file is previewed
- a URL string: an absolute
Optional config:
showDownload: shows a download button over the preview
Supported file types: PDF, Word (.docx), PowerPoint (.pptx), and images the browser can display. The file type comes from the file field entry for datum sources, the URL extension for URL sources, and otherwise the file's Content-Type. Unsupported types, and files that fail to load, render as a link to the file. The preview fills the block's width and height and scrolls within it. Text in a PDF can be selected and copied.
Properties
Property | Type | Required | Notes |
|---|---|---|---|
|
| Yes | Shared block identifier. |
|
| Yes | Block discriminator. |
|
| Yes | Variant discriminator. |
|
|
| Data source reference. |
| URL, |
| Document source. |
|
| No |
|
|
| No |
|
| object | With |
|
|
| No |
|
| object |
| The edges' datum, source, target, label and styles. |
| object | No |
|
| object | No |
|
|
| No |
|
|
| No | Visualisation width. |
|
| No | Visualisation height. |
|
| No | Optional state-specific overrides. |
The shared block style, layout, and data properties also apply to Visualisation blocks.
States
State entries follow the shared state shape and support partial Visualisation overrides.
No states are currently available for Visualisation blocks.
Minimal Valid Example
{
"id": "vis-1",
"type": "visualisation",
"component": "WordCloud",
"datumReference": {
"type": "datumReference",
"referenceId": "queryResults"
}
}