Timestamp overrides_

Set custom $createdAt and $updatedAt timestamps for your documents when using server SDKs.

2 min read

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

const sdk = require('node-appwrite');

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

const vectorsDB = new sdk.VectorsDB(client);

await vectorsDB.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(),
        embeddings: [0.12, 0.84, 0.33, 0.57],
        metadata: { title: 'Hamlet' }
    }
});

Update with custom timestamps

When updating documents, you can also set a custom $updatedAt timestamp. The existing $createdAt is preserved unless you provide a new one:

await vectorsDB.updateDocument({
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    data: {
        '$updatedAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        metadata: { title: 'Hamlet, revised' }
    }
});

Bulk operations

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

Bulk create

await vectorsDB.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(),
            embeddings: [0.1, 0.1, 0.1, 0.1],
            metadata: { batch: 1 }
        },
        {
            '$id': sdk.ID.unique(),
            '$createdAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            embeddings: [0.2, 0.2, 0.2, 0.2],
            metadata: { batch: 2 }
        }
    ]
});

Bulk upsert

await vectorsDB.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(),
            embeddings: [0.3, 0.3, 0.3, 0.3],
            metadata: { source: 'sync' }
        }
    ]
});

Common use cases

Custom timestamps are particularly useful in several scenarios:

Data migration

When migrating existing vectors from another system, you can preserve the original creation and modification times:

await vectorsDB.createDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documentId: sdk.ID.unique(),
  data: {
    '$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt': '<LAST_MODIFIED_ISO>',
    embeddings: [0.12, 0.84, 0.33, 0.57],
    metadata: { title: 'Imported post' }
  }
});

Backdating records

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

await vectorsDB.createDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documentId: sdk.ID.unique(),
  data: {
    '$createdAt': '2023-12-31T23:59:59.000Z',
    '$updatedAt': '2023-12-31T23:59:59.000Z',
    embeddings: [0.5, 0.5, 0.5, 0.5],
    metadata: { type: 'year-end-bonus', amount: 1000 }
  }
});

Synchronization

When synchronizing data between systems while maintaining timestamp consistency:

await vectorsDB.upsertDocument({
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    embeddings: [0.6, 0.6, 0.6, 0.6],
    metadata: { profile: 'external' }
  }
});

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.

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.