.md

Range queries

Filter by numeric ranges and date comparisons using gt, gte, lt, lte operators. Use setGroup with "and" type to combine range conditions. Perfect for price filters, date ranges, stock thresholds, and rating cutoffs.

Syntax

list.catalog.query.setGroup({
  groupKey: string,
  groupType: 'and',
  queries: [
    { attribute: string, operator: 'gte', value: number | Date },
    { attribute: string, operator: 'lte', value: number | Date }
  ]
})

Parameters

groupKeystringOptional
Set it so you can replace or remove the range later. Without it, setGroup() replaces the first group without a key
groupType'and' | 'or'Optional
Set it to "and" so all conditions must match (range behavior), on every setGroup(): a group without groupType is stored as "or", also when it replaces an existing range
queriesCondition[]Required
Array of conditions with attribute, operator (gt/gte/lt/lte), and value

Return type

setGroup() returns the updated query (DcuplGlobalQueryOptions); call items() for the matching items:

// list.catalog.query
setGroup(group: DcuplQueryGroup): DcuplGlobalQueryOptions<any>; // the list's query
items(options?: DcuplListQueryOptions<T>): T[];

Usage notes

  • gt: value > bound, gte: value >= bound, lt: value < bound, lte: value <= bound
  • gte + lte is an inclusive range [50, 200], gt + lt an exclusive one (50, 200), gte + lt a half-open one [50, 200)
  • Use setGroup with groupType "and" to combine gte + lte for ranges
  • Two addCondition() calls on the same attribute are combined with OR, so they do not form a range
  • groupKey allows you to update or remove the range filter later
  • Works with numbers, dates, and strings (strings compare by character code, so case-sensitively)
  • For date properties, pass a Date object (or a timestamp); an ISO string value does not match
  • Use gt (exclusive) when you want to exclude the boundary
  • Use gte (inclusive) when you want to include the boundary

Related methods

  • catalog.query.setGroup() — Create grouped conditions with AND/OR logic
  • catalog.fn.aggregate() — Get min/max values for range bounds

Related guides/docs

Examples

Minimum price filter

Find products priced above a threshold using greater-than.

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

// gt = exclusive (>), does NOT include the threshold value
productList.catalog.query.addCondition({
  attribute: 'price',
  operator: 'gt',
  value: 100,
});

// Matches: 100.01, 150, 500
// No match: 100 (exclusive)
const results = productList.catalog.query.items();
Maximum price filter

Find products under a price limit using less-than-or-equal.

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

// lte = inclusive (<=), includes the threshold value
productList.catalog.query.addCondition({
  attribute: 'price',
  operator: 'lte',
  value: 50,
});

// Matches: 50, 49.99, 25, 0
const affordableProducts = productList.catalog.query.items();
Price range (inclusive)

Find products between $50 and $200 (inclusive on both ends).

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

// Use setGroup with "and" type for inclusive range
productList.catalog.query.setGroup({
  groupKey: 'price-range',
  groupType: 'and',
  queries: [
    { attribute: 'price', operator: 'gte', value: 50 },
    { attribute: 'price', operator: 'lte', value: 200 },
  ],
});

// Matches: 50, 75, 100, 150, 200
const results = productList.catalog.query.items();
Price range (exclusive)

Find products between $50 and $200 (exclusive on both ends).

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

// Use setGroup with "and" type for exclusive range
productList.catalog.query.setGroup({
  groupKey: 'price-range',
  groupType: 'and',
  queries: [
    { attribute: 'price', operator: 'gt', value: 50 },
    { attribute: 'price', operator: 'lt', value: 200 },
  ],
});

// Matches: 50.01, 75, 100, 199.99
// No match: 50, 200
const results = productList.catalog.query.items();
Low stock alert

Find products with critically low inventory.

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

productList.catalog.query.addCondition({
  attribute: 'stock',
  operator: 'lt',
  value: 10,
});

// Also filter to active products only
productList.catalog.query.addCondition({
  attribute: 'status',
  operator: 'eq',
  value: 'active',
});

const lowStockProducts = productList.catalog.query.items();
console.log('Need to reorder:', lowStockProducts.length, 'products');
Date after (recent items)

Find orders placed on or after a specific date.

const orderList = dcupl.lists.create({ modelKey: 'Order' });

orderList.catalog.query.addCondition({
  attribute: 'orderDate',
  operator: 'gte',
  value: new Date('2025-01-01'),
});

const recentOrders = orderList.catalog.query.items();
Date range (last 30 days)

Find items created within the last 30 days.

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

const thirtyDaysAgo = new Date();
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

// Use setGroup with "and" type for date range
productList.catalog.query.setGroup({
  groupKey: 'date-range',
  groupType: 'and',
  queries: [
    { attribute: 'createdAt', operator: 'gte', value: thirtyDaysAgo },
    { attribute: 'createdAt', operator: 'lte', value: new Date() },
  ],
});

const newProducts = productList.catalog.query.items();
Rating threshold

Find products with 4+ stars rating.

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

productList.catalog.query.addCondition({
  attribute: 'rating',
  operator: 'gte',
  value: 4.0,
});

const topRatedProducts = productList.catalog.query.items();
Combine range with other filters

Find electronics between $100-$500 that are in stock.

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

// Use setGroup for price range
productList.catalog.query.setGroup({
  groupKey: 'price-range',
  groupType: 'and',
  queries: [
    { attribute: 'price', operator: 'gte', value: 100 },
    { attribute: 'price', operator: 'lte', value: 500 },
  ],
});

// Add other filters separately
productList.catalog.query.addCondition({
  attribute: 'category',
  operator: 'eq',
  value: 'Electronics',
});
productList.catalog.query.addCondition({
  attribute: 'inStock',
  operator: 'isTruthy',
  value: true,
});

const results = productList.catalog.query.items();
// Price range filter: $50 - $150
const list = dcupl.lists.create({ modelKey: 'Article' });

// Use setGroup with "and" type for range queries
list.catalog.query.setGroup({
  groupKey: 'price-range',
  groupType: 'and',
  queries: [
    { attribute: 'price', operator: 'gte', value: 50 },
    { attribute: 'price', operator: 'lte', value: 150 },
  ],
});

const results = list.catalog.query.items();
console.log('Products in range:', results.length);