Functions API reference

The six analysis functions in their two forms, the rules for the global form's query, and the errors they throw. Options, semantics, return shapes and examples of each function live on its own page under /sdk/fn/; the option and result types are indexed on Type definitions.

Overview

The Functions API provides data analysis capabilities including aggregations, facets, suggestions, grouping, and pivot tables.

// Access via dcupl instance: { modelKey, options, query? }
dcupl.fn.facets({ modelKey: 'Product', options: { ... } });
dcupl.fn.aggregate({ modelKey: 'Product', options: { ... } });
dcupl.fn.suggest({ modelKey: 'Product', options: { ... } });
dcupl.fn.groupBy({ modelKey: 'Product', options: { ... } });
dcupl.fn.pivot({ modelKey: 'Product', options: { ... } });
dcupl.fn.metadata({ modelKey: 'Product' });

// Or via list catalog: pass the options directly; the list's current query applies
list.catalog.fn.facets({ ... });
list.catalog.fn.metadata();

The optional query of the global functions is a full query: { modelKey: 'Product', groupType: 'and', queries: [...] }. Set groupType explicitly ('and' to require every condition). Without it, the query is evaluated as 'and', the same as dcupl.query.execute() and lists.create({ query }).

dcupl.fn.* apply their query as the list's whole (root) query. For facets() this means plain conditions in it sit in no group keyed by their attribute and are never left out of the counts; for disjunctive counts, put the selection in a group keyed by the attribute ({ groupKey: 'category', groupType: 'or', queries: [...] }) or use a list. dcupl.fn.facets() declares its result as FilterItemEntry[], the same shape as DcuplFacet.

Errors

Call	Result
`dcupl.fn.*` with an unknown `modelKey`	throws `Model with key <modelKey> not found`
`suggest()` on an unknown attribute (not a dotted path)	throws `Attribute <attribute> does not exist`; a dotted path returns `[]`
`aggregate()`, `groupBy()` on an unknown attribute	throws `Attribute not found`
`facets()` on an unknown attribute	returns `[]`
`pivot()` without a `rows` or `columns` array, or with empty `values`	logs `Invalid pivot options` and returns `{ key: 'invalid_options' }`

Facet values of one attribute with their counts and result keys, for filter UIs. Options, disjunctive counting and examples: facets().

list.catalog.fn.facets(options: DcuplFacetOptions): DcuplFacet[]
dcupl.fn.facets({ modelKey, options: DcuplFacetOptions, query? }): FilterItemEntry[]

aggregate()

Sum, average, count, min, max, distinct values or custom groups of one attribute. Options, result and examples: aggregate().

list.catalog.fn.aggregate(options: AggregationOptions): Aggregation
dcupl.fn.aggregate({ modelKey, options: AggregationOptions, query? }): Aggregation

suggest()

Autocomplete suggestions for a search value on one attribute. Matching rules, options and examples: suggest().

list.catalog.fn.suggest(options: SuggestionOptions): Suggestion[]
dcupl.fn.suggest({ modelKey, options: SuggestionOptions, query? }): Suggestion[]

groupBy()

Groups items by an attribute value, with aggregates and items per group. Options, the group shape and examples: groupBy().

list.catalog.fn.groupBy(options: DcuplGroupByOptions): GroupByResponse
dcupl.fn.groupBy({ modelKey, options: DcuplGroupByOptions, query? }): GroupByResponse

pivot()

A pivot table over row and column dimensions with aggregated cells and totals. Options, the result tree and examples: pivot().

list.catalog.fn.pivot(options: PivotOptions): PivotResponse
dcupl.fn.pivot({ modelKey, options: PivotOptions, query? }): PivotResponse

metadata()

The size of a result, its applied query, the model's attributes and views. Result fields and examples: metadata().

list.catalog.fn.metadata(): ListMetadata
dcupl.fn.metadata({ modelKey, query? }): ListMetadata

Complete examples

Worked examples per function are on the /sdk/fn/ pages; a full faceted search UI is on Faceted search and autocomplete on Search autocomplete.