{"__v":2,"_id":"55097a8a4c7c3f2300aabf09","category":{"__v":16,"_id":"550974cc368a56170041475c","project":"55070e814bb83b2500ec9404","version":"550974cb368a561700414757","pages":["55097a674c7c3f2300aabf07","55097a8a4c7c3f2300aabf09","55097a92ad1f0523008ecbd4","55097a9faa9bd525001a065c","55097aa92dd6a11900e6e7b4","55097ab2ad1f0523008ecbd6","55097ac74c7c3f2300aabf0b","55097ace2dd6a11900e6e7b7","55097ad5dd77250d007369fa","55097adead1f0523008ecbd9","55097ae72dd6a11900e6e7b9","55097aefdd77250d007369fc","55097af8dd77250d00736a05","55097aff4c7c3f2300aabf0d","55097b07aa9bd525001a0660","55097b11dd77250d00736a07"],"reference":false,"createdAt":"2015-03-18T11:08:27.090Z","from_sync":false,"order":4,"slug":"database-interaction-through-models","title":"Database Interaction Through Models"},"project":"55070e814bb83b2500ec9404","user":"55070d24d30b3f190011b941","version":{"__v":1,"_id":"550974cb368a561700414757","forked_from":"55070e814bb83b2500ec9407","project":"55070e814bb83b2500ec9404","createdAt":"2015-03-18T12:51:23.709Z","releaseDate":"2015-03-18T12:51:23.709Z","categories":["550974cc368a561700414758","550974cc368a561700414759","550974cc368a56170041475a","550974cc368a56170041475b","550974cc368a56170041475c","550974cc368a56170041475d","550974cc368a56170041475e"],"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.4.0","version":"1.4"},"updates":[],"createdAt":"2015-03-18T13:15:54.811Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"order":3,"body":"When you have created or retrieved an object, you can save it to the database by calling its [save()](doc:save) method. This method returns `true` if the object passes all validations and the object was saved to the database. Otherwise, it returns `false`.\n\nThis chapter will focus on how to update records. Read the [Creating Records](doc:creating-records) chapter for more information about how to create new records.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"A Practical Example\"\n}\n[/block]\nLet's start with an example of getting a blog post from the database, updating its title, and saving it back:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset post = model(\\\"post\\\").findByKey(33)>\\n<cfset post.title = \\\"New version of Wheels just released\\\">\\n<cfset post.save()>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou can also change the values of one or more properties and save them to the database in one single call using the `update()` method, like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset post = model(\\\"post\\\").findByKey(33)>\\n<cfset post.update(title=\\\"New version of Wheels just released\\\")>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Updating Via struct Values\"\n}\n[/block]\nYou can also pass in name/value pairs to `update()` as a struct. The main reason this method accepts a struct is to allow you to easily use it with forms.\n\nThis is how it would look if you wanted to update the properties for a post based on a submitted form.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset post = model(\\\"post\\\").findByKey(params.key)>\\n<cfset post.update(params.post)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nIt's also possible to combine named arguments with a struct, but then you need to name the struct argument as `properties`.\n\nExample:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset post = model(\\\"post\\\").findByKey(params.key)>\\n<cfset\\n    post.update(\\n        title=\\\"New version of Wheels just released\\\", properties=params.post\\n    )\\n>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Combine Reading and Updating into a Single Call\"\n}\n[/block]\nTo cut down even more on lines of code, you can also combine the reading and saving of the objects by using the class-level methods [updateByKey()](doc:updatebykey) and [updateAll()](doc:updateall).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"The updateByKey() Method\"\n}\n[/block]\nGive the [updateByKey()](doc:updatebykey) method a primary key value (or several if you use composite keys) in the `key` argument, and it will update the corresponding record in your table with the properties you give it. You can pass in the properties either as named arguments or as a struct to the `properties` argument.\n\nThis method returns the object with the primary key value you specified. If the object does not pass validation, it will be returned anyway, but nothing will be saved to the database.\n\nBy default, [updateByKey()](doc:updatebykey) will fetch the object first and call the `update()` method on it, thus invoking any callbacks and validations you have specified for the model. You can change this behavior by passing in `instantiate=false`. Then it will just update the record from the table using a simple UPDATE query.\n\nAn example of using [updateByKey()](doc:updatebykey) by passing a struct:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset result = model(\\\"post\\\").updateByKey(33, params.post)>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nAnd an example of using [updateByKey()](doc:updatebykey) by passing named arguments:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset\\n    result = model(\\\"post\\\").updateByKey(\\n        id=33, title=\\\"New version of Wheels just released\\\", published=1\\n    )\\n>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Updating Multiple Rows with updateAll()\"\n}\n[/block]\nThe [updateAll()](doc:updateall) method allows you to update more than one record in a single call. You specify what records to update with the `where` argument and tell Wheels what updates to make using named arguments for the properties.\n\nThe `where` argument is used exactly as you specify it in the `WHERE` clause of the query (with the exception that Wheels automatically wraps everything properly in `cfqueryparam` tags). So make sure that you place those commas and quotes correctly!\n\nAn example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<cfset\\n    recordsReturned = model(\\\"post\\\").updateAll(\\n        published=1, publishedAt=Now(), where=\\\"published=0\\\"\\n    )\\n>\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nUnlike [updateByKey()](doc:updatebykey), the [updateAll()](doc:updateall) method will not instantiate the objects by default. That could be really slow if you wanted to update a lot of records at once.","excerpt":"Updating records in your database tables.","slug":"updating-records","type":"basic","title":"Updating Records"}

