Query Methods & Operators

Access the query API through list.catalog.query:

• Every DcuplList has a catalog with a query object
• The query object manages conditions, groups, and options
• Changes to the query automatically update filtered results

The query API provides methods to add, set, remove, and execute queries.

addCondition() appends filter conditions to the query:

• Pass a single QueryCondition object
• Or pass an array of conditions
• Multiple calls combine with AND logic

Use addCondition when building queries incrementally, like adding filters one at a time based on user selections.

setCondition() replaces all existing conditions:

• Clears any previous conditions and groups
• Sets the new condition(s) as the only filter
• Useful when switching to a completely different filter

Use setCondition when you want to replace the entire query state, not add to it.

Use addGroup() and setGroup() for complex boolean logic:

• groupType: 'and' - All conditions must match
• groupType: 'or' - Any condition can match
• groupKey - Optional identifier for later removal

Groups can be nested for arbitrary boolean expressions like (A AND B) OR (C AND D).

Remove specific conditions or clear the entire query:

Method	Description
removeCondition()	Remove conditions by attribute name
removeGroup()	Remove a group by its groupKey
clear()	Remove all conditions and groups

applyOptions() configures pagination, sorting, and projection:

Option	Description
start	Skip N items (offset for pagination)
count	Limit results to N items
sort	Order by attribute(s), asc or desc
projection	Select specific properties to return

Retrieve query results with these methods:

Method	Returns	Use Case
items()	Array of matching items	Display lists, tables
first()	First matching item or undefined	Single item lookup
any()	Boolean: has any matches	Check existence
count()	Number of matches	Display total count

Inspect the current state of a query:

Method	Returns	Use Case
current()	QueryExecutionContext	Serialize, debug, or restore query
isEmpty()	Boolean	Check if query has conditions
has()	Boolean	Check for specific condition/group

The operator property determines how values are compared:

Category	Operators
Equality	eq, neq
Comparison	gt, gte, lt, lte
Text	find, sw, ew
Set	in, nin
Existence	exists
Range	rg

See Operators Reference for full documentation.

Fine-tune condition behavior with the options property:

Option	Description
transform	Transform value before comparison (lowercase, uppercase)
invert	Negate the condition result
arrayValueHandling	How to match array properties (some, every)