---
layout: article
title: Timestamp overrides
description: Set custom $createdAt and $updatedAt timestamps for your documents when using server SDKs.
---

When creating or updating documents, Appwrite automatically sets `$createdAt` and `$updatedAt` timestamps. However, there are scenarios where you might need to set these timestamps manually, such as when migrating data from another system or backfilling historical records.

**Server SDKs required**

To manually set `$createdAt` and `$updatedAt`, you must use a **server SDK** with an **API key**. These attributes can be passed inside the `data` parameter on any of the create, update, or upsert routes (single or bulk).

# Setting custom timestamps

You can override a document's timestamps by providing ISO 8601 strings (for example, `2025-08-10T12:34:56.000Z`) in the `data` payload. If these attributes are not provided, Appwrite will set them automatically.

Custom timestamps work with all document operations: create, update, upsert, and their bulk variants.

## Single document operations

When working with individual documents, you can set custom timestamps during create, update, and upsert operations.

### Create with custom timestamps

```server-nodejs
const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');

const documentsDB = new sdk.DocumentsDB(client);

await documentsDB.createDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: sdk.ID.unique(),
    data: {
        '$createdAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        '$updatedAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        // ...your attributes
    }
});
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\DocumentsDB;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$documentsDB = new DocumentsDB($client);

$documentsDB->createDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: ID::unique(),
    data: [
        '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        // ...your attributes
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let documentsDB = DocumentsDB(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let customDate = isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date()
let createdAt = isoFormatter.string(from: customDate)
let updatedAt = isoFormatter.string(from: customDate)

do {
    let created = try await documentsDB.createDocument(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documentId: "<DOCUMENT_ID>",
        data: [
            "$createdAt": createdAt,
            "$updatedAt": updatedAt,
            // ...your attributes
        ]
    )
    print("Created:", created)
} catch {
    print("Create error:", error)
}
```
```server-python
from appwrite.client import Client
from appwrite.services.documents_db import DocumentsDB
from appwrite.id import ID
from datetime import datetime, timezone

client = Client()
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
client.set_project('<PROJECT_ID>')
client.set_key('<API_KEY>')

documents_db = DocumentsDB(client)

iso = datetime(2025, 8, 10, 12, 34, 56, tzinfo=timezone.utc).isoformat()

documents_db.create_document(
        database_id='<DATABASE_ID>',
        collection_id='<COLLECTION_ID>',
        document_id=ID.unique(),
        data={
                '$createdAt': iso,
                '$updatedAt': iso,
                # ...your attributes
        }
)
```
```server-ruby
require 'appwrite'
require 'time'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

documents_db = DocumentsDB.new(client)

custom_date = Time.parse('2025-08-10T12:34:56.000Z').iso8601

documents_db.create_document(
    database_id: '<DATABASE_ID>',
    collection_id: '<COLLECTION_ID>',
    document_id: ID.unique(),
    data: {
        '$createdAt' => custom_date,
        '$updatedAt' => custom_date,
        # ...your attributes
    }
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

DocumentsDB documentsDB = new DocumentsDB(client);

string customDate = DateTimeOffset.Parse("2025-08-10T12:34:56.000Z").ToString("O");

await documentsDB.CreateDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: ID.Unique(),
    data: new Dictionary<string, object>
    {
        ["$createdAt"] = customDate,
        ["$updatedAt"] = customDate,
        // ...your attributes
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

DocumentsDB documentsDB = DocumentsDB(client);

String customDate = DateTime.parse('2025-08-10T12:34:56.000Z').toIso8601String();

await documentsDB.createDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: ID.unique(),
    data: {
        '\$createdAt': customDate,
        '\$updatedAt': customDate,
        // ...your attributes
    },
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.create_document(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        &ID::unique(),
        json!({
            "$createdAt": "2025-08-10T12:34:56.000Z",
            "$updatedAt": "2025-08-10T12:34:56.000Z"
            // ...your attributes
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```

### Update with custom timestamps

When updating documents, you can also set a custom `$updatedAt` timestamp:

