Understanding Queries

Query structure overview

A dcupl query statement consists of a nested structure containing DcuplQueryGroups and DcuplQueries. Groups are identified by their groupKey and specify a groupType that influences the evaluation of their queries. A query determines how an attribute value is evaluated using a specific operator.

Query example

A full query might look overwhelming at first. But the query api handles a lot of complexity for you so that when jus "just want to set a specific query" it will generate the full query for you like in the example.

{
  "modelKey": "product",
  "count": 10, // paging - 10 items will be returned
  "start": 2, // paging - paging starts at the 2nd item
  "projection": { "$": true }, // defines what attributes are returned by the query
  "sort": {
    "attributes": ["key"],
    "order": ["ASC"]
  },
  "groupKey": "root", // a query always has a 'root' groupKey to mark the beginning of the nested structure
  "groupType": "and", // 'and' | 'or' - defines how the direct child queries are evaluated
  "queries": [
    {
      "groupKey": "myQuery", // groupKey to identify it's child queries. Needed to apply/remove queryies dynamically
      "groupType": "or",
      "queries": [
        {
          "attribute": "inStock",
          "operator": "eq", // eq | find | gt | ...
          "value": true // can be "any" value - depending on your selected operator
        }
      ]
    }
  ]
}

operators

The following operators are currently available and can be used to query your data:

["eq", "find", "gt", "gte", "lt", "lte", "typeof", "isTruthy", "size"]

one/many

If you already know the key(s) of the items you want to query, you can simply use dcupl.query.one() or dcupl.query.many() to retrieve your data. These functions are often used in combination with list functionality, which we'll cover later in the tutorial.

generate

Most of the time, you may not want to write a full query statement but instead perform a single, simple query. dcupl.query.generate() accepts one or more Queries/Groups and returns a valid query statement that you can adapt or execute.

execute

dcupl.query.execute() only accepts a valid query statement. Use the generate helper or the dcupl Console query inspector to ensure you get the desired results. Query performance largely depends on the amount of data and the query operator used. For instance, eq outperforms find on large datasets by utilizing indices in the background, while find allows for more diverse queries by supporting Regex search.

Example Queries

// Example 1
// Return all products that have an attribute "inStock" equal to true
{
  "modelKey": "product",
  "groupKey": "root",
  "groupType": "and",
  "queries": [
    {
      "groupKey": "myQuery",
      "groupType": "or",
      "queries": [
        {
          "attribute": "inStock",
          "operator": "eq",
          "value": true
        }
      ]
    }
  ]
}

// Example 2
// return 10 products that are in stock AND have price lower than 100
{
  "modelKey": "product",
  "groupKey": "root",
  "groupType": "and",
  "count": 10,
  "queries": [
    {
      "groupKey": "myQuery",
      "groupType": "and", // both queries must be valid
      "queries": [
        {
          "attribute": "inStock",
          "operator": "eq",
          "value": true
        },
        {
          "attribute": "price",
          "operator": "lt",
          "value": 100
        }
      ]
    }
  ]
}

// Example 3
// return all products where...
// their name contains "Backpack" and are cheaper than 100
// OR
// are inStock and their price is higher than 100

{
  "modelKey": "product",
  "groupKey": "root",
  "groupType": "or", // one of the two nested queryGroups has to be valid
  "queries": [
    {
      "groupKey": "myQuery1",
      "groupType": "and",
      "queries": [
        {
          "attribute": "name",
          "operator": "find",
          "value": "/Backpack/" // the "find" operator accepts a Regex
        },
        {
          "attribute": "price",
          "operator": "lt",
          "value": 100
        }
      ]
    },
    {
      "groupKey": "myQuery2",
      "groupType": "and",
      "queries": [
        {
          "attribute": "inStock",
          "operator": "eq",
          "value": false
        },
        {
          "attribute": "price",
          "operator": "gt",
          "value": 100
        }
      ]
    }
  ]
}