Metrics

Metrics display live counts from your data at the top of a space. They give your team instant visibility into key numbers (orders waiting to be picked, items low on stock, invoices pending payment) without running a query.

How metrics work

A metric executes a list action and displays the total count of matching records. The count updates each time the space loads, giving you a real-time snapshot of your data.

For example, if you have a listOrders action that returns all orders with status "pending", adding it as a metric shows you exactly how many pending orders exist right now.

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Orders to Pick │  │  Low Stock Items │  │  Open POs       │
│       12        │  │        7         │  │       3         │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Adding a metric

To add a metric to a space:

Enter edit mode by clicking Edit
Click Add metric in the metrics section at the top
Select a list action from the dropdown
Configure the display:
- Title — What to call this metric (e.g., "Orders to Pick")
- Description (optional) — Additional context, shown as a tooltip
Click Add

Only list actions are available as metric sources. Other action types don't return the count data metrics need.

If you're adding multiple metrics at once, toggle Add more to keep the dialog open after each addition.

Configuring metrics

Title

The title appears above the count. Choose something clear and concise that tells users what they're looking at:

Good titles	Why they work
Orders to Pick	Describes the workflow state
Low Stock Items	Clear about what's being counted
Pending Invoices	Actionable — implies something needs doing

If you don't set a title, Keel uses the pluralized model name (e.g., "Orders" for a listOrders action).

Description

The description appears as a tooltip when users hover over the info icon. Use it to provide context:

What criteria define this count?
What action should users take when the number is high (or low)?
Any caveats or notes about the data?

For example: "Orders placed more than 24 hours ago that haven't been picked yet."

Editing a metric

To change a metric's configuration:

Enter edit mode
Click the edit icon on the metric card
Update the title, description, or source action
Click Save

Removing a metric

Enter edit mode
Click the delete icon on the metric card
Confirm the deletion

Removing a metric doesn't affect the underlying action or data. It only removes the display from this space.

Metric refresh behaviour

Metrics refresh their counts when:

The space first loads
You navigate back to the space
The page is refreshed

Metrics don't automatically poll for updates while you're viewing the space. If you need to see the latest count, refresh the page.

Metrics are designed for at-a-glance awareness, not real-time monitoring. For time-sensitive workflows, consider using list actions directly to see the most current data.

Example: Warehouse operations dashboard

Here's how a warehouse team might configure metrics for their space:

Metric	Source action	Description
Orders to Pick	`listOrdersReadyToPick`	Orders that have been paid and are waiting in the pick queue
Items to Receive	`listPendingDeliveries`	Inbound shipments expected today
Low Stock Items	`listLowStockItems`	Products below reorder threshold
Backorders	`listBackorders`	Customer orders waiting on stock

With these metrics at the top of their space, the warehouse team can immediately see their workload when they start their day.

Example: Finance dashboard

A finance team's space might include:

Metric	Source action	Description
Unpaid Invoices	`listUnpaidInvoices`	Invoices sent but not yet paid
Overdue Payments	`listOverdueInvoices`	Invoices past their due date
Pending Approvals	`listPendingApprovals`	Expenses or POs awaiting approval

Creating effective metric actions

Metrics work best when the underlying list action is filtered to return exactly what you want to count. Consider creating dedicated list actions for metrics:

schema.keel

model Order {
  fields {
    reference Text
    status OrderStatus
    placedAt Timestamp
  }
 
  actions {
    // General-purpose list for browsing orders
    list listOrders(status?)
 
    // Specific list for the "Orders to Pick" metric
    list listOrdersReadyToPick() {
      @where(order.status == OrderStatus.ReadyToPick)
    }
  }
}

This approach keeps your metric counts precise and meaningful.

Limitations

List actions only — Metrics can only use list actions, not get, create, update, or delete actions
No input parameters — Metrics execute actions without user-provided inputs, using only default values defined in the action
Count only — Metrics display the total count; they don't show aggregations like sums or averages

External Links Copying Spaces