---
title: CREATE
slug: v4-8/crud/create
docTags: 
createdAt: 2023-07-28T20:02:36.395Z
---

This article provides how-to instructions for creating and organizing documents, linking them to associated files, called *attachments*, and creating `MAP` structures for additional document hierarchies.

Attachments in Ditto are represented using the `ATTACHMENT` data type, which you can use to store binary data, such as images, alongside queryable descriptive information, such as file name and description. 

# Database Operations

Syncing data across the mesh is an entirely separate process from CRUD, involving replicating documents across different databases rather than interacting with a single datastore. 

# Creating Documents

To insert a document, call the `EXECUTE` API method against the `ditto.store` object and include an `INSERT INTO` query that specifies the document to be inserted.

:::hint{type="info"}
Ditto does *not* support nesting documents within documents. Instead, opt for a foreign-key relationship by referencing the document ID. For more information, see [Relationships](docId:4aywTEZ9suT17PMQw-lh4).
:::

For example, the following snippet demonstrates how to insert a new document with a single field `"color"` set to `"blue"`:

:::CodeblockTabs
```swift
await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: ["newCar": ["color": "blue"]]);
```

```kotlin
ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  mapOf("newCar" to mapOf("color" to "blue")))
```

```javascript
await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  { newCar: { color: "blue" } }
);
```

```java
DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO cars DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", Collections.singletonMap("color", "blue")),
);
```

```csharp
var args = new Dictionary<string, object>();
args.Add("newCar", new { color = "blue" });

await ditto.Store.ExecuteAsync(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);
```

```cpp
std::map<std::string, std::map<std::string, std::string>> args;
args["newCar"] = {{"color", "blue"}};

ditto.get_store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);
```

```rust
let query_result = ditto
    .store()
    .execute(
        "INSERT INTO cars DOCUMENTS (:newCar)",
        Some(serde_json::json!({
            "newCar": {
                "color": "blue"
            }
        }).into()),
    ).await?;
```

```dart
await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: {"newCar": {"color": "blue"}},
);
```
:::

To create multiple documents efficiently, batch your `CREATE` operations in a single operation.

If desired, supply a document ID in your creation request; otherwise, Ditto automatically generates and assigns one.&#x20;

## Inserting Multiple Documents

To create multiple documents in a single operation, use the `INSERT INTO` operation as follows:

:::CodeblockTabs
```swift
let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: [
    newCar: ["color": "blue"]
  ]);

// "507f191e810c19729de860ea"
print(result.mutatedDocumentIDs()[0])
```

```kotlin
var result = ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  mapOf("newCar" to mapOf("color" to "blue")))

// "507f191e810c19729de860ea"
println(result.mutatedDocumentIDs().first())
```

```javascript
const result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  { newCar: { color: 'blue' } }
);

// "507f191e810c19729de860ea"
console.log(result.mutatedDocumentIDs()[0].value)
```

```java
DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO cars DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", Collections.singletonMap("color", "blue")),
    new Continuation<>() {
        @NonNull
        @Override
        public CoroutineContext getContext() {
            return EmptyCoroutineContext.INSTANCE;
        }

        @Override
        public void resumeWith(@NonNull Object o) {
            if (o instanceof Result.Failure) {
                // Handle failure
            }
        }
    }
);

// "507f191e810c19729de860ea"
System.out.println(result.mutatedDocumentIDs()[0]);
```

```csharp
var insertArgs = new Dictionary<string, object>();
insertArgs.Add("newCar", new { color = "blue" });

var result = await ditto.Store.ExecuteAsync(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  insertArgs);
  
// "507f191e810c19729de860ea"
result.MutatedDocumentIds.ForEach(id => Console.WriteLine(id));
```

```cpp
std::map<std::string, std::map<std::string, std::string>> args;
args["newCar"] = {{"color", "blue"}};

auto result = ditto.get_store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);

// "507f191e810c19729de860ea"
std::cout << result.mutated_document_ids()[0].to_string();
```

