Visualization reference

Use this reference after Visualize your data when you know the question and need the exact GraphJSON controls.

Start with the simplest representation that answers the decision. A chart is not better than a table when the reader needs exact rows, and a pie chart is not better than a bar chart when labels are hard to compare.

Collection visualization matrix#

Saved SQL queries support Single Line, Multi Line, Stacked Line, Single Value, Table, Bar Chart, Pie Chart, and Funnel through explicit result-column mappings.

Samples#

Use Samples before building a metric:

• confirm the event exists
• inspect exact field names and types
• add filters from observed values
• check occurrence timestamps
• download a small CSV for inspection

Samples are not a substitute for a complete raw archive. See Export, delete, and move your data.

Single Line#

Use for:

• daily signups
• hourly failures
• weekly active accounts
• revenue by month

Choose:

• time range
• time zone
• filters
• aggregation
• numeric metric for Sum, Avg, or percentile
• granularity
• optional prior-period comparison

Use Count for event volume. Use Sum for additive numeric values in one unit. Use Avg or a percentile for distributions such as latency.

Do not sum multiple currencies or incompatible units in one line.

Multi Line#

Use Multi Line to split a time-series metric by a categorical field such as:

• plan
• region
• feature
• status family

Avoid high-cardinality splits such as user_id, raw URL, or request ID. A chart with hundreds of series is difficult to render and harder to interpret.

Limit the input with filters or choose a stable category upstream.

Stacked Line#

Use Stacked Line when the total and its composition both matter:

• requests by status family
• active accounts by plan
• completed jobs by worker region

Stacking can hide a small series when one category dominates. Use Multi Line when comparing trends is more important than showing the combined total.

Do not stack overlapping populations; the visual total would double-count them.

Cumulative Line#

Use for a running total inside the selected range:

• cumulative signups during a launch
• cumulative processed rows during a backfill
• cumulative revenue during a campaign

The line starts from the beginning of the selected window, not from the first event in the collection’s history. Make the range explicit in the title.

Do not use a cumulative chart for a stock value already representing current state, such as account balance.

Ratio Line#

Ratio Line divides a numerator population by a denominator population over time.

Examples:

• failed requests / all requests
• completed checkouts / checkout starts
• upgraded accounts / trial accounts

Make the denominator logically include or relate to the numerator. A ratio between unrelated event populations may be mathematically valid and analytically meaningless.

Name the unit in the title. Use a percentage suffix when displaying 0–100, or document whether the result is a fraction.

Compare Line#

Compare Line places two filtered populations on one timeline:

• treatment versus control
• enterprise versus self-serve
• production versus staging
• one endpoint versus another

Use it for descriptive comparison. It does not calculate statistical significance or prove causality.

For experiment design, use Build a conversion funnel and A/B test.

Single Value#

Use for one headline KPI:

• signups this week
• active accounts today
• revenue this month
• P95 API latency

The time range, time zone, unit, filters, and aggregation should be understandable from the title and surrounding dashboard.

Avoid placing a bare number such as 24.7 on a dashboard. Prefer:

Checkout success rate · last 24 hours
24.7%

Table#

Use a table when ranked categories or exact values matter:

• feature adoption by account plan
• errors by endpoint
• revenue by currency
• webhook failures by provider

Sort deliberately. The largest value first is common for rankings; chronological ordering belongs in a time-series result.

CSV export reflects the table result, not every raw event behind the aggregate.

Bar Chart#

Use a bar chart for categorical comparisons when labels and magnitude need to be read quickly.

Prefer bars over pie slices when:

• there are more than five categories
• values are close together
• category names are long
• exact ranking matters

Filter or group rare long-tail values into a meaningful upstream category rather than showing dozens of unreadable bars.

Pie Chart#

Use a pie chart only for a small set of mutually exclusive categories that form a meaningful whole.

Good:

Successful requests by status family
Paid accounts by current plan

Poor:

Top 40 endpoints
Features used, where one account can use several features

If the categories overlap, the slices do not represent parts of one whole.

Funnel from saved SQL#

Funnel is available in the saved SQL visualization workflow.

Return an ordered label and numeric value:

The notebook maps the label and value columns. Preserve ordering in SQL; do not rely on alphabetical sorting of unnumbered labels.

Aggregations#

Use integer minor units for money:

{
  "amount": 4900,
  "currency": "usd"
}

Filter or group by currency before summing.

Filters#

A flat filter list is AND:

[
  ["event", "=", "checkout_completed"],
  ["plan", "=", "pro"]
]

Nested groups are OR groups whose conditions are ANDed:

[
  [
    ["event", "=", "checkout_completed"],
    ["plan", "=", "pro"]
  ],
  [
    ["event", "=", "subscription_renewed"],
    ["plan", "=", "pro"]
  ]
]

Supported operators are documented in the Data API. Consistent field types remain important even when equality can match numeric-looking values in more than one representation.

Time range and granularity#

The selected time zone affects calendar buckets and display. Use:

• UTC for system operations and cross-region comparisons
• the business reporting zone for finance or executive reviews
• the viewer’s zone only when the product explicitly promises local reporting

Choose the coarsest granularity that preserves the decision:

Too-fine granularity creates noisy charts and more query work.

Missing buckets#

Time-series charts may fill missing buckets with zero. Enable the supported Hide missing customization when an absent bucket should remain absent rather than implying a measured zero.

Decide what absence means:

• zero events
• delayed ingestion
• no producer running
• data outside retention
• query failure

The visual treatment cannot decide this for you.

Customizations#

Customization support varies by graph type. Build the visualization in the dashboard first, then export the generated payload.

Common line options:

• title
• value prefix and suffix
• primary and secondary colors
• background color
• summary visibility
• x-axis and y-axis visibility
• tooltip visibility
• dots
• missing-bucket behavior

Table options include title, value prefix and suffix, colors, and summary visibility. Bar and pie charts support title, colors, and summary visibility. Single Value supports value prefix, suffix, and primary color. Funnel supports a title.

Custom CSS overrides are an advanced presentation mechanism. Test them against the current rendered embed and avoid relying on undocumented internal selectors.

Export support#

Alerts are created from collection Single Line visualizations.

Accessibility and review#

• Write a title that states metric and period.
• Do not encode meaning by color alone.
• Use a table when exact values are essential.
• Keep legends short.
• Avoid excessive decimal precision.
• Test narrow screens and embedded loading states.
• Provide explanatory text for customer-facing metrics.

Before sharing, ask another person to explain the chart without opening the query. If their interpretation differs from the metric contract, fix the title, unit, or surrounding copy.