Update operators for collections

Some Data API commands, like Update a document, Update documents, and Find and update a document, use update operators to modify documents in a collection.

Field update operators

You can use the following operators to update fields in a document. All operators are case-sensitive.

Set

The $set operator sets the value of the specified field to the specified value.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$set": {"number_of_pages": 423, "rating": "4.5"}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $set: { number_of_pages: 423, rating: "4.5" } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().set("number_of_pages", 423).set("rating", 4.5);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$set": {
        "number_of_pages": 423,
        "rating": "4.5"
      }
    }
  }
}'

Set on insert

The $setOnInsert operator sets the value of the specified field only if an upsert is performed.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {"$and": [{"title": "Name of the Mountain"}, {"author": "Gina Marlin"}]},
    {"$setOnInsert": {"rating": 5.0, "is_checked_out": False}},
    upsert=True,
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $setOnInsert: { rating: 5.0, is_checked_out: false } },
    { upsert: true },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.options.CollectionUpdateOneOptions;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Map;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Name of the Mountain"), Filters.eq("author", "Gina Marlin"));

    Update update = Update.create().setOnInsert(Map.of("rating", 5.0, "is_checked_out", false));

    CollectionUpdateOneOptions options = new CollectionUpdateOneOptions().upsert(true);

    CollectionUpdateResult result = collection.updateOne(filter, update, options);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
    System.out.println(result.getUpsertedId());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Name of the Mountain"},
      {"author": "Gina Marlin"}
    ]},
    "update": {
      "$setOnInsert": {
        "rating": 5.0,
        "is_checked_out": false
      }
    },
    "options": { "upsert": true }
  }
}'

Unset

The $unset operator removes the specified field.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$unset": {"borrower": "", "due_date": ""}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $unset: { borrower: "", due_date: "" } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().unset("borrower").unset("due_date");

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$unset": {
        "borrower": "",
        "due_date": ""
      }
    }
  }
}'

Current date

The $currentDate operator sets the value of the specified field to the current date and time.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$currentDate": {"due_date": True}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $currentDate: { due_date: true } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().currentDate("due_date");

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$currentDate": {
        "due_date": true
      }
    }
  }
}'

Increment

The $inc operator increments the value of the specified field by the specified amount.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$inc": {"number_of_pages": 25}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $inc: { number_of_pages: 25 } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().inc("number_of_pages", 25.0);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$inc": {
        "number_of_pages": 25
      }
    }
  }
}'

Minimum

The $min operator updates the specified field only if the specified value is less than the existing field value.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$min": {"rating": 3.9}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $min: { rating: 3.9 } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().min("rating", 3.9);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$min": {
        "rating": 3.9
      }
    }
  }
}'

Maximum

The $max operator updates the specified field only if the specified value is greater than the existing field value.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$max": {"rating": 3.9}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $max: { rating: 3.9 } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().max("rating", 3.9);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$max": {
        "rating": 3.9
      }
    }
  }
}'

Multiply

The $mul operator multiplies the value of the specified field.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$mul": {"rating": 1.2}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $mul: { rating: 1.2 } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Map;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().mul(Map.of("rating", 1.2));

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$mul": {
        "rating": 1.2
      }
    }
  }
}'

Rename

The $rename operator renames the specified field.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$rename": {"old_field": "new_field", "other_old_field": "other_new_field"}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $rename: { old_field: "new_field", other_old_field: "other_new_field" } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update =
        Update.create()
            .rename("old_field", "new_field")
            .rename("other_old_field", "other_new_field");

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$rename": {
        "old_field": "new_field",
        "other_old_field": "other_new_field"
      }
    }
  }
}'

Array update operators

You can use the following operators to update array values in documents. All operators are case-sensitive.

Add to set

The $addToSet operator adds an item to an array only if the item does not already exist in the array.

To append multiple items, use the $each operator.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$addToSet": {"genres": "SciFi"}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $addToSet: { genres: "SciFi" } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().addToSet("genres", "SciFi");

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$addToSet": {
        "genres": "SciFi"
      }
    }
  }
}'

Pop

The $pop operator removes the first or last item of the array, depending on the value of the operator. Use -1 to remove the first item. Use 1 to remove the last item.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$pop": {"genres": -1}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $pop: { genres: -1 } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().pop("genres", -1);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$pop": {
        "genres": -1
      }
    }
  }
}'

Push

The $push operator appends data to the field value. The specified field must be an array or must not yet exist.

If the specified field does not exist, the field is created, and the value is an array containing the pushed items.

Use $each to append multiple properties. Use $position to modify the position of the new items in the array.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$push": {"genres": "SciFi"}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $push: { genres: "SciFi" } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update = Update.create().push("genres", "SciFi");

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$push": {
        "genres": "SciFi"
      }
    }
  }
}'

Each

