@overscore/client

React hooks for Overscore dashboards. One useQuery() hook: load once into DuckDB-WASM, query many.

Your dashboard's queries are registered server-side and run against your warehouse. This package fetches the results as Arrow, loads them into DuckDB in the browser, and lets you filter, join and aggregate them locally — so a dropdown change is a millisecond, not a round trip.

Install

npm install @overscore/client

Use

Wrap your app once:

import { OverscoreProvider } from "@overscore/client";

<OverscoreProvider
  projectSlug={import.meta.env.VITE_OVERSCORE_PROJECT_SLUG}
  dashboardSlug={import.meta.env.VITE_OVERSCORE_DASHBOARD_SLUG}
>
  <App />
</OverscoreProvider>

Then read a registered query by name:

import { useQuery } from "@overscore/client";

const { data, loading, error } = useQuery("revenue_by_month");

Querying locally

Pass SQL as a second argument and it runs in DuckDB against the loaded result, not your warehouse:

const { data } = useQuery(
  "revenue_by_month",
  `SELECT month, SUM(total_revenue) AS revenue
   FROM revenue_by_month
   WHERE month >= '2026-01'
   GROUP BY month
   ORDER BY month`
);

Join across several registered queries by passing an array. This is the reason the local engine exists — combining two results in JavaScript means looping over both raw datasets, which is how a metric ends up computed somewhere nobody can read or audit:

const { data } = useQuery(
  ["revenue_by_month", "targets_by_month"],
  `SELECT r.month, r.revenue, t.target
   FROM revenue_by_month r
   JOIN targets_by_month t USING (month)`
);

Re-run on dependency change by passing a third argument, the same way you would with useEffect:

const { data } = useQuery("orders", `SELECT * FROM orders WHERE region = '${escapeSql(region)}'`, [region]);

Also exported

| Export | Purpose | |---|---| | usePreload, useLoadingProgress | warm queries at mount, report load progress | | useOverscore, useRefreshAll | provider context, force a refresh of every query | | useCsvExport | CSV export with a row cap | | toCsv, downloadTextFile, safeFilename | export primitives | | escapeSql | escape a value before interpolating it into local SQL |

Docs

• useQuery hook
• Core concepts
• Data caching
• overscore.dev

License

Proprietary. Part of the Overscore platform.