4.3.3 Collection.modify()

modify(SearchConditionStr) 函數用於修改集合中的文件,類似於 SQL 資料庫的 UPDATE 陳述式。它採用搜尋條件字串 (SearchConditionStr) 作為參數,以指定要修改的文件 — 有關 SearchConditionStr 的詳細討論,請參閱 第 4.3.2 節「Collection.find()」

如果搜尋條件字串符合一或多個文件,則會透過在 modify() 方法之後串連的任何這些方法來修改它們。它們可以一個接一個地串連,且可以多次串連

注意事項
  • 文件的 _id 無法透過下列方法修改或移除。

  • 對於下列任何採用 DocPath 運算式作為其中一個引數的方法,適用下列規則

    • DocPath 運算式中,任何包含空格或特殊字元的欄位名稱都必須以引號括住;例如,set("name.'last name'", "Smith")unset("name.'last%name'")

    • DocPath 運算式不能包含萬用字元符號(* 或 **)。

    • DocPath 運算式不能為 Null 或空白。

  • set("DocPath", ExprOrLiteral):使用運算式或常值 (ExprOrLiteral) 運算式表示的值來設定「文件路徑」(DocPath) 運算式所比對的元素。

    DocPath 運算式是一個 JSON 路徑運算式,用於識別 modify() 函數找到的文件中的一或多個 JSON 元素。請參閱第 4.3.2 節「Collection.find()」中,有關 JSON 路徑的討論。如果 DocPath 指定的元素不存在,則會將其作為新元素新增至文件中。

    ExprOrLiteral 指定要為 DocPath 代表的元素設定的值。它可以是下列任何一種

    • 常值。例如,10 或「John」。

    • 任何 X DevAPI 運算式,都包含在 expr() 函數中(或是針對 MySQL Shell 和某些連接器的 mysql.expr()),如此一來才不會被視為常值。以下是一些範例,這些範例並未詳盡列出使用 mysql.expr(運算式) 作為 ExprOrLiteral 的可能性

      • 另一個 DocPath,用於從正在修改的文件中選取值 (例如,set("favorNums[0]", mysqlx.expr("favorNums[1]")),或 set("name", mysqlx.expr("$.'last name'"))

      • 一個功能運算式,其中包含一或多個 運算式(例如,set("favorNums[0]", mysqlx.expr("abs(favorNums[1])")))。

      • 一個或多個由運算子連線的 運算式(例如,set("favorNums[0]", mysqlx.expr("favorNums[1]+favorNums[2]+favorNums[3]+3")),或 set("SameValueOrNot", mysqlx.expr("favorNums[1] = favorNums[2]")))。

      • JSON 文件 (例如,set("Greeting", mysqlx.expr("{'season':'winter', 'phrase': 'Happy Holiday'}"))

    注意事項

    set("$", mysqlx.expr("json_document") 會使用提供的 json_document 取代 modify() 符合的所有文件,除了原始的 _id 欄位之外,該欄位一旦在建立文件時設定就無法變更。

  • unset("DocPath[, DocPath] ..."):刪除由一或多個 DocPath 清單代表的一或多個欄位或陣列元素(例如,unset("name")unset("name.'last name'", name.'first name'")unset("favorNums[0]"))。

    如果未提供 DocPath,或 DocPath 為 $,則會傳回錯誤(如果要刪除整個文件,請改用 remove())。

    警告

    請注意,當取消設定或刪除多個陣列元素時,它們會一個接一個地被移除,因此陳述式中的相同陣列索引可能會因每個取消設定動作而參照不同的元素。移除陣列元素時請考慮這一點。例如,對於文件

    mysql-js> myColl.find("name = 'Ann'");
    {
        "_id": "00006239f74a0000000000000004",
        "name": "Ann",
        "favorNums": [
            1,
            2,
            3,
            4,
            5
        ]
    }

    下列陳述式並未如預期移除陣列的第一個和第二個元素

    mysql-js> myColl.modify("name = 'Ann'").unset("favorNums[0]","favorNums[1]");
    Query OK, 1 item affected (0.0038 sec)
    
    mysql-js> myColl.find("name = 'Ann'").fields("favorNums");
    {
        "favorNums": [
            2,
            4,
            5
        ]
    }
    1 document in set (0.0007 sec)

    而是移除陣列的第一個和第三個元素。若要刪除前兩個元素,您可以執行下列動作

    mysql-js> myColl.modify("name = 'Ann'").unset("favorNums[0]","favorNums[0]");
    Query OK, 1 item affected (0.0108 sec)
    
    Rows matched: 1  Changed: 1  Warnings: 0
    mysql-js > myColl.find("name = 'Ann'").fields("favorNums");
    {
        "favorNums": [
            3,
            4,
            5
        ]
    }
    1 document in set (0.0005 sec)

  • patch(Document):針對 modify() 比對的任何文件,以及作為參數提供的 JSON Document,執行合併修補。此作業會遵循網際網路工程任務組 (IETF) 建立的 JSON 合併修補 RFC 7396 規格。下表說明欄位的動作,這取決於兩個文件中欄位的狀態(請注意,這是一個遞迴作業)

    表 4.1 文件欄位的 JSON 修補合併

    原始文件中欄位的狀態 修補文件中欄位的狀態 要在原始文件中對欄位採取的動作
    任何值 值為 Null 移除欄位
    值 B 值 A (非 Null)

    如果值 A 或 B 其中一個是純量,則以值 A 取代值 B

    如果值 A 和 B 都是 JSON 物件,則使用此表格中所述的相同規則合併它們(也就是說,合併是針對 JSON 文件遞迴應用)。

    欄位不存在 值 A (非 Null) 新增具有值 A 的欄位
    值 C 欄位不存在 欄位不變更

    以下是使用 patch() 進行合併的簡單範例

    mysql-js> myColl.find("name = 'John Doe'");
    {
        "DOB": "1970-01-01",
        "_id": "0000626028c30000000000000002",
        "name": "John Doe",
        "Phone": 1234567,
        "Standing": "Good",
        "favorNums": {
           "a": 1,
           "b":2 
        }
    }
    1 document in set (0.0009 sec)
     
    mysql-js> myColl.modify("name = 'John Doe'")
        .patch({ name: "Jane Doe", DOB: null, Phone: 9876543, favorNums: { a: 3, b:4 } });
    Query OK, 1 item affected (0.0413 sec)
    
    Rows matched: 1  Changed: 1  Warnings: 0
     
    mysql-js> myColl.find("name = 'Jane Doe'");
    {
        "_id": "0000626028c30000000000000002",
        "name": "Jane Doe",
        "Phone": 9876543,
        "Standing": "Good",
        "favorNums": {
            "a": 3,
            "b": 4
        }
    }
    1 document in set (0.0008 sec)

  • arrayInsert(DocPath, ExprOrLiteral):將 ExprOrLiteral(請參閱上述說明)插入陣列中,其位置由 DocPath 識別,並將陣列中的任何後續值向右移動。例如:arrayInsert("favorNums[1]", 7)arrayInsert("favorNums[1]", {even: 2, odd: 3, irrational: 'pi'})。適用下列規則

    • 如果 DocPath 未識別陣列元素,則會傳回錯誤。

    • 如果 DocPath 識別陣列位置超出陣列末端,則該值會插入在陣列末端。

  • arrayAppend(DocPath, ExprOrLiteral):將 ExprOrLiteral 所代表的值附加到 DocPath 所識別的陣列末尾。例如,arrayAppend("favorNums", 555)

    請注意,如果 DocPath 指向純量或文件值,則該值會自動包裝在陣列中,而 ExprOrLiteral 所代表的值會被加入該陣列中。例如:

    mysql-js> myColl.find("name='Jane Doe'");
    {
        "_id": "000062b0faf90000000000000001",
        "name": "Jane Doe",
        "favorNum": 2
    }
    1 document in set (0.0011 sec)
    
    mysql-js> myColl.modify("name='Jane Doe'").arrayAppend("favorNum",3);
    Query OK, 1 item affected (0.0094 sec)
    
    Rows matched: 1  Changed: 1  Warnings: 0
    mysql-js> myColl.find("name='Jane Doe'");
    {
        "_id": "000062b0faf90000000000000001",
        "name": "Jane Doe",
        "favorNum": [
            2,
            3
        ]
    }
    1 document in set (0.0006 sec)

以下方法可以鏈接到上述修改方法,以配置修改行為:

  • sort(sortCriteriaList):根據 sortCriteriaList 對要修改的文件進行排序,sortCriteriaList 可以是逗號分隔的列表或 sortCriteria 的陣列。每個 sortCriteria 包含一個組件名稱和一個搜尋順序(asc 代表遞增,desc 代表遞減)。例如:

    • sort('name asc', 'age desc')

    • sort(['name asc', 'age desc'])

    此方法與 limit() 方法結合使用,以確定要修改哪些符合 modify(SearchConditionStr) 條件的文件。

  • limit(int):限制要修改的文件數量為 int。當鏈接在 sort() 之後時,只會修改排序列表中前 int 個文件。

以下是如何使用 sort().limit() 來限制修改文件的範例:

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)

也支援使用 bind() 進行參數綁定。execute() 函式觸發 modify() 操作的實際執行。以下範例說明如何使用 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"}

另請參閱 CollectionModifyFunction 以了解 EBNF 中 add() 的語法。