datagrok-exec

The ONLY way code runs in the Datagrok browser is via the datagrok_exec tool. Regular markdown code blocks do NOT execute.

Call datagrok_exec to perform an action the user asked for (add a viewer, filter, open a file, run a function). For informational questions — "how do I…", "what is…", "explain…", "can you…" — do not call datagrok_exec; find the page via workspace/help/INDEX.md, read it, use it to find needed material, then answer in plain text.

Globals available inside the code

Variable	Type	Available
grok	module	Always
ui	module	Always
DG	module	Always
view	DG.ViewBase	Always — check view.type for specific view type
t	DG.DataFrame	Only when view.type === 'TableView'

The code runs in an async IIFE, so await works directly.

Tool result

The tool returns {success, returnValue?, verified?, error?}.

success only means the JS did not throw — NOT that the intended effect happened. A typo'd viewer name, a no-op, or an action that ran twice all return success: true. returnValue is whatever object your own code chose to return; it populates the chat confirmation shown to the user, but it is not proof — it is self-reported by the same code that took the action. Make your code return a plain confirmation object so the user sees accurate details:

Action	Return
open / load table	{name, rowCount}
add viewer	{type}
filter	{filteredRowCount, totalRowCount}
upload DataFrame	{tableInfoId}
save layout	{layoutId}
open app / view	{viewName, viewType}
color / sort / pin	{column}

Error: {success: false, error: "..."} — report verbatim, do not silently retry.

Never pre-announce success before calling the tool.

Verifying actions — required with every action

Proof does not come from your own action code — it comes from re-reading live state in a fresh scope. For any state-changing datagrok_exec, pass the verify parameter with the call: {assertion, description}. The browser runs your action code, then immediately runs the assertion in a fresh scope (globals grok, ui, DG, view, t) that cannot see your action's variables, and returns its result as verified: {passed, observed?} — one round-trip, no separate verify call needed.

The assertion is yours to design for whatever you changed: re-read that thing and return the observed result (truthy = verified). verified.passed: true → report the observed value, not the value you intended. verified.passed: false (or missing) → the action is NOT confirmed — but do not assume it failed: a faulty assertion (wrong property, wrong count, missing return) reads exactly the same. Never re-run state-changing action code on a failed verify. First re-read the affected state with a read-only check (a corrected datagrok_verify assertion); only if that shows the change is genuinely absent, fix and re-run the action — re-running one that already worked creates duplicate viewers/columns/rows. The standalone datagrok_verify tool exists for that fix-loop and for MCP calls that changed platform state (it takes the same {assertion, description}). The runtime blocks the turn from ending until a verification passes (bounded retries — if they run out, the response is shown to the user flagged as unverified, so never present unverified work as done).

Returning a result to the chat

Only return an HTMLElement when the explicit user goal is to see output in the chat ("show me the molecule", "display the table", "draw a plot"). Never return HTMLElements for intermediate results, confirmation data, or actions where the platform UI is the destination. An HTMLElement return replaces the confirmation object — no returnValue is sent.

Raw scalars, strings, or DG.DataFrame will NOT render; convert via the table below:

Result type	How to render
scalar	ui.divText(String(value))
key-value pairs	ui.tableFromMap({key: value})
list of items	ui.divV(items.map((x) => ui.divText(x)))
DG.DataFrame	DG.Viewer.grid(df).root
DG.Viewer / DG.Widget	obj.root
DG.ViewBase (incl. apps)	open via grok.shell.addView(v) — do NOT return
molecule (SMILES / molblock)	grok.chem.drawMolecule(smiles, 300, 200)
macromolecule (HELM)	see HELM output below
graphics	see Graphics output below

Native top-menu commands

If an operation already exists as a top-menu command (aggregate, join, cluster, add column, …), invoke it instead of building a custom ui.dialog. Walk the menu with find() (chain through | groups), matching leaf text exactly:

grok.shell.topMenu.find('Data').find('Aggregate Rows...').click();
grok.shell.topMenu.find('Edit').find('Go To').find('Row...').click();

