X DevAPI User Guide for MySQL Shell in Python Mode

4.3.3 Collection.modify()

The modify(SearchConditionStr) function is for modifying documents in a collection, similar to an UPDATE statement for an SQL database. It takes a search condition string (SearchConditionStr) as a parameter to specify the documents that are to be modified—a detailed discussion on the SearchConditionStr can be found in Section 4.3.2, “Collection.find()”.

If one or more documents are matched by the search condition string, they are modified by any of these methods that are chained after the modify() method. They can be chained one after another and for multiple times:

Notes

  • The _id of a document cannot be modified or removed by the methods below.

  • For any methods below that take a DocPath expression as one of its arguments, the following rules apply:

    • Within the DocPath expression, any field names containing a space or a special character must be quoted; for example, set("name.'last name'", "Smith"), unset("name.'last%name'")

    • The DocPath expression cannot contain a wildcard token (either * or **).

    • The DocPath expression cannot be null or empty.

The following methods can be chained to the modification methods described above to configure the modification:

This is an example of using sort().limit() to limit modifications to the documents: 

mysql-js> myColl.find("name like '%Doe'");
{
    "_id": "000062b0faf90000000000000001",
    "name": "Jane Doe",
    "favorNum": [
        2,
        3
    ]
}
{
    "_id": "000062b372f80000000000000001",
    "name": "Bob Doe",
    "favorNum": [
        1,
        2
    ]
}
{
    "_id": "000062b372f80000000000000002",
    "name": "Mark Doe",
    "favorNum": [
        7,
        8
    ]
}
{
    "_id": "000062b372f80000000000000003",
    "name": "John Doe",
    "favorNum": [
        0,
        4
    ]
}
mysql-js> myColl.modify("name like '%Doe'").unset("favorNum").sort("name asc").limit(2);
Query OK, 2 items affected (0.0082 sec)

Rows matched: 2  Changed: 2  Warnings: 0
mysql-js> myColl.find("name like '%Doe'").sort('name asc');
{
    "_id": "000062b372f80000000000000001",
    "name": "Bob Doe"
}
{
    "_id": "000062b0faf90000000000000001",
    "name": "Jane Doe"
}
{
    "_id": "000062b372f80000000000000003",
    "name": "John Doe",
    "favorNum": [
        0,
        4
    ]
}
{
    "_id": "000062b372f80000000000000002",
    "name": "Mark Doe",
    "favorNum": [
        7,
        8
    ]
}
4 documents in set (0.0068 sec)

Parameter binding using bind() is also supported. The execute() function triggers the actual execution of the modify() operation. The following example illustrates the use of modify(): 

# Use the collection 'my_collection'
myColl = db.get_collection('my_collection')
# Add a new document to the collection 
myColl.add({ "name":"John Doe", "DOB":"1970-01-01", "Phone":1234567, "Standing": "Good" }).execute()

# Patch the added document, adding, removing, and changing some fields 
myColl.modify("name = 'John Doe'").patch({ "name": "Jane Doe", "DOB": None, "Phone": 9876543, "favorNums": [1,2,3,4,5] }).execute()

# Modify fields with different methods
myColl.modify("name like :param").set("Standing", "Bad").bind("param", "J%Doe").execute()
myColl.modify("name like :param").unset("Phone").bind("param", "J%Doe").execute()
myColl.modify("name like :param").array_insert("favorNums[1]", 7).bind("param", "J%Doe").execute()
myColl.modify("name like :param").array_append("favorNums", 99).bind("param", "J%Doe").execute()
myColl.modify("name like :param").unset("favorNums[2]").bind("param", "J%Doe").execute()

doc = myColl.find('name like :param').limit(1).bind('param', 'J%Doe').execute()

print(doc.fetch_one())

# The output looks like:
# {"Standing": "Bad", "_id": "0000626718c10000000000000005", "favorNums": [1, 7, 3, 4, 5, 99], "name": "Jane Doe"}

See also CollectionModifyFunction for the syntax of add() in EBNF.

MySQL Documentation Library