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.

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 YAML Schema Reference.

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
Dataface 0246810121416182022242628303234363840Ad Spend150200250Pipeline ValueAd Spend vs Pipeline Value 2026-07-17 15:04 UTC made with dataface
▶

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.
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
    style:
      number_format: percent_whole
      axis_x:
        format: currency_whole
      axis_y:
        format: percent_whole
rows:
  - segment_scatter
Dataface $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 Size25%30%35%40%Win RateEnterpriseMid-MarketSMBStrategicSegment020406080100120140Open PipelineDeal Size vs Win Rate by Segment 2026-07-17 15:04 UTC made with dataface
▶

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
Dataface 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-07-17 15:04 UTC made with dataface
▶

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.visible encoding.color.legend true or false Typed legend control. false hides the legend.
style.axis.grid.visible axis grid visibility true or false false hides grid lines. Use style.axis.grid.visible: false (nested under grid:).
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:
        visible: false
      axis:
        grid:
          visible: false
      axis_x:
        format: percent_whole
      axis_y:
        format: percent_whole
rows:
  - experiment_scatter
Dataface 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%Confidence10%15%LiftConfidence vs Lift 2026-07-17 15:04 UTC made with dataface
▶

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: percent_whole
      axis_y:
        format: percent_whole
      scale:
        zero: false
rows:
  - health_scatter
Dataface 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 Rate70%75%80%85%Retention RateActivation Rate vs Retention Rate 2026-07-17 15:04 UTC made with dataface
▶

Value Labels

Show the numeric value beside each point on a scatter chart by enabling style.scatter.marks.point.labels.visible.

<!-- dft-snippet: scaffold=scatter_chart_base -->
style:
  scatter:
    marks:
      point:
        labels:
          visible: true
          position: top    # top | bottom | left | right | middle
          format: null     # null inherits axis_quantitative.format (the measure-axis format, e.g. "~s"); or set e.g. ".2f"
          dx: null         # pixel horizontal offset (overrides position default)
          dy: null         # pixel vertical offset (overrides position default)
          font:
            color: "#6b7280"
            size: 11

Position values:

Value Placement
top Above the point — default
bottom Below the point
left To the left of the point
right To the right of the point
middle Centered on the point

Point and line charts share the same position vocabulary and Vega-Lite mapping.

Mark Fields

Dataface scatter charts are authored with type: scatter 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.