Guides
Dash CoreDash PlatformDash.orgDash User DocsLog In
These docs are for v0.22.0. Click to read the latest docs for v0.25-redirect.

Query Syntax

Overview

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

🚧

Query limitations

Dash Platform v0.22 introduced a number of limitations due to the switch to using GroveDB. See details in pull requests 77 and 230 that implemented these changes.

Query validation details may be found here along with the associated validation tests.

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:

❗️

As of Dash Platform v0.22, all fields referenced in a query's where clause must be defined in the same index. This includes $createdAt and $updatedAt.

{
  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

Equal

NameDescription
==Matches values that are equal to a specified value

Range

🚧

Dash Platform v0.22 notes

  • Only one range operator is allowed in a query (except for between behavior)
  • The in operator is only allowed for last two indexed properties
  • Range operators are only allowed after == and in operators
  • Range operators are only allowed for the last two fields used in the where condition
  • Queries using range operators must also include an orderBy statement
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 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

❗️

NOTE

The following operators are not available in Dash Platform v0.22.

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). Must include an orderBy statement.

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'],
    ]
}
// Not available in Dash Platform v0.22
// See https://github.com/dashevo/platform/pull/77
{
  where: [
      // Return documents that have 5 values in their `items` array
      ['items', 'length', 5],
    ]
}
// Not available in Dash Platform v0.22
// See https://github.com/dashevo/platform/pull/77
{
  where: [
      // Return documents that have both "red" and "blue" 
      // in the `colors` array
      ['colors', 'contains', ['red', 'blue']],
    ]
}
// Not available in Dash Platform v0.22
// See https://github.com/dashevo/platform/pull/77
{
  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.

❗️

Breaking changes

Starting with Dash Platform v0.22, startAt and startAfter must be provided with a document ID rather than an integer.

ModifierEffectExample
limitRestricts the number of results returned (maximum: 100)limit: 10
orderByReturns records sorted by the field(s) provided (maximum: 2). Sorting must be by the last indexed property. Can only be used with >, <, >=, <=, and startsWith queries.orderBy: [['normalizedLabel', 'asc']]
startAtReturns records beginning with the document ID providedstartAt: Buffer.from(Identifier.from(<document ID>))
startAfterReturns records beginning after the document ID providedstartAfter: Buffer.from(Identifier.from(<document ID>))

🚧

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 refer to pull request 230 for additional information related to compound index constraints in Platform v0.22.

Example query

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

import Dash from "dash"

const { Essentials: { Buffer }, PlatformProtocol: { Identifier } } = Dash;

const query = {
  limit: 5,
  startAt: Buffer.from(Identifier.from('4Qp3menV9QjE92hc3BzkUCusAmHLxh1AU6gsVsPF4L2q')),
  where: [
    ['normalizedParentDomainName', '==', 'dash'],
    ['normalizedLabel', 'startsWith', 'test'],
  ],
  orderBy: [
    ['normalizedLabel', 'asc'],
  ],
}