Catalog API

The Catalog API (list.catalog) provides powerful querying, filtering, and analytical functions for working with data in a list. It's the primary interface for retrieving and analyzing data.

Overview

Each list has its own catalog instance that maintains independent query state and provides access to:

Query operations: Apply, execute, and manage filters
Analytical functions: Facets, aggregations, pivot tables, grouping, suggestions
Data retrieval: Get items with projection and sorting

API Namespaces

catalog.query

Main query interface for filtering and retrieving data.

See: Query Operations

catalog.fn

Analytical functions for data analysis.

See: Analytical Functions

Legacy filter interface (deprecated, use catalog.query instead).

Query Operations

addCondition()

Adds query condition(s) to the catalog. Use this to filter data.

Signature:

addCondition(
  condition: DcuplQuery | DcuplQuery[],
  options?: { skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`condition`	`DcuplQuery \| DcuplQuery[]`	Yes	Query condition(s) to add
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Current query state

Examples:

Add single condition

list.catalog.query.addCondition({
  operator: 'eq',
  attribute: 'status',
  value: 'active',
});

Add multiple conditions

list.catalog.query.addCondition([
  { operator: 'eq', attribute: 'status', value: 'active' },
  { operator: 'gte', attribute: 'price', value: 100 },
]);

Add condition with query key for later removal

list.catalog.query.addCondition({
  operator: 'eq',
  attribute: 'category',
  value: { key: 'electronics' },
  queryKey: 'categoryFilter',
});

setCondition()

Replaces all existing conditions with new condition(s).

Signature:

setCondition(
  condition: DcuplQuery | DcuplQuery[],
  options?: { skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`condition`	`DcuplQuery \| DcuplQuery[]`	Yes	Query condition(s) to set
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Current query state

Examples:

Replace with single condition

list.catalog.query.setCondition({
  operator: 'eq',
  attribute: 'status',
  value: 'active',
});

Replace with multiple conditions

list.catalog.query.setCondition([
  { operator: 'eq', attribute: 'status', value: 'active' },
  { operator: 'gte', attribute: 'price', value: 100 },
]);

addGroup()

Adds a query group with multiple conditions combined by AND/OR logic.

Signature:

addGroup(
  group: DcuplQueryGroup,
  options?: { skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`group`	`DcuplQueryGroup`	Yes	Query group to add
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Current query state

Examples:

Add price range group (AND logic)

list.catalog.query.addGroup({
  groupKey: 'priceRange',
  groupType: 'and',
  queries: [
    { operator: 'gte', attribute: 'price', value: 50 },
    { operator: 'lte', attribute: 'price', value: 200 },
  ],
});

Add category group (OR logic)

list.catalog.query.addGroup({
  groupKey: 'categories',
  groupType: 'or',
  queries: [
    { operator: 'eq', attribute: 'category', value: { key: 'electronics' } },
    { operator: 'eq', attribute: 'category', value: { key: 'books' } },
  ],
});

items()

Executes the current query and returns matching items.

Signature:

items<T>(options?: DcuplListQueryOptions<T>): T[]

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplListQueryOptions`	No	Query execution options

Returns: T[] - Array of matching items

Examples:

Get all matching items

const items = list.catalog.query.items();

With pagination

const page = list.catalog.query.items({
  start: 0,
  count: 20,
});

With sorting

const sorted = list.catalog.query.items({
  sort: { price: 'desc', name: 'asc' },
});

With projection

const projected = list.catalog.query.items({
  projection: {
    name: true,
    price: true,
    category: true,
  },
});

Complete query execution

const results = list.catalog.query.items({
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
  start: 0,
  count: 20,
  sort: { price: 'desc' },
  projection: { name: true, price: true },
});

first()

Returns the first matching item.

Signature:

first<T>(options?: DcuplListQueryOptions<T>): T | undefined

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplListQueryOptions`	No	Query execution options

Returns: T | undefined - First matching item or undefined

Examples:

Get first item

const item = list.catalog.query.first();

First matching condition

const activeItem = list.catalog.query.first({
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
});

count()

Returns the count of matching items.

Signature:

count<T>(options?: DcuplListQueryOptions<T>): number

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplListQueryOptions`	No	Query execution options

Returns: number - Count of matching items

Examples:

Count all items

const total = list.catalog.query.count();

Count matching condition

const activeCount = list.catalog.query.count({
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
});

any()

Checks if any results exist.

Signature:

any<T>(options?: DcuplListQueryOptions<T>): boolean

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplListQueryOptions`	No	Query execution options

Returns: boolean - True if any results exist

Examples:

Check if any items exist

if (list.catalog.query.any()) {
  console.log('Items found');
}

Check for specific condition

const hasActive = list.catalog.query.any({
  queries: [{ operator: 'eq', attribute: 'status', value: 'active' }],
});

removeCondition()

Removes specific query condition(s).

Signature:

removeCondition(
  condition: DcuplQuery | DcuplQuery[],
  options?: { skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`condition`	`DcuplQuery \| DcuplQuery[]`	Yes	Condition(s) to remove
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Updated query state

Examples:

Remove by query key

list.catalog.query.removeCondition({
  queryKey: 'statusFilter',
});

Remove by attribute

list.catalog.query.removeCondition({
  attribute: 'status',
});

Remove multiple

list.catalog.query.removeCondition([{ attribute: 'status' }, { attribute: 'category' }]);

removeGroup()

Removes a query group by its key.

Signature:

removeGroup(
  groupKey: string,
  options?: { skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`groupKey`	`string`	Yes	Key of the group to remove
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Updated query state

Examples:

Remove price range group

list.catalog.query.removeGroup('priceRange');

clear()

Clears all query conditions.

Signature:

clear(options?: { skipProcessing?: boolean }): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Empty query state

Examples:

Clear all filters

list.catalog.query.clear();

Clear without processing

list.catalog.query.clear({ skipProcessing: true });

Clear and get all items

list.catalog.query.clear();
const allItems = list.catalog.query.items();

current()

Returns the current query state.

Signature:

current(): DcuplGlobalQueryOptions

Returns: DcuplGlobalQueryOptions - Current query configuration

Examples:

Get current query

const query = list.catalog.query.current();
console.log(query.queries);
console.log(query.groupType);

Save query state

const savedQuery = list.catalog.query.current();

Restore query state later

list.catalog.query.setCondition(savedQuery.queries);

isEmpty()

Checks if the query has any conditions.

Signature:

isEmpty(): boolean

Returns: boolean - True if no conditions are applied

Examples:

if (list.catalog.query.isEmpty()) {
  console.log('No filters applied');
}

has()

Checks if a specific query or group exists.

Signature:

has(options: { groupKey: string; queryKey?: string }): boolean

Parameters:

Parameter	Type	Required	Description
`options.groupKey`	`string`	Yes	Group key to check
`options.queryKey`	`string`	No	Optional query key within group

Returns: boolean - True if exists

Examples:

Check if group exists

if (list.catalog.query.has({ groupKey: 'priceRange' })) {
  console.log('Price range filter is active');
}

Check if specific query exists

if (
  list.catalog.query.has({
    groupKey: 'filters',
    queryKey: 'status',
  })
) {
  console.log('Status filter is active');
}

applyOptions()

Applies item options (pagination, sorting, projection) to the query state. This method sets or updates the non-filter options that affect how results are retrieved.

Signature:

applyOptions(
  itemOptions: DcuplItemsOptions,
  options?: { mode?: 'set' | 'update'; skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`itemOptions`	`DcuplItemsOptions`	Yes	Item options including start, count, projection, and sort
`options.mode`	`'set' \| 'update'`	No	`'set'` replaces all options, `'update'` merges with existing (default: `'set'`)
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

DcuplItemsOptions:

Property	Type	Description
`start`	`number`	Starting index for pagination
`count`	`number`	Number of items to return
`projection`	`Projection`	Fields to include in results
`sort`	`SortingProjection`	Sorting configuration

Returns: DcuplGlobalQueryOptions - Updated query state

Examples:

Set pagination

list.catalog.query.applyOptions({
  start: 0,
  count: 20,
});

Set sorting

list.catalog.query.applyOptions({
  sort: { price: 'desc', name: 'asc' },
});

Set projection

list.catalog.query.applyOptions({
  projection: {
    name: true,
    price: true,
    category: true,
  },
});

Complete options

list.catalog.query.applyOptions({
  start: 0,
  count: 20,
  sort: { price: 'desc' },
  projection: { name: true, price: true, category: true },
});

Update existing options (merge)

// First set initial options
list.catalog.query.applyOptions({
  start: 0,
  count: 20,
});

// Later, update only the sorting (keeps start and count)
list.catalog.query.applyOptions(
  { sort: { price: 'desc' } },
  { mode: 'update' }
);

Replace all options

// Set new options, clearing any previously set options
list.catalog.query.applyOptions(
  { count: 50 },
  { mode: 'set' }
);

Batch operations with skipProcessing

// Apply multiple changes without intermediate processing
list.catalog.query.addCondition(
  { operator: 'eq', attribute: 'status', value: 'active' },
  { skipProcessing: true }
);
list.catalog.query.applyOptions({
  start: 0,
  count: 20,
  sort: { createdAt: 'desc' },
});
// Processing happens on the final call

one()

Returns a single item by key.

Signature:

one<T>(options: DcuplItemOptions<T>): T | undefined

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplItemOptions`	Yes	Item retrieval options

Returns: T | undefined - The item or undefined if not found

Examples:

Get item by key

const item = list.catalog.query.one({ itemKey: 'p1' });

With projection

const item = list.catalog.query.one({
  itemKey: 'p1',
  projection: { name: true, price: true },
});

many()

Returns multiple specific items by keys.

Signature:

many<T>(options: DcuplManyItemsOptions<T>): T[]

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplManyItemsOptions`	Yes	Items retrieval options

Returns: T[] - Array of items

Examples:

Get specific items

const items = list.catalog.query.many({
  itemKeys: ['p1', 'p2', 'p3'],
});

With projection

const items = list.catalog.query.many({
  itemKeys: ['p1', 'p2', 'p3'],
  projection: { name: true, price: true },
});

Core Query Methods

These are the foundational query methods. The semantic aliases (like addCondition, clear, items) provide a more intuitive API built on top of these core methods.

apply()

Applies query condition(s) to the catalog. This is the core method that addCondition(), setCondition(), and addGroup() are built on.

Signature:

apply(
  query: DcuplQueryGroup | DcuplQuery | DcuplQuery[] | DcuplQueryGroup[],
  options?: { mode?: 'set' | 'add'; skipProcessing?: boolean }
): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`query`	`DcuplQueryGroup \| DcuplQuery \| DcuplQuery[] \| DcuplQueryGroup[]`	Yes	Query condition(s) or group(s) to apply
`options.mode`	`'set' \| 'add'`	No	`'set'` replaces existing queries, `'add'` appends (default: `'set'`)
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Updated query state

Examples:

Add a condition

list.catalog.query.apply(
  { operator: 'eq', attribute: 'status', value: 'active' },
  { mode: 'add' }
);

Replace all conditions

list.catalog.query.apply(
  { operator: 'eq', attribute: 'status', value: 'active' },
  { mode: 'set' }
);

Apply multiple conditions

list.catalog.query.apply([
  { operator: 'eq', attribute: 'status', value: 'active' },
  { operator: 'gte', attribute: 'price', value: 100 },
], { mode: 'add' });

Apply a query group

list.catalog.query.apply({
  groupKey: 'priceRange',
  groupType: 'and',
  queries: [
    { operator: 'gte', attribute: 'price', value: 50 },
    { operator: 'lte', attribute: 'price', value: 200 },
  ],
}, { mode: 'add' });

remove()

Removes query condition(s) or groups from the catalog. This is the core method that removeCondition() and removeGroup() are built on.

Signature:

remove(options?: Partial<DcuplQueryGroup> | DcuplQuery): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`options`	`Partial \| DcuplQuery`	No	Condition or group to remove. If omitted, removes all.

Returns: DcuplGlobalQueryOptions - Updated query state

Examples:

Remove by query key

list.catalog.query.remove({ queryKey: 'statusFilter' });

Remove by attribute

list.catalog.query.remove({ attribute: 'status' });

Remove by group key

list.catalog.query.remove({ groupKey: 'priceRange' });

Remove all conditions

list.catalog.query.remove();

reset()

Resets the query to its initial empty state. This is the core method that clear() wraps.

Signature:

reset(options?: { skipProcessing?: boolean }): DcuplGlobalQueryOptions

Parameters:

Parameter	Type	Required	Description
`options.skipProcessing`	`boolean`	No	Skip immediate query processing

Returns: DcuplGlobalQueryOptions - Empty query state

Examples:

Reset query

list.catalog.query.reset();

Reset without processing

list.catalog.query.reset({ skipProcessing: true });

execute()

Executes the current query and returns matching items. This is the core method that items() wraps.

Signature:

execute<T>(options?: DcuplListQueryOptions<T>): T[]

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplListQueryOptions`	No	Query execution options

Returns: T[] - Array of matching items

Examples:

Execute current query

const items = list.catalog.query.execute();

Execute with options

const items = list.catalog.query.execute({
  start: 0,
  count: 20,
  sort: { price: 'desc' },
});

Execute with additional conditions

const items = list.catalog.query.execute({
  queries: [{ operator: 'eq', attribute: 'featured', value: true }],
  count: 10,
});

get()

Returns the current query state. This is the core method that current() wraps.

Signature:

get(): DcuplGlobalQueryOptions

Returns: DcuplGlobalQueryOptions - Current query configuration

Examples:

Get current query

const query = list.catalog.query.get();
console.log(query.queries);

Save and restore query state

const savedQuery = list.catalog.query.get();
// ... make changes ...
list.catalog.query.apply(savedQuery.queries, { mode: 'set' });

Analytical Functions

Computes facet values for an attribute (filter options with counts).

Signature:

facets(options: DcuplFacetOptions): DcuplFacet[]

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplFacetOptions`	Yes	Facet computation options

Returns: DcuplFacet[] - Array of facet entries

Examples:

Basic facets

const categories = list.catalog.fn.facets({
  attribute: 'category',
});

With count limit

const topCategories = list.catalog.fn.facets({
  attribute: 'category',
  count: 10,
});

Without zero counts

const activeFacets = list.catalog.fn.facets({
  attribute: 'category',
  excludeZeros: true,
});

With results calculation

const facets = list.catalog.fn.facets({
  attribute: 'category',
  calculateResults: true,
});

Deep query facets

const manufacturerFacets = list.catalog.fn.facets({
  attribute: 'category.manufacturer',
});

aggregate()

Performs aggregation operations on an attribute.

Signature:

aggregate(options: AggregationOptions): Aggregation

Parameters:

Parameter	Type	Required	Description
`options`	`AggregationOptions`	Yes	Aggregation configuration

Returns: Aggregation - Aggregation results

Examples:

Multiple aggregation types

const stats = list.catalog.fn.aggregate({
  attribute: 'price',
  types: ['sum', 'avg', 'min', 'max', 'count'],
});
console.log(stats.sum, stats.avg, stats.min, stats.max, stats.count);

Count aggregation

const itemCount = list.catalog.fn.aggregate({
  attribute: 'key',
  types: ['count'],
});

Distinct values

const distinctCategories = list.catalog.fn.aggregate({
  attribute: 'category',
  types: ['distinct'],
  distinctOptions: {
    limit: 20,
    skipKeys: false,
  },
});

Grouped aggregation

const priceGroups = list.catalog.fn.aggregate({
  attribute: 'price',
  types: ['group'],
  groupOptions: {
    groups: [
      { from: 0, to: 50 },
      { from: 50, to: 100 },
      { from: 100, to: 200 },
    ],
    calculateNotFound: true,
  },
});

With exclusions

const cleanStats = list.catalog.fn.aggregate({
  attribute: 'price',
  types: ['sum', 'avg'],
  excludeZeros: true,
  excludeUndefineds: true,
});

suggest()

Provides autocomplete suggestions for an attribute.

Signature:

suggest(options: SuggestionOptions): Suggestion[]

Parameters:

Parameter	Type	Required	Description
`options`	`SuggestionOptions`	Yes	Suggestion configuration

Returns: Suggestion[] - Array of suggestions

Examples:

Basic suggestions

const suggestions = list.catalog.fn.suggest({
  attribute: 'name',
  value: 'prod',
});

With max results

const topSuggestions = list.catalog.fn.suggest({
  attribute: 'name',
  value: 'prod',
  max: 10,
});

Case-insensitive

const suggestions = list.catalog.fn.suggest({
  attribute: 'name',
  value: 'prod',
  transform: ['lowercase'],
});

Without result keys

const quickSuggestions = list.catalog.fn.suggest({
  attribute: 'name',
  value: 'prod',
  calculateResultKeys: false,
});

From all data (not just filtered)

const allSuggestions = list.catalog.fn.suggest({
  attribute: 'name',
  value: 'prod',
  relevantData: 'all',
});

Exclude current query

const otherSuggestions = list.catalog.fn.suggest({
  attribute: 'category',
  value: 'elect',
  relevantData: 'excludeQuery',
  excludeQuery: { attribute: 'category' },
});

groupBy()

Groups items by an attribute value.

Signature:

groupBy(options: DcuplGroupByOptions): GroupByResponse

Parameters:

Parameter	Type	Required	Description
`options`	`DcuplGroupByOptions`	Yes	Grouping configuration

Returns: GroupByResponse - Grouped items

Examples:

Basic grouping

const grouped = list.catalog.fn.groupBy({
  primaryAttribute: 'category',
});

With aggregations

const groupedWithStats = list.catalog.fn.groupBy({
  primaryAttribute: 'category',
  aggregates: [{ attribute: 'price', types: ['sum', 'avg'] }],
});

With sorting

const sortedGroups = list.catalog.fn.groupBy({
  primaryAttribute: 'category',
  sort: { count: 'desc' },
});

Nested grouping (via model references)

const nestedGroups = list.catalog.fn.groupBy({
  primaryAttribute: 'category.parent',
});

pivot()

Creates a pivot table from the data.

Signature:

pivot(options: PivotOptions): PivotResponse

Parameters:

Parameter	Type	Required	Description
`options`	`PivotOptions`	Yes	Pivot table configuration

Returns: PivotResponse - Pivot table structure

Examples:

Basic pivot

const pivot = list.catalog.fn.pivot({
  rows: [{ attribute: 'category' }],
  columns: [{ attribute: 'status' }],
  values: [{ attribute: 'price', types: ['sum'] }],
});

Multi-dimensional pivot

const complexPivot = list.catalog.fn.pivot({
  rows: [{ attribute: 'category' }, { attribute: 'manufacturer' }],
  columns: [{ attribute: 'status' }, { attribute: 'featured' }],
  values: [
    { attribute: 'price', types: ['sum', 'avg'] },
    { attribute: 'quantity', types: ['sum'] },
  ],
});

Deep query pivot

const deepPivot = list.catalog.fn.pivot({
  rows: [{ attribute: 'category.parent' }],
  columns: [{ attribute: 'manufacturer.country' }],
  values: [{ attribute: 'price', types: ['sum'] }],
});

metadata()

Returns metadata about the list and its data.

Signature:

metadata(): ListMetadata

Returns: ListMetadata - List metadata

Examples:

const meta = list.catalog.fn.metadata();
console.log(meta.key); // Model key
console.log(meta.currentSize); // Filtered item count
console.log(meta.initialSize); // Total item count
console.log(meta.attributes); // Model attributes
console.log(meta.views); // Available views
console.log(meta.appliedQuery); // Current query

Type Definitions

DcuplQuery

Single query condition.

Type Definition:

type DcuplQuery = {
  operator: DcuplQueryOperator;
  attribute: string;
  value: any;
  queryKey?: any;
  options?: {
    transform?: DcuplQueryTransformOptions[];
    invert?: boolean;
    arrayValueHandling?: 'some' | 'every';
  };
};

Operators:

Operator	Description	Value Type
`'eq'`	Equals	`any`
`'find'`	Contains/Search	`string \| object`
`'gt'`	Greater than	`number \| Date \| string`
`'gte'`	Greater than or equal	`number \| Date \| string`
`'lt'`	Less than	`number \| Date \| string`
`'lte'`	Less than or equal	`number \| Date \| string`
`'typeof'`	Type check	`string`
`'isTruthy'`	Truthiness check	`boolean`
`'size'`	Array/string length	`number`

Examples:

Equality

{ operator: 'eq', attribute: 'status', value: 'active' }

Text search

{ operator: 'find', attribute: 'name', value: 'search term' }

Numeric comparison

{ operator: 'gte', attribute: 'price', value: 100 }
{ operator: 'lt', attribute: 'quantity', value: 10 }

Type check

{ operator: 'typeof', attribute: 'data', value: 'object' }

Truthiness

{ operator: 'isTruthy', attribute: 'featured', value: true }

Array size

{ operator: 'size', attribute: 'tags', value: 3 }

With options

{
  operator: 'eq',
  attribute: 'name',
  value: 'john',
  options: { transform: ['lowercase'] }
}

Array handling

{
  operator: 'eq',
  attribute: 'tags',
  value: 'featured',
  options: { arrayValueHandling: 'some' }
}

Inverted condition

{
  operator: 'eq',
  attribute: 'status',
  value: 'active',
  options: { invert: true }
}

DcuplQueryGroup

Group of query conditions with combination logic.

Type Definition:

type DcuplQueryGroup = {
  groupType?: 'and' | 'or';
  groupKey?: string;
  queries: Array<DcuplQuery | DcuplQueryGroup>;
};

Examples:

AND group

{
  groupType: 'and',
  groupKey: 'activeProducts',
  queries: [
    { operator: 'eq', attribute: 'status', value: 'active' },
    { operator: 'gte', attribute: 'price', value: 100 }
  ]
}

OR group

{
  groupType: 'or',
  queries: [
    { operator: 'eq', attribute: 'category', value: { key: 'cat1' } },
    { operator: 'eq', attribute: 'category', value: { key: 'cat2' } }
  ]
}

Nested groups

{
  groupType: 'and',
  queries: [
    { operator: 'eq', attribute: 'status', value: 'active' },
    {
      groupType: 'or',
      queries: [
        { operator: 'eq', attribute: 'featured', value: true },
        { operator: 'gte', attribute: 'rating', value: 4.5 }
      ]
    }
  ]
}

DcuplListQueryOptions

Query execution options.

Type Definition:

type DcuplListQueryOptions<T> = {
  queries?: Array<DcuplQuery | DcuplQueryGroup>;
  groupType?: 'and' | 'or';
  start?: number;
  count?: number;
  projection?: Projection<T>;
  sort?: SortingProjection<T>;
};

Examples:

Pagination

{
  start: 0,
  count: 20
}

Sorting

{
  sort: { price: 'desc', name: 'asc' }
}

Projection

{
  projection: {
    name: true,
    price: true,
    category: true
  }
}

Complete options

{
  queries: [
    { operator: 'eq', attribute: 'status', value: 'active' }
  ],
  groupType: 'and',
  start: 0,
  count: 20,
  sort: { price: 'desc' },
  projection: { name: true, price: true }
}

DcuplFacetOptions

Facet computation options.

Type Definition:

type DcuplFacetOptions = {
  attribute: string;
  count?: number;
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;
  calculateResults?: boolean;
};

Examples:

Basic

{
  attribute: 'category';
}

With options

{
  attribute: 'category',
  count: 10,
  excludeZeros: true,
  excludeUndefineds: true,
  calculateResults: true
}

AggregationOptions

Aggregation configuration.

Type Definition:

type AggregationOptions = {
  attribute: string;
  types: AggregationType[];
  distinctOptions?: {
    limit?: number;
    skipKeys?: boolean;
  };
  groupOptions?: {
    limit?: number;
    calculateNotFound?: boolean;
    groups?: AggregationGroupOption[];
  };
  excludeZeros?: boolean;
  excludeUndefineds?: boolean;
  excludeUnresolved?: boolean;
};

type AggregationType = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct' | 'group';

Examples:

Multiple types

{
  attribute: 'price',
  types: ['sum', 'avg', 'min', 'max']
}

Distinct values

{
  attribute: 'category',
  types: ['distinct'],
  distinctOptions: { limit: 20 }
}

Grouped aggregation

{
  attribute: 'price',
  types: ['group'],
  groupOptions: {
    groups: [
      { from: 0, to: 50 },
      { from: 50, to: 100 }
    ]
  }
}

SuggestionOptions

Autocomplete suggestion options.

Type Definition:

type SuggestionOptions = {
  attribute: string;
  value: any;
  max?: number;
  calculateResultKeys?: boolean;
  excludeUndefineds?: boolean;
  excludeNulls?: boolean;
  transform?: DcuplQueryTransformOptions[];
  relevantData?: 'filtered' | 'all' | 'excludeQuery';
  excludeQuery?: Partial<DcuplQuery | DcuplQueryGroup>;
};

Examples:

Basic

{
  attribute: 'name',
  value: 'prod'
}

Advanced

{
  attribute: 'name',
  value: 'prod',
  max: 10,
  transform: ['lowercase'],
  relevantData: 'all'
}

PivotOptions

Pivot table configuration.

Type Definition:

type PivotOptions = {
  rows: Array<{ attribute: string }>;
  columns: Array<{ attribute: string }>;
  values: Array<{
    attribute: string;
    types: AggregationType[];
  }>;
};

Examples:

{
  rows: [{ attribute: 'category' }],
  columns: [{ attribute: 'status' }],
  values: [{ attribute: 'price', types: ['sum', 'avg'] }]
}

Complete Examples

const productList = dcupl.lists.create({ modelKey: 'Product' });

// Add search query
productList.catalog.query.addCondition({
  operator: 'find',
  attribute: 'name',
  value: searchTerm,
  options: { transform: ['lowercase'] },
});

// Get facets for filters
const categories = productList.catalog.fn.facets({
  attribute: 'category',
  excludeZeros: true,
});

const manufacturers = productList.catalog.fn.facets({
  attribute: 'manufacturer',
  excludeZeros: true,
});

// Add category filter
productList.catalog.query.addCondition({
  operator: 'eq',
  attribute: 'category',
  value: { key: selectedCategory },
  queryKey: 'categoryFilter',
});

// Get results
const results = productList.catalog.query.items({
  start: 0,
  count: 20,
  sort: { relevance: 'desc', name: 'asc' },
});

Price Range Filter

// Add price range as group
productList.catalog.query.addGroup({
  groupKey: 'priceRange',
  groupType: 'and',
  queries: [
    { operator: 'gte', attribute: 'price', value: minPrice },
    { operator: 'lte', attribute: 'price', value: maxPrice },
  ],
});

// Update range
productList.catalog.query.removeGroup('priceRange');
productList.catalog.query.addGroup({
  groupKey: 'priceRange',
  groupType: 'and',
  queries: [
    { operator: 'gte', attribute: 'price', value: newMinPrice },
    { operator: 'lte', attribute: 'price', value: newMaxPrice },
  ],
});

// Clear range
productList.catalog.query.removeGroup('priceRange');

Statistics Dashboard

// Get overall statistics
const stats = productList.catalog.fn.aggregate({
  attribute: 'price',
  types: ['sum', 'avg', 'min', 'max', 'count'],
});

// Group by category
const categoryStats = productList.catalog.fn.groupBy({
  primaryAttribute: 'category',
  aggregates: [
    { attribute: 'price', types: ['sum', 'avg'] },
    { attribute: 'quantity', types: ['sum'] },
  ],
});

// Pivot by category and status
const pivot = productList.catalog.fn.pivot({
  rows: [{ attribute: 'category' }],
  columns: [{ attribute: 'status' }],
  values: [
    { attribute: 'price', types: ['sum'] },
    { attribute: 'quantity', types: ['count'] },
  ],
});

Autocomplete Search

function autocomplete(query: string) {
  const suggestions = productList.catalog.fn.suggest({
    attribute: 'name',
    value: query,
    max: 10,
    transform: ['lowercase'],
    relevantData: 'all',
  });

  return suggestions.map((s) => ({
    label: s.value,
    count: s.keys.length,
  }));
}

Catalog API

Overview

API Namespaces

catalog.query

catalog.fn

catalog.filters

Query Operations

addCondition()

setCondition()

addGroup()

items()

first()

count()

any()

removeCondition()

removeGroup()

clear()

current()

isEmpty()

has()

applyOptions()

one()

many()

Core Query Methods

apply()

remove()

reset()

execute()

get()

Analytical Functions

facets()

aggregate()

suggest()

groupBy()

pivot()

metadata()

Type Definitions

DcuplQuery

DcuplQueryGroup

DcuplListQueryOptions

DcuplFacetOptions

AggregationOptions

SuggestionOptions

PivotOptions

Complete Examples

Product Search with Facets

Price Range Filter

Statistics Dashboard

Autocomplete Search

See Also