Output Artifact Reference

Reference tables for final output viewers, Markdown breyta-resource embeds,
table queries, aggregates, charts, downloads, media, and structured output.

For the authoring model and examples in context, start with
Output Artifacts.

Complete Report Pattern

Use this as the reference pattern when you need to combine the full output
authoring surface in one report:

Minimal authoring shape:

(let [orders-table (flow/step :function :persist-orders
                              {:persist {:type :table
                                         :rows-path [:rows]}})
      nested-report (flow/step :function :persist-nested-report
                               {:persist {:type :blob
                                          :content-type "text/markdown"}})
      image (flow/step :function :persist-image
                       {:persist {:type :blob
                                  :content-type "image/svg+xml"}})
      video (flow/step :function :persist-video
                       {:persist {:type :blob
                                  :content-type "video/mp4"}})
      table-uri (:uri orders-table)
      report (str "# Daily retail operations brief\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource table-uri
                           :view :table
                           :mode :snapshot
                           :title "Filtered open orders"
                           :table {:query {:select [:order-id :customer :amount]
                                           :where [[:status := "open"]]
                                           :sort [[:created-at :desc]]
                                           :page {:mode :offset :limit 25}}
                                   :row-transform "(fn [row]\n  (assoc row :customer (str (:customer row) \" - review\")))"
                                   :columns {"amount" {:label "Amount"
                                                       :format {:display "currency"
                                                                :currency "USD"}}}}})
                  "\n```\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource table-uri
                           :view :table
                           :mode :snapshot
                           :title "Orders by status"
                           :table {:aggregate {:group-by ["status"]
                                               :metrics [{:op :count :as "orders"}]}
                                   :chart {:x "status"
                                           :series [{:field "orders"
                                                     :type :bar}]}}})
                  "\n```\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource table-uri
                           :view :table
                           :mode :snapshot
                           :title "Order value trend"
                           :table {:query {:select [:created-at :amount]
                                           :sort [[:created-at :asc]]
                                           :page {:mode :offset :limit 25}}
                                   :columns {"created-at" {:label "Created"
                                                           :format {:display "timestamp"}}
                                             "amount" {:label "Order value"
                                                       :format {:display "currency"
                                                                :currency "USD"}}}
                                   :chart {:x "created-at"
                                           :series [{:field "amount"
                                                     :label "Order value"
                                                     :type :line}]}}})
                  "\n```\n\n"
                  "See [Analyst note](" (:uri nested-report) ").\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource (:uri image)
                           :view :image
                           :alt "Fulfillment lane dashboard snapshot"})
                  "\n```\n\n"
                  "## Attachments\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource table-uri
                           :view :download
                           :title "Orders source CSV"
                           :format :csv})
                  "\n```\n\n"
                  "```breyta-resource\n"
                  (pr-str {:resource (:uri video)
                           :view :download
                           :title "Packing station clip video"})
                  "\n```")]
  {:breyta.viewer/kind :markdown
   :breyta.viewer/options {:title "Markdown resource output"}
   :breyta.viewer/value report})

The complete pattern can include one example of every current embed adapter:
:table, table :aggregate, bar and line table :chart, :download, :markdown,
:text, :json, :image, and :video.

Viewer Envelope

Return a viewer envelope when you want predictable rendering:

{:breyta.viewer/kind :markdown
 :breyta.viewer/options {:title "Summary"}
 :breyta.viewer/value "# Summary\n\nDone."}

:breyta.viewer/options {:title ...} provides viewer metadata and can label
grouped child artifacts. It does not rename the canonical flow-output resource
or the single final output page/panel chrome. Recent-run row titles are
configured separately on the run form with :title.

Viewer Kinds

Markdown Resource Directive

Inside a Markdown viewer, embed resources with a fenced block:

```breyta-resource
{:resource "res://v1/ws/ws-123/result/table/tbl_orders"
 :view :table
 :mode :snapshot
 :title "Open orders"
 :table {:query {:select ["order-id" "customer" "amount"]
                 :where [["status" := "open"]]
                 :page {:mode :offset :limit 25}}}}
```

Embed Pattern Matrix

Snapshot And Live Mode

Markdown resource embeds are resolved as snapshots. The resource is read or
queried by the output resolver, converted into viewer metadata, and rendered
from that snapshot in document order.

V1 does not support live resource-backed pagination, arbitrary re-querying from
the browser, or client-side resource fetches from Markdown embeds. Use bounded
query/aggregate options in the directive so the report output is stable.

Directive blocks are intentionally bounded authoring data. Keep each
breyta-resource block small, use the documented enum-like values for fields
such as :view, :mode, and :format, and put large row shaping logic in flow
functions before persisting the resource. The renderer rejects oversized
directives and unsupported values with an inline fallback.

Table Query Options

Static Markdown tables and Breyta table resource embeds are separate output
patterns. Use normal Markdown table syntax for fixed explanatory rows inside a
report. Use :view :table when the output should render a persisted table
resource with bounded query, aggregate, chart, download, or drilldown behavior.

