Skip to content

Point Charts

Point charts encode values primarily through the position of points, often on one or two common scales; this family includes dot plots, lollipop charts, scatterplots, beeswarm, and strip plots. They are especially useful when precision, comparison, distribution, or relationships matter, with dot plots and lollipops excelling at ranked comparisons and scatterplots excelling at showing association between two variables.

Dataface point charts currently map most directly to scatterplots and dot-plot-style charts. The canonical type is type: scatter: it uses Vega-Lite point marks under the hood and supports the familiar point-chart channels such as color, size, and shape. type: point is accepted as an alias and normalized to scatter during compilation.

A chart's control surface is the full set of authored properties available on a single chart. In Dataface, that surface is primarily top-level chart fields plus a typed style object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including default ownership and lower-level property coverage, see the Single-Chart Property Catalog.

Minimum Required for a Point Chart

These are the minimum fields required to render a basic point chart in Dataface. In practice, that minimum usually means a scatterplot, so type: scatter is the most natural starting point.

Dataface field Maps to Vega-Lite Allowed values Notes
query data.values Query name or query reference Supplies the dataset.
type: scatter mark.type: "point" Literal scatter Recommended starting point for scatterplots and dot-plot-style point charts.
x encoding.x.field Field name First position field.
y encoding.y.field Field name Second position field.

Minimum Example

queries:
  campaign_efficiency:
    columns: [ad_spend, pipeline_value]
    values:
      - [18, 140]
      - [22, 165]
      - [26, 182]
      - [31, 205]
      - [34, 214]
      - [39, 246]

charts:
  spend_vs_pipeline:
    query: campaign_efficiency
    type: scatter
    title: Ad Spend vs Pipeline Value
    x: ad_spend
    y: pipeline_value
rows:
  - spend_vs_pipeline
0246810121416182022242628303234363840Ad Spend140145150155160165170175180185190195200205210215220225230235240245250Pipeline ValueAd Spend vs Pipeline Value 2026-05-12 12:35
▶

Top-Level Chart Fields

These are the top-level chart properties you set directly on a point chart before you get into nested properties under style.

Dataface field Maps to Vega-Lite Allowed values Notes
query data.values Query name or query reference Query results become the plotted dataset.
type: scatter mark.type: "point" Literal scatter Canonical point-chart type.
type: point mark.type: "point" Literal point Accepted alias, normalized to scatter during compilation.
x encoding.x.field Field name First position field. Often quantitative, but categorical x fields also support dot-plot-style charts.
y encoding.y.field Field name Second position field. Often quantitative in scatterplots and categorical in dot plots.
title title.text String Chart title.
description metadata String Available for tooling and docs.
color encoding.color.field Field name Category or grouping field.
size encoding.size.field Field name Quantitative field mapped to point size.
shape encoding.shape.field Field name Category field mapped to symbol shape.
x_label encoding.x.title String Custom x-axis title.
y_label encoding.y.title String Custom y-axis title.
format quantitative y-axis format Format string Numeric formatting for the quantitative y axis. Use style.axis_x when you need x-axis formatting too.
sort categorical axis sort Sort object Most useful for dot plots and other ordered categorical comparisons.

Size and Category Grouping

This example shows the most common top-level point-chart additions after x and y: color for grouping and size for magnitude.

queries:
  segment_performance:
    columns: [avg_deal_size, win_rate, segment, open_pipeline]
    values:
      - [18000, 0.22, "SMB", 45]
      - [24000, 0.26, "SMB", 58]
      - [52000, 0.31, "Mid-Market", 72]
      - [61000, 0.34, "Mid-Market", 86]
      - [120000, 0.41, "Enterprise", 108]
      - [138000, 0.44, "Enterprise", 124]
      - [195000, 0.37, "Strategic", 140]
      - [215000, 0.40, "Strategic", 156]

charts:
  segment_scatter:
    query: segment_performance
    type: scatter
    title: Deal Size vs Win Rate by Segment
    x: avg_deal_size
    y: win_rate
    color: segment
    size: open_pipeline
    x_label: Average Deal Size
    y_label: Win Rate
    format: ".0%"
    style:
      axis_x:
        format: "$,.0f"
      axis_y:
        format: ".0%"
rows:
  - segment_scatter
$0$10,000$20,000$30,000$40,000$50,000$60,000$70,000$80,000$90,000$100,000$110,000$120,000$130,000$140,000$150,000$160,000$170,000$180,000$190,000$200,000$210,000$220,000Average Deal Size22%23%24%25%26%27%28%29%30%31%32%33%34%35%36%37%38%39%40%41%42%43%44%Win RateEnterpriseMid-MarketSMBStrategicsegment020406080100120140open_pipelineDeal Size vs Win Rate by Segment 2026-05-12 12:35
▶

