Visualisation

Type identifier: visualisation Category: Experience Blocks

Description

Data-visualisation block with component-specific configuration for WordCloud, BarChart, Map, and Document.

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"
• datumReference (required for Map; required for WordCloud and BarChart unless they set entityQuery, also in state overrides that set component)
• src (required for Document)

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 at textPath/countPath or xAxisPath/yAxisPath. Nothing is counted or totalled: to chart counts this way, the datum must already hold one item per count.
• Grouped query (entityQuery with bindings): 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 Source
• textPath, countPath
• padding (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 Source
• yAxisPath, xAxisPath
• barColor, showGrid, showTooltip, xAxisAngle, barRadius
• showXAxis, showYAxis, layout
• labelPosition, labelFontSize, labelFontWeight, labelFill
• useColorRange, colorRangeStart, colorRangeEnd

Grouped Query Source

entityQuery is a grouped query in the input format of Record Queries, without spaceId, sort, offset and cursor.

bindings names the select aliases the chart shows:

Rules, checked against the query's output types before it runs:

• Every groupBy key 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 a sum, avg, min or max of 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 keyDateFormat when 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 as MMM yyyy for 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) or Mar 3, 2025 (day). The query returns the first day of the period (2025-03-01). A date key without a bucket uses its property's defaultFormat when it has one, and is otherwise shown as stored (2025-03-01). The standard properties createdAt and updatedAt have no defaultFormat.
• When there are more groups than limit, the chart shows the first groups and the note Showing first N of M groups. With a series key, 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.
• useColorRange colours bars by value when there is no series.

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:

• zoomFiltering
• styleMapping
• pointBlock, hoverBlock
• hoverStyle
• worldCopyJump, 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:

• mode must be geography-reference
• rows[].id is 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 literals
• rows[].sources[].geographySet is required for reference sources

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 codes
• world-admin1-ne-v1: global first-order subdivisions, identified by ISO 3166-2 codes
• world-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[].id is 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 reference sources from the same geography set merge into one output geometry.
• reference sources from different geography sets can be combined, but the output is then a custom composite feature rather than a simple boundary-pack join.
• Inline geojson sources can be mixed with reference sources 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.

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-v1 applies.
• 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.

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 http or https URL. A URL with another scheme, such as javascript: or data:, renders nothing
  • a static fileReference (schemaId, entityId, fileId) to a file stored on a Record
  • a datumReference (with schemaId and a path to a file field) resolved from a datum when the block renders. For a multiple file field, the first file is previewed

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.

Properties

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"
  }
}