{"_id":"574c400a99ccd80e00195938","parentDoc":null,"user":"54774c47f3736008009e9e0c","__v":14,"category":{"_id":"5735a52431a73b1700887ca0","project":"54774d9af3736008009e9e0e","__v":0,"version":"56a0bd9e3697d80d002ac5e7","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-05-13T09:57:56.274Z","from_sync":false,"order":13,"slug":"data-objects","title":"Data Objects"},"version":{"_id":"56a0bd9e3697d80d002ac5e7","project":"54774d9af3736008009e9e0e","__v":20,"createdAt":"2016-01-21T11:14:38.131Z","releaseDate":"2016-01-21T11:14:38.131Z","categories":["56a0bd9f3697d80d002ac5e8","56a0bd9f3697d80d002ac5e9","56a0bd9f3697d80d002ac5ea","56a0bd9f3697d80d002ac5eb","56b098a43a5b810d00745e3f","56b098da8f7a4f0d0029dd10","56d5a8ecf612b80b00fb69cd","570989853ab43c0e0072b2d6","571006aa10300c0e007f6133","5735a52431a73b1700887ca0","5744b0529e045c0e00b7a7a2","5744b1d0b56d431700d8a4fb","5744b1fb55d65a0e00b436e1","5744b218f9c7411700ce560e","5744b220f9c7411700ce560f","5744b2259e045c0e00b7a7a7","5744b22cf8b79f0e00de6a2d","5744b23155d65a0e00b436e4","5744b242c758290e00fbc235","5744b2569e045c0e00b7a7a8","5756a3f2bb92962900dafe3d","57ee23e81e42900e0014a42f","581c822c98676e0f00d240ef"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"Sockets","version_clean":"1.1.0","version":"1.1"},"project":"54774d9af3736008009e9e0e","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-05-30T13:28:42.315Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nAs you already know, Data Objects can have various custom field types (read about it [here](classes#section-types-of-class-schema-fields)). One of the possible types is an `array`. If you choose to add this field you can not only set the field value but also add or remove particular elements of an array.\n\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Add, Add Unique and Remove\"\n}\n[/block]\nThere are 3 possible operations you can currently perform on array fields:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`_add`\",\n    \"1-0\": \"`_addunique`\",\n    \"2-0\": \"`_remove`\",\n    \"0-2\": \"Appends the given array of objects to the end of an array field.\",\n    \"1-2\": \"Adds only the given objects which aren't already contained in an array field to that field. The position of the insert is not guaranteed.\",\n    \"2-2\": \"Removes all instances of each given object from an array field.\",\n    \"h-0\": \"Oerator\",\n    \"h-1\": \"Example\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"{\\\"_add\\\": [123, 456]}\",\n    \"1-1\": \"{\\\"_addunique\\\": [123, 456]}\",\n    \"2-1\": \"{\\\"_remove\\\": [123, 456]}\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Elements in an array are type and case sensitive so \\\"this\\\" =/= \\\"This\\\" and 1 =/= \\\"1\\\" etc.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Examples\"\n}\n[/block]\n## Add\nLet's say I have a `Car` Data Object with an array field that contains years when the car was manufactured. Since the car is still being produced, I'd like to add another year to an array. This is how such a call will look like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"X-API-KEY: API_KEY\\\" \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-d '{\\\"manufactured\\\": {\\\"_add\\\":[2016]}}' \\\\\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"Car *car = [Car new];\\n[car addArrayOfObjects::::at:::[@2016] forArrayWithKey:@\\\"manufactured\\\" withCompletion:^(NSError * _Nullable error) {\\n    // Handle error\\n}];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"let book:Book = Book()\\nbook.addArray(of: [2016], forArrayWithKey: \\\"manufactured\\\") { (error) in\\n    //handle error\\n}\\n\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nThe response will return the Data Object with an updated `manufactured` array field:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// some built-in fields skipped for brevity\\n{\\n    \\\"id\\\": 11,\\n    \\\"brand\\\": \\\"Lincoln\\\",\\n    \\\"model\\\": \\\"MKT\\\"\\n    \\\"manufactured\\\": [\\n        2016,\\n        2015,\\n        2014,\\n        2013,\\n        2012,\\n        2011,\\n        2010\\n    ],\\n    \\\"revision\\\": 5,\\n    \\\"updated_at\\\": \\\"2016-05-31T12:14:24.503740Z\\\",\\n    \\\"created_at\\\": \\\"2016-05-31T12:08:39.304228Z\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Add Unique\nThe above example works well when we know what years are already in the array. If I'm not sure whether I added a year or not, instead of getting the Data Object and iterating over it's fields I could simply use `_addunique` operator. Let's say I have a car with this array:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"manufactured\\\": [2015,2014,2013,2012,2011,2010]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAnd I want to add these years: `2016`,`2015`,`2014`\n\nThis how I'll make a call to Syncano:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"X-API-KEY: API_KEY\\\" \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-d '{\\\"manufactured\\\": {\\\"_addunique\\\":[2016,2015,2014]}}' \\\\\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"Car *car = [Car new];\\n[car addUniqueArrayOfObjects:@[@2016,@2015,@2014] forArrayWithKey:@\\\"manufactured\\\" withCompletion:^(NSError * _Nullable error) {\\n    // Handle error\\n}];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"let car:Car = Car()\\ncar.addUniqueArray(of: [2016,2015,2014], forArrayWithKey: \\\"manufactured\\\") { (error) in\\n    //handle error\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nSince only `2016` isn't duplicated, It will be added to the array. Rest of the values will be omitted:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// some built-in fields skipped for brevity\\n{\\n    \\\"id\\\": 11,\\n    \\\"brand\\\": \\\"Lincoln\\\",\\n    \\\"model\\\": \\\"MKT\\\"\\n    \\\"manufactured\\\": [\\n        2016,\\n        2015,\\n        2014,\\n        2013,\\n        2012,\\n        2011,\\n        2010\\n    ],\\n    \\\"revision\\\": 5,\\n    \\\"updated_at\\\": \\\"2016-05-31T12:14:24.503740Z\\\",\\n    \\\"created_at\\\": \\\"2016-05-31T12:08:39.304228Z\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n## Remove\n\nAs you probably guessed, `_remove` allows for deleting elements from an array. This is how such a call could look like:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST \\\\\\n-H \\\"X-API-KEY: API_KEY\\\" \\\\\\n-H \\\"Content-type: application/json\\\" \\\\\\n-d '{\\\"manufactured\\\": {\\\"remove\\\":[2016,2015,2014]}}' \\\\\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"Car *car = [Car new];\\n[car removeArrayOfObjects:@[@2016,@2015,@2014] fromArrayWithKey:@\\\"manufactured\\\" withCompletion:^(NSError * _Nullable error) {\\n    // Handle error\\n}];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"let book:Book = Book()\\nbook.removeArray(of: [2016,2015,2014], fromArrayWithKey: \\\"manufactured\\\") { (error) in\\n    //handle error\\n}\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nAnd the updated Data Object will have `2016`, `2015` and `2014` elements removed:\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// some built-in fields skipped for brevity\\n{\\n    \\\"id\\\": 11,\\n    \\\"brand\\\": \\\"Lincoln\\\",\\n    \\\"model\\\": \\\"MKT\\\"\\n    \\\"manufactured\\\": [\\n        2013,\\n        2012,\\n        2011,\\n        2010\\n    ],\\n    \\\"revision\\\": 5,\\n    \\\"updated_at\\\": \\\"2016-05-31T12:14:24.503740Z\\\",\\n    \\\"created_at\\\": \\\"2016-05-31T12:08:39.304228Z\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"In this chapter you will learn how to add or remove specific elements in your Data Object's array field","slug":"array-operations","type":"basic","title":"Array operations"}

Array operations

In this chapter you will learn how to add or remove specific elements in your Data Object's array field

[block:api-header] { "type": "basic", "title": "Overview" } [/block] As you already know, Data Objects can have various custom field types (read about it [here](classes#section-types-of-class-schema-fields)). One of the possible types is an `array`. If you choose to add this field you can not only set the field value but also add or remove particular elements of an array. [block:api-header] { "type": "basic", "title": "Add, Add Unique and Remove" } [/block] There are 3 possible operations you can currently perform on array fields: [block:parameters] { "data": { "0-0": "`_add`", "1-0": "`_addunique`", "2-0": "`_remove`", "0-2": "Appends the given array of objects to the end of an array field.", "1-2": "Adds only the given objects which aren't already contained in an array field to that field. The position of the insert is not guaranteed.", "2-2": "Removes all instances of each given object from an array field.", "h-0": "Oerator", "h-1": "Example", "h-2": "Description", "0-1": "{\"_add\": [123, 456]}", "1-1": "{\"_addunique\": [123, 456]}", "2-1": "{\"_remove\": [123, 456]}" }, "cols": 3, "rows": 3 } [/block] [block:callout] { "type": "info", "body": "Elements in an array are type and case sensitive so \"this\" =/= \"This\" and 1 =/= \"1\" etc." } [/block] [block:api-header] { "type": "basic", "title": "Examples" } [/block] ## Add Let's say I have a `Car` Data Object with an array field that contains years when the car was manufactured. Since the car is still being produced, I'd like to add another year to an array. This is how such a call will look like: [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"X-API-KEY: API_KEY\" \\\n-H \"Content-type: application/json\" \\\n-d '{\"manufactured\": {\"_add\":[2016]}}' \\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/", "language": "curl" }, { "code": "Car *car = [Car new];\n[car addArrayOfObjects:@[@2016] forArrayWithKey:@\"manufactured\" withCompletion:^(NSError * _Nullable error) {\n // Handle error\n}];", "language": "objectivec" }, { "code": "let book:Book = Book()\nbook.addArray(of: [2016], forArrayWithKey: \"manufactured\") { (error) in\n //handle error\n}\n", "language": "swift" } ] } [/block] The response will return the Data Object with an updated `manufactured` array field: [block:code] { "codes": [ { "code": "// some built-in fields skipped for brevity\n{\n \"id\": 11,\n \"brand\": \"Lincoln\",\n \"model\": \"MKT\"\n \"manufactured\": [\n 2016,\n 2015,\n 2014,\n 2013,\n 2012,\n 2011,\n 2010\n ],\n \"revision\": 5,\n \"updated_at\": \"2016-05-31T12:14:24.503740Z\",\n \"created_at\": \"2016-05-31T12:08:39.304228Z\"\n}", "language": "json" } ] } [/block] ## Add Unique The above example works well when we know what years are already in the array. If I'm not sure whether I added a year or not, instead of getting the Data Object and iterating over it's fields I could simply use `_addunique` operator. Let's say I have a car with this array: [block:code] { "codes": [ { "code": "\"manufactured\": [2015,2014,2013,2012,2011,2010]", "language": "json" } ] } [/block] And I want to add these years: `2016`,`2015`,`2014` This how I'll make a call to Syncano: [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"X-API-KEY: API_KEY\" \\\n-H \"Content-type: application/json\" \\\n-d '{\"manufactured\": {\"_addunique\":[2016,2015,2014]}}' \\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/", "language": "curl" }, { "code": "Car *car = [Car new];\n[car addUniqueArrayOfObjects:@[@2016,@2015,@2014] forArrayWithKey:@\"manufactured\" withCompletion:^(NSError * _Nullable error) {\n // Handle error\n}];", "language": "objectivec" }, { "code": "let car:Car = Car()\ncar.addUniqueArray(of: [2016,2015,2014], forArrayWithKey: \"manufactured\") { (error) in\n //handle error\n}", "language": "swift" } ] } [/block] Since only `2016` isn't duplicated, It will be added to the array. Rest of the values will be omitted: [block:code] { "codes": [ { "code": "// some built-in fields skipped for brevity\n{\n \"id\": 11,\n \"brand\": \"Lincoln\",\n \"model\": \"MKT\"\n \"manufactured\": [\n 2016,\n 2015,\n 2014,\n 2013,\n 2012,\n 2011,\n 2010\n ],\n \"revision\": 5,\n \"updated_at\": \"2016-05-31T12:14:24.503740Z\",\n \"created_at\": \"2016-05-31T12:08:39.304228Z\"\n}", "language": "json" } ] } [/block] ## Remove As you probably guessed, `_remove` allows for deleting elements from an array. This is how such a call could look like: [block:code] { "codes": [ { "code": "curl -X POST \\\n-H \"X-API-KEY: API_KEY\" \\\n-H \"Content-type: application/json\" \\\n-d '{\"manufactured\": {\"remove\":[2016,2015,2014]}}' \\\nhttps://api.syncano.io/v1.1/instances/INSTANCE_NAME/classes/cars/objects/11/", "language": "curl" }, { "code": "Car *car = [Car new];\n[car removeArrayOfObjects:@[@2016,@2015,@2014] fromArrayWithKey:@\"manufactured\" withCompletion:^(NSError * _Nullable error) {\n // Handle error\n}];", "language": "objectivec" }, { "code": "let book:Book = Book()\nbook.removeArray(of: [2016,2015,2014], fromArrayWithKey: \"manufactured\") { (error) in\n //handle error\n}", "language": "swift" } ] } [/block] And the updated Data Object will have `2016`, `2015` and `2014` elements removed: [block:code] { "codes": [ { "code": "// some built-in fields skipped for brevity\n{\n \"id\": 11,\n \"brand\": \"Lincoln\",\n \"model\": \"MKT\"\n \"manufactured\": [\n 2013,\n 2012,\n 2011,\n 2010\n ],\n \"revision\": 5,\n \"updated_at\": \"2016-05-31T12:14:24.503740Z\",\n \"created_at\": \"2016-05-31T12:08:39.304228Z\"\n}", "language": "json" } ] } [/block]