```rust
use serde::Serialize;

#[derive(Serialize)]
struct Args {
  newCar: Car,
}
#[derive(Serialize)]
struct Car {
  color: String
}

// ...

let args = Args {
  newCar: Car {
    color: "blue".to_string()
  },
};

let result = ditto.store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  Some(args.into())); 

// "507f191e810c19729de860ea"
println!("{}", result.mutated_document_ids()[0].to_string())
```

```dart
final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:doc1),(:doc2)",
  arguments: {
    "doc1": {"color": 'blue'},
    "doc2": {"color": 'red'},
  },
);


```
:::

## Identifying Documents

Unless manually supplied, Ditto automatically generates and assigns the new document a 128‑bit Universally Unique Identifier (UUID).&#x20;

The document identifier is represented as `_id` and serves as the primary key for the document.

### Retrieving Document IDs

To access the IDs of the documents affected by the `INSERTION INTO` operation, call the `mutatedDocumentIDs` method on the `result`  object after the insertion like this:&#x20;

:::CodeblockTabs
```swift
let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: [
    newCar: ["color": "blue"]
  ]);

// "507f191e810c19729de860ea"
print(result.mutatedDocumentIDs()[0])
```

```kotlin
var result = ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  mapOf("newCar" to mapOf("color" to "blue")))

// "507f191e810c19729de860ea"
println(result.mutatedDocumentIDs().first())
```

```javascript
const result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  { newCar: { color: 'blue' } }
);

// "507f191e810c19729de860ea"
console.log(result.mutatedDocumentIDs()[0].value)
```

```java
DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO cars DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", Collections.singletonMap("color", "blue")),
    new Continuation<>() {
        @NonNull
        @Override
        public CoroutineContext getContext() {
            return EmptyCoroutineContext.INSTANCE;
        }

        @Override
        public void resumeWith(@NonNull Object o) {
            if (o instanceof Result.Failure) {
                // Handle failure
            }
        }
    }
);

// "507f191e810c19729de860ea"
System.out.println(result.mutatedDocumentIDs()[0]);
```

```csharp
var insertArgs = new Dictionary<string, object>();
insertArgs.Add("newCar", new { color = "blue" });

var result = await ditto.Store.ExecuteAsync(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  insertArgs);
  
// "507f191e810c19729de860ea"
result.MutatedDocumentIds.ForEach(id => Console.WriteLine(id));
```

```cpp
std::map<std::string, std::map<std::string, std::string>> args;
args["newCar"] = {{"color", "blue"}};

auto result = ditto.get_store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);

// "507f191e810c19729de860ea"
std::cout << result.mutated_document_ids()[0].to_string();
```

```rust
use serde::Serialize;

#[derive(Serialize)]
struct Args {
  newCar: Car,
}
#[derive(Serialize)]
struct Car {
  color: String
}

// ...

let args = Args {
  newCar: Car {
    color: "blue".to_string()
  },
};

let result = ditto.store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  Some(args.into())); 

// "507f191e810c19729de860ea"
println!("{}", result.mutated_document_ids()[0].to_string())
```

```dart
final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: {
    "newCar": {"color": 'blue'},
  },
);


// "507f191e810c19729de860ea"
print(result.mutatedDocumentIDs.first);
```
:::

### Supplying String IDs

When creating a document, you can assign it a custom ID. This custom ID can be generated using a single string value or a combination of two or more string values.&#x20;

This flexibility in structuring document identifiers allows you to customize document IDs to your specific requirements, use cases, or standard naming conventions.&#x20;

The following snippet demonstrates a new document assigned the custom ID `"123"`.

:::CodeblockTabs
```swift
let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: [
    newCar: [ "_id": "123", "color": "blue"]
  ]);

// "123"
print(result.mutatedDocumentIDs()[0])
```

```kotlin
var result = ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  mapOf("newCar" to mapOf("_id" to "123", "color" to "blue")))
  
// "507f191e810c19729de860ea"
println(result.mutatedDocumentIDs().first())
```

```javascript
const newCar = {
  _id: "123",
  color: "blue"
}

const result = await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:newCar)`,
  { newCar }
);

// "123"
console.log(result.mutatedDocumentIDs()[0].value)
```

```java
Map<String, String> newCar = new HashMap<>();
newCar.put("_id", "123");
newCar.put("color", "blue");

DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO cars DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", newCar),
    new Continuation<>() {
        @NonNull
        @Override
        public CoroutineContext getContext() {
            return EmptyCoroutineContext.INSTANCE;
        }

        @Override
        public void resumeWith(@NonNull Object o) {
            if (o instanceof Result.Failure) {
                // Handle failure
            }
        }
    }
);

// "123"
System.out.println(result.mutatedDocumentIDs()[0]);
```

```csharp
var insertArgs = new Dictionary<string, object>();
insertArgs.Add("newCar", new { _id = "123", color = "blue" });

var result = await ditto.Store.ExecuteAsync(
  "INSERT INTO your_collection_name DOCUMENTS (:newCar)",
  insertArgs);
  
// "123"
result.MutatedDocumentIds.ForEach(id => Console.WriteLine(id));
```

```cpp
std::map<std::string, std::map<std::string, std::string>> args;
args["newCar"] = {{"_id", "123"},{"color", "blue"}};

auto result = ditto.get_store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);

// "123"
std::cout << result.mutated_document_ids()[0].to_string();
```

```rust
use serde::Serialize;

#[derive(Serialize)]
struct Args {
  newCar: Car,
}
#[derive(Serialize)]
struct Car {
  _id: String,
  color: String
}

// ...

let args = Args {
  newCar: Car {
    _id: "123".to_string(),
    color: "blue".to_string()
  },
};

let result = ditto.store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  Some(args.into())); 

// "123"
println!("{}", result.mutated_document_ids()[0].to_string())
```

```dart
final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: {
    "newCar": {"_id":"123","color": 'blue'},
  },
);


// "123"
print(result.mutatedDocumentIDs.first);
```
:::

Following is the new `123` document that results:

:::CodeblockTabs
Ditto Document

```json
{
  "_id": "123",
  "color": "blue"
}
```
:::

### Forming Composite Keys

The following demonstrates combining the `vin` and `make` fields to form the composite key:

:::CodeblockTabs
```swift
let arguments = [
  newCar: [ "_id": [vin: "123", make: "Toyota"], "color": "blue"]
];

let result = await ditto.store.execute(
  query: "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: arguments);

// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs()[0])
```

```kotlin
var result = ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  mapOf(
    "newCar" to mapOf(
      "_id" to mapOf(
        "vin" to "123",
        "make" to "Toyota"
      ),
      "color" to "blue"
  )))
  
// "{vin: "123", make: "Toyota"}"
println(result.mutatedDocumentIDs().first())
```

```javascript
const newCar = {
  _id: {
    vin: "123",
    make: "Toyota"
  },
  color: "blue"
}
const result = await ditto.store.execute(`
  INSERT INTO cars
  DOCUMENTS (:newCar)`,
  { newCar });

// { vin: "123", make: "Toyota" }
console.log(result.mutatedDocumentIDs()[0].value)
```

```java
Map<String, String> newCarId = new HashMap<>();
newCarId.put("vin", "123");
newCarId.put("make", "Toyota");
Map<String, Object> newCar = new HashMap<>();
newCar.put("_id", newCarId);
newCar.put("color", "blue");

DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO cars DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", newCar),
    new Continuation<>() {
        @NonNull
        @Override
        public CoroutineContext getContext() {
            return EmptyCoroutineContext.INSTANCE;
        }

        @Override
        public void resumeWith(@NonNull Object o) {
            if (o instanceof Result.Failure) {
                // Handle failure
            }
        }
    }
);

// "{vin: "123", make: "Toyota"}"
System.out.println(result.mutatedDocumentIDs()[0]);
```

```csharp
var newId = new { vin: "123", make: "Toyota"};
var insertArgs = new Dictionary<string, object>();
insertArgs.Add("newCar", new { _id = newId, color = "blue" });

var result = await ditto.Store.ExecuteAsync(
  "INSERT INTO your_collection_name DOCUMENTS (:newCar)",
  insertArgs);
  
// "{vin: "123", make: "Toyota"}"
result.MutatedDocumentIds.ForEach(id => Console.WriteLine(
  System.Text.Json.JsonSerializer.Serialize(id)));
