Add query pushdown documentation (FerretDB#2339)

Closes FerretDB#1956.
fenogentov · Apr 17, 2023 · eb0cd70 · eb0cd70
1 parent 298d6c8
commit eb0cd70
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 6 deletions.
diff --git a/website/docs/configuration/_category_.yml b/website/docs/configuration/_category_.yml
@@ -1,6 +1,6 @@
 ---
 label: Configuration
-position: 6
+position: 7
 link:
   type: generated-index
   description: >

diff --git a/website/docs/contributing/_category_.yml b/website/docs/contributing/_category_.yml
@@ -1,6 +1,6 @@
 ---
 label: Contributing to FerretDB
-position: 11
+position: 12
 link:
   type: generated-index
   description: >

diff --git a/website/docs/diff.md b/website/docs/diff.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 slug: /diff/ # referenced in README.md and beacon
 ---
 

diff --git a/website/docs/pushdown.md b/website/docs/pushdown.md
@@ -0,0 +1,52 @@
+---
+sidebar_position: 6
+hide_table_of_contents: true
+---
+
+# Query pushdown
+
+**Query pushdown** is the method of optimizing a query by reducing the amount of data read and processed.
+It saves memory space, network bandwidth, and reduces the query execution time by moving some parts
+of the query execution closer to the data source.
+
+Initially FerretDB retrieved all data related to queried collection, and applies filters on its own, making
+it possible to implement complex logic safely and quickly.
+To make this process more efficient, we minimize the amount of incoming data, by applying WHERE clause on SQL queries.
+
+:::info
+You can learn more about query pushdown in our [blog post](https://blog.ferretdb.io/ferretdb-fetches-data-query-pushdown/).
+:::
+
+## Supported types and operators
+
+The following table shows all operators and types that FerretDB pushdowns on PostgreSQL backend.
+If filter uses type and operator, that's marked as pushdown-supported on this list,
+FerretDB will prefetch less data, resulting with more performent query.
+
+If your application requires better performance for specific operation,
+feel free to share this with us in our [community](/#community)!
+
+:::tip
+As query pushdown allows developers to implement query optimizations separately from the features,
+the table will be updated frequently.
+:::
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable MD001 MD033 MD051 -->
+|            | Object   | Array   | Double                 | String   | Binary   | ObjectID   | Boolean   | Date   | Null   | Regex   | Integer   | Timestamp   | Long                   |
+| ---------- | -------- | ------- | ---------------------- | -------- | -------- | ---------- | --------- | ------ | ------ | ------- | --------- | ----------- | ---------------------- |
+| `=`        | ✖️        | ✖️       | ⚠️ <sub>[[1]](#1)</sub> | ✅       | ✖️        | ✅         | ✅        | ✅     | ✖️      | ✖️       | ✅        | ✖️           | ⚠️ <sub>[[1]](#1)</sub> |
+| `$eq`      | ✖️        | ✖️       | ⚠️ <sub>[[1]](#1)</sub> | ✅       | ✖️        | ✅         | ✅        | ✅     | ✖️      | ✖️       | ✅        | ✖️           | ⚠️ <sub>[[1]](#1)</sub> |
+| `$gt`      | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+| `$gte`     | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+| `$lt`      | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+| `$lte`     | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+| `$in`      | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+| `$ne`      | ✖️        | ✖️       | ⚠️ <sub>[[1]](#1)</sub> | ✅       | ✖️        | ✅         | ✅        | ✅     | ✖️      | ✖️       | ✅        | ✖️           | ⚠️ <sub>[[1]](#1)</sub> |
+| `$nin`     | ✖️        | ✖️       | ✖️                      | ✖️        | ✖️        | ✖️          | ✖️         | ✖️      | ✖️      | ✖️       | ✖️         | ✖️           | ✖️                      |
+
+###### [1] {#1}
+
+Numbers outside the range of the safe IEEE 754 precision (`< -9007199254740991.0, 9007199254740991.0 >`),
+will prefetch all numbers larger/smaller than max/min value of the range.
+<!-- markdownlint-restore -->
diff --git a/website/docs/reference/_category_.yml b/website/docs/reference/_category_.yml
@@ -1,6 +1,6 @@
 ---
 label: Reference
-position: 10
+position: 11
 link:
   type: generated-index
   description: >

diff --git a/website/docs/security.md b/website/docs/security.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 slug: /security/ # referenced in README.md
 description: TLS and authentication
 ---

diff --git a/website/docs/telemetry.md b/website/docs/telemetry.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 slug: /telemetry/ # referenced in many places; must not change
 ---