Menu	Commands
Edit	Undo, Redo, Add New Column..., Add Rows..., Column Properties..., Find and Replace..., Go To | Row..., Go To | Next Selected, Go To | Prev Selected, Remove | Selected Rows, Remove | Selected Columns, Remove | Selected Rows or Columns
View	Columns, Console, Context Panel, Schema, Tables, Variables, Toolbox, Windows, Home, Reset Filter, Edit Tooltip..., Embed..., Full Screen, Presentation Mode, Layout | Save to Gallery, Layout | Open Gallery, Layout | Clone View, Layout | Download, Layout | Clear
Select	All, None, Invert, All Columns, Duplicates..., Missing Values..., Random Rows..., Extract Selected Rows, Filter to Column..., Selection to Column..., Selection to Filter
Data	Aggregate Rows... (also pivot), Join Tables..., Link Tables..., Compare Tables..., Compare Columns..., Append Tables..., Unpivot..., Split Column..., Split Column by RegExp..., Categorize..., Anonymize..., Batch Edit...
ML	Analyze | PCA..., Analyze | PLS..., Analyze | ANOVA..., Analyze | Multivariate Analysis..., Cluster | DBSCAN..., Cluster | MCL..., Models | Train Model..., Models | Apply Model..., Notebooks | New Notebook..., Reduce Dimensionality..., Impute Missing Values..., Pareto Front...

Per-area skills

For task-specific API surface, open the matching skill before writing code:

User intent	Skill
Find / describe / add / remove / rename columns; set semType/units/format/friendly name; color coding	datagrok-df-and-columns
Calculated (formula-driven) columns	datagrok-calc-column
Filter rows (range, categorical, contains, substructure, predicate)	datagrok-filtering
Select rows; current row; selection ↔ filter	datagrok-selection
Add / configure / find / close viewers	datagrok-viewers
Grid sort, visibility, widths, pins, freeze; grid-only cell tint	datagrok-grid-customization
Cheminformatics: SMILES/MolBlock/InChI/canonicalize	datagrok-chem-data / datagrok-chem-toolkit

Multiple tool calls in one response

Each datagrok_exec call runs in its own scope (a fresh new Function(...) IIFE). Calls execute sequentially, but JS variables declared in one call are NOT visible in the next.

Persists across calls:

• The view reference and the t DataFrame reference (column additions, filter changes, and other mutations are visible to later calls)
• Anything pushed into the platform: viewers added, dialogs opened, columns appended, server-side state

Does NOT persist: const/let/var bindings, helper functions, cached values. A second call must re-derive from t.

Before consuming a query/function result, check the wrapper's return type in the apiRef:

// CORRECT — wrapper returns Promise<string>
const helm = await grok.data.query('Biologics:GetBiologicsPeptideHelmByIdentifier',
  { peptideIdentifier: 'GROKPEP-000002' });

// WRONG — assuming a DataFrame because most queries return one
const df = await grok.data.query('Biologics:GetBiologicsPeptideHelmByIdentifier', {...});
const helm = df.columns.byIndex(0).get(0);

Launching apps & views

Datagrok apps are functions with meta.role: app. Calling one via grok.functions.call('Pkg:appName') may return a DG.ViewBase (or nothing if the app opens its own view). A returned view is NOT yet attached to the workspace — hand it to grok.shell.addView(). Do NOT return the view from the code; open it.

const result = await grok.functions.call('Pkg:appName');
if (result instanceof DG.ViewBase)
  grok.shell.addView(result);

HELM output

const helmInput = await ui.input.helmAsync('', { editable: false });
helmInput.stringValue = helmString;
return helmInput.root;

Graphics output

Returned graphics elements may render blank without intrinsic dimensions. Extract Base64-encoded image data and wrap with explicit width and height:

const b64 = await grok.functions.call('Chem:ChemistryGasteigerPartialCharges', {mol: 'CCC', contours: 10});
return ui.image('data:image/png;base64,' + b64, 300, 200);