docs: custom chart GraphQL query guide (WBDOCS-1606)

[johndmulhausen]

Summary

Addresses WBDOCS-1606: clearer documentation for building queries in Custom Charts (GraphQL), including how to choose summaryTable vs historyTable, set tableKey, and use Chart fields. Cross-links the existing tutorial and the step-slider support article.

Changes

• custom-charts.mdx: New subsection Build the GraphQL query with source descriptions, three concrete examples, chart field naming note, and distinction from Query panels.
• walkthrough.mdx: Fix incorrect example key (my_custom_table → custom_data_table); link to the new section.

Sources and decision log

• JIRA WBDOCS-1606: Customer ask for clarity on custom chart queries and pointing at different log tables; Productboard link in ticket.
• Existing docs: Log data (summaryTable/historyTable definitions), walkthrough, step slider support (historyTable for step selector).
• Structure: How-to style subsection under Customize the chart so readers land on query guidance before Vega editing.

Needs SME verification

• Confirm summary bullet wording ("last value" for wandb.Run.log keys) matches current product behavior for all edge cases.
• Confirm Edit query advanced path is still accurate if the UI copy changed.

Resume prompt

Continue from PR (replace with actual URL after create): add SME review on WBDOCS-1606, then TW pass. Ticket: WBDOCS-1606.

{
  "skill": "author-docs",
  "version": "1.0.0",
  "depends_on": {"style-guide": "1.0.0"},
  "model": "unknown"
}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Apr 17, 2026, 6:49 PM

[johndmulhausen]

Follow-up after review questions:

• Q1 (summary value behavior): user deferred to SME; left existing 'usually holds the last value' wording and added to Needs SME verification below.
• Q2 (UI labels): softened references to specific menu labels. The section now says 'query editor' instead of naming Edit query, and refers to 'the step selector in the custom chart editor' instead of naming Other settings. SME please confirm the softer wording still makes sense for the current UI, and flag if we should name exact labels.

Needs SME verification (updated)

• Summary population rule for wandb.Run.log-only keys (is it strictly last-value? any define_metric-driven exceptions worth calling out here?)
• Confirm the softened wording about the query editor and step selector is accurate; if specific labels are stable, we can name them.

[Copilot]

Pull request overview

Improves the Custom Charts documentation by adding a focused guide on constructing the GraphQL query (including when to use summaryTable vs historyTable, how to set tableKey, and how to work with Chart fields), and updates the walkthrough to align with the corrected example key and cross-link the new guidance.

Changes:

• Added a new “Build the GraphQL query” subsection with source descriptions, examples, and Chart fields naming guidance.
• Updated the custom charts walkthrough to fix the logged table key example and link readers to the new GraphQL query section.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
models/app/features/custom-charts/walkthrough.mdx	Fixes the example tableKey and adds a cross-link to the new query-building guidance.
models/app/features/custom-charts.mdx	Adds a new subsection explaining GraphQL query sources (config/summary/history/summaryTable/historyTable), tableKey, examples, and Chart fields naming.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The “Summary” bullet links to /models/track/log/, which is the general logging overview. If this is specifically about how the run summary behaves/gets populated, linking to /models/track/log/log-summary/ would be a more direct reference for readers.

Suggested change

	* **Summary** pulls [summary](/models/track/log/) values. For keys you log with `wandb.Run.log()`, the summary usually holds the last value written for that key unless you set the summary yourself.
	* **Summary** pulls [summary](/models/track/log/log-summary/) values. For keys you log with `wandb.Run.log()`, the summary usually holds the last value written for that key unless you set the summary yourself.

[github-actions]

📚 Mintlify Preview Links

🔗 View Full Preview

📝 Changed (2 total)

📄 Pages (2)

File	Preview
models/app/features/custom-charts.mdx	Custom Charts
models/app/features/custom-charts/walkthrough.mdx	Walkthrough

---

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: b457bd5 at 2026-04-17 19:37:00 UTC

[github-actions]

🔗 Link Checker Results

✅ All links are valid!

No broken links were detected.

Checked against: https://wb-21fd5541-wbdocs-1606.mintlify.app

[johndmulhausen]

Claim adjudication

I re-investigated every new technical claim in this PR against code and engineering sources. Results below.

Primary sources consulted

• wandb-workspaces reports/v2/interface.py (public): CustomChart class and from_table
• wandb-workspaces reports/v2/internal.py (public): Vega2, QueryField, UserQuery
• wandb SDK wandb/sdk/wandb_summary.py (public): Summary class docstring
• Existing docs: models/app/features/custom-charts.mdx, models/app/features/custom-charts/walkthrough.mdx, support/models/articles/how-do-you-show-a-step-slider-in-a-custo.mdx