```

```cpp
struct CarId {
  std::string vin;
  std::string make;
};
struct Car {
  CarId _id;
  std::string color;
};

std::map<std::string, Car> args;
args["newCar"] = {{"123", "Toyota"}, "blue"};

auto result = ditto.get_store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  args);

// "{vin: "123", make: "Toyota"}"
std::cout << result.mutated_document_ids()[0].to_string();
```

```rust
use serde::Serialize;

#[derive(Serialize)]
struct Args {
  newCar: Car,
}
#[derive(Serialize)]
struct CarId {
  vin: String,
  make: String
}
#[derive(Serialize)]
struct Car {
  _id: CarId,
  color: String
}

// ...

let args = Args {
  newCar: Car {
    _id: CarId {
      vin: "123".to_string(),
      make: "Toyota".to_string()
    },
    color: "blue".to_string()
  },
};

let result = ditto.store().execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  Some(args.into())); 

// "{vin: "123", make: "Toyota"}"
println!("{}", result.mutated_document_ids()[0].to_string())
```

```dart
final result = await ditto.store.execute(
  "INSERT INTO cars DOCUMENTS (:newCar)",
  arguments: {
    "newCar": {
      "_id": {"vin": "123", "make": "Toyota"},
      "color": 'blue'
    },
  },
);


// "{vin: "123", make: "Toyota"}"
print(result.mutatedDocumentIDs.first);
```
:::

# Creating Attachments

There are two separate steps in the process of creating an attachment:

::::WorkflowBlock
:::WorkflowBlockItem
Create the attachment in the Ditto store. ([Initiating ATTACHMENT Objects](./#initiating-attachment-objects))
:::

:::WorkflowBlockItem
Reference the returned attachment token in a document. ([Referencing Attachment Tokens)](./#referencing-attachment-tokens)
:::
::::

:::hint{type="info"}
For a realworld usage scenario, see either the demo chat app for iOS or Android in the getditto > [demoapp-chat](https://github.com/getditto/demoapp-chat/tree/main) GitHub repository.&#x20;
:::

## Initiating ATTACHMENT Objects

To create the `ATTACHMENT` object that encodes the actual contents of the file to store externally, call the `newAttachment` method on the`store`namespace.

::::ExpandableHeading
When creating an attachment...

:::hint{type="warning"}
When creating an attachment, provide a valid path to the large file or deeply embedded document you want to encode as an `ATTACHMENT`.  Failure to do so may result in errors related to input-output (IO) operations.&#x20;
:::

:::hint{type="info"}
Storing an attachment in the local Ditto store (instead of externally) is currently only available in the Ditto SDK for JavaScript.
:::

:::hint{type="info"}
To use a DQL type other than a `REGISTER` — the default data type in Ditto — you must explicitly specify the type in your query; otherwise, Ditto defaults to the `REGISTER` type as follows.&#x20;
:::
::::

If desired, enclose extra information about the attachment, such as name and description. This metadata is useful for attachment fetching operations. &#x20;

:::CodeblockTabs
```swift
let newAttachment = try await ditto.store.newAttachment(path: filePath)
```

```kotlin
val attachment = runBlocking { ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata) }
```

```javascript
const newAttachment = await ditto.store.newAttachment(filePathOrData)
```

```java
try (DittoAttachment attachment = ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata)) {
```

```csharp
var newAttachment = await ditto.Store.NewAttachmentAsync(path: filePath);
```

```cpp
auto attachment = ditto.get_store().new_attachment("/path/to/my/file.pdf");
```

```rust
use ::dittolive_ditto::prelude::*;
use ::serde_json::json;
use ::std::{collections::HashMap, path::Path};
use serde::Serialize;

async fn attachment_doc_snippet(
    peer_a: &Ditto,
    peer_b: &Ditto,
    filepath: &Path,
) -> Result<(), Error> {
    // Creating an attachment in the local ditto store from a file:
    let new_attachment = peer_a
        .store()
        .new_attachment(filepath, <_>::default())
        .await?;
```

```dart
final newAttachment = await ditto.store.newAttachment(filePathOrData);
```
:::

### Adding Optional Metadata

If you want to include information about the attachment, such as the attachment filename, as shown in the following snippet, a description, and other relevant details, enclose it in a `metadata` object as key-value pairs.&#x20;

:::CodeblockTabs
```swift
let metadata = ["name": "name_of_file"]
let newAttachmentWithMetadata = try await ditto.store.newAttachment(path: filePath, metadata: metadata)
```

```kotlin
val attachmentMetadata = mapOf("name" to attachmentFileName)
val attachment = runBlocking { ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata) }
```

```javascript
const metadata = { name: 'image.png' }
const newAttachment = await ditto.store.newAttachment(imageBytes, metadata)
```

```java
val attachmentMetadata = mapOf("name" to attachmentFileName)
val attachment = runBlocking { ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata) }
```

```csharp
var metadata = new Dictionary<string, string>()
{
    { "name", "image.png" }
};
var newAttachmentWithMetadata = await Ditto.Store.NewAttachmentAsync(filePath, metadata);
```

```cpp
auto attachment = ditto.get_store().new_attachment("/path/to/my/file.pdf", {
    {"name", "name_of_file"}
});
```

```rust
let user_data = HashMap::from_iter([
    ("name".into(), "image.png".into()),
    // Idea: attach a small "summary" of the file contents to preview them in
    // the UI so that the user has some idea of what to "download"/_fetch_
    //
    // For example:
    // - For a text file, include a title or the first word of the filename
    // - For an image, include a base64-encoded thumbnail, as follows
    (
        "thumbnail".into(),
        "/9j/4atg9y_zw0ga_x_bzd_w0g_zg9sb...".into(),
    ),
]);
```

```dart
// Coming soon
```
:::

For example, in the following snippet, the `metadata` property encapsulates the `name` of the attachment, as well as its `description`:

:::CodeblockTabs
```swift
val attachmentMetadata = mapOf(
    "name" to "japan.png",
    "description" to "This is an image of a sunset in Japan."
)
val attachment = runBlocking { ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata) }
```

```kotlin
val attachmentMetadata = mapOf(
    "name" to "japan.png",
    "description" to "This is an image of a sunset in Japan."
)

