docs: split sample code and add explanation

Author: kenjis

user_guide_src/source/database/query_builder.rst

@@ -1109,6 +1109,11 @@ Here is an example using an array:
 
 The first parameter is an associative array of values, the second parameter is the where key.
 
+Since v4.3.0, you can also use the ``setQueryAsData()``, ``onConstraint()``, and
+``updateFields()`` methods:
+
+.. literalinclude:: query_builder/120.php
+
 .. note:: All values except ``RawSql`` are escaped automatically producing safer queries.
 
 .. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.

user_guide_src/source/database/query_builder/092.php

@@ -14,28 +14,7 @@
         'date'   => 'Date 2',
     ],
 ];
-
 $builder->updateBatch($data, ['title', 'author']);
-
-// OR
-$builder->setData($data)->onConstraint('title, author')->updateBatch();
-
-// OR
-$builder->setData($data, null, 'u')
-    ->onConstraint(['`mytable`.`title`' => '`u`.`title`', 'author' => new RawSql('`u`.`author`')])
-    ->updateBatch();
-
-// OR
-foreach ($data as $row) {
-    $builder->setData($row);
-}
-$builder->onConstraint('title, author')->updateBatch();
-
-// OR
-$builder->setData($data, true, 'u')
-    ->onConstraint(new RawSql('`mytable`.`title` = `u`.`title` AND `mytable`.`author` = `u`.`author`'))
-    ->updateFields(['last_update' => new RawSql('CURRENT_TIMESTAMP()')], true)
-    ->updateBatch();
 /*
  * Produces:
  * UPDATE `mytable`
@@ -47,6 +26,5 @@
  * SET
  * `mytable`.`title` = `u`.`title`,
  * `mytable`.`name` = `u`.`name`,
- * `mytable`.`date` = `u`.`date`,
- * `mytable`.`last_update` = CURRENT_TIMESTAMP() // this only applies to the last scenario
+ * `mytable`.`date` = `u`.`date`
  */

user_guide_src/source/database/query_builder/120.php

@@ -0,0 +1,36 @@
+<?php
+
+use CodeIgniter\Database\RawSql;
+
+$builder->setData($data)->onConstraint('title, author')->updateBatch();
+
+// OR
+$builder->setData($data, null, 'u')
+    ->onConstraint(['`mytable`.`title`' => '`u`.`title`', 'author' => new RawSql('`u`.`author`')])
+    ->updateBatch();
+
+// OR
+foreach ($data as $row) {
+    $builder->setData($row);
+}
+$builder->onConstraint('title, author')->updateBatch();
+
+// OR
+$builder->setData($data, true, 'u')
+    ->onConstraint(new RawSql('`mytable`.`title` = `u`.`title` AND `mytable`.`author` = `u`.`author`'))
+    ->updateFields(['last_update' => new RawSql('CURRENT_TIMESTAMP()')], true)
+    ->updateBatch();
+/*
+ * Produces:
+ * UPDATE `mytable`
+ * INNER JOIN (
+ * SELECT 'Title 1' `title`, 'Author 1' `author`, 'Name 1' `name`, 'Date 1' `date` UNION ALL
+ * SELECT 'Title 2' `title`, 'Author 2' `author`, 'Name 2' `name`, 'Date 2' `date`
+ * ) `u`
+ * ON `mytable`.`title` = `u`.`title` AND `mytable`.`author` = `u`.`author`
+ * SET
+ * `mytable`.`title` = `u`.`title`,
+ * `mytable`.`name` = `u`.`name`,
+ * `mytable`.`date` = `u`.`date`,
+ * `mytable`.`last_update` = CURRENT_TIMESTAMP() // this only applies to the last scenario
+ */