Merge pull request #8452 from kenjis/docs-query_builder

docs: improve query_builder

user_guide_src/source/database/query_builder.rst

@@ -878,6 +878,9 @@ insertBatch
 $builder->insertBatch()
 -----------------------
 
+Insert from Data
+^^^^^^^^^^^^^^^^
+
 Generates an insert 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:
@@ -890,6 +893,9 @@ The first parameter is an associative array of values.
 
 .. warning:: When you use ``RawSql``, you MUST escape the data manually. Failure to do so could result in SQL injections.
 
+Insert from a Query
+^^^^^^^^^^^^^^^^^^^
+
 You can also insert from a query:
 
 .. literalinclude:: query_builder/117.php
@@ -954,18 +960,26 @@ $builder->upsertBatch()
 
 .. versionadded:: 4.3.0
 
+Upsert from Data
+^^^^^^^^^^^^^^^^
+
 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
-constraint by default. Here is an example using an array:
+constraint by default.
+
+Here is an example using an array:
 
 .. literalinclude:: query_builder/108.php
 
 The first parameter is an associative array of values.
 
 .. note:: All values are escaped automatically producing safer queries.
 
+Upsert from a Query
+^^^^^^^^^^^^^^^^^^^
+
 You can also upsert from a query:
 
 .. literalinclude:: query_builder/115.php
@@ -1096,6 +1110,16 @@ Or as an array:
 You may also use the ``$builder->set()`` method described above when
 performing updates.
 
+$builder->getCompiledUpdate()
+-----------------------------
+
+This works exactly the same way as ``$builder->getCompiledInsert()`` except
+that it produces an **UPDATE** SQL string instead of an **INSERT** SQL string.
+
+For more information view documentation for `$builder->getCompiledInsert()`_.
+
+.. note:: This method doesn't work for batched updates.
+
 .. _update-batch:
 
 UpdateBatch
@@ -1141,16 +1165,6 @@ Since v4.3.0, you can also update from a query with the ``setQueryAsData()`` met
 
 .. note:: It is required to alias the columns of the select query to match those of the target table.
 
-$builder->getCompiledUpdate()
------------------------------
-
-This works exactly the same way as ``$builder->getCompiledInsert()`` except
-that it produces an **UPDATE** SQL string instead of an **INSERT** SQL string.
-
-For more information view documentation for ``$builder->getCompiledInsert()``.
-
-.. note:: This method doesn't work for batched updates.
-
 *************
 Deleting Data
 *************
@@ -1174,27 +1188,42 @@ the data to the first parameter of the method:
 If you want to delete all data from a table, you can use the ``truncate()``
 method, or ``emptyTable()``.
 
+$builder->getCompiledDelete()
+-----------------------------
+
+This works exactly the same way as ``$builder->getCompiledInsert()`` except
+that it produces a **DELETE** SQL string instead of an **INSERT** SQL string.
+
+For more information view documentation for `$builder->getCompiledInsert()`_.
+
 .. _delete-batch:
 
+DeleteBatch
+===========
+
 $builder->deleteBatch()
 -----------------------
 
 .. versionadded:: 4.3.0
 
+Delete from Data
+^^^^^^^^^^^^^^^^
+
 Generates a batch **DELETE** statement based on a set of data.
 
 .. literalinclude:: query_builder/118.php
 
 This method may be especially useful when deleting data in a table with a composite primary key.
 
-.. note:: SQLite does not support the use of ``where()``.
+.. note:: SQLite3 does not support the use of ``where()``.
+
+Delete from a Query
+^^^^^^^^^^^^^^^^^^^
 
 You can also delete from a query:
 
 .. literalinclude:: query_builder/119.php
 
-.. note:: ``$deleteBatch()`` can be used since v4.3.0.
-
 $builder->emptyTable()
 ----------------------
 
@@ -1213,14 +1242,6 @@ Generates a **TRUNCATE** SQL string and runs the query.
 .. note:: If the TRUNCATE command isn't available, ``truncate()`` will
     execute as "DELETE FROM table".
 
-$builder->getCompiledDelete()
------------------------------
-
-This works exactly the same way as ``$builder->getCompiledInsert()`` except
-that it produces a **DELETE** SQL string instead of an **INSERT** SQL string.
-
-For more information view documentation for ``$builder->getCompiledInsert()``.
-
 **********************
 Conditional Statements
 **********************