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") 會將 modify() 比對的所有文件取代為提供的 json_document但原始 _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 其中一個是純量,則將值 B 取代為值 A

    如果值 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'
var myColl = db.getCollection('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: null, 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").arrayInsert("favorNums[1]", 7).bind("param", "J%Doe").execute();
myColl.modify("name like :param").arrayAppend("favorNums", 99).bind("param", "J%Doe").execute();
myColl.modify("name like :param").unset("favorNums[2]").bind("param", "J%Doe").execute();

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

print(doc.fetchOne());
/* The output looks like: 
{
    "Standing": "Bad", 
    "_id": "0000626718c10000000000000002", 
    "favorNums": [
        1, 
        7, 
        3, 
        4, 
        5, 
        99
    ], 
    "name": "Jane Doe"
} */

有關 EBNF 中 add() 的語法,請參閱 CollectionModifyFunction