val attachment = runBlocking {
    ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata)
}
```

```javascript
const metadata = { 
    name: 'japan.png', 
    description: 'This is an image of a sunset in Japan.' 
}
const newAttachment = await ditto.store.newAttachment(imageBytes, metadata)
```

```java
val attachmentMetadata = mapOf(
    "name" to "japan.png",
    "description" to "This is an image of a sunset in Japan."
)
val attachment = runBlocking { ditto.store.newAttachment(attachmentPathOrInputStream, attachmentMetadata) }
```

```csharp
var metadata = new Dictionary<string, string>()
{
    { "name", "japan.png" },
    { "description", "This is an image of a sunset in Japan." }
};
var newAttachmentWithMetadata = await Ditto.Store.NewAttachmentAsync(filePath, metadata);
```

```cpp
auto attachment = ditto.get_store().new_attachment("/path/to/my/file.pdf", {
    {"name", "japan.png"},
    {"description", "This is an image of a sunset in Japan."}
});
```

```rust
let user_data = HashMap::from_iter([
    ("name".into(), "japan.png".into()),
    (
        "thumbnail".into(),
        "/9j/4atg9y_zw0ga_x_bzd_w0g_zg9sb...".into(),
    ),
    (
        "description".into(), 
        "This is an image of a sunset in Japan.".into()
    ),        
]);

