Queries & Mutations
Fetch and write data from your tools. The model writes the wiring, the runtime runs it.
Queries and mutations connect a generated UI to your backend. The model writes which tool to call and where the result goes. The runtime calls your tools directly, without the model.
For example, a support agent asks for "a table of open tickets with a form to add one". The model writes one Query that lists tickets and one Mutation that creates a ticket. The table fills from your API, and each new ticket appears in it after the user submits the form. No click goes through the model.
A tool is any function your app exposes: a database query, an API call, or a calculation. The model generates Query and Mutation statements that call these tools. The runtime runs them and feeds the results into your UI.
Reading data with Query
data = Query("list_tickets", {}, {rows: []})What each argument means:
"list_tickets": the tool name. It matches a tool yourtoolProviderexposes.{}: the arguments passed to the tool.{rows: []}: the default value. The UI renders it until the tool responds.
The default value lets the UI render while the data loads.
Using Query results
Query results are data. Access fields with dot notation:
tbl = Table([Col("Title", data.rows.title), Col("Status", data.rows.status)])
chart = LineChart(data.rows.day, [Series("Views", data.rows.views)])data.rows.title takes the title field from every row, like a column pluck.
Reactive queries
Pass a $variable in the query arguments. The query runs again when the variable changes:
$days = "7"
data = Query("analytics", {days: $days}, {rows: []})
filter = Select("days", [SelectItem("7", "7 days"), SelectItem("30", "30 days")], null, null, $days)The user picks "30", $days updates, the Query fetches again with {days: "30"}, and the chart updates.
Auto-refresh
A fourth argument sets a refresh interval in seconds:
health = Query("get_server_health", {}, {cpu: 0, memory: 0}, 30)This fetches the data again every 30 seconds.
Writing data with Mutation
createResult = Mutation("create_ticket", {title: $title, priority: $priority})A Mutation does not run when the page loads. It runs only when an action runs it with @Run:
submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title)]))This button runs three actions in order:
@Run(createResult)runs the mutation and creates the ticket.@Run(tickets)fetches the tickets query again, so the table refreshes.@Reset($title)clears the title field.
If the mutation fails, the actions after it do not run.
Error handling
Check result.status to show feedback. Assign each check to a statement and place it in the layout:
createError = createResult.status == "error" ? Callout("error", "Failed", createResult.error) : null
createDone = createResult.status == "success" ? Callout("success", "Created", "Ticket added.") : nullHow tools connect to the runtime
The Renderer takes a toolProvider prop that runs the tools. Pass a function map or an MCP client. The Renderer is a client component, so these functions run in the browser. Point them at your API routes:
// Function map
<Renderer
toolProvider={{
list_tickets: async () => fetch("/api/tickets").then((r) => r.json()),
}}
response={code}
library={library}
/>
// Or an MCP client
<Renderer toolProvider={mcpClient} response={code} library={library} />Complete example
A ticket tracker with a create form and a table.
Your app gives the renderer two tools. Each calls an API route on your server:
"use client";
import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui";
export function Tickets({ response }: { response: string }) {
return (
<Renderer
library={openuiLibrary}
response={response}
toolProvider={{
list_tickets: async () => fetch("/api/tickets").then((r) => r.json()),
create_ticket: async (args) =>
fetch("/api/tickets", { method: "POST", body: JSON.stringify(args) }).then((r) =>
r.json(),
),
}}
/>
);
}The model writes:
root = Stack([CardHeader("Tickets"), form, createError, tbl])
$title = ""
$priority = "medium"
tickets = Query("list_tickets", {}, {rows: []})
createResult = Mutation("create_ticket", {title: $title, priority: $priority})
form = Form("create", Buttons([submitBtn]), [titleField, priorityField])
titleField = FormControl("Title", Input("title", "Ticket title", "text", {required: true}, $title))
priorityField = FormControl("Priority", Select("priority", [SelectItem("low", "Low"), SelectItem("medium", "Medium"), SelectItem("high", "High")], null, null, $priority))
submitBtn = Button("Create", Action([@Run(createResult), @Run(tickets), @Reset($title, $priority)]), "primary")
createError = createResult.status == "error" ? Callout("error", "Could not create the ticket", createResult.error) : null
tbl = Table([Col("Title", tickets.rows.title), Col("Priority", tickets.rows.priority)])The user sees a form and a table with the current tickets. The user types a title, picks a priority, and clicks "Create". The renderer calls create_ticket, then list_tickets, and the new ticket appears in the table. The form clears. If create_ticket fails, an error callout appears above the table.
When to use it
Use queries and mutations when:
- The UI shows data that lives in your systems, such as tickets, orders, or metrics.
- The data changes after the response, and the UI should show the latest rows.
- The user creates, updates, or deletes records from the UI.
Do not use them when:
- The data is small and fixed when the model answers. The model can write the values into the program.
- The result needs the model to reason about it. Call the tool on your backend before the model answers, or use
@ToAssistant.