loadOptions

The goal for the implementation of devextreme-query-mongodb was to create an interface between the Custom Store querying functionality supplied by DevExtreme and the MongoDB APIs. All queries should utilize MongoDB server functionality, if possible.

At the core of the DevExtreme querying features is a structure commonly called loadOptions, which defines the parameters for a data query. Here is an overview of the supported parameters:

Parameter	Details
take	Integer. Restrict the number of top level results to return.
skip	Integer. Skip a number of items from the start of the result set. In conjunction with take, this is often used to implement paging.
sort	Array. Elements have the structure { selector: "field", desc: true/false } and are applied to the data in sequence to implement multi-level sorting.
filter	Array. This can be a hierarchical structure of elements and arrays. Details of this can be found below.
searchExpr, searchOperation and searchValue	Strings. Another mechanism to define a filter, restricted to one criterion. The filtering details described below apply to these parameters.
select	Array. A simple list of field name strings that restricts the returned data objects to that set of fields.
requireTotalCount	Bool. Indicate that a total count of result set data objects must be returned in the totalCount field of the result. The count is expected to consider any filters that are being applied, but it is supposed to disregard any take parameter used for the query. The count must reflect the number of data items available after filtering, not for instance the number of grouping nodes or similar.
totalSummary	Array. Elements have the structure { selector: "field", summaryType: "type" }, where summaryType can be one of sum, avg, min, max and count. Results of these summary calculations are returned in an array called summary that contains the result values in the same order used for the summary definitions.
group	Array. The structures in this array define the grouping levels that need to be applied to the data. Details of this can be found below.
requireGroupCount	Bool, default false. When used in conjunction with group, require the return of a top-level group count in the groupCount field of the result.
groupSummary	Array. The structure is the same as for totalSummary, but these summary values will be returned for each group if group is used.

If parameters are not included in the options, they don't apply. In other words, for an empty loadOptions object the full set of data objects will be returned.

Result data structure

The result of a query operation returned by devextreme-query-mongodb looks like this:

{
  data: [ ... ],    // list of result data objects
  summary: [ ... ], // list of summary results if requested in totalSummary
  totalCount: 10,   // if required in requireTotalCount
  groupCount: 3     // if required in requireGroupCount
}

Filtering

Individual filter criteria have the format [ "field", "operator", "value" ], where operator is one of =, <>, <, >, <=, >=, startsWith, endswith, contains and notcontains. The last four are used for strings, otherwise operators apply to all value types. Criteria can be combined in hierarchies using nested arrays with and and or operators like this:

[
  [ "field", "=", 10 ],
  "and",
  [
    [ "otherField", "<", 3 ],
    "or",
    [ "otherField", ">", 11 ]
  ]
]

It is possible to negate a criterion (or hierarchy of criteria) by applying the operator ! like this: [ "!", [ "field", "=", 3 ]].

Finally, special syntax is supported to access "parts" of the information contained in date values. This feature is used by the Pivot Grid in situations where groupInterval settings for date fields are applied, but can be used independently. A field postfix in a criterion looks like this: [ "dateField.Month", "=", 4 ]. Supported postfixes are Year, Quarter (1-4), Month (1-12), Day and DayOfWeek (0=Sunday - 6=Saturday). The implementation doesn't require particular casing for these postfixes.

Note that you need to consider time zones when you use field prefixes that extract date detail. Please see the Query API documentation to find out more.

ObjectId Filtering

The special operator equalsObjectId is supported to filter by MongoDB ObjectId values. This is required if your MongoDB document has a value of ObjectId type and you want to compare it to a string representation of such an id. The standard = operator doesn't work correctly in that case, but equalsObjectId does. (Two tests illustrate this feature.)

Grouping

The group structure is a flat array of group definitions. Each group definition can have the following parameters:

Parameter	Details
selector	String, required. The field name to group on.
desc	Bool, default false. Define descending sort order on the selector field.
isExpanded	Bool, default false. Confusingly named, this field has meaning only for the last group definition and setting it to true requires the group data objects to be returned with the result set. To be clear, nested grouping data is always returned, even if isExpanded is false for a group definition that is not the last one. isExpanded only defines whether data objects will be returned as well.
groupInterval	Integer or String. For Integer values, data will be grouped in ranges of the given length. String values apply only to date fields, supported options are year, quarter, month, day, dayOfWeek, hour, minute and second.

For group queries, the result data structure is different from the simple query result structure shown above. Here it is:

{
  data: [              // list of groups
    {
      count: 3,        // count of items in this group, even if items=null
      key: "groupKey", // value that grouping was applied on
      items: [ ... ],  // sub-groups or data objects (for the last group when isExpanded=true)
                       //   can be null when isExpanded=false and there are no further groups
      summary: [ ...]  // list of group summary results if requested in groupSummary
    },
    ...                // further groups on this level
  ],
  summary: [ ... ],    // list of summary results if requested in totalSummary
  totalCount: 10,      // if required in requireTotalCount
  groupCount: 3        // if required in requireGroupCount
}

Note that the key in each group is the value used for grouping. In simple selector based group definitions, the key will be a value valid for the selector field, but if groupInterval is also used the key will contain the interval value (which, in the case of date intervals, is not a valid value for/from the selector field).

Examples

The tests implemented for the package show many examples of loadOptions structures.