Merge pull request #7223 from kenjis/docs-improve-query_builder

docs: improve query_builder.rst

Author: samsonasik

user_guide_src/source/database/query_builder.rst

@@ -908,6 +908,8 @@ Upsert
 $builder->upsert()
 ------------------
 
+.. versionadded:: 4.3.0
+
 Generates an upsert string based on the data you supply, and runs the
 query. You can either pass an **array** or an **object** to the
 method. By default a constraint will be defined in order. A primary
@@ -929,6 +931,8 @@ The first parameter is an object.
 $builder->getCompiledUpsert()
 -----------------------------
 
+.. versionadded:: 4.3.0
+
 Compiles the upsert query just like ``$builder->upsert()`` but does not
 *run* the query. This method simply returns the SQL query as a string.
 
@@ -944,10 +948,12 @@ upsertBatch
 $builder->upsertBatch()
 -----------------------
 
+.. versionadded:: 4.3.0
+
 Generates an upsert string based on the data you supply, and runs the
 query. You can either pass an **array** or an **object** to the
 method. By default a constraint will be defined in order. A primary
-key will be selected first and then unique keys. Mysql will use any
+key will be selected first and then unique keys. MySQL will use any
 constraint by default. Here is an example using an array:
 
 .. literalinclude:: query_builder/108.php
@@ -960,13 +966,16 @@ You can also upsert from a query:
 
 .. literalinclude:: query_builder/115.php
 
-.. note:: ``setQueryAsData()`` can be used since v4.3.0.
+.. note:: The ``setQueryAsData()``, ``onConstraint()``, and ``updateFields()``
+    methods can be used since v4.3.0.
 
 .. note:: It is required to alias the columns of the select query to match those of the target table.
 
 $builder->onConstraint()
 ------------------------
 
+.. versionadded:: 4.3.0
+
 Allows manually setting constraint to be used for upsert. This does
 not work with MySQL because MySQL checks all constraints by default.
 
@@ -976,6 +985,9 @@ This method accepts a string or an array of columns.
 
 $builder->updateFields()
 ------------------------
+
+.. versionadded:: 4.3.0
+
 Allows manually setting the fields to be updated when performing upserts.
 
 .. literalinclude:: query_builder/110.php
@@ -1084,14 +1096,24 @@ UpdateBatch
 $builder->updateBatch()
 -----------------------
 
+.. note:: Since v4.3.0, the second parameter ``$index`` of ``updateBatch()`` has
+    changed to ``$constraints``. It now accepts types array, string, or ``RawSql``.
+
 Generates an update string based on the data you supply, and runs the query.
 You can either pass an **array** or an **object** to the method.
 Here is an example using an array:
 
 .. literalinclude:: query_builder/092.php
 
+.. note:: Since v4.3.0, the generated SQL structure has been Improved.
+
 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.
@@ -1104,7 +1126,8 @@ You can also update from a query:
 
 .. literalinclude:: query_builder/116.php
 
-.. note:: ``setQueryAsData()`` can be used since v4.3.0.
+.. note:: The ``setQueryAsData()``, ``onConstraint()``, and ``updateFields()``
+    methods can be used since v4.3.0.
 
 .. note:: It is required to alias the columns of the select query to match those of the target table.
 
@@ -1146,6 +1169,8 @@ method, or ``emptyTable()``.
 $builder->deleteBatch()
 -----------------------
 
+.. versionadded:: 4.3.0
+
 Generates a batch **DELETE** statement based on a set of data.
 
 .. literalinclude:: query_builder/118.php
@@ -1198,6 +1223,8 @@ When
 $builder->when()
 ----------------
 
+.. versionadded:: 4.3.0
+
 This allows modifying the query based on a condition without breaking out of the
 query builder chain. The first parameter is the condition, and it should evaluate
 to a boolean. The second parameter is a callable that will be ran
@@ -1223,6 +1250,8 @@ WhenNot
 $builder->whenNot()
 -------------------
 
+.. versionadded:: 4.3.0
+
 This works exactly the same way as ``$builder->when()`` except that it will
 only run the callable when the condition evaluates to ``false``, instead of ``true`` like ``when()``.
 
@@ -1415,6 +1444,8 @@ Class Reference
 
     .. php:method:: setQueryAsData($query[, $alias[, $columns = null]])
 
+        .. versionadded:: 4.3.0
+
         :param BaseBuilder|RawSql $query: Instance of the BaseBuilder or RawSql
         :param string|null $alias: Alias for query
         :param array|string|null $columns: Array or comma delimited string of columns in the query

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/115.php

@@ -7,7 +7,10 @@
 
 $additionalUpdateField = ['updated_at' => new RawSql('CURRENT_TIMESTAMP')];
 
-$sql = $builder->setQueryAsData($query)->onConstraint('email')->updateFields($additionalUpdateField, true)->upsertBatch();
+$sql = $builder->setQueryAsData($query)
+    ->onConstraint('email')
+    ->updateFields($additionalUpdateField, true)
+    ->upsertBatch();
 /* MySQLi produces:
     INSERT INTO `db_user` (`country`, `email`, `name`)
     SELECT user2.name, user2.email, user2.country

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
+ */