# 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](/sdk/api/types#function-types).

---

## Overview

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

```typescript
// 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' }`     |

---

## facets()

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

```typescript
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()](/sdk/fn/aggregate).

```typescript
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()](/sdk/fn/suggest).

```typescript
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()](/sdk/fn/group-by).

```typescript
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()](/sdk/fn/pivot).

```typescript
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()](/sdk/fn/metadata).

```typescript
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](/sdk/advanced/faceted-search) and autocomplete on [Search autocomplete](/sdk/advanced/search-autocomplete).

---

## See also

- [Facets](/sdk/fn/facets) - Detailed facet guide
- [Aggregations](/sdk/fn/aggregate) - Aggregation patterns
- [Suggestions](/sdk/fn/suggest) - Autocomplete implementation
- [Pivot Tables](/sdk/fn/pivot) - Pivot table guide
- [Group By](/sdk/fn/group-by) - Grouping with per-group aggregates and items
- [Metadata](/sdk/fn/metadata) - Result counts and pagination info
- [Faceted Search Pattern](/sdk/advanced/faceted-search) - Complete example
- [Custom Operators](/sdk/api/query-operators#custom-operators) - `dcupl.query.registerCustomOperator()` and operator scripts