ExpressionEngine · intoeetive · Nov 30, 2023
diff --git a/docs/development/services/model/fetching.md b/docs/development/services/model/fetching.md
@@ -21,15 +21,15 @@ Use the `get()` method with a model name to begin a query:
 
     $builder = ee('Model')->get('Template');
 
-This will return a builder object, which we will use narrow down the selection. When you're ready to retrieve the matching data, call `all()`. You will be returned a [Collection](development/services/model/collection.md):
+This will return a [Query Builder](development/services/model/query-builder.md) object, which we will use narrow down the selection. When you're ready to retrieve the matching data, call `all()`. You will be returned a [Collection](development/services/model/collection.md):
 
     $templates = $builder->all();
 
 Usually these calls are chained for brevity:
 
     $templates = ee('Model')->get('Template')->all();
 
-NOTE: **Note:** Please see [Collection](development/services/model/collection.md) for list of methods to operate returned data.
+NOTE: **Note:** Please see [Query Builder](development/services/model/query-builder.md) for list of methods to build model query and [Collection](development/services/model/collection.md) for list of methods to operate returned data.
 
 ## Filters
 
@@ -203,3 +203,11 @@ In order to reduce memory usage, you can ask for only a subset of the available
       ->first();
 
 NOTE: **Note:** This method should only be used for querying data. It should not be used for models that will be edited, deleted, or passed to other code for processing.
+
+## Caching
+
+The queries are not cached by default. If you'll need to reuse same model query at a later time, you can specify boolean `true` as parameter for `->all()` or `->first()` methods:
+
+    $templates = ee('Model')->get('Template')->all(true);
+
+    $template = ee('Model')->get('Template')->first(true);
diff --git a/docs/development/services/model/query-builder.md b/docs/development/services/model/query-builder.md
@@ -0,0 +1,169 @@
+---
+lang: php
+---
+
+<!--
+    This source file is part of the open source project
+    ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
+
+    @link      https://expressionengine.com/
+    @copyright Copyright (c) 2003-2020, Packet Tide, LLC (https://packettide.com)
+    @license   https://expressionengine.com/license Licensed under Apache License, Version 2.0
+-->
+
+# Model Query Builder
+
+Model Query Builder class is providing a bridge between Model instance and the database by transforming PHP code into SQL queries.
+
+In order to use methods of this class, you need to have a [Model](development/services/model.html) instance. You can get a Model instance by using `ee('Model')` service and getting or making a new model.
+
+    $existingTemplate = ee('Model')->get('Template');
+
+    $newTemplate = ee('Model')->make('Template');
+
+## Method Reference
+
+**class `ExpressionEngine\Service\Model\Query\Builder`**
+
+[TOC=3]
+
+### `first($cache = FALSE)`
+
+Run the query limited to one result and return the first element in the [Collection](development/services/model/collection.md)
+
+| Parameter | Type    | Description                                            |
+| --------- | ------- | ------------------------------------------------------ |
+| \$cache   | `Bool`  | Whether the query results should be cached. Defaults to `false` |
+| Returns   | `Mixed` | The first element in the collection (or NULL if empty) |
+
+### `all($cache = FALSE)`
+
+Run the query and return the results as a [Collection](development/services/model/collection.md)
+
+| Parameter | Type    | Description                                            |
+| --------- | ------- | ------------------------------------------------------ |
+| \$cache   | `Bool`  | Whether the query results should be cached. Defaults to `false` |
+| Returns   | `Mixed` | All elements in the collection (or NULL if empty) |
+
+### `update()`
+
+Updates the model(s) data by running SQL `UPDATE` query.
+NOTE: It's not recommended to use this method directly. Use `save()` method of the model instead.
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| Returns   | `Void`  |                      |
+
+### `insert()`
+
+Inserts new database record for model by running SQL `INSERT` query.
+NOTE: It's not recommended to use this method directly. Use `save()` method of the model instead.
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| Returns   | `Void`  |                      |
+
+### `delete()`
+
+Delete the model(s) from database by running SQL `DELETE` query.
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| Returns   | `Void`  |                      |
+
+### `count()`
+
+Get the number of records that match criterias by running SQL `COUNT` query
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| Returns   | `Int`   | The number of matching models |
+
+### `search($properties, $value)`
+
+Performs search using `LIKE` operator on specified columns.
+Subsequent calls to this method will be chained with `AND` operator.
+
+| Parameter | Type      | Description          |
+| --------- | --------- | -------------------- |
+| \$properties | `String|Array`  | Model property name, or array of property names |
+| \$value | `String`  | String value to search |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `filter($property, $operator = '==', $value = NULL)`
+
+Filter the query by adding a `WHERE` clause to the SQL query.
+Note: when third parameter is omited, second parameter is used as value and `==` operator is used.
+Subsequent calls to this method will be chained with `AND` operator.
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| \$property | `String`  | Model property name |
+| \$operator | `String`  | Comparison operator. (List of supported operators)[development/services/model/fetching.md#available-filters]. Defaults to `==` |
+| \$value | `String`  | Value to compare to |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `orFilter()`
+
+Same as `filter()` but chained with `OR` operator.
+
+### `filterGroup()`
+
+Used to group filters with `AND` operator. Should be closed with `endFilterGroup()` method.
+
+### `orFilterGroup()`
+
+Used to group filters with `OR` operator. Should be closed with `endFilterGroup()` method.
+
+### `endFilterGroup()`
+
+Indicates the end of filter group.
+
+### `fields($field1, $field2, ...)`
+
+Limits the `SELECT` part of SQL query to only fetch certain model properties.
+
+### `set($property, $value)`
+
+Sets the model property with SQL `SET` so it could be saved to database later
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| \$property | `String`  | Model property name |
+| \$value | `String`  | New property value |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `with($relationship)`
+
+Adds [related model](development/services/model/fetching.md#relationships) to the query by performing SQL `JOIN`
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| \$property | `String|Array`  | Name of model relatioship, or deeply nested array of relationship names |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `order()`
+
+Name of property to order by, converted to SQL `ORDER BY` clause
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `limit($limit)`
+
+Limit the query by applying SQL `LIMIT` clause
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| \$limit | `Int`  | Number to limit by. Defaults to 2^64 |
+| Returns   | `Builder` | Modified instance of Query Builder |
+
+### `offset($offset)`
+
+Limit the query by applying offset to SQL `LIMIT` clause
+
+| Parameter | Type    | Description          |
+| --------- | ------- | -------------------- |
+| \$offset | `Int`  | Number to offset. Defaults to 0 |
+| Returns   | `Builder` | Modified instance of Query Builder |
diff --git a/docs/toc_sections/_advanced_usage_toc.yml b/docs/toc_sections/_advanced_usage_toc.yml
@@ -362,6 +362,8 @@
               href: development/services/model/fetching.md
             - name: Relationships
               href: development/services/model/relationships.md
+            - name: Query Builder
+              href: development/services/model/query-builder.md
             - name: Collections
               href: development/services/model/collection.md
             - name: Building your own Models