let _new_attachment_with_metadata = peer_a.store().new_attachment(filepath, user_data).await?;
```

```dart
// Coming Soon
```
:::

## Referencing Attachment Tokens

After creating and storing a new attachment object in Ditto, you receive an *attachment token* as part of the response.

:::ExpandableHeading
An attachment token is...

An attachment token is a pointer that references its associated `ATTACHMENT` object. This token is how you interact with the attachment, such as when fetching or linking it with a document.
:::

The following snippet demonstrates how to create a new document object containing a new attachment, and then insert it into the `cars` collection:

:::CodeblockTabs
```swift
// Create a new document object and store the attachment on the `my_attachment` field.
let newDocument: [String: Any] = ["_id": "123", "my_attachment": newAttachment]

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be declared as an `ATTACHMENT` data type
try await ditto.store.execute(
    query: """
        INSERT INTO COLLECTION cars (my_attachment ATTACHMENT)
        DOCUMENTS (:newDocument)
    """,
    arguments: ["newDocument": newDocument]
)
```

```kotlin
// Create a new document object and store the attachment on the `my_attachment` field.
val document = mapOf("some" to "string", "my_attachment" to attachment)
val insertQuery = "INSERT INTO COLLECTION cars (my_attachment ATTACHMENT) DOCUMENTS (:document)"

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be declared as an `ATTACHMENT` data type
val insertQuery = "INSERT INTO COLLECTION cars (my_attachment ATTACHMENT) DOCUMENTS (:document)"
val insertArguments = mapOf("document" to document)
val insertQueryResult = runBlocking { ditto.store.execute(insertQuery, insertArguments) }
```

```javascript
// Create a new document object and store the attachment on the `my_attachment` field.
const newDocument = { _id: "123", my_attachment: newAttachment }

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be defined as an ATTACHMENT data type
await ditto.store.execute(`
  INSERT INTO COLLECTION cars (my_attachment ATTACHMENT)
  DOCUMENTS (:newDocument)`,
  { newDocument }
);
```

```java
// Create a new document object and store the attachment on the `my_attachment` field.
val document = mapOf("some" to "string", "my_attachment" to attachment)
val insertQuery = "INSERT INTO COLLECTION cars (my_attachment ATTACHMENT) DOCUMENTS (:document)"

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be declared as an `ATTACHMENT` data type
val insertQuery = "INSERT INTO COLLECTION cars (my_attachment ATTACHMENT) DOCUMENTS (:document)"
val insertArguments = mapOf("document" to document)
val insertQueryResult = runBlocking { ditto.store.execute(insertQuery, insertArguments) }
```

```csharp
// Creating a Ditto Document with an Attachment
// Create a new document object and store the attachment on the `my_attachment` field.
var newDocument = new Dictionary<string, object>()
{
    { "_id", "123" },
    { "my_attachment", newAttachment }
};

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be declared as an `ATTACHMENT` data type
await ditto.Store.ExecuteAsync(
    query: @"
         INSERT INTO COLLECTION cars (my_attachment ATTACHMENT)
         DOCUMENTS (:newDocument)
         ",
    arguments: new Dictionary<string, object>() { { "newDocument", newDocument } }
);
```

```cpp
```

```rust
// Creating a Ditto document with an attachment
let new_document /*: impl Serialize */ = json!({
    "_id": "123",
    "my_attachment": new_attachment,
});

// Insert the new document into the collection
// Note that the `my_attachment` field needs to be declared as an `attachment` data type
peer_a
    .store()
    .execute(
        r#"
        INSERT INTO COLLECTION cars (my_attachment ATTACHMENT)
        DOCUMENTS (:new_document)
    "#,
        Some(
            json!({
                "new_document": new_document,
            })
            .into(),
        ),
    )
    .await?;
```

```dart
// Coming Soon
```
:::

# Creating MAPs

There are two ways to create a `MAP` structure within a document:

- In an `INSERT` operation — Create a new document and nest it with this set of fields.&#x20;
- In an `UPDATE` operation — If the `MAP` does not exist, create it. (See [UPDATE](docId\:LIuprvsTd4Fs75_E3jI3K))

To represent a highly complex data structure in a `MAP`, consider embedding it with an additional `MAP`. Embedding a `MAP` within a `MAP` establishes an additional hierarchy.&#x20;

The decision to use deeply embedded `MAPS` in a single document or opt for a *flat model* depends on your requirements, relationships between data, and tolerance for certain tradeoffs.&#x20;

:::hint{type="info"}
The flat model is a simple, non‑embedded structure in which you spread your data across multiple, separate documents.&#x20;
:::

## Inserting to Create a MAP

When inserting a new document in Ditto, you can define a field as a `MAP` and include the structure of key-value pairs nested within it — a two-in-one approach. For example:

:::CodeblockTabs
```swift
let arguments: [String: Any] = [
  "newCar": [
    "_id": "123",
    "properties": [
      "color": "blue",
      "mileage": 3000
    ]
  }
];

