Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add query pushdown documentation #2339

Merged
merged 23 commits into from
Apr 12, 2023
Merged

Add query pushdown documentation #2339

Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
0c48048
init docs
noisersup Mar 31, 2023
1c470dd
Merge branch 'main' into pushdown-docs-1956
noisersup Mar 31, 2023
f8dd592
wip
noisersup Apr 4, 2023
331ea0b
Merge branch 'main' into pushdown-docs-1956
noisersup Apr 4, 2023
c80a70d
Merge branch 'main' into pushdown-docs-1956
AlekSi Apr 4, 2023
c687585
make docs less blogpost-ish
noisersup Apr 4, 2023
52580b1
Merge branch 'main' into pushdown-docs-1956
AlekSi Apr 5, 2023
e27b84a
Update website/docs/pushdown.md
noisersup Apr 6, 2023
160d5db
Update website/docs/pushdown.md
noisersup Apr 6, 2023
c0a598e
fix linters
noisersup Apr 6, 2023
7dbb7a1
sort linter rules order
noisersup Apr 6, 2023
cfcd489
change page order
noisersup Apr 6, 2023
054807c
Merge branch 'main' into pushdown-docs-1956
noisersup Apr 6, 2023
a9fd999
remove table of contents
noisersup Apr 7, 2023
39b9186
change order
noisersup Apr 11, 2023
8870034
change order
noisersup Apr 11, 2023
cde7162
Merge branch 'main' into pushdown-docs-1956
noisersup Apr 11, 2023
68f7c82
Merge branch 'main' into pushdown-docs-1956
noisersup Apr 11, 2023
3c994bd
add suggestion
noisersup Apr 12, 2023
9168c25
add suggestion
noisersup Apr 12, 2023
fcb12e7
Merge branch 'main' into pushdown-docs-1956
noisersup Apr 12, 2023
8c823ef
Update website/docs/pushdown.md
noisersup Apr 12, 2023
d630394
Merge branch 'main' into pushdown-docs-1956
Apr 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/docs/configuration/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
label: Configuration
position: 6
position: 7
link:
type: generated-index
description: >
Expand Down
2 changes: 1 addition & 1 deletion website/docs/contributing/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
label: Contributing to FerretDB
position: 11
position: 12
link:
type: generated-index
description: >
Expand Down
2 changes: 1 addition & 1 deletion website/docs/diff.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 7
sidebar_position: 8
slug: /diff/ # referenced in README.md and beacon
---

Expand Down
52 changes: 52 additions & 0 deletions website/docs/pushdown.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 not prefetching
unnecessary data to the database management system.
AlekSi marked this conversation as resolved.
Show resolved Hide resolved

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 proper SQL filters.
AlekSi marked this conversation as resolved.
Show resolved Hide resolved

:::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 on [FerretDB Slack](https://join.slack.com/t/ferretdb/shared_invite/zt-zqe9hj8g-ZcMG3~5Cs5u9uuOPnZB8~A)!
noisersup marked this conversation as resolved.
Show resolved Hide resolved

:::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 |
rumyantseva marked this conversation as resolved.
Show resolved Hide resolved
| ---------- | -------- | ------- | ---------------------- | -------- | -------- | ---------- | --------- | ------ | ------ | ------- | --------- | ----------- | ---------------------- |
| `=` | ✖️ | ✖️ | ⚠️ <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}
Fashander marked this conversation as resolved.
Show resolved Hide resolved

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 -->
2 changes: 1 addition & 1 deletion website/docs/reference/_category_.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
label: Reference
position: 10
position: 11
link:
type: generated-index
description: >
Expand Down
2 changes: 1 addition & 1 deletion website/docs/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 9
sidebar_position: 10
slug: /security/ # referenced in README.md
description: TLS and authentication
---
Expand Down
2 changes: 1 addition & 1 deletion website/docs/telemetry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
sidebar_position: 8
sidebar_position: 9
slug: /telemetry/ # referenced in many places; must not change
---

Expand Down