Implementation:Iterative Dvc Match Defs Renderers

Knowledge Sources	DVC
Domains	Visualization, Template_Rendering
Last Updated	2026-02-10 00:00 GMT

Overview

Concrete tool for matching plot definitions to renderer types, converting data through appropriate converters, and producing filled Vega-Lite renderer objects, provided by the DVC library. This function wraps the dvc_render template and renderer infrastructure.

Description

The match_defs_renderers function is the central orchestration point that connects DVC's plot data collection pipeline to the dvc_render rendering library. It takes the fully resolved plot data (with definitions and parsed sources across all revisions), groups definitions by their logical plot ID using PlotsData.group_definitions, selects the appropriate renderer class (VegaRenderer or ImageRenderer from the dvc_render package), instantiates the matching converter (VegaConverter or ImageConverter), and calls flat_datapoints to produce the final datapoint list for each renderer.

The PlotsData helper class encapsulates the nested data structure and provides group_definitions to consolidate definitions across revisions, and get_definition_data to retrieve the parsed file contents for specific source files at a given revision.

The function returns a list of RendererWithErrors named tuples, each bundling a renderer object with dictionaries of source-level errors (e.g., file not found in a specific revision) and definition-level errors (e.g., field mismatch during conversion). This design allows the output layer to render whatever data succeeded while reporting failures.

Usage

Use match_defs_renderers after Plots.show or Plots.diff has collected and resolved all plot data. It is the final transformation step before output rendering (to JSON or HTML). It is called directly by CmdPlots.run in the command-line interface.

Code Reference

Source Location

• Repository: DVC
• File: dvc/render/match.py
• Lines: L68-132 (match_defs_renderers)
• File: dvc/render/match.py
• Lines: L31-59 (PlotsData)
• File: dvc/render/convert.py
• Lines: L8-18 (_get_converter)

Signature

def match_defs_renderers(
    data: dict,
    out: Optional[str] = None,
    templates_dir: Optional["StrPath"] = None,
) -> list[RendererWithErrors]:
    ...

class PlotsData:
    def __init__(self, data: dict):
        self.data = data

    def group_definitions(self) -> dict:
        ...

    def get_definition_data(
        self, target_files: list[str], rev: str,
    ) -> dict:
        ...

class RendererWithErrors(NamedTuple):
    renderer: "Renderer"
    source_errors: dict[str, dict[str, Exception]]
    definition_errors: dict[str, Exception]

Import

from dvc.render.match import match_defs_renderers
from dvc.render.match import PlotsData, RendererWithErrors

I/O Contract

Inputs

Name	Type	Required	Description
data	dict	Yes	The fully resolved plots data structure as returned by Plots.show(). Keyed by revision name, each value containing "definitions" and "sources" sub-dicts with parsed data.
out	Optional[str]	No	Output directory path for writing image files to disk (passed to ImageConverter). If None, images are base64-encoded inline.
templates_dir	Optional[StrPath]	No	Directory path to search for custom Vega-Lite templates. Falls back to built-in templates from dvc_render if not provided.

Outputs

Name	Type	Description
renderers	list[RendererWithErrors]	A list of named tuples, each containing: (1) a renderer object (VegaRenderer or ImageRenderer from dvc_render) with filled template and datapoints, (2) source_errors dict mapping revision to {source_file: Exception} for I/O failures, and (3) definition_errors dict mapping revision to Exception for conversion failures.

Usage Examples

Basic Usage

from dvc.repo import Repo
from dvc.render.match import match_defs_renderers

repo = Repo()

# Collect and resolve plot data
plots_data = repo.plots.show(
    targets=None,
    revs=["workspace"],
    props={"template": "linear"},
)

# Match definitions to renderers
renderers_with_errors = match_defs_renderers(
    data=plots_data,
    out="dvc_plots/static",
    templates_dir=repo.plots.templates_dir,
)

for rwe in renderers_with_errors:
    renderer = rwe.renderer
    print(f"Plot: {renderer.name}, Type: {renderer.TYPE}")
    print(f"  Datapoints: {len(renderer.datapoints)}")
    if rwe.source_errors:
        print(f"  Source errors: {rwe.source_errors}")
    if rwe.definition_errors:
        print(f"  Definition errors: {rwe.definition_errors}")

Multi-Revision Comparison

from dvc.repo import Repo
from dvc.render.match import match_defs_renderers

repo = Repo()

# Collect data across revisions
plots_data = repo.plots.diff(
    targets=["metrics.csv"],
    revs=["v1.0", "v2.0"],
    props={"x": "step", "y": "loss"},
)

# Renderers will contain datapoints from all revisions
renderers_with_errors = match_defs_renderers(
    data=plots_data,
    templates_dir=repo.plots.templates_dir,
)

for rwe in renderers_with_errors:
    renderer = rwe.renderer
    revisions = renderer.get_revs()
    print(f"Plot '{renderer.name}' spans revisions: {revisions}")
    # The Vega-Lite template uses the "rev" field to color-code lines

Extracting Filled Templates

from dvc.repo import Repo
from dvc.render.match import match_defs_renderers

repo = Repo()
plots_data = repo.plots.show()

renderers_with_errors = match_defs_renderers(data=plots_data)

for rwe in renderers_with_errors:
    renderer = rwe.renderer
    if renderer.TYPE == "vega":
        # Get the complete Vega-Lite JSON specification
        vega_spec = renderer.get_filled_template()
        print(f"Vega-Lite spec for '{renderer.name}':")
        print(f"  Schema: {vega_spec.get('$schema', 'N/A')}")
        print(f"  Data values: {len(vega_spec.get('data', {}).get('values', []))}")

Related Pages

Implements Principle

• Principle:Iterative_Dvc_Vega_Lite_Template_Application