Ligantic
Knowledge Base
Tutorials
Updates
Search Articles
Login
Free Sign Up
Home
Get Started
Tutorials
How-to guides
Reference
Explanation
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Browse documentation
Home
Get Started
Spaces
Schemas
Flows
Experiences
Endpoints
SDK and CLI
Docs
/

Visualisation

Type identifier: visualisation Category: 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 for Map; required for WordCloud and BarChart unless they set entityQuery, also in state overrides that set component)
  • src (required for Document)
  • edges (required for Graph)

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.

Property

Notes

schemaId

The Schema whose Records are grouped.

filter

Optional Filter. Filters the Records before they are grouped. Like a block query filter, it may compare with datum references and Experience parameters, which are filled in when the block renders.

groupBy

1 or 2 group keys (Record Queries — Group Keys), with an optional date bucket (day, week, month, quarter, year).

select

Group entries and aggregates (count, sum, avg, min, max) of each group's Records. A subset of the Record query select: an aggregate with filter or over is rejected (Unsupported key(s) in a visualisation aggregate); filter the Records with the query's filter.

limit

Optional, 1..1000, default 100. The most groups shown. With a series key, each group is one category and series pair, so the limit counts bars, not categories.

bindings names the select aliases the chart shows:

Component

Bindings

Notes

BarChart

category, series (optional), value

category is a group key: one category per value. series is the second group key: each category gets one bar per series value, with a legend. value is the aggregate each bar shows.

WordCloud

text, weight

text is the group key (one word per value) and weight the aggregate that sizes the word.

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.

Data level in your rows

Expected code format

Geography set to use

When it applies

Country

ISO 3166-1 alpha-2, for example AU, GB, US

world-country-ne-v1

Each row represents a country.

Admin-1 (first-order subdivision)

ISO 3166-2, for example AU-NSW, GB-ENG, US-CA

world-admin1-ne-v1

Rows span multiple continents or the whole world.

world-admin1-africa-ne-v1

All rows are within Africa.

world-admin1-antarctica-ne-v1

All rows are within Antarctica.

world-admin1-asia-ne-v1

All rows are within Asia.

world-admin1-europe-east-ne-v1

All rows are within Eastern Europe.

world-admin1-europe-west-ne-v1

All rows are within Western Europe.

world-admin1-north-america-ne-v1

All rows are within North America.

world-admin1-oceania-ne-v1

All rows are within Oceania.

world-admin1-south-america-ne-v1

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-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.

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

datumReference

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.

sourcePath

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' idPath.

targetPath

Yes

The target node in each row, read as sourcePath is.

labelPath

No

A value shown in a badge on the edge, such as its number.

style

No

The edge style of every edge. See Graph Styles.

styleMapping

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

datumReference

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.

idPath

The node's id in each node row, and in each Record an edge lists. Default id.

labelPath

The node's label, wrapped to at most two lines and cut with … when longer. Default: the node's id.

width, height

The node size in pixels: 20..600 and 16..400. Default 120 by 40.

style

The node style of every node. See Graph Styles.

styleMapping

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) or BT
    • nodeSpacing (0..500, default 32): the gap between nodes in the same rank
    • rankSpacing (0..1000, default 64): the gap between ranks
  • legend: true shows a legend under the diagram. It lists the values of the first node mapping that sets a fill, and the values of the first edge mapping, except values that hide edges.

Graph Styles

Style

Properties

Node

fill, border, color (the label colour): CSS colours. Defaults: white fill, grey border, near-black label.

Edge

line (solid, dashed or dotted, default solid), color (default grey), width (0.5..10, default 1.5), arrows (end, start, both or none, default end: an arrowhead at the target), and hidden (true leaves the edge out).

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 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. Text in a PDF can be selected and copied.

Properties

Property

Type

Required

Notes

id

string

Yes

Shared block identifier.

type

"visualisation"

Yes

Block discriminator.

component

"WordCloud" | "BarChart" | "Map" | "Document" | "Graph"

Yes

Variant discriminator.

datumReference

datumReference

Map; WordCloud and BarChart unless entityQuery is set

Data source reference.

src

URL, datumReference, or file reference

Document only

Document source.

showDownload

boolean

No

Document only. Shows a download button over the preview.

entityQuery

VisualisationEntityQuery

No

WordCloud and BarChart only. A grouped query the block runs instead of reading a datum.

bindings

object

With entityQuery

WordCloud and BarChart only. The query output aliases the chart shows.

keyDateFormat

DateFormat

No

WordCloud and BarChart only. The format of the date group keys of entityQuery.

edges

object

Graph only

The edges' datum, source, target, label and styles.

nodes

object

No

Graph only. The nodes' datum, id, label, size and styles.

layout

object

No

Graph only. Direction and spacing.

legend

boolean

No

Graph only. Shows a legend of the mapped styles.

width

cssSizeProp

No

Visualisation width.

height

cssSizeProp

No

Visualisation height.

states

State[]

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

Related pages

Experience Blocks Reference
This reference documents all currently defined Experience block types in Ligantic.
Page not found. It may have moved or may not be published.
Browse documentation