From 42f1fc50db57a734df6eaa6dc8dc53b24a2af0a8 Mon Sep 17 00:00:00 2001 From: Bastien Gerard Date: Sun, 23 Aug 2026 15:17:28 +0200 Subject: [PATCH] Document the fact that mongodb takes keys order into account when querying using a dict --- docs/guide/querying.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst index 1d1f8c53e..d4cb33bd4 100644 --- a/docs/guide/querying.rst +++ b/docs/guide/querying.rst @@ -39,6 +39,28 @@ syntax:: # been written by a user whose 'country' field is set to 'uk' uk_pages = Page.objects(author__country='uk') +.. warning:: + + Be aware that MongoDB considers field order when matching an embedded + document. As a result, querying a :class:`~mongoengine.fields.DictField` or + :class:`~mongoengine.fields.MapField` against a complete dictionary only + matches when its keys are in the same order as the stored document. The same + applies when querying an :class:`~mongoengine.fields.EmbeddedDocumentField` + with an embedded document instance. For example, this query may not match + when the stored keys are in the opposite order:: + + SurveyResponse.objects( + answers={"question_2": "no", "question_1": "yes"}, + ) + + Query individual dictionary keys to match their values regardless of + order:: + + SurveyResponse.objects( + answers__question_1="yes", + answers__question_2="no", + ) + .. note:: (version **0.9.1+**) if your field name is like mongodb operator name (for example