```server-nodejs
await documentsDB.updateDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: {
        '$updatedAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        // ...your attributes
    }
});
```
```server-php
$documentsDB->updateDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: [
        '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        // ...your attributes
    ]
);
```
```server-python
from datetime import datetime, timezone

documents_db.update_document(
    database_id='<DATABASE_ID>',
    collection_id='<COLLECTION_ID>',
    document_id='<DOCUMENT_ID>',
    data={
        '$updatedAt': datetime(2025, 8, 10, 12, 34, 56, tzinfo=timezone.utc).isoformat(),
        # ...your attributes
    }
)
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let documentsDB = DocumentsDB(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let updatedAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let updated = try await documentsDB.updateDocument(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documentId: "<DOCUMENT_ID>",
        data: [
            "$updatedAt": updatedAt,
            // ...your attributes
        ]
    )
    print("Updated:", updated)
} catch {
    print("Update error:", error)
}
```
```server-ruby
require 'appwrite'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

documents_db = DocumentsDB.new(client)

custom_date = Time.parse('<CUSTOM_DATE>').iso8601

documents_db.update_document(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  document_id: '<DOCUMENT_ID>',
  data: {
    '$updatedAt' => custom_date,
    # ...your attributes
  }
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

DocumentsDB documentsDB = new DocumentsDB(client);

string customDate = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await documentsDB.UpdateDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    data: new Dictionary<string, object>
    {
        ["$updatedAt"] = customDate,
        // ...your attributes
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

DocumentsDB documentsDB = DocumentsDB(client);

String customDate = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await documentsDB.updateDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documentId: '<DOCUMENT_ID>',
  data: {
    '\$updatedAt': customDate,
    // ...your attributes
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.update_document(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        "<DOCUMENT_ID>",
        Some(json!({
            "$updatedAt": "2025-08-10T12:34:56.000Z"
            // ...your attributes
        })),
        None,
        None,
    ).await?;

    println!("Updated: {:?}", result);
    Ok(())
}
```

## Bulk operations

Custom timestamps also work with bulk operations, allowing you to set different timestamps for each document in the batch:

### Bulk create

```server-nodejs
await documentsDB.createDocuments({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        {
            '$id': sdk.ID.unique(),
            '$createdAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        },
        {
            '$id': sdk.ID.unique(),
            '$createdAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        }
    ]
});
```
```server-python
documents_db.create_documents(
        database_id='<DATABASE_ID>',
        collection_id='<COLLECTION_ID>',
        documents=[
            {
                '$id': ID.unique(),
                '$createdAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
                '$updatedAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
                # ...your attributes
            },
            {
                '$id': ID.unique(),
                '$createdAt': datetime(2024, 2, 1, tzinfo=timezone.utc).isoformat(),
                '$updatedAt': datetime(2024, 2, 1, tzinfo=timezone.utc).isoformat(),
                # ...your attributes
            }
        ]
)
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\DocumentsDB;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$documentsDB = new DocumentsDB($client);

$documentsDB->createDocuments(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        [
            '$id' => ID::unique(),
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
        [
            '$id' => ID::unique(),
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let documentsDB = DocumentsDB(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]

let first = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())
let second = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let bulkCreated = try await documentsDB.createDocuments(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documents: [
            [
                "$id": ID.unique(),
                "$createdAt": first,
                "$updatedAt": first,
                // ...your attributes
            ],
            [
                "$id": ID.unique(),
                "$createdAt": second,
                "$updatedAt": second,
                // ...your attributes
            ]
        ]
    )
    print("Bulk create:", bulkCreated)
} catch {
    print("Bulk create error:", error)
}
```
```server-ruby
require 'appwrite'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

documents_db = DocumentsDB.new(client)

first = Time.parse('<CUSTOM_DATE>').iso8601
second = Time.parse('<CUSTOM_DATE>').iso8601

documents_db.create_documents(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  documents: [
    {
      '$id' => ID.unique(),
      '$createdAt' => first,
      '$updatedAt' => first,
      # ...your attributes
    },
    {
      '$id' => ID.unique(),
      '$createdAt' => second,
      '$updatedAt' => second,
      # ...your attributes
    }
  ]
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

DocumentsDB documentsDB = new DocumentsDB(client);

string first = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");
string second = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await documentsDB.CreateDocuments(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documents: new List<object>
    {
        new Dictionary<string, object>
        {
            ["$id"] = ID.Unique(),
            ["$createdAt"] = first,
            ["$updatedAt"] = first,
            // ...your attributes
        },
        new Dictionary<string, object>
        {
            ["$id"] = ID.Unique(),
            ["$createdAt"] = second,
            ["$updatedAt"] = second,
            // ...your attributes
        }
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

DocumentsDB documentsDB = DocumentsDB(client);

String first = DateTime.parse('<CUSTOM_DATE>').toIso8601String();
String second = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await documentsDB.createDocuments(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documents: [
    {
      '\$id': ID.unique(),
      '\$createdAt': first,
      '\$updatedAt': first,
      // ...your attributes
    },
    {
      '\$id': ID.unique(),
      '\$createdAt': second,
      '\$updatedAt': second,
      // ...your attributes
    }
  ],
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.create_documents(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        vec![
            json!({
                "$id": ID::unique(),
                "$createdAt": "2024-01-01T00:00:00.000Z",
                "$updatedAt": "2024-01-01T00:00:00.000Z"
                // ...your attributes
            }),
            json!({
                "$id": ID::unique(),
                "$createdAt": "2024-02-01T00:00:00.000Z",
                "$updatedAt": "2024-02-01T00:00:00.000Z"
                // ...your attributes
            }),
        ],
        None,
    ).await?;

    println!("Bulk create: {:?}", result);
    Ok(())
}
```

