Search docs.molo17.com

    Visualize

    Visualize turns an entity you already replicate into a chart, keeps that chart current, and can publish it at a stable public URL. Charts that belong to one collection are a canvas: you arrange them together, and you can publish the whole canvas with one link. You describe a chart to Spark, the Enterprise brain grounds it to real columns, and Core Hub refreshes it by hand, on a Chronos schedule, or when the bound entity changes. Visualize is included in the product; it is not an add-on.

    Visualize ships with Gluesync 2.3.1. It is not part of Gluesync 2.3.0.

    Overview

    A visualization is one chart. It has:

    • a spec: the chart type, the entity it is bound to, and the fields it plots;

    • a refresh policy: when the snapshot behind the chart is rebuilt;

    • an owner, and a visibility of PERSONAL or TEAM;

    • an optional collection.

    A collection is a canvas. Opening it in the Control Plane shows every chart saved in it, and sharing it publishes that set at one public URL. Deleting a collection detaches its visualizations; it does not delete them. The public canvas URL stops answering when the share is removed or the collection is deleted.

    The Control Plane renders charts with Recharts. The chart types are BAR, STACKED_BAR, LINE, AREA, PIE, DONUT, SCATTER, TABLE, KPI, and HEATMAP. A pie or donut drops its legend when the tile is too small to show both, and draws it again when the tile grows.

    Every query Visualize runs executes as the visualization owner, read-only, with the same data-access policies and PII masking as Query Studio.

    What you can bind

    In 2.3.1 a visualization is bound to a single-table SQL entity on a SQL-capable agent. Any other binding is rejected with HTTP 422 and code UNSUPPORTED_BINDING.

    Who sees what

    Visibility Behaviour

    PERSONAL

    Visible to its owner and to a Super admin.

    TEAM

    Visible to everyone who can sign in. Editable by its owner, a Super admin, and a Manager.

    A visualization or collection the caller may not see answers 404, not 403.

    Action Who

    View

    Any authenticated user.

    Create, edit, delete visualizations and collections

    Super admin, Manager, Monitor.

    Refresh

    Super admin, Manager, Monitor, and the external module role (this is how Chronos refreshes).

    Share publicly

    Super admin, Manager.

    Change the feature setting

    Super admin only.

    Enable Visualize

    Visualize is controlled by a Core Hub setting and an optional environment override.

    • The Hub setting is visualize.enabled. Read it with GET /visualize/settings and change it with PUT /visualize/settings. Only a Super admin can change it.

    • The environment variable GLUESYNC_VISUALIZE_ENABLED=false is a hard off switch. It wins over the stored setting.

    • The Control Plane shows the Visualize tab only when the UI flag VITE_VISUALIZE_ENABLED is on.

    When Visualize is off, every Visualize endpoint, including public reads, answers 403 with code FEATURE_DISABLED, and any background refresh already queued is skipped.

    Author a chart with Spark

    Open Visualize in the Control Plane. Spark sits beside the canvas. On a narrow window, where the chat would cover the charts, Spark collapses into a button and opens over the canvas when you ask for it. Choosing the empty New chart slot opens that chat.

    A turn is POST /visualize/chat. Spark searches the catalog and answers with a message and, when it can, a chart proposal. Nothing is saved until you apply the proposal with POST /visualize/chat/apply. Applying creates a new visualization, or patches the one you have open when the request carries its id.

    POST /visualize/author is the one-shot form of the same authoring: Core Hub grounds the prompt, builds a spec, validates it, and saves the visualization in one call. A follow-up that sends visualizationId patches that visualization instead of creating a new one. The Control Plane uses the chat endpoints, not this one.

    When the brain cannot ground a name

    If the prompt names an identifier the brain cannot resolve to a real column or entity, Core Hub answers HTTP 422 with code UNRESOLVED and writes nothing. In the Control Plane the current chart stays in place; rephrase the prompt or pick the field by its real name.

    Authoring budgets

    Each authoring call runs under a budget: by default 200 rows, 64 KiB, and 4 tool calls. A caller may raise these, but never past 1,000 rows, 256 KiB, and 8 tool calls.

    Work on a canvas

    From Collections, each collection is one canvas.

    • Opening a chart card shows that chart in a preview. From the preview you can open it on the canvas or share that chart on its own.

    • Share canvas publishes every chart in the collection at one public URL. A shared collection is marked Shared canvas.

    • Open canvas opens the canvas in Visualize.

    On the canvas itself:

    • Share canvas is in the toolbar, and is available when the canvas has at least one saved chart.

    • Share this chart is on each chart’s own menu, not in the toolbar. Sharing a chart publishes that chart alone; it does not publish the rest of the canvas.

    • Saving, forking, and refresh settings act on the chart you have picked.

    Keep a chart current

    Charts are served from a snapshot, the last stored result of the visualization’s query. Visualize rebuilds the snapshot in three ways.

    Manual

    POST /visualize/visualizations/{id}/refresh runs the query inline as the caller and returns the run. In the Control Plane this is the refresh action on the chart.

    Chronos schedule

    A Chronos job of task type visualize_refresh posts visualize.refresh to POST /visualize/refresh as the Chronos module, and Core Hub runs the refresh as the visualization owner. The request body, the Chronos fields, and how each HTTP status is handled are on Refresh a visualization. Core Hub also accepts a legacy taskType spelling and a body nested under payload on that endpoint; Chronos itself sends neither.

    Entity change (CDC)

    When Core Hub stores a transaction for a bound entity, it refreshes every visualization bound to that pipeline and entity, whether the entity is on the source or the target side of the pipeline. This applies only when the visualization’s policy has on entity change enabled, which is the default.

    Snapshot lifecycle

    Policy setting Default Meaning

    On entity change

    true

    Refresh when a bound entity receives a transaction.

    Schedule flag

    false

    Marks the visualization as scheduled. The schedule itself lives in Chronos.

    Snapshot TTL

    900 s

    A snapshot younger than the TTL is fresh and served as is.

    Stale-while-revalidate

    3600 s

    Between TTL expiry and the end of this window the snapshot is served marked stale and a refresh is queued. After the window it is dropped.

    Debounce

    2000 ms

    Wait applied before a change-driven refresh starts.

    Minimum interval

    15000 ms

    Shortest gap between two refreshes of the same visualization.

    Authenticated snapshot reads can build a snapshot inline when nothing usable is cached. Public reads never run the query: they serve the cached snapshot, or report that no snapshot is available, and may queue a refresh in the background. On a public canvas, a chart whose snapshot is not ready yet comes back with snapshot null; the page says that chart is being prepared.

    Changing a visualization’s spec bumps its data version and drops the snapshots built for the previous version.

    Authenticated API

    All authenticated endpoints live under /visualize and take a Core Hub JWT. See Core Hub REST API for how to obtain one.

    Endpoint Purpose

    GET, PUT /visualize/settings

    Read or change visualize.enabled. PUT is Super admin only.

    /visualize/collections

    List, create, get, update, and delete collections.

    GET, PUT, DELETE /visualize/collections/{id}/share

    Read, set, or remove the public canvas share. See Share a chart or a canvas.

    GET /visualize/collections/{id}/share/audit

    Audit trail of the canvas share.

    /visualize/visualizations

    List (optionally filtered by collectionId), create, get, update, and delete visualizations.

    POST /visualize/chat

    One Spark turn. Returns a message and, when Spark can draw one, a proposal. Nothing is saved.

    POST /visualize/chat/apply

    Save a proposal from chat as a new visualization, or as a patch of visualizationId.

    POST /visualize/author

    Author or patch a visualization from a prompt in one call. See Author a chart with Spark.

    POST /visualize/visualizations/{id}/save

    With parameters, ensures a snapshot exists at the current data version.

    POST /visualize/visualizations/{id}/refresh

    Refresh inline as the caller and return the run.

    POST /visualize/visualizations/{id}/fork

    Create a personal copy of the visualization.

    GET /visualize/visualizations/{id}/snapshot

    Read the snapshot. Pass chart parameters as p.<param>=<value> query arguments.

    GET /visualize/visualizations/{id}/runs

    List refresh runs.

    GET, PUT, DELETE /visualize/visualizations/{id}/share

    Read, set, or remove the public share of one chart. See Share a chart or a canvas.

    GET /visualize/visualizations/{id}/share/audit

    Audit trail of the chart share.

    POST /visualize/refresh

    Scheduled refresh entry point used by Chronos. See Refresh a visualization.

    Share a chart or a canvas

    A Super admin or Manager can publish one chart, or a whole canvas, at a stable URL. The two kinds of share use one slug namespace: a slug belongs to either a chart or a canvas, never both.

    What you share Public API Page a browser opens

    One chart

    GET /public/viz/{slug}

    /ui/v2/public/viz/{slug}

    A canvas (the collection)

    GET /public/canvas/{slug}

    /ui/v2/public/canvas/{slug}

    A browser request (Accept: text/html) to either public API is redirected to the matching page, and the query string is kept. A client that asks for JSON receives the body instead of the redirect.

    Chart parameters are passed as p.<param>=<value>. On a canvas, each chart keeps only the parameter names its own spec declares.

    The public chart response contains the chart fields and a snapshot the page can draw. It does not include bindings, filters, SQL, the brain thread id, pipeline or entity identifiers, or the password hash. The snapshot does not include its id, the visualization id, or query warnings on a series. options keeps that name and returns only color, colors, palette, legend, xAxis, yAxis, stacked, curve, orientation, showGrid, and showLegend. The public canvas response is the collection name, its description, the protection, and one such chart object per visualization; a chart that is not ready yet has snapshot null. The share object returned to signed-in users says whether a password is set; it never returns the password or its hash.

    Both public pages show Made with Gluesync in the header. The mark links to the Gluesync website.

    Protections

    The same three protections apply to a chart and to a canvas. The unlock path follows the subject: POST /public/viz/{slug}/unlock for a chart, POST /public/canvas/{slug}/unlock for a canvas.

    Protection Behaviour

    NONE

    Anonymous. Anyone with the link can read the snapshot.

    PASSWORD

    The reader first calls the unlock endpoint with the password and receives a short-lived token. Later reads send it in the X-Viz-Share-Token header. The token lasts 12 hours and is tied to the current password, so changing the password invalidates every existing token. Rotating the share or removing it also stops every existing share token. Failed attempts are limited to 5 per 15 minutes per client address, and the failure count is shared across Core Hub processes, not kept in one process; beyond that the endpoint answers 429 with a Retry-After header.

    SSO

    The reader must hold a valid Core Hub session.

    • A slug is 12 to 64 characters of lowercase letters, digits, and single hyphens. A chosen slug uses the same 12-character minimum as a generated one. Reserved words such as unlock, api, and admin are refused.

    • You can set a custom slug. Rotating the slug generates a new one.

    • After a rotation, or after the share is removed, the old URL answers 404. Nothing redirects it.

    • Absolute public links use GLUESYNC_PUBLIC_URL when that Core Hub base URL is set. Otherwise the Control Plane builds the link from the browser location.

    Error codes

    Code HTTP Meaning

    NOT_FOUND

    404

    The object does not exist, or the caller may not see it. An unknown or disabled public slug also answers 404.

    BAD_REQUEST

    400

    The request is malformed.

    UNAUTHORIZED

    401

    No valid Hub JWT or public token.

    PERMISSION_DENIED

    403

    The caller’s role does not allow the action.

    FEATURE_DISABLED

    403

    Visualize is off, by setting or by GLUESYNC_VISUALIZE_ENABLED=false.

    CONFLICT

    409

    The slug is already taken, by a chart or by a canvas.

    UNSUPPORTED_BINDING

    422

    The binding is not a single-table SQL entity on a SQL-capable agent.

    UNRESOLVED

    422

    The prompt named an identifier the Enterprise brain could not ground. Nothing was written.

    REFRESH_FAILED

    422

    The refresh query did not complete.

    RATE_LIMITED

    429

    Too many attempts; honour Retry-After.

    SNAPSHOT_NOT_AVAILABLE

    503

    No usable snapshot is cached and the read could not build one inline. Public reads never build inline.