await ditto.store.execute(
  query: "INSERT INTO COLLECTION cars (properties MAP) DOCUMENTS (:newCar)",
  arguments: arguments);
```

```kotlin
val arguments = mapOf(
  "newCar" to mapOf(
    "_id" to "123",
    "properties" to mapOf(
      "color" to "blue",
      "mileage" to 3000
      )
    )
  )
)

ditto.store.execute("""
  INSERT INTO COLLECTION cars (properties MAP)
  DOCUMENTS (:newCar)
  """,
  arguments)
```

```javascript
const newCar = {
  _id: "123",
  properties: {
    color: 'blue',
    mileage: 3000
  }
}

await ditto.store.execute(`
  INSERT INTO COLLECTION cars (properties MAP)
  DOCUMENTS (:newCar)`,
  { newCar }
);
```

```java
Map<String, Object> properties = new HashMap<>();
properties.put("color", "blue");
properties.put("mileage", 3000);

Map<String, Object> newCar = new HashMap<>();
newCar.put("_id", "123");
newCar.put("properties", properties);

DittoQueryResult result = (DittoQueryResult) ditto.store.execute(
    "INSERT INTO COLLECTION cars (properties MAP) DOCUMENTS (:newCar)",
    Collections.singletonMap("newCar", newCar),
    new Continuation<>() {
        @NonNull
        @Override
        public CoroutineContext getContext() {
            return EmptyCoroutineContext.INSTANCE;
        }

        @Override
        public void resumeWith(@NonNull Object o) {
            if (o instanceof Result.Failure) {
                // Handle failure
            }
        }
    }
);
```

```csharp
var subMap = new {
  color = "blue",
  mileage = 3000
};
var insertArgs = new Dictionary<string, object>();
insertArgs.Add("newCar", new { _id = newId, properties = subMap })

var result = await ditto.Store.ExecuteAsync(
  "INSERT INTO COLLECTION cars (properties MAP) DOCUMENTS (:newCar)",
  insertArgs);
```

```cpp
struct Properties {
  std::string color;
  int mileage;
};
struct Car {
  std::string _id;
  Properties properties;
};

// ...

std::map<std::string, Car> args;
args["newCar"] = {"123", {"blue", 3000}};

ditto.get_store().execute(
  "INSERT INTO COLLECTION your_collection_name (properties MAP)"
+ " DOCUMENTS (:newCar)",
  args);
```

```rust
struct Args {
  newCar: Car,
}
struct Properties {
  color: String,
  mileage: i32
}
struct Car {
  _id: String,
  properties: Properties
}

// ...

let args = Args {
  newCar: Car {
    _id: "123".to_string(),
    properties: Properties {
      color: "blue".to_string(),
      mileage: 3000
    }
  },
};

await ditto.store().execute(
  "INSERT INTO COLLECTION cars (properties MAP) DOCUMENTS (:newCar)",
  args);
```

```dart
final newCar = {
  "_id": "123",
  "properties": {
    "color": 'blue',
    "mileage": 3000,
  },
};

await ditto.store.execute("""
  INSERT INTO COLLECTION cars (properties MAP) 
  DOCUMENTS (:newCar)""",
  arguments: {"newCar": newCar},
);
```
:::

Another method to creating a `MAP` within a document is to perform an `UPDATE` operation. &#x20;

In the `UPDATE` approach, you set the structure of key-value pairs and specify the document ID for storage.&#x20;

For example, this statement creates the `MAP` structure — unless it already exists — setting a single key-value pair of color is red within the properties `MAP` for the document with the ID 123 in the cars collection:

:::CodeblockTabs
DQL

```sql
UPDATE COLLECTION cars (properties MAP)
SET
  properties -> (
    color = 'red'
  )
WHERE
  _id = '123' 
```
:::