### Bulk upsert

```server-nodejs
await documentsDB.upsertDocuments({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        {
            '$id': '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2025-01-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        }
    ]
});
```
```server-python
documents_db.upsert_documents(
    database_id='<DATABASE_ID>',
    collection_id='<COLLECTION_ID>',
    documents=[
        {
            '$id': '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
            '$updatedAt': datetime(2025, 1, 1, tzinfo=timezone.utc).isoformat(),
            # ...your attributes
        }
    ]
)
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\DocumentsDB;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$documentsDB = new DocumentsDB($client);

$documentsDB->upsertDocuments(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        [
            '$id' => '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let documentsDB = DocumentsDB(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let createdAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())
let updatedAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let bulkUpserted = try await documentsDB.upsertDocuments(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documents: [
            [
                "$id": "<DOCUMENT_ID_OR_NEW_ID>",
                "$createdAt": createdAt,
                "$updatedAt": updatedAt,
                // ...your attributes
            ]
        ]
    )
    print("Bulk upsert:", bulkUpserted)
} catch {
    print("Bulk upsert error:", error)
}
```
```server-ruby
require 'appwrite'
require 'time'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

documents_db = DocumentsDB.new(client)

custom_date = Time.parse('<CUSTOM_DATE>').iso8601

documents_db.upsert_documents(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  documents: [
    {
      '$id' => '<DOCUMENT_ID_OR_NEW_ID>',
      '$createdAt' => custom_date,
      '$updatedAt' => custom_date,
      # ...your attributes
    }
  ]
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

DocumentsDB documentsDB = new DocumentsDB(client);

string createdAt = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");
string updatedAt = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await documentsDB.UpsertDocuments(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documents: new List<object>
    {
        new Dictionary<string, object>
        {
            ["$id"] = "<DOCUMENT_ID_OR_NEW_ID>",
            ["$createdAt"] = createdAt,
            ["$updatedAt"] = updatedAt,
            // ...your attributes
        }
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

DocumentsDB documentsDB = DocumentsDB(client);

String createdAt = DateTime.parse('<CUSTOM_DATE>').toIso8601String();
String updatedAt = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await documentsDB.upsertDocuments(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documents: [
    {
      '\$id': '<DOCUMENT_ID_OR_NEW_ID>',
      '\$createdAt': createdAt,
      '\$updatedAt': updatedAt,
      // ...your attributes
    }
  ],
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.upsert_documents(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        vec![
            json!({
                "$id": "<DOCUMENT_ID_OR_NEW_ID>",
                "$createdAt": "2024-01-01T00:00:00.000Z",
                "$updatedAt": "2025-01-01T00:00:00.000Z"
                // ...your attributes
            }),
        ],
        None,
    ).await?;

    println!("Bulk upsert: {:?}", result);
    Ok(())
}
```

