Skip to content

Results embeds

Documentation and blog pages can show a benchmark result from the Results Explorer next to the text that discusses it. There are two kinds, and each one tells the reader which of the two they are looking at.

  • Cited result. One result, fixed to a named snapshot. The page keeps the values it was published with and shows the snapshot’s identity and date. Use it in analysis that must not change after publication.
  • Current results. One or more results, read from the snapshot that the site serves right now and labelled Live. Use it for pages that should stay up to date.

Both use the Explorer’s own code for metric names, number formats, the primary metric of each benchmark and the visibility, ranking and withdrawal rules, so a value in an embed is the value the Explorer shows for the same snapshot.

Writing an embed

An embed is a fenced code block whose language is benchbox-result, holding key: value lines. It is plain GitHub-flavoured Markdown: GitHub shows the block as code, which reads as the citation record, and the site replaces it with the embed. The MyST guard has nothing to object to, because the fence language is not a directive.

Cited result

Do not type the values by hand. Print the block for a result in the current snapshot with the cite command and paste it into the page:

Terminal window
npm run results:cite -w website -- tpch-duckdb-sf1.0-20261007-83a01707

The command prints the block below. It fails when the result is not in the current snapshot, because a withdrawn result cannot be cited.

```benchbox-result
kind: cited
result: "tpch-duckdb-sf1.0-20261007-83a01707"
snapshot: "0e189624e6712c0e96cac56022b6530ec99648e2a1ffa0aade638652490822ea"
snapshot_date: "2026-11-06"
platform: "DuckDB"
benchmark: "TPC-H"
scale: "SF 1"
run_date: "2026-10-07"
metric: "Throughput@Size"
direction: "higher is better"
value: "297,653"
```
KeyMeaning
resultThe Explorer result id.
snapshotThe sha256 of the Results Explorer snapshot the values came from.
snapshot_dateThe date of the bundle that carried that snapshot.
platform, benchmark, scale, run_dateThe identity of the run, as the Explorer shows it.
metric, direction, valueThe primary metric of the run, as the Explorer formats it.

The build fails with the file and line when a key is missing or unknown, the snapshot is not 64 hex characters, or a date is not YYYY-MM-DD.

Current results

List the result ids. Each one is shown as a row, in the order written, with at most ten results in one block.

```benchbox-result
kind: current
results:
- tpch-duckdb-sf1.0-20261007-83a01707
- tpch-spark-sf1.0-20261007-9c57f2ae
```

What the reader sees

The page carries the cited values in its HTML, so they are readable without JavaScript and are found by site search. The Explorer’s code and the DuckDB engine are not fetched until the embed scrolls into view. A page without an embed fetches nothing from the Explorer.

Once an embed is in view, it reads the current snapshot and reports:

  • Published. A cited result says whether the current snapshot reports the same value. It never replaces the cited value; when the current value differs, it says so next to the cited one. A current result shows the platform, benchmark, run date, primary metric and whether the run is ranked, with the Explorer’s reason when it is not.
  • Withdrawn. A result that the current snapshot no longer contains, or whose visibility is not public, is shown as withdrawn. The values are removed and the id, and for a cited result the snapshot identity, stay. A withdrawn result is never dropped from the page and never shown as if it were still published.
  • Not readable. When the snapshot cannot be loaded, a cited result keeps its values and says it could not be checked. A current result says so and points to the Results Explorer.

Examples

A cited result, from the snapshot of the bundle that was current when this page was written:

Cited resultFixed to the snapshot of

DuckDB · TPC-H · SF 1

297,653Throughput@Size (higher is better)

Run on

Cited snapshot sha256:0e189624e6710e189624e6712c0e96cac56022b6530ec99648e2a1ffa0aade638652490822ea

Current results, where the last id is not in the snapshot and so shows as withdrawn:

LiveReads the current published snapshot and changes when it does.
Current results
PlatformBenchmarkRun datePrimary metricRanking
tpch-duckdb-sf1.0-20261007-83a01707The current value loads in the browser.
tpch-spark-sf1.0-20261007-9c57f2aeThe current value loads in the browser.
tpch-duckdb-sf1.0-20200101-00000000The current value loads in the browser.
Snapshot at site build sha256:cc71e4d1b0c2cc71e4d1b0c2881ff7155cb5802b16f469b3074bcbf4f7f5364f7f89ad970d6d