The $each operator modifies the $push and $addToSet operators to append multiple items.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$push": {"genres": {"$each": ["Mystery", "Fiction"]}}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $push: { genres: { $each: ["Mystery", "Fiction"] } } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Arrays;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update =
        Update.create().pushEach("genres", Arrays.asList("biology", "algebra", "swimming"), 0);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$push": {
        "genres": {
          "$each": ["Mystery", "Fiction"]
        }
      }
    }
  }
}'

Position

The $position operator modifies the $push operator to specify the position in the array to add items.

Use a positive $position value to count from the start of the array. For example, 2 inserts the items after the first two items in the array.
Use a negative $position value to count from the end of the array. For example, -2 inserts the items before the last two items in the array.
Use a $position value of 0 to insert items at the start of the array

When you use $position, the $each operator is required, even if you want to insert a single item at the specified position.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment


# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {
        "$and": [
            {"title": "Into Shadows of Tomorrow"},
            {"author": "Nicole Wright"},
        ]
    },
    {"$push": {"genres": {"$each": ["Mystery", "Fiction"], "$position": 3}}},
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.table("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    {
      $and: [
        { title: "Into Shadows of Tomorrow" },
        { author: "Nicole Wright" },
      ],
    },
    { $push: { genres: { $each: ["Mystery", "Fiction"], $position: 3 } } },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import java.util.Arrays;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    Collection<Document> collection =
        DataAPIClients.clientHCD("USERNAME", "PASSWORD")
            .getDatabase("API_ENDPOINT", "KEYSPACE_NAME")
            .getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter =
        Filters.and(
            Filters.eq("title", "Into Shadows of Tomorrow"), Filters.eq("author", "Nicole Wright"));

    Update update =
        Update.create().pushEach("genres", Arrays.asList("biology", "algebra", "swimming"), 3);

    CollectionUpdateResult result = collection.updateOne(filter, update);

    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {"$and": [
      {"title": "Into Shadows of Tomorrow"},
      {"author": "Nicole Wright"}
    ]},
    "update": {
      "$push": {
        "genres": {
          "$each": ["Mystery", "Fiction"],
          "$position": 3
        }
      }
    }
  }
}'

Combine operators

You can use multiple update operators in a single update.

Python
TypeScript
Java
curl

from astrapy import DataAPIClient
from astrapy.authentication import UsernamePasswordTokenProvider
from astrapy.constants import Environment

# Get an existing collection
client = DataAPIClient(environment=Environment.HCD)
database = client.get_database(
    "API_ENDPOINT",
    token=UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
)
collection = database.get_collection(
    "COLLECTION_NAME", keyspace="KEYSPACE_NAME"
)

# Update a document
result = collection.update_one(
    {"_id": "101"},
    {
        "$set": {"color": "blue", "classes": ["biology", "algebra", "swimming"]},
        "$unset": {"phone": ""},
        "$inc": {"age": 1},
    },
)

print(result)

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

// Get an existing collection
const client = new DataAPIClient({ environment: "hcd" });
const database = client.db("API_ENDPOINT", {
  token: new UsernamePasswordTokenProvider("USERNAME", "PASSWORD"),
});
const collection = database.collection("COLLECTION_NAME", {
  keyspace: "KEYSPACE_NAME",
});

// Update a document
(async function () {
  const result = await collection.updateOne(
    { _id: "101" },
    {
      $set: {
        color: "blue",
        classes: ["biology", "algebra", "swimming"],
      },
      $unset: {
        phone: "",
      },
      $inc: {
        age: 1,
      },
    },
  );

  console.log(result);
})();

import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIClients;
import com.datastax.astra.client.collections.Collection;
import com.datastax.astra.client.collections.commands.Update;
import com.datastax.astra.client.collections.commands.results.CollectionUpdateResult;
import com.datastax.astra.client.collections.definition.documents.Document;
import com.datastax.astra.client.core.query.Filter;
import com.datastax.astra.client.core.query.Filters;
import com.datastax.astra.client.databases.Database;
import java.util.Arrays;

public class Example {

  public static void main(String[] args) {
    // Get an existing collection
    DataAPIClient client = DataAPIClients.clientHCD("USERNAME", "PASSWORD");
    Database database = client.getDatabase("API_ENDPOINT", "KEYSPACE_NAME");
    Collection<Document> collection = database.getCollection("COLLECTION_NAME");

    // Update a document
    Filter filter = Filters.eq("_id", "101");
    Update update =
        Update.create()
            .set("color", "blue")
            .set("classes", Arrays.asList("biology", "algebra", "swimming"))
            .unset("phone")
            .inc("age", 1.0);
    CollectionUpdateResult result = collection.updateOne(filter, update);
    System.out.println(result.getMatchedCount());
    System.out.println(result.getModifiedCount());
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "updateOne": {
    "filter": {
      "_id": "101"
    },
    "update": {
        "$set": {
            "color": "blue",
            "classes": ["biology", "algebra", "swimming"]
            },
        "$unset": {
            "phone": ""
        },
        "$inc": {
          "age": 1
        }
    }
  }
}'