Merge branch 'document-list-view-timeouts' into 'master'

Document slow list views and APIs

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/165890



Merged-by: Krasimir Angelov <kangelov@gitlab.com>
Approved-by: Adam Hegyi <ahegyi@gitlab.com>
Approved-by: Krasimir Angelov <kangelov@gitlab.com>
Co-authored-by: Dylan Griffith <dyl.griffith@gmail.com>

doc/development/database/query_performance.md

@@ -73,3 +73,21 @@ In `psql`:
 ```sql
 Buffers: shared hit=7202 read=121
 ```
+
+## Slow list views and APIs
+
+We often build filtered list views and APIs in GitLab which need to have many
+different filter and sorting options. All these options are usually
+encapsulated in finders and exposed by API/GraphQL arguments. While we have many possible
+[pagination performance optimizations](pagination_performance_guidelines.md)
+, there is
+often no way to make all combinations of sorting and filtering performant.
+Attempts to make many options performant might involve
+[adding too many indexes](adding_database_indexes.md)
+which sacrifices performance of our primary database. This is only justified
+for common use cases and should not be considered as a way to make all
+permutations of filter and sort performant. What this means practically is that
+there will likely be filtered views and API requests that timeout when certain
+sorting or filtering options are applied. We still allow them to be added by
+teams where they benefit certain customers with specific combinations of
+filtering/sorting, but we need to accept that they will timeout for some users.