github.com/cozy/cozy-stack@v0.0.0-20240327093429-939e4a21320e/docs/pouchdb-quirks.md (about)

     1  [Table of contents](README.md#table-of-contents)
     2  
     3  # Pouchdb Mango Quirks
     4  
     5  The findings below were obtained while working on sorting performance in Cozy
     6  Drive. For reference, the final PR
     7  [can be seen here](https://github.com/cozy/cozy-drive/pull/1002/files).
     8  
     9  ## Understanding what's going on
    10  
    11  Before diving into some of the quirks, it's important to understand some things
    12  when it comes to Pouchdb and especially Mango queries.
    13  
    14  First, you can add a plugin called `pouchdb-debug` and enable extra logs with
    15  `PouchDB.debug.enable( "pouchdb:find" );`. This will add explanation about the
    16  queries you run in the console and it's very helpful to understand what's going
    17  on under the hood.
    18  
    19  You will realize that Pouchdb operates in 2 phases: one part of your query may
    20  be done using indexes, and the other may be done in memory. Long story short:
    21  anything done in memory has significant performance impacts, especially as the
    22  number of items gets larger. A more detailed guide can be found
    23  [here](https://www.bennadel.com/blog/3258-understanding-the-query-plan-explained-by-the-find-plugin-in-pouchdb-6-2-0.htm).
    24  
    25  ## About indexes
    26  
    27  Creating an index takes some time, but the first query will _also_ take time —
    28  you are encouraged to warm up the indexes by firing a query that uses it before
    29  it is actually needed. An exemple implementation can be found
    30  [here](https://github.com/cozy/cozy-drive/blob/0326e3d253ca51e0fdb18a9e9b3b5c8ff0b87eba/src/drive/mobile/lib/replication.js#L15-L80).
    31  
    32  If there is a change in the underlying documents, the index will be partially
    33  recalculated on the next query.
    34  [The post-replication callback may be a good place to warm up the index again.](https://github.com/cozy/cozy-drive/blob/0326e3d253ca51e0fdb18a9e9b3b5c8ff0b87eba/src/drive/mobile/lib/replication.js#L86-L91)
    35  
    36  By default, Pouch will try to find the best index to use on your query. For more
    37  advanced queries, you generally want to force it with the `use_index` option. If
    38  the query and the index you force are not compatible, Pouch will emit an error
    39  and not run the query at all.
    40  
    41  ## Indexing more than one field
    42  
    43  Creating an index on several fields is _not_ the same as creating multiple
    44  indexes on one field each. The effects of a single index on multiple fields is
    45  illustrated in the
    46  [official docs](https://pouchdb.com/guides/mango-queries.html#more-than-one-field)
    47  and is important to understand.
    48  
    49  Furthermore, the order in which fields are indexed on a multi-index is
    50  significant, most notably when it comes to sorting. If you declare an index on
    51  the fields `['name', 'age']`, you should also sort them by `['name', 'age']`.
    52  Sorting them in a different order or using other fields will likely be done in
    53  memory and kill your performance.
    54  
    55  ## Avoiding in memory selectors
    56  
    57  Filtering results with a selector on a field that has not been indexed is almost
    58  guaranteed to be done in memory and should be avoided. Since you can't have too
    59  many indexes, some filtering may have to be done in your own code — but if you
    60  can narrow down the results beforehand, that shouldn't be a problem.
    61  
    62  Even selectors on indexed field may end up being done in memory. Operators that
    63  don't rely on equality such as `$ne` should typically be avoided. Even equality
    64  operators run on secondary fields tend to be done in memory, and should therefor
    65  be used with care.