Querying Data

Query and display data in your app UI

App UIs query data with the useData hook, which provides real-time updates as data changes in your workspace.

useData hook

import { useData, YStack, SizableText } from 'start/ui'

export default () => {
  const [data] = useData({
    kindFilter: 'customer',
    sortColumn: 'createdAt',
    sortDirection: 'desc',
    limit: 20,
  })

  return (
    <YStack p="$4" gap="$2">
      {data.map((item) => (
        <SizableText key={item.id}>{item.title}</SizableText>
      ))}
    </YStack>
  )
}

Pass a filter object to useData. All fields are optional — calling useData() with no arguments returns all data for the current server.

Filter params

Param	Type	Description
`kindFilter`	string	Filter by kind
`statusFilter`	string	Filter by status
`keyFilter`	string	Search keys (case-insensitive)
`appIdFilter`	string	Filter by app install
`channelId`	string	Filter by channel
`sortColumn`	string	Column to sort by
`sortDirection`	string	`'asc'` or `'desc'`
`limit`	number	Max results (may be capped)

Return value

The hook returns a [data, actions] tuple:

const [data, { mutate, delete: deleteRow }] = useData({
  kindFilter: 'order',
  limit: 50,
})

data — array of matching rows
mutate(row) — update a data row
delete(id) — delete a data row by id

Block queries

Blocks use string queries to fetch data. These follow the {app}-{metric} naming convention for keys and categories:

// stat block — query by exact key
<Currency query="stripe-mrr" label="MRR" />

// chart block — query series by category
<Chart
  query="category:stripe-daily-revenue type:series sort:oldest limit:30"

  chartType="line"
  label="Revenue"
  format="currency"
/>

// sparkline from aggregate row
<Chart />

// table block — query by app and category
<Table
  query="app:stripe category:recent-transactions sort:newest"
  columns="title status amount:currency"
  label="Recent Payments"
  limit={10}
/>

// list block — from an action result
<List from="/stripe payments" extract="data" label="Payments" />

DataTable

For a full-featured data browsing UI, use the DataTable component:

import { DataTable } from 'start/ui'

export default () => <DataTable />

DataTable provides multi-column sorting, filtering by key/value/kind/status, column visibility toggle, row selection with bulk operations, expanded row view, and JSON formatting.

Mini block useData

Mini blocks use a simpler version of useData that returns data for the current app install only, limited to 10 items, with no query parameters:

export default () => {
  const data = useData()
  return { text: String(data.length) }
}

Writing Data

Patterns