# Common use cases

Custom timestamps are particularly useful in several scenarios:

## Data migration
When migrating existing data from another system, you can preserve the original
creation and modification times:

```server-nodejs
await documentsDB.createDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: 'blog_posts',
  documentId: sdk.ID.unique(),
  data: {
    '$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt': '<LAST_MODIFIED_ISO>',
    title: '<TITLE>',
    content: '<CONTENT>'
  }
});
```
```server-php
$documentsDB->createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'blog_posts',
  documentId: ID::unique(),
  data: [
    '$createdAt' => '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt' => '<LAST_MODIFIED_ISO>',
    'title' => '<TITLE>',
    'content' => '<CONTENT>'
  ]
);
```
```server-swift
let _ = try await documentsDB.createDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "blog_posts",
  documentId: ID.unique(),
  data: [
    "$createdAt": "<ORIGINAL_CREATED_AT_ISO>",
    "$updatedAt": "<LAST_MODIFIED_ISO>",
    "title": "<TITLE>",
    "content": "<CONTENT>"
  ]
)
```
```server-python
documents_db.create_document(
  database_id='<DATABASE_ID>',
  collection_id='blog_posts',
  document_id=ID.unique(),
  data={
    '$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt': '<LAST_MODIFIED_ISO>',
    'title': '<TITLE>',
    'content': '<CONTENT>'
  }
)
```
```server-ruby
documents_db.create_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'blog_posts',
  document_id: ID.unique(),
  data: {
    '$createdAt' => '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt' => '<LAST_MODIFIED_ISO>',
    'title' => '<TITLE>',
    'content' => '<CONTENT>'
  }
)
```
```server-dotnet
await documentsDB.CreateDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "blog_posts",
  documentId: ID.Unique(),
  data: new Dictionary<string, object>
  {
    ["$createdAt"] = "<ORIGINAL_CREATED_AT_ISO>",
    ["$updatedAt"] = "<LAST_MODIFIED_ISO>",
    ["title"] = "<TITLE>",
    ["content"] = "<CONTENT>"
  }
);
```
```server-dart
await documentsDB.createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'blog_posts',
  documentId: ID.unique(),
  data: {
    '\$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '\$updatedAt': '<LAST_MODIFIED_ISO>',
    'title': '<TITLE>',
    'content': '<CONTENT>'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.create_document(
        "<DATABASE_ID>",
        "blog_posts",
        &ID::unique(),
        json!({
            "$createdAt": "<ORIGINAL_CREATED_AT_ISO>",
            "$updatedAt": "<LAST_MODIFIED_ISO>",
            "title": "<TITLE>",
            "content": "<CONTENT>"
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```

## Backdating records
For historical data entry or when creating records that represent past events:

```server-nodejs
await documentsDB.createDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: 'transactions',
  documentId: sdk.ID.unique(),
  data: {
    '$createdAt': '2023-12-31T23:59:59.000Z',
    '$updatedAt': '2023-12-31T23:59:59.000Z',
    amount: 1000,
    type: 'year-end-bonus'
  }
});
```
```server-php
$documentsDB->createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'transactions',
  documentId: ID::unique(),
  data: [
    '$createdAt' => '2023-12-31T23:59:59.000Z',
    '$updatedAt' => '2023-12-31T23:59:59.000Z',
    'amount' => 1000,
    'type' => 'year-end-bonus'
  ]
);
```
```server-swift
let _ = try await documentsDB.createDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "transactions",
  documentId: ID.unique(),
  data: [
    "$createdAt": "2023-12-31T23:59:59.000Z",
    "$updatedAt": "2023-12-31T23:59:59.000Z",
    "amount": 1000,
    "type": "year-end-bonus"
  ]
)
```
```server-python
documents_db.create_document(
  database_id='<DATABASE_ID>',
  collection_id='transactions',
  document_id=ID.unique(),
  data={
    '$createdAt': '2023-12-31T23:59:59.000Z',
    '$updatedAt': '2023-12-31T23:59:59.000Z',
    'amount': 1000,
    'type': 'year-end-bonus'
  }
)
```
```server-ruby
documents_db.create_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'transactions',
  document_id: ID.unique(),
  data: {
    '$createdAt' => '2023-12-31T23:59:59.000Z',
    '$updatedAt' => '2023-12-31T23:59:59.000Z',
    'amount' => 1000,
    'type' => 'year-end-bonus'
  }
)
```
```server-dotnet
await documentsDB.CreateDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "transactions",
  documentId: ID.Unique(),
  data: new Dictionary<string, object>
  {
    ["$createdAt"] = "2023-12-31T23:59:59.000Z",
    ["$updatedAt"] = "2023-12-31T23:59:59.000Z",
    ["amount"] = 1000,
    ["type"] = "year-end-bonus"
  }
);
```
```server-dart
await documentsDB.createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'transactions',
  documentId: ID.unique(),
  data: {
    '\$createdAt': '2023-12-31T23:59:59.000Z',
    '\$updatedAt': '2023-12-31T23:59:59.000Z',
    'amount': 1000,
    'type': 'year-end-bonus'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.create_document(
        "<DATABASE_ID>",
        "transactions",
        &ID::unique(),
        json!({
            "$createdAt": "2023-12-31T23:59:59.000Z",
            "$updatedAt": "2023-12-31T23:59:59.000Z",
            "amount": 1000,
            "type": "year-end-bonus"
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```

## Synchronization
When synchronizing data between systems while maintaining timestamp consistency:

```server-nodejs
await documentsDB.upsertDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: 'users',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    profile: '<PROFILE_DATA>'
  }
});
```
```server-php
$documentsDB->upsertDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'users',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  data: [
    '$updatedAt' => '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile' => '<PROFILE_DATA>'
  ]
);
```
```server-swift
let _ = try await documentsDB.upsertDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "users",
  documentId: "<DOCUMENT_ID_OR_NEW_ID>",
  data: [
    "$updatedAt": "<EXTERNAL_LAST_MODIFIED_ISO>",
    "profile": "<PROFILE_DATA>"
  ]
)
```
```server-python
documents_db.upsert_document(
  database_id='<DATABASE_ID>',
  collection_id='users',
  document_id='<DOCUMENT_ID_OR_NEW_ID>',
  data={
    '$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile': '<PROFILE_DATA>'
  }
)
```
```server-ruby
documents_db.upsert_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'users',
  document_id: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '$updatedAt' => '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile' => '<PROFILE_DATA>'
  }
)
```
```server-dotnet
await documentsDB.UpsertDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "users",
  documentId: "<DOCUMENT_ID_OR_NEW_ID>",
  data: new Dictionary<string, object>
  {
    ["$updatedAt"] = "<EXTERNAL_LAST_MODIFIED_ISO>",
    ["profile"] = "<PROFILE_DATA>"
  }
);
```
```server-dart
await documentsDB.upsertDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'users',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '\$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile': '<PROFILE_DATA>'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::documents_db::DocumentsDB;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let documents_db = DocumentsDB::new(&client);

    let result = documents_db.upsert_document(
        "<DATABASE_ID>",
        "users",
        "<DOCUMENT_ID_OR_NEW_ID>",
        Some(json!({
            "$updatedAt": "<EXTERNAL_LAST_MODIFIED_ISO>",
            "profile": "<PROFILE_DATA>"
        })),
        None,
        None,
    ).await?;

    println!("Upserted: {:?}", result);
    Ok(())
}
```

**Timestamp format and usage**

- Values must be valid ISO 8601 date-time strings (UTC recommended). Using `toISOString()` (JavaScript) or `datetime.isoformat()` (Python) is a good default.
- You can set either or both attributes as needed. If omitted, Appwrite sets them automatically.