Updating Records

Updating records in your database tables.

When you have created or retrieved an object, you can save it to the database by calling its [save()](doc:save) method. This method returns `true` if the object passes all validations and the object was saved to the database. Otherwise, it returns `false`. This chapter will focus on how to update records. Read the [Creating Records](doc:creating-records) chapter for more information about how to create new records. [block:api-header] { "type": "basic", "title": "A Practical Example" } [/block] Let's start with an example of getting a blog post from the database, updating its title, and saving it back: [block:code] { "codes": [ { "code": "<cfset post = model(\"post\").findByKey(33)>\n<cfset post.title = \"New version of Wheels just released\">\n<cfset post.save()>", "language": "text" } ] } [/block] You can also change the values of one or more properties and save them to the database in one single call using the `update()` method, like this: [block:code] { "codes": [ { "code": "<cfset post = model(\"post\").findByKey(33)>\n<cfset post.update(title=\"New version of Wheels just released\")>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Updating Via struct Values" } [/block] You can also pass in name/value pairs to `update()` as a struct. The main reason this method accepts a struct is to allow you to easily use it with forms. This is how it would look if you wanted to update the properties for a post based on a submitted form. [block:code] { "codes": [ { "code": "<cfset post = model(\"post\").findByKey(params.key)>\n<cfset post.update(params.post)>", "language": "text" } ] } [/block] It's also possible to combine named arguments with a struct, but then you need to name the struct argument as `properties`. Example: [block:code] { "codes": [ { "code": "<cfset post = model(\"post\").findByKey(params.key)>\n<cfset\n post.update(\n title=\"New version of Wheels just released\", properties=params.post\n )\n>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Combine Reading and Updating into a Single Call" } [/block] To cut down even more on lines of code, you can also combine the reading and saving of the objects by using the class-level methods [updateByKey()](doc:updatebykey) and [updateAll()](doc:updateall). [block:api-header] { "type": "basic", "title": "The updateByKey() Method" } [/block] Give the [updateByKey()](doc:updatebykey) method a primary key value (or several if you use composite keys) in the `key` argument, and it will update the corresponding record in your table with the properties you give it. You can pass in the properties either as named arguments or as a struct to the `properties` argument. This method returns the object with the primary key value you specified. If the object does not pass validation, it will be returned anyway, but nothing will be saved to the database. By default, [updateByKey()](doc:updatebykey) will fetch the object first and call the `update()` method on it, thus invoking any callbacks and validations you have specified for the model. You can change this behavior by passing in `instantiate=false`. Then it will just update the record from the table using a simple UPDATE query. An example of using [updateByKey()](doc:updatebykey) by passing a struct: [block:code] { "codes": [ { "code": "<cfset result = model(\"post\").updateByKey(33, params.post)>", "language": "text" } ] } [/block] And an example of using [updateByKey()](doc:updatebykey) by passing named arguments: [block:code] { "codes": [ { "code": "<cfset\n result = model(\"post\").updateByKey(\n id=33, title=\"New version of Wheels just released\", published=1\n )\n>", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Updating Multiple Rows with updateAll()" } [/block] The [updateAll()](doc:updateall) method allows you to update more than one record in a single call. You specify what records to update with the `where` argument and tell Wheels what updates to make using named arguments for the properties. The `where` argument is used exactly as you specify it in the `WHERE` clause of the query (with the exception that Wheels automatically wraps everything properly in `cfqueryparam` tags). So make sure that you place those commas and quotes correctly! An example: [block:code] { "codes": [ { "code": "<cfset\n recordsReturned = model(\"post\").updateAll(\n published=1, publishedAt=Now(), where=\"published=0\"\n )\n>", "language": "text" } ] } [/block] Unlike [updateByKey()](doc:updatebykey), the [updateAll()](doc:updateall) method will not instantiate the objects by default. That could be really slow if you wanted to update a lot of records at once.