Types and Definitions

Ditto Query Language (DQL) offers a set of data types designed to accommodate any edge sync scenario.

A data type is different than a standard scalar type by declaring merge behaviors, operations, and the spectrum of scalar types accessible for individual fields:

Data Types

In DQL, you'll use three data types:REGISTER, MAP, and ATTACHMENT type. By default, fields in a DQL statement are assigned the REGISTER type unless otherwise specified by way of type definition.

Following are the key characteristics:

REGISTER (Default)

MAP

ATTACHMENT

Last-write-wins merge

Add-wins merge

Last-write-wins merge

Supports multiple scalar types, including primitive types, such as string and boolean, as well as a JSON blob, encapsulating multiple field‑value pairs that function as a single object.

Supports embedded data types

Ditto attachment object

Declaring Type Definition

DQL type definitions describe the schema of the documents within a specific collection — defining the field types within the collection and specifying the assigned data types for each field.

Since REGISTER is the default type in DQL, you only need to specify the type definition when overriding with type MAP or ATTACHMENT within your query.

To explicitly declare the type definition as non-REGISTER type, add a prefix of COLLECTION and the suffix of (field1 data_type, field2 data_type, ...) to list the fields within the collection and their associated data types:

DQL


In this syntax:

DQL

  • COLLECTION declares that the collection has a type definition
  • your_collection_name is the name of the collection from which you want to set a definition.
  • (field1 data_type, field2 data_type, ...) specifies the data type of each field such as REGISTER , MAP, or ATTACHMENT

SELECT with Definition

DQL


UPDATE with Definition

DQL


INSERT with Definition

DQL


MAP Type Specifics

The MAP (Add-Wins Map) contains fields with their own data type. Data types for these fields are defined using parentheses following the MAP keyword. For example, MAP(sub1 data_type, sub2 data_type, ...):

DQL


Single MAP

The syntax for a single MAP with all other fields type REGISTER:

DQL


Single ATTACHMENT

The syntax for a single ATTACHMENT with all other fields type REGISTER:

DQL


MAP and ATTACHMENT

The syntax for a single MAP and a single ATTACHMENT with all other fields type REGISTER:

DQL


Deeply Embedded MAP

The syntax for a document hierarchy of depth two — a single MAP nested with another MAP — with all other fields type REGISTER:

SQL


The syntax for a document hierarchy of depth four with all other fields type REGISTER:

DQL


Data Type Operations

Data types have different operations available.

  • Assignment operations are denoted with an equals (=).
  • Functional operations are denoted with an arrow (->).

REGISTER Operations

The REGISTER can only be set to a specific field. For example:

DQL


MAP Operations

The MAP type supports inserting and tombstoning of fields using the functional operators. Inserting a field is an implicit operation performed by assigning a value to a field or a child of the field.

To assign a default value to a field, use the default() operation.

To perform MAP operations, use the arrow -> operator followed by parentheses (), which contain one or more operations on child fields of the MAP.

Setting or Inserting field1.sub1 to 1

DQL


Tombstoning (Remove) 'field1.sub1'

DQL


Setting the Value of 'sub1' to 1 and Tombstoning 'sub2'

DQL


Setting the Value of field1.sub1.s_sub1 to 1

DQL


Setting the Value of field1.sub1 as Default Value

DQL


ATTACHMENT Operations

To set the last-write-wins ATTACHMENT data type, provide an ATTACHMENT object:

DQL


Default Value Operation

All data types can be set to a default value type using the default() functional operator.

  • REGISTERNULL
  • AWMAP → Empty Map {}

ATTACHMENTNOT SUPPORTED

DQL


Tombstone Operation

To remove all fields from a document, use the tombstone() functional operator.

DQL


In Ditto, fields need to be marked as "deleted" for other peers to know the field has been removed.

Ditto does this by internally setting a tombstone metadata on the field and removing the value:

  • When tombstoning a MAP, all children data types are iteratively tombstoned.
  • Fields that are tombstoned are ignored during subsequent DQL statements.
  • While tombstoned fields are relatively inexpensive, they cannot be permanently deleted. Therefore, tombstoning in large numbers may cause performance to degrade.

Document Operations

Documents have the same data type operations as the MAP. For syntax, see MAP Operations.