Data and connectors

Keep small observations in the block. Keep larger inputs in files beside the report. The same file can feed several charts and tables; paths are relative to the .rmd, never to the shell’s working directory.

Choose one source per block

This is the CSV variant of the tutorial chart:

data:
  csv: data/visits.csv

Use data.json for a JSON array of flat row objects. Inline, CSV and JSON cells may be text, finite numbers, booleans or null. Nested objects and arrays are not table cells. The data contract defines encoding, quoting, trimming, date precision and limits in full.

CSV uses UTF-8, commas and a header row with unique, nonempty names. Empty cells and recognized missing tokens remain missing observations. Leading-zero identifiers remain text. Long decimals and integers that cannot round-trip through binary64 remain source text; chart coordinates still use binary64. Tables and source downloads retain their digits. JSON cannot recover precision its producer already lost.

A source or one resolved dataset is limited to 16 MiB; complete generated HTML is limited to 64 MiB, including runtime, fonts and media. Reduce the input outside RichView when you need a smaller analytical result. Preserve what you filtered or aggregated in the source note.

The accepted data.url field is not loaded by the native or browser hosts. Download remote data into the report folder. Paths and symlinks cannot escape that folder.

Query through a native connector

The native host also resolves SQL, MetricFlow and cached results. A report names its connector in report.connectors.yaml; a trusted host configuration binds that name to a runtime and data source. Credentials belong to that configuration, never to the report.

Work through a local DuckDB query

Download these files into a dedicated sql-report/ folder, preserving their paths: report.rmd, report.connectors.yaml, data/seed.sql and queries/orders-by-month.sql. The seed contains fictional monthly orders.

The report-local declaration is:

connectors:
  local-duckdb:
    kind: duckdb
    database: data/warehouse.duckdb

The chart names that connector and the query file:

data:
  sql:
    connector: local-duckdb
    query: queries/orders-by-month.sql

Install DuckDB 1.5.6 for this example. The bundled reader uses the 1.5 storage format; a database created by DuckDB 2.0 is rejected. Create the database before rendering:

cd sql-report
duckdb data/warehouse.duckdb < data/seed.sql
richview generate report.rmd --format json

A successful render reports data.provenance with three rows from local-duckdb via SQL. The HTML carries the resolved rows, not the database or a live connection. A missing database currently appears as an unregistered connector; check the declared database path first.

Connect an existing MetricFlow project

MetricFlow requires your own configured semantic project, warehouse access and compatible mf launcher. This is configuration guidance, not a standalone runnable demo. The report only declares a runtime handle:

connectors:
  analytics:
    kind: metricflow
    runtime: analytics-local

Keep the trusted host configuration outside the report folder, for example as connectors.toml:

[metricflow.analytics-local]
launcher = ["mf"]
project_dir = "/absolute/path/to/your/semantic-project"

A report’s data.metricflow names connector: analytics and the metrics defined by that project. Run it with richview generate your-report/report.rmd --connectors /absolute/path/to/connectors.toml, or set RICHVIEW_CONNECTORS to that configuration file. Keep credentials in the launch environment. Browser-only drafts do not run warehouse queries.

The generated chart fields define the connector and cache shapes. A missing connector declaration is a resource-resolution failure. A successful query is still data to review: RichView does not establish that the query answers your business question.

For integrity-pinned uploads, read asset storage. Reports still read their chart data and media from local files.