Hey! These docs are for version 0.18.0, which is no longer officially supported. Click here for the latest version, 0.21.0!

Query Syntax

Overview

Generally queries will consist of a where clause plus optional modifiers controlling the specific subset of results returned.

Where Clause

The Where clause must be a non-empty array containing not more than 10 conditions. For some operators, value will be an array. See the following general syntax example:

{
  where: [
    [<fieldName>, <operator>, <value>],
    [<fieldName>, <array operator>, [<value1>, <value2>]] 
  ] 
}

Fields

Valid fields consist of the indices defined for the document being queried. For example, the DPNS data contract defines three indices:

Index Field(s)Index TypeUnique
normalizedParentDomainName, normalizedLabelCompoundYes
records.dashUniqueIdentityIdSingle FieldYes
records.dashAliasIdentityIdSingle FieldNo

Comparison Operators

NameDescription
<Matches values that are less than a specified value
<=Matches values that are less than or equal to a specified value
==Matches values that are equal to a specified value
=>Matches values that are greater than or equal to a specified value
>Matches values that are greater than a specified value
inMatches all document(s) where the value of the field equals any value in the specified array
Array may include up to 100 (unique) elements

Array Operators

NameDescription
lengthSelects documents if the array field is a specified size (integer)
contains- Matches arrays that contain all elements specified in the query condition array
- 100 element maximum
elementMatch- Matches documents that contain an array field with at least one element that matches all the criteria in the query condition array
- Two or more conditions must be provided

Evaluation Operators

NameDescription
startsWithSelects documents where the value of a field begins with the specified characters (string, <= 255 characters)

Operator Examples

{
  where: [
    ['nameHash', '<', '56116861626961756e6176657a382e64617368'],
  ],
}
{
  where: [
      ['normalizedParentDomainName', '==', 'dash'],
      // Return all matching names from the provided array
      ['normalizedLabel', 'in', ['alice', 'bob']],
    ]
}
{
  where: [
      ['normalizedParentDomainName', '==', 'dash'],
      // Return any names beginning with "al" (e.g. alice, alfred)
      ['normalizedLabel', 'startsWith', 'al'],
    ]
}
{
  where: [
      // Return documents that have 5 values in their `items` array
      ['items', 'length', 5],
    ]
}
{
  where: [
      // Return documents that have both "red" and "blue" 
      // in the `colors` array
      ['colors', 'contains', ['red', 'blue']],
    ]
}
{
  where: [
    // Return `scores` documents where the results contain 
    // elements in the range 80-90
    ['scores', 'elementMatch',
      [
        ['results', '>=', '80'],
        ['results', '<=', '90']
      ],
    ],
  ]
}

Query Modifiers

The query modifiers described here determine how query results will be sorted and what subset of data matching the query will be returned.

ModifierEffectExample
limitRestricts the number of results returned (maximum: 100)limit: 10
orderByReturns records sorted by the field(s) provided (maximum: 2)orderBy: [['normalizedLabel', 'asc']]
startAtReturns records beginning with the index provided (minimum: 1, maximum: 20000)startAt: 100
startAfterReturns records beginning after the index provided (maximum: 20000)startAfter: 50

🚧

Compound Index Constraints

For indices composed of multiple fields (example from the DPNS data contract), the sort order in an orderBy must either match the order defined in the data contract OR be the inverse order. Please see the mongoDB documention for further details related to this topic.
Additionally, the order in which the properties are defined in a compound index affects how queries may be constructed per this mongoDB documentation. For example, a DPNS query for normalizedLabel must also include normalizedParentDomainName while the inverse is not true (index definition in the DPNS contract).

❗️

Compound Index Inverse Sort

Currently inverse sort functionality for compound indices is not available on Evonet. Drive PR #313 will enable this functionality once deployed.

Example query

The following query combines both a where clause and query modifiers.

{
    where: [
        ['normalizedParentDomainName', '==', 'dash'],
        ['normalizedLabel', 'startsWith', 'test'],
    ],
    startAt: 15,
    limit: 20,
    orderBy: [
        ['records.dashUniqueIdentityId', 'asc']
    ]
}

MongoDB Comparision

Currently Dash Platform uses mongoDB for storage. The following table shows a mapping of platform operators to the underlying mongoDB operators that are used internally:

Platform OperatormongoDB Operator
<$lt
<=$lte
==$eq
=>$gte
>$gt
in$in
length$size
startsWith$regex
elementMatch$elemMatch
contains$all

Did this page help you?