Verified

• summaryTable / historyTable / tableKey shape — Confirmed in CustomChart.from_table: query={"summaryTable": {"tableKey": table_name}}. table_name is the user's run.log() key, not a table column. Matches what the PR says about 'set tableKey to the dictionary key you used inside run.log(), not to a column name.'
• runSets as the root of the query — Confirmed in internal.py: QueryField.name: str = "runSets", and the CustomChart._to_model wraps user fields under a runSets root with ${runSets} substitution. This matches the existing walkthrough example column names (runSets_historyTable_r, etc.) and the PR's 'names often begin with runSets_' claim.
• Vega2 panel backing — Confirmed: class CustomChart maps to internal.Vega2 with view_type="Vega2". Consistent with the PR's framing that this is the GraphQL/Vega2 panel and is distinct from Weave Query Panels.
• Step slider requires historyTable — Confirmed in support article. PR links this correctly.
• Walkthrough key fix (my_custom_table → custom_data_table) — Confirmed by reading the code block in walkthrough.mdx that the step refers to; the logged key is custom_data_table. Old text was an internal inconsistency.
• Query panels use a different language — Confirmed by comparing models/app/features/panels/query-panels.mdx (Weave expressions like runs.summary["cifar10_sample_table"]) against the Vega2 QueryField DSL used by custom charts.

Fixed during adjudication

• Summary default behavior (previously hedged as 'usually holds the last value') — I was able to confirm exact behavior from wandb/sdk/wandb_summary.py Summary docstring: 'By default, a metric's summary is the last value of its History.' It can be changed via run.define_metric(summary=...) with accepted values "min" | "max" | "mean" | "best" | "last" | "none", or by assigning to run.summary[key] directly. Updated the bullet to state this precisely (commit b641695), replacing the earlier 'usually' hedge.

Partial / terminology caveat (not fixed)

• 'GraphQL query' framing — The existing page already calls this a GraphQL query, and the Vega2 panel ultimately resolves to GraphQL against the runs API. However, the CustomChart docstring in wandb-workspaces describes it as 'a weave query' (the legacy W&B query DSL — unrelated to the W&B Weave product). I kept the 'GraphQL query' framing because (a) it is what the surrounding existing doc uses, and (b) it is what the Vega2 panel resolves to under the hood. SME should decide whether to use a more precise term (for example, 'Vega2 panel query') in a follow-up style pass. This affects only wording, not the query examples.

Could not independently verify (still flagged for SME)

• Current exact UI labels in the custom chart editor. The PR now uses softer phrases ('query editor', 'step selector in the custom chart editor') to avoid drifting from the UI. SME should confirm whether specific labels are now stable enough to name.

Resulting PR state

• No technical claims were found to conflict with sources.
• One claim was strengthened (summary default + define_metric).
• All other claims are sourced from the wandb-workspaces and wandb SDK code or existing docs.

[johndmulhausen]

Style guide pass (Google + AGENTS.md)

Applied to PR #2482 files only: models/app/features/custom-charts.mdx (new Build the GraphQL query block) and models/app/features/custom-charts/walkthrough.mdx (modified step and adjacent typo).

Checkpoint 1 (structure and context)

• Replaced bold-only What each source is for with a complete introductory sentence (Each source in the query maps to different logged data:) before the bulleted list (list introduction rule).
• Replaced the numbered Examples list with a bulleted list and intro sentence (The following examples cover common cases:) because the three items are parallel alternatives, not sequential steps.
• Split the long Summary bullet into shorter sentences while preserving the same technical points (default last value, define_metric(..., summary=...), direct run.summary assignment).

Checkpoint 2 (language, formatting, polish)

• Walkthrough: fixed loading in to → loading into (typo).
• Walkthrough link line: For more detail on → For more information about (slightly clearer cross-reference).
• Third example: the chart sees → the chart shows (less anthropomorphic).

Not changed (out of scope)

• Full-document style issues outside this PR’s diff (for example older sentences in Customize the chart below the new section) were left as-is to avoid mixing unrelated edits with this PR.

Recommendations for technical review

Style-only pass. Please confirm the following if anything reads differently in product behavior.

• Summary bullet: The split still correctly states that the default summary is the last logged value and that overrides use define_metric(..., summary=...) or direct wandb.Run.summary assignment.
• Examples as bullets: No implied ordering; if product or support treats these as a fixed sequence, revert to a numbered list.

Commit: 6df87a82d