Line chart

Use a line chart to show a metric changing across an ordered category such as time.

Every preview on this page is generated from the YAML shown below it using a fixed documentation dataset.

Basic

Use one ordered query.dimensions field for the horizontal axis and one query.metrics field for the plotted value. Sorting by month keeps the line chronological, while explicitly hidden labels keep the trend readable.

Key fields

visuals:
  revenue_line:
    title: Revenue line by month
    type: line
    presentation:
      type: cartesian
      labels:
        density: hidden
        priority: []
        maxCharacters: 24
        minimumSpacing: 0
        tooltipFallback: true
    query:
      type: aggregate
      dimensions:
      - purchase_month
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 30

Explicit axis policies

Use a time axis for date-grained categories and an inverted bounded value axis when lower values should appear higher in the frame. Explicit tick, grid, rotation, and date-unit policies keep the renderer behavior visible in the example.

Key fields

visuals:
  revenue_line_axis_policies:
    title: Revenue with explicit axis policies
    type: line
    presentation:
      type: cartesian
      axes:
      - id: x
        type: time
        scale: automatic
        zero: automatic
        tickDensity: normal
        ticks: visible
        grid: hidden
        labelRotation: diagonal
        dateUnit: month
      - id: primary_y
        type: value
        scale: linear
        zero: exclude
        inversion: inverted
        minimum: 0
        maximum: 600
        tickDensity: dense
        ticks: visible
        grid: visible
        labelRotation: horizontal
    query:
      type: aggregate
      dimensions:
      - dimension: purchase_date
        grain: month
        alias: purchase_month
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 30

Multiple series

Use two ordered query.dimensions fields to split the metric into one line per status. The first dimension supplies the category axis and the second supplies the series identity.

Key fields

visuals:
  revenue_line_status:
    title: Revenue line by status
    type: line
    presentation:
      type: cartesian
      legend: right
      legendTitle: Fulfillment status
      legendItems:
      - value: delivered
        label: Delivered
      - value: processing
        label: Processing
      - value: shipped
        label: Shipped
      - value: canceled
        label: Canceled
      seriesIntent:
      - value: delivered
        order: 0
        color: success
      - value: processing
        order: 1
        color: warning
      - value: shipped
        order: 2
        color: data_2
      - value: canceled
        order: 3
        color: danger
      tooltip:
      - field: purchase_month
        label: Purchase month
      - field: status
        label: Order status
      - field: revenue
        label: Revenue
        format:
          kind: currency
          currency: USD
          maximumFractionDigits: 0
    query:
      type: aggregate
      dimensions:
      - purchase_month
      - status
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 60

Visual calculation

Add a running-total calculation to the same result frame. Calculation references use compiled result aliases, so the ordering field is the category dimension returned by the query.

Key fields

visuals:
  revenue_line_running:
    title: Revenue and running total
    type: line
    calculations:
    - id: running_revenue
      label: Running revenue
      template: running_total
      source: revenue
      orderBy:
      - field: purchase_month
        direction: asc
    presentation:
      type: cartesian
    query:
      type: aggregate
      dimensions:
      - purchase_month
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 30

Stepped line

Set presentation.step: true for discrete changes between periods, hide point symbols for a quieter trace, and enable dataZoom for long ranges.

Key fields

visuals:
  revenue_line_step:
    title: Long-range revenue line
    type: line
    presentation:
      type: cartesian
      step: true
      showSymbols: false
      dataZoom: true
    query:
      type: aggregate
      dimensions:
      - purchase_month
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 30

Governed decision context

Reference lines, bands, and event annotations on a log axis use the positive numeric domain: authored numeric literals must be greater than zero. Field and reducer references are evaluated after the result is filtered; a nonpositive resolved line or event is omitted, and a band is omitted when either endpoint is nonpositive. A positive reference outside the visible log bounds remains an ordinary out-of-range reference.

Use a named context dataset when a title or description must be recomputed from the same active semantic filters as the chart. Context queries are compiled with the visual and delivered in the typed visualization envelope.

Here the context query summarizes the first status separately; it does not filter the revenue line to that status. Its metadata is labeled as context, independently of the fixed reference target.

Key fields

visuals:
  revenue_line_context:
    title: Revenue trend
    subtitle: Total revenue with separate status context
    type: line
    datasets:
      context:
        type: aggregate
        dimensions:
        - status
        metrics:
        - metric: revenue
          alias: context_revenue
        sort:
        - field: status
          direction: asc
        limit: 1
    metadata:
      title:
        dataset: context
        field: status
        reducer: first
        prefix: "Revenue — context status: "
        fallback: Revenue trend
      description:
        dataset: context
        field: context_revenue
        reducer: mean
        prefix: "Context revenue is "
        suffix: " USD."
        fallback: Context revenue is unavailable.
    presentation:
      type: cartesian
      axes:
      - id: primary_y
        title: Revenue
        scale: linear
        zero: exclude
        displayUnits: none
        tickDensity: dense
      referenceLines:
      - id: target
        axis: primary_y
        value:
          kind: number
          value: 400
        label: Target
        tone: success
      referenceBands:
      - id: observed_range
        axis: primary_y
        from:
          kind: field
          field: revenue
          reducer: minimum
        to:
          kind: field
          field: revenue
          reducer: maximum
        label: Observed range
        tone: neutral
      eventAnnotations:
      - id: fiscal_year
        axis: x
        value:
          kind: text
          value: "2025-01"
        label: Fiscal year
        description: Start of fiscal year
        tone: ink
    query:
      type: aggregate
      dimensions:
      - purchase_month
      metrics:
      - revenue
      sort:
      - field: purchase_month
        direction: asc
      limit: 30

API reference

Kind: chart. Renderer: echarts. Supported result shapes: category_series_value category_value.

Field	Type	Default	Allowed values	Description
`datasets`	`named query mapping`	—	—	Declares bounded context queries that inherit the visual's active semantic filters.
`query.dimensions`	`field mapping`	—	—	Groups query results and supplies category or hierarchy labels.
`query.limit`	`integer`	`no limit`	`positive integer`	Caps the number of rows returned to the renderer.
`query.metrics`	`metric mapping`	—	—	Selects governed semantic metrics consumed by the visual shape.
`query.sort`	`sort list`	—	—	Orders query results by a returned field or metric alias.
`presentation.dataZoom`	`boolean`	`false`	`true` `false`	Adds bounded zoom controls to supported Cartesian charts.
`presentation.labels`	`label policy`	`hidden`	`hidden` `automatic` `dense` `always`	Controls deterministic label density, priority, truncation, and tooltip fallback.
`presentation.legend`	`string`	`none`	`none` `top` `right` `bottom` `left`	Controls the renderer-neutral legend position.
`presentation.showSymbols`	`boolean`	`true`	`true` `false`	Shows point symbols on compatible Cartesian charts.
`presentation.step`	`boolean`	`false`	`true` `false`	Renders line segments as discrete steps between ordered categories.
`presentation.tooltip`	`result field list`	`none`	—	Binds governed result fields exposed in point tooltips.
`calculations`	`closed visual calculation list`	`none`	`running_total` `moving_average` `difference` `percentage_difference` `percent_of_parent` `percent_of_grand_total` `rank` `cumulative_contribution` `lookup`	Evaluates governed post-aggregation templates over compiler-owned result-frame aliases with explicit ordering, partitions, and incomplete-frame diagnostics.

Accessibility. Use a descriptive title and unit, and do not rely on color alone to distinguish series or values.