1. SuiteCloud Platform
  2. SuiteScript
  3. SuiteScript 2.1 API Reference
  4. SuiteScript 2.1 Modules
  5. N/dataStore Module
  6. Data Store Query Object
  7. Data Store Query Rules

Data Store Query Rules

When constructing a query object, consider the supported comparison values and how you refer to document properties. A field's data type and whether it exists affect which documents satisfy the defined conditions.

For more information about query object rules, see the following sections:

Document Properties

  • Use supported property names. When inserting or updating documents, property names must contain at least one character. They can't contain dots, start with $, or be __proto__, constructor, or prototype. These restrictions also apply to properties in nested objects and arrays.

  • Use dot notation for nested properties. Separate property names with dots. For example, profile.country refers to the country property within the profile object. For conditions on array elements, see Data Store Array Queries.

Comparison Values

  • Use supported comparison values. Accepted values depend on the query operator. Objects and arrays can't be compared as whole values. For the values accepted by each operator, see Data Store Query Operators.

  • Use values rather than functions. Query objects can't contain JavaScript functions as values, including within nested objects or arrays. To use a function's result, call the function before passing the query object.

  • Use the correct data type. For example, the string "5" doesn't match the number 5.

  • Use the correct letter case. String comparisons against document values are case-sensitive. For example, 'pending' doesn't match 'Pending'.

  • Query stored date values as strings. Date values are stored as UTC strings in ISO 8601 format. For details about date values, see dataStore.Document.

Missing Fields and Null Values

A field can be missing from a document or present with a null value. These cases have different matching rules:

  • Use $exists: false to match a missing field.

  • Use $exists: true to match an existing field, including one containing null.

  • A query for null matches a field containing null or a null element directly within an array. It doesn't match a missing field.

  • A condition using $ne: null doesn't match any field value. Don't use it to find fields with non-null values.

Related Topics

General Notices