Skip to main content
API contract 3.4
Premium

useAggregate

Premium

useAggregate and useGetAggregateSchema ship in habarico-enterprise — they call the /aggregate and /aggregate/schema endpoints, which only a paid backend serves. Install it and import from there; the free package no longer exports either hook.

Runs an aggregation over a resource — a count, sum or average, optionally grouped — through the resource's /aggregate endpoint.

The dashboard's chart widgets are built on it. Use it directly for a KPI tile or a chart of your own, instead of loading records and summing them in the browser.

Signature​

import {useAggregate} from 'habarico-enterprise';

const {data, isLoading, error, isUnsupported} = useAggregate({
  resource: 'eshop/order',
  function: 'sum',
  field: 'total_amount',
  groupBy: [{field: 'status'}],
});

Parameters​

NameTypeDefaultDescription
resource (required)string—Resource in "service/resource" form
function (required)AggregateFunctionType—count, sum, avg, min, max — the backend whitelists them per field (Python, Ruby)
fieldstring—Field to aggregate; required for every function except count
groupByGroupByItem[]—Fields to bucket by ({field, bucket?}); without it the result is a single bucket
filterFiltersConfiguration—Filters applied before aggregating
enabledbooleantrueSet to false to hold the query back until its inputs are ready

Returns​

NameTypeDescription
dataAggregateBucket[] | undefinedOne {group?, value} bucket per group, or a single bucket when groupBy is empty
isLoadingbooleanThe query is in flight
errorunknownThe failure, if any
isUnsupportedbooleanAggregation is not available — see below

isUnsupported is what lets a widget say "this resource cannot be aggregated" instead of showing a generic error. It is true in two cases: the backend answered 404, which is what it returns when aggregate_enabled is off for the resource; or the application is wired with the free data provider, which has no aggregate method at all. A missing method means the feature is unavailable, not that something broke — pass dataProviderFactory={getEnterpriseDataProviderFactory} to SchemaAdmin, or render EnterpriseSchemaAdmin, which does it for you.

Behaviour​

  • The query does not fire until an identity is known, and its cache key includes the user id — a different account never reuses another's results.
  • With a function other than count, the query waits for a field rather than firing an incomplete request.
  • Failures are not retried; an aggregation that the backend rejects would fail again the same way.

useGetAggregateSchema​

The companion hook fetches what a resource may be aggregated by — which fields, with which functions — so a configuration UI can offer only valid combinations.

const {schema, isLoading, isError} = useGetAggregateSchema({resource: 'eshop/order'});

It returns {schema, isLoading, error, isError, isUnsupported}, where schema is an AggregateSchema. The query is keyed by locale and identity, so switching language refetches the translated labels. It reads getAggregateSchema off the schema provider in context; with the free provider wired the method is absent, so the query never runs, schema stays undefined and isUnsupported is true. Pass schemaProviderFactory={getEnterpriseSchemaProvider} to SchemaAdmin, or render EnterpriseSchemaAdmin.

See also​