--- title: Types and Definitions slug: dql/types-and-definitions docTags: createdAt: 2023-11-02T21:43:20.895Z --- 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](./#data-types) - [Declaring Type Definitions](./#declaring-type-definition) - [MAP Type Specifics](./#map-type-specifics) - [Data Type Operations](./#data-type-operations) - [Document Operations](./#document-operations) # 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: :::CodeblockTabs DQL ```sql SELECT * FROM COLLECTION your_collection_name (field1 MAP, field2 ATTACHMENT) WHERE field1.rating > 100 ``` ::: In this syntax: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (field1 data_type, field2 data_type, ...) ... ``` ::: - `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 :::CodeblockTabs DQL ```sql SELECT * FROM COLLECTION your_collection_name (field1 MAP, field2 ATTACHMENT) ``` ::: ## UPDATE with Definition :::CodeblockTabs DQL ```sql UPDATE COLLECTION your_collection_name (field1 MAP, field2 ATTACHMENT) SET ... ``` ::: ## INSERT with Definition :::CodeblockTabs DQL ```sql INSERT INTO COLLECTION your_collection_name (field1 MAP, field2 ATTACHMENT) DOCUMENTS (...) ``` ::: # 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, ...)`: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (map_name MAP(sub1 ATTACHMENT, sub2 MAP)) ``` ::: ## Single MAP The syntax for a single `MAP` with all other fields type `REGISTER`: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (field1 MAP) ``` ::: ## Single ATTACHMENT The syntax for a single `ATTACHMENT` with all other fields type `REGISTER`: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (field1 ATTACHMENT) ``` ::: ## MAP and ATTACHMENT The syntax for a single `MAP` and a single `ATTACHMENT` with all other fields type `REGISTER`: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (field1 MAP, field2 ATTACHMENT) ``` ::: ## 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 ... COLLECTION your_collection_name (field1 MAP(sub1 MAP)) ``` The syntax for a document hierarchy of depth four with all other fields type `REGISTER`: :::CodeblockTabs DQL ```sql ... COLLECTION your_collection_name (field1 MAP(sub1 MAP(s_sub1 MAP(s_s_sub1 MAP)))) ``` ::: # 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: :::CodeblockTabs DQL ```sql -- Setting `field1` to 1 field1 = 1 ``` ::: ## 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** :::CodeblockTabs DQL ```sql field1 -> ( sub1 = 1 ) ``` ::: **Tombstoning (Remove) 'field1.sub1'** :::CodeblockTabs DQL ```sql field1 -> ( sub1 -> tombstone() ) ``` ::: **Setting the Value of 'sub1' to 1 and Tombstoning 'sub2'** :::CodeblockTabs DQL ```sql field1 -> ( sub1 = 1, sub2 -> tombstone() ) ``` ::: **Setting the Value of **`field1.sub1.s_sub1`** to 1** :::CodeblockTabs DQL ```sql field1 -> ( sub1 -> ( s_sub1 = 1 ) ) ``` ::: **Setting the Value of **`field1.sub1`** as Default Value** :::CodeblockTabs DQL ```sql field1 -> ( sub1 -> default() ) ``` ::: ## ATTACHMENT Operations To set the last-write-wins `ATTACHMENT` data type, provide an `ATTACHMENT` object: :::CodeblockTabs DQL ```sql field1 = :attachment ``` ::: ## Default Value Operation All data types can be set to a default value type using the `default()` functional operator. - `REGISTER` → `NULL` - `AWMAP` → Empty Map `{}` :::hint{type="info"} `ATTACHMENT` → *NOT SUPPORTED* ::: :::CodeblockTabs DQL ```sql field1 -> default() ``` ::: ## Tombstone Operation To remove all fields from a document, use the `tombstone()` functional operator. :::CodeblockTabs DQL ```sql field1 -> tombstone() ``` ::: :::hint{type="info"} 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](./#map-operations).