$date in collections

Python
TypeScript
Java
curl

The handling of datetime objects changed in Python client version 2.0.

DataStax recommends upgrading to the latest version of the Python client. For more information, see Data API client upgrade guide.

The Python client provides the DataAPITimestamp and DataAPIDate objects for storing dates. However, if you insert a document with a DataAPIDate value, the client will always return DataAPITimestamp. DataStax recommends that you use DataAPITimestamp instead of DataAPIDate for collections since equality filters on DataAPIDate may not behave as expected if the implicit conversion to DataAPITimestamp uses a different timezone than expected. The DataAPITime and DataAPIDuration objects cannot be used with collections. For more information, see Python client usage: Client custom data types.

The Python client also supports standard-library date and datetime. If you use a standard-library datetime that is not timezone-aware (or just a date, which is always timezone-naive), the client will raise an error by default. For more information, see Python client usage: DataAPITimestamp and datetimes.

from astrapy import DataAPIClient
from astrapy.data_types import DataAPITimestamp
from datetime import datetime

# Get an existing collection
client = DataAPIClient("APPLICATION_TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")

# Use DataAPITimestamp in insertions
collection.insert_one(
    {"when": DataAPITimestamp.from_string("2024-12-06T12:34:56.789Z")}
)
collection.insert_one({"registered_at": DataAPITimestamp.from_datetime(datetime.now())})

# Use $current date in an update
collection.update_one(
    {"registered_at": {"$exists": True}},
    {"$currentDate": {"last_reviewed": True}},
)

# Use DataAPITimestamp in an equality filter
collection.update_one(
    {"registered_at": DataAPITimestamp.from_string("2024-12-06T12:34:56.789Z")},
    {"$set": {"message": "happy Sunday!"}},
)

# Use DataAPITimestamp in a "less than" filter

collection.find_one(
    {"registered_at": {"$lt": DataAPITimestamp.from_string("2025-12-06T12:34:56.789Z")}}
)

# Print a document with a date
# Will print something like:
# {'registered_at': DataAPITimestamp(timestamp_ms=1733488496789 [2024-12-06T12:34:56.789Z])}
print(
    collection.find_one(
        {
            "registered_at": {
                "$lt": DataAPITimestamp.from_string("2025-12-06T12:34:56.789Z")
            }
        },
        projection={"_id": False},
    )
)

You can use standard JS Date objects anywhere in documents to represent dates and times. Read operations also return Date objects for document fields stored using { $date: number }.

The following example uses dates in insert, update, and find commands:

import { DataAPIClient } from "@datastax/astra-db-ts";

// Get an existing collection
const client = new DataAPIClient("APPLICATION_TOKEN");
const database = client.db("API_ENDPOINT");
const collection = database.collection("COLLECTION_NAME");

(async function () {
  // Use dates in insertions
  await collection.insertOne({ dateOfBirth: new Date(1394104654000) });
  await collection.insertOne({ dateOfBirth: new Date("1863-05-28") });

  // Use $currentDate in an update
  await collection.updateOne(
    {
      dateOfBirth: new Date("1863-05-28"),
    },
    {
      $set: { message: "Happy Birthday!" },
      $currentDate: { lastModified: true },
    },
  );

  // Use a date in a filter
  const found = await collection.findOne({
    dateOfBirth: { $lt: new Date("1900-01-01") },
  });
})();

The Data API uses the ejson standard to represents time-related objects. The Java client introduces custom serializers as three types of objects: java.util.Date, java.util.Calendar, java.util.Instant. You can use these objects in documents as well as filter clauses and update clauses.

The following example uses dates in insert, update, and find commands:

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Updates;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filters;
import java.time.Instant;
import java.util.Calendar;
import java.util.Date;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        new DataAPIClient("**APPLICATION_TOKEN**")
            .getDatabase("**API_ENDPOINT**")
            .getCollection("**COLLECTION_NAME**");

    Calendar calendar = Calendar.getInstance();

    // Use date in insertions
    collection.insertOne(new Document().append("registered_at", calendar));
    collection.insertOne(new Document().append("date_of_birth", new Date()));
    collection.insertOne(new Document().append("just_a_date", Instant.now()));

    // Use date in a filter
    collection.updateOne(
        Filters.eq("registered_at", calendar), Updates.set("message", "happy Sunday!"));
    collection.findOne(
        Filters.lt("date_of_birth", new Date(System.currentTimeMillis() - 1000 * 1000)));
  }
}

You can use $date to represent dates as Unix timestamps in the JSON payload of a Data API command:

"date_of_birth": { "$date": 1690045891 }

The following example includes a date in an insertOne command:

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "insertOne": {
    "document": {
      "$vector": [0.25, 0.25, 0.25, 0.25, 0.25],
      "date_of_birth": { "$date": 1690045891 }
    }
  }
}'

The following example uses the date to find and update a document with the updateOne command:

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {
      "date_of_birth": { "$date": 1690045891 }
    },
    "update": { "$set": { "message": "Happy birthday!" } }
  }
}'

The following example uses the $currentDate update operator to set a property to the current date:

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findOneAndUpdate": {
    "filter": { "_id": "doc1" },
    "update": {
      "$currentDate": {
        "createdAt": true
        }
      }
    }
}'

$date in collections

Was this helpful?

Give Feedback