Dot Plot

This example uses the same point-chart family to create a dot plot, where the y-axis is categorical and the x-axis carries the quantitative comparison.

queries:
  response_times:
    columns: [team, median_response_hours]
    values:
      - ["Onboarding", 1.8]
      - ["Support", 2.4]
      - ["Success", 3.1]
      - ["Renewals", 4.0]
      - ["Escalations", 5.3]

charts:
  team_response_dots:
    query: response_times
    type: scatter
    title: Median Response Time by Team
    x: median_response_hours
    y: team
    x_label: Hours
    y_label: Team
    sort:
      by: median_response_hours
      order: desc
    style:
      axis_x:
        format: ".1f"
rows:
  - team_response_dots
0.00.20.40.60.81.01.21.41.61.82.02.22.42.62.83.03.23.43.63.84.04.24.44.64.85.05.25.4HoursEscalationsRenewalsSuccessSupportOnboardingTeamMedian Response Time by Team 2026-05-12 12:35
▶

Style Fields

Use style for Dataface shorthand properties that affect presentational defaults such as legend visibility and grid lines.

Dataface field Maps to Vega-Lite Allowed values Notes
style.legend.disable encoding.color.legend true or false Typed legend control. true hides the legend.
style.axis.grid axis grid flags true or false Typed grid visibility control.
style.background chart SVG background wrapper Color value Applies a chart-level background fill behind the rendered SVG.

Legend and Grid Lines

This example keeps the same basic scatter structure while showing the small style surface for point charts.

queries:
  experiment_results:
    columns: [confidence, lift, cohort]
    values:
      - [0.62, 0.07, "Baseline"]
      - [0.68, 0.10, "Baseline"]
      - [0.73, 0.12, "Baseline"]
      - [0.66, 0.14, "Guided"]
      - [0.71, 0.17, "Guided"]
      - [0.77, 0.19, "Guided"]

charts:
  experiment_scatter:
    query: experiment_results
    type: scatter
    title: Confidence vs Lift
    x: confidence
    y: lift
    color: cohort
    style:
      legend:
        disable: true
      axis:
        grid:
          hidden: true
      axis_x:
        format: ".0%"
      axis_y:
        format: ".0%"
rows:
  - experiment_scatter
0%2%4%6%8%10%12%14%16%18%20%22%24%26%28%30%32%34%36%38%40%42%44%46%48%50%52%54%56%58%60%62%64%66%68%70%72%74%76%78%80%Confidence7%8%8%9%9%10%10%11%11%12%12%13%13%14%14%14%15%16%16%17%17%18%18%19%19%LiftConfidence vs Lift 2026-05-12 12:35
▶

Axis and Scale Style

Use style for axis and scale properties that shape how a point chart is framed and read.

Dataface field Maps to Vega-Lite Allowed values Notes
style.axis_x config.axisX / encoding.x.axis AxisStyle object Per-axis styling (format, ticks, labels, grid, title).
style.axis_y config.axisY / encoding.y.axis AxisStyle object Per-axis styling.
style.scale config.scale ScaleStyle object Global scale config (zero, nice, domain, clamp).

Axis Formatting and Scale Bounds

This example shows the most common style work on point charts: formatting axes and trimming the visible scale range to the comparison that matters.

queries:
  product_health:
    columns: [activation_rate, retention_rate]
    values:
      - [0.52, 0.67]
      - [0.58, 0.71]
      - [0.63, 0.74]
      - [0.69, 0.78]
      - [0.74, 0.83]
      - [0.81, 0.88]

charts:
  health_scatter:
    query: product_health
    type: scatter
    title: Activation Rate vs Retention Rate
    x: activation_rate
    y: retention_rate
    style:
      axis_x:
        format: ".0%"
      axis_y:
        format: ".0%"
      scale:
        zero: false
rows:
  - health_scatter
52%53%54%55%56%57%58%59%60%61%62%63%64%65%66%67%68%69%70%71%72%73%74%75%76%77%78%79%80%81%82%Activation Rate66%67%68%69%70%71%72%73%74%75%76%77%78%79%80%81%82%83%84%85%86%87%88%Retention RateActivation Rate vs Retention Rate 2026-05-12 12:35
▶

Mark Fields

Dataface scatter charts are authored with type: scatter (or the type: point alias) plus top-level channels such as x, y, color, size, and shape. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition blocks are rejected on the authored surface. Use top-level Dataface fields and the typed style: object.