{:query {:select [:order-id :customer :amount :created-at]
         :where [[:status := "open"]]
         :sort [[:created-at :desc]]
         :page {:mode :offset :limit 25}}}

Field names in :select, :where, :sort, :group-by, :order-by, and
metric :field / :as values may be strings or keywords.

Table Aggregate Options

{:aggregate {:where [["created-at" :>= "2026-05-01T00:00:00Z"]]
             :group-by ["status"]
             :metrics [{:op :count :as "orders"}
                       {:op :sum :field "amount" :as "total-amount"}]
             :having [["orders" :>= 1]]
             :order-by [["status" :asc]]
             :limit 10}}

Metric-local filters are supported:

{:op :count
 :where [["status" := "open"]]
 :as "open-orders"}

Argument metric example:

{:op :arg-max
 :field "order-id"
 :order-field "amount"
 :as "largest-order-id"}

Bucketed group-by examples:

{:group-by [{:field "created-at"
             :bucket {:op :date-trunc :unit :month}
             :as "created-month"}]
 :metrics [{:op :count :as "orders"}]
 :limit 12}

{:group-by [{:field "amount"
             :bucket {:op :numeric-bin :size 10}
             :as "amount-bin"}]
 :metrics [{:op :count :as "orders"}
           {:op :percentile :field "amount" :p 0.95 :as "p95-amount"}]
 :limit 20}

Table Column Presentation

{:columns {"amount" {:label "Amount"
                     :format {:display "currency" :currency "USD"}}
           "created-at" {:label "Created"
                         :format {:display "timestamp"}}}}

Table Row Transform

Use :row-transform when column labels and built-in formats are not enough for
the final display row. The transform runs once while the Markdown resource
snapshot is produced, after query/aggregate/selection and before the output is
stored. It is not re-run on every page read.

{:resource "res://v1/ws/ws-123/result/table/tbl_orders"
 :view :table
 :mode :snapshot
 :table {:query {:select [:order-id :customer :amount]
                 :where [[:status := "open"]]
                 :page {:mode :offset :limit 25}}
         :row-transform "(fn [row]\n  (assoc row :customer\n         (str (:customer row) \" - \"\n              (if (< (:amount row) 10)\n                \"batch pickup\"\n                \"monitor cutoff\"))))"}}

Table Chart Options

{:chart {:title "Order count by status"
         :x "status"
         :series [{:field "orders"
                   :label "Orders"
                   :type :bar}]
         :height 220}}

Line chart:

{:chart {:title "Order value trend"
         :x "created-at"
         :series [{:field "amount"
                   :label "Order value"
                   :type :line}]
         :height 220}}

Chart x-axis and hover labels reuse the table column display formatting for the
:x field. For timestamp/date period fields, set the column :format so the
chart shows compact labels instead of raw ISO strings:

{:query {:select [:created-at :amount]
         :page {:mode :offset :limit 25}}
 :columns {"created-at" {:label "Created"
                         :format {:display "timestamp"}}}
 :chart {:x "created-at"
         :series [{:field "amount" :type :line}]}}

Charts include zero in the y-domain by default. Use explicit :y-min and
:y-max chart options when a custom y-domain is required.

Table Family Partitions

Pin partitioned table families for stable snapshots:

{:resource "res://v1/ws/ws-123/result/table/tbl_orders_by_year"
 :view :table
 :table {:partition-key "2026"
         :query {:select ["order-id" "amount"]
                 :page {:mode :offset :limit 25}}}}

Download Options

{:resource "res://v1/ws/ws-123/result/table/tbl_orders"
 :view :download
 :title "Orders source CSV"
 :format :csv}

In the rendered Breyta UI this becomes a compact source/download affordance.
When a user copies the whole Markdown output, the same embed becomes a normal
Markdown link with an absolute Breyta app deep link to the resource viewer:

[Orders source CSV](https://flows.breyta.ai/ws-123/resources/panel?uri=...)

Use this when a report should show a table snapshot inline but also expose the
underlying source/export as a portable link.

Resource Links In Tables

Table cells can point at other resources by storing canonical resource refs in
row data:

{:resource "Analyst note"
 :type "Markdown"
 :open {:type :resource-ref
        :uri "res://v1/ws/ws-123/file/blob/.../analyst-note.md"
        :label "Analyst note"}}

The web table renderer displays these cells as clickable resource links. In a
run Output panel, clicking the link opens the target resource in the same panel
and shows a compact Output return link. CLI/API table reads and CSV export
keep the canonical raw resource-ref value. Copied Markdown table output uses the
rendered label for the cell.

Structured Map Output

Do not paste maps into Markdown paragraphs. Use one of these:

Copy Markdown Export

The floating copy action on a Markdown output exports portable Markdown where
resolved resource embeds are converted when possible.

Absolute links are built from the current Breyta request host. Resource-backed
links prefer Breyta app deep links so clicking them opens the resource output in
Breyta. Normal Breyta access controls still apply when the linked resource is
opened.