<OxyAppProvider> — the provider resolves
the app’s identity and shares a credentialed fetcher. Hooks fail loudly if called
outside it.
Reading data
useQuery
Run inline SQL against the project’s warehouse and get typed rows back.
SELECT / WITH only, capped at 10,000 rows.
paramsinterpolate into the SQL with the{{ params.X | sqlquote }}syntax — quoted safely on the client before the request is sent.enabled: falsedefers the request until required inputs (e.g. a user-picked filter) are available.- The query re-runs whenever
sqlor the enabledparamschange.
useSemanticQuery
Query the semantic model by name
instead of writing SQL. The server compiles it through airlayer and executes it
on the same connector path as useQuery, so the result shape matches.
truncated is true when the result hit the server row cap. Pass
{ debug: true } as the second argument to also get the compiled sql back
while developing.
Running agents
useAgentRun
Start an analytics agent run and stream its events over
SSE. Use this when you want to build your own chat or results UI.
state is needs_clarification, call ask() again to answer and resume.
useProcedureRun
Start a long-running automation, poll its progress,
and cancel it. Runs survive server restarts.
Rendering components
<OxyChat>
A drop-in chat UI over useAgentRun — the fastest way to embed conversational
analytics in your app.
<OxyAnswer>
Renders an agent answer: markdown plus SQL artifacts and a link back to the full
thread. Link URL schemes are allowlisted (it rejects javascript: and similar),
so it’s safe to render model output.
Errors
OxyApiError is the structured { message, code? } envelope the server returns.
Hook error values are normal Error objects you can render directly; check for
OxyApiError when you want to branch on code.
Metric-tree analyses
For programmatic access to the metric tree and anomaly inbox, the package root also exportsMetricTreeClient and
AnomaliesClient (plus their result types — ExplainResult,
SensitivityResult, OpportunityResult, Anomaly, and more). These call the
same endpoints the World Model graph uses, so you can build custom
root-cause and sensitivity views.
Next steps
Oxygen Functions
Run server-side handlers with
useFunctionThe semantic model
Define the measures
useSemanticQuery reads