From 362e594d76ec27c0e849b9240e548fc269f8b3eb Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Thu, 24 Sep 2015 11:55:20 -0400 Subject: [PATCH] DOCS-5855: Document the new bitwise query operators --- .../includes/extracts-fact-query-bitwise.yaml | 183 ++++++++ .../ref-toc-operator-query-bitwise.yaml | 16 + source/reference/operator/query-bitwise.txt | 9 + source/reference/operator/query.txt | 14 + .../reference/operator/query/bitsAllClear.txt | 87 ++++ .../reference/operator/query/bitsAllSet.txt | 86 ++++ .../reference/operator/query/bitsAnyClear.txt | 89 ++++ .../reference/operator/query/bitsAnySet.txt | 91 ++++ .../3.1-dev-series-reference.txt | 426 ------------------ 9 files changed, 575 insertions(+), 426 deletions(-) create mode 100644 source/includes/extracts-fact-query-bitwise.yaml create mode 100644 source/includes/ref-toc-operator-query-bitwise.yaml create mode 100644 source/reference/operator/query-bitwise.txt create mode 100644 source/reference/operator/query/bitsAllClear.txt create mode 100644 source/reference/operator/query/bitsAllSet.txt create mode 100644 source/reference/operator/query/bitsAnyClear.txt create mode 100644 source/reference/operator/query/bitsAnySet.txt diff --git a/source/includes/extracts-fact-query-bitwise.yaml b/source/includes/extracts-fact-query-bitwise.yaml new file mode 100644 index 00000000000..85d40384422 --- /dev/null +++ b/source/includes/extracts-fact-query-bitwise.yaml @@ -0,0 +1,183 @@ +ref: _fact-query-bitwise-description +content: | + .. list-table:: + + * - ``{ : { {{op}}: } }`` + + * - ``{ : { {{op}}: <`` :bsontype:`BinData ` ``bitmask> } }`` + + * - ``{ : { {{op}}: [ , , ... ] } }`` + + The ``field`` value must be either numerical or a + :bsontype:`BinData ` instance. Otherwise, :query:`{{op}}` + will not match the current document. + + Numeric Bitmask + You can provide a numeric bitmask to be matched against the operand field. + It must be representable as a non-negative 32-bit signed integer. Otherwise, + :query:`{{op}}` will return an error. + + BinData Bitmask + You can also use an arbitrarily large :bsontype:`BinData ` + instance as a bitmask. + + Position List + If querying a list of bit positions, each ```` must be a non-negative + integer. Bit positions start at ``0`` from the least significant bit. For + example, the decimal number ``254`` would have the following bit positions: + + .. list-table:: + + * - **Bit Value** + + - 1 + + - 1 + + - 1 + + - 1 + + - 1 + + - 1 + + - 1 + + - 0 + + * - **Position** + + - 7 + + - 6 + + - 5 + + - 4 + + - 3 + + - 2 + + - 1 + + - 0 +--- +ref: fact-query-bitsallset-description +replacement: + op: "$bitsAllSet" +inherit: + ref: _fact-query-bitwise-description + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyset-description +replacement: + op: "$bitsAnySet" +inherit: + ref: _fact-query-bitwise-description + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsallclear-description +replacement: + op: "$bitsAllClear" +inherit: + ref: _fact-query-bitwise-description + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyclear-description +replacement: + op: "$bitsAnyClear" +inherit: + ref: _fact-query-bitwise-description + file: extracts-fact-query-bitwise.yaml +--- +ref: _fact-query-bitwise-floating-point +content: | + :query:`{{op}}` will not match numerical values that cannot be represented as + a signed 64-bit integer. This can be the case if a value is either too large + or small to fit in a signed 64-bit integer, or if it has a fractional + component. +--- +ref: fact-query-bitsallset-floating-point +replacement: + op: "$bitsAllSet" +inherit: + ref: _fact-query-bitwise-floating-point + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyset-floating-point +replacement: + op: "$bitsAnySet" +inherit: + ref: _fact-query-bitwise-floating-point + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsallclear-floating-point +replacement: + op: "$bitsAllClear" +inherit: + ref: _fact-query-bitwise-floating-point + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyclear-floating-point +replacement: + op: "$bitsAnyClear" +inherit: + ref: _fact-query-bitwise-floating-point + file: extracts-fact-query-bitwise.yaml +--- +ref: _fact-query-bitwise-sign-extension +content: | + Numbers are sign extended. For example, {{op}} considers bit position ``200`` + to be set for the negative number ``-5``, but bit position ``200`` to be clear + for the positive number ``+5``. + + In contrast, :bsontype:`BinData ` instances are zero-extended. + For example, given the following document: + + .. code-block:: javascript + + db.collection.save({ x: BinData(0, "ww=="), binaryValueofA: "11000011" }) + + {{op}} will consider all bits outside of ``x`` to be clear. +--- +ref: fact-query-bitsallset-sign-extension +replacement: + op: "$bitsAllSet" +inherit: + ref: _fact-query-bitwise-sign-extension + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyset-sign-extension +replacement: + op: "$bitsAnySet" +inherit: + ref: _fact-query-bitwise-sign-extension + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsallclear-sign-extension +replacement: + op: "$bitsAllClear" +inherit: + ref: _fact-query-bitwise-sign-extension + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitsanyclear-sign-extension +replacement: + op: "$bitsAnyClear" +inherit: + ref: _fact-query-bitwise-sign-extension + file: extracts-fact-query-bitwise.yaml +--- +ref: fact-query-bitwise-example-collection +content: | + The following examples will use a collection with the following documents: + + .. code-block:: javascript + + db.collection.save({ _id: 1, a: 54, binaryValueofA: "00110110" }) + db.collection.save({ _id: 2, a: 20, binaryValueofA: "00010100" }) + db.collection.save({ _id: 3, a: 20.0, binaryValueofA: "00010100" }) + db.collection.save({ _id: 4, a: BinData(0, "Zg=="), binaryValueofA: "01100110" }) +... diff --git a/source/includes/ref-toc-operator-query-bitwise.yaml b/source/includes/ref-toc-operator-query-bitwise.yaml new file mode 100644 index 00000000000..820ae4d1c4c --- /dev/null +++ b/source/includes/ref-toc-operator-query-bitwise.yaml @@ -0,0 +1,16 @@ +name: ":query:`$bitsAllSet`" +file: /reference/operator/query/bitsAllSet +description: "Matches numeric or binary values in which a set of bit positions *all* have a value of ``1``." +--- +name: ":query:`$bitsAnySet`" +file: /reference/operator/query/bitsAnySet +description: "Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``1``." +--- +name: ":query:`$bitsAllClear`" +file: /reference/operator/query/bitsAllClear +description: "Matches numeric or binary values in which a set of bit positions *all* have a value of ``0``." +--- +name: ":query:`$bitsAnyClear`" +file: /reference/operator/query/bitsAnyClear +description: "Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``0``." +... diff --git a/source/reference/operator/query-bitwise.txt b/source/reference/operator/query-bitwise.txt new file mode 100644 index 00000000000..b100e6e1ab5 --- /dev/null +++ b/source/reference/operator/query-bitwise.txt @@ -0,0 +1,9 @@ +======================= +Bitwise Query Operators +======================= + +.. default-domain:: mongodb + +.. include:: /includes/toc/table-operator-query-bitwise.rst + +.. include:: /includes/toc/operator-query-bitwise.rst diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt index 265f640cbc5..49707bf8bc2 100644 --- a/source/reference/operator/query.txt +++ b/source/reference/operator/query.txt @@ -94,6 +94,20 @@ Array /reference/operator/query-array +Bitwise +~~~~~~~ + +.. only:: website + + .. include:: /includes/toc/table-operator-query-bitwise.rst + +.. class:: hidden + + .. toctree:: + :titlesonly: + + /reference/operator/query-bitwise + Comments ~~~~~~~~ diff --git a/source/reference/operator/query/bitsAllClear.txt b/source/reference/operator/query/bitsAllClear.txt new file mode 100644 index 00000000000..12907bc77e5 --- /dev/null +++ b/source/reference/operator/query/bitsAllClear.txt @@ -0,0 +1,87 @@ +============= +$bitsAllClear +============= + +.. default-domain:: mongodb + +.. query:: $bitsAllClear + + .. versionadded:: 3.2 + + :query:`$bitsAllClear` matches documents where *all* of the bit positions + given by the query are clear (i.e. ``0``) in ``field``. + + .. include:: /includes/extracts/fact-query-bitsallclear-description.rst + +Behavior +-------- + +Floating Point Values +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallclear-floating-point.rst + +Sign Extension +~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallset-sign-extension.rst + +Examples +-------- + +.. include:: /includes/extracts/fact-query-bitwise-example-collection.rst + +Bit Position Array +~~~~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllClear` operator to test +whether field ``a`` has bits clear at position ``1`` and position +``5``, where the least significant bit is position ``0``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllClear: [ 1, 5 ] } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" } + + +Integer Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllClear` operator to test +whether field ``a`` has bits clear at positions ``0``, ``1``, and ``5``, +because the binary representation of the bitmask ``35`` is ``00100011``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllClear: 35 } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" } + +BinData Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllClear` operator to test +whether field ``a`` has bits clear at positions `1`, `4`, and `5`, because the +binary representation of ``BinData(0, "MC==")`` is ``00110010``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllClear: BinData(0, "ID==") } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20, "binaryValueofA" : "00010100" } diff --git a/source/reference/operator/query/bitsAllSet.txt b/source/reference/operator/query/bitsAllSet.txt new file mode 100644 index 00000000000..a1cc1dbf46a --- /dev/null +++ b/source/reference/operator/query/bitsAllSet.txt @@ -0,0 +1,86 @@ +=========== +$bitsAllSet +=========== + +.. default-domain:: mongodb + +.. query:: $bitsAllSet + + .. versionadded:: 3.2 + + :query:`$bitsAllSet` matches documents where *all* of the bit positions + given by the query are set (i.e. ``1``) in ``field``. + + .. include:: /includes/extracts/fact-query-bitsallset-description.rst + +Behavior +-------- + +Floating Point Values +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallset-floating-point.rst + +Sign Extension +~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallset-sign-extension.rst + +Examples +-------- + +.. include:: /includes/extracts/fact-query-bitwise-example-collection.rst + +Bit Position Array +~~~~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllSet` operator to test +whether field ``a`` has bits set at position ``1`` and position +``5``, where the least significant bit is position ``0``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllSet: [ 1, 5 ] } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } + + +Integer Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllSet` operator to test +whether field ``a`` has bits set at positions ``0``, ``1``, and ``5``, +because the binary representation of the bitmask ``35`` is ``00100011``. + + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllSet: 50 } } ) + +The query matches the following document: + +.. code-block:: javascript + + { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" } + +BinData Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAllSet` operator to test +whether field ``a`` has bits set at positions `1`, `4`, and `5`, because the +binary representation of ``BinData(0, "MC==")`` is ``00110010``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAllSet: BinData(0, "MC==") } } ) + +The query matches the following document: + +.. code-block:: javascript + + { _id: 1, a: 54, binaryValueofA: "00110110" } diff --git a/source/reference/operator/query/bitsAnyClear.txt b/source/reference/operator/query/bitsAnyClear.txt new file mode 100644 index 00000000000..d0125f816b4 --- /dev/null +++ b/source/reference/operator/query/bitsAnyClear.txt @@ -0,0 +1,89 @@ +============= +$bitsAnyClear +============= + +.. default-domain:: mongodb + +.. query:: $bitsAnyClear + + .. versionadded:: 3.2 + + :query:`$bitsAnyClear` matches documents where *any* of the bit positions + given by the query are clear (i.e. ``0``) in ``field``. + + .. include:: /includes/extracts/fact-query-bitsanyclear-description.rst + +Behavior +-------- + +Floating Point Values +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsanyclear-floating-point.rst + +Sign Extension +~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallset-sign-extension.rst + +Examples +-------- + +.. include:: /includes/extracts/fact-query-bitwise-example-collection.rst + +Bit Position Array +~~~~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnyClear` operator to test +whether field ``a`` has either bit position ``1`` or bit position ``5`` clear, +where the least significant bit is position ``0``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnyClear: [ 1, 5 ] } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20.0, "binaryValueofA" : "00010100" } + +Integer Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnyClear` operator to test +whether field ``a`` has any bits clear at positions ``0``, ``1``, and ``5``, +because the binary representation of the bitmask ``35`` is ``00100011``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnyClear: 50 } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20.0, "binaryValueofA" : "00010100" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } + + +BinData Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnyClear` operator to test +whether field ``a`` has any bits clear at positions `1`, `4`, and `5`, because +the binary representation of ``BinData(0, "MC==")`` is ``00110010``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnyClear: BinData(0, "MC==") } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20.0, "binaryValueofA" : "00010100" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } diff --git a/source/reference/operator/query/bitsAnySet.txt b/source/reference/operator/query/bitsAnySet.txt new file mode 100644 index 00000000000..6d06989bfba --- /dev/null +++ b/source/reference/operator/query/bitsAnySet.txt @@ -0,0 +1,91 @@ +=========== +$bitsAnySet +=========== + +.. default-domain:: mongodb + +.. query:: $bitsAnySet + + .. versionadded:: 3.2 + + :query:`$bitsAnySet` matches documents where *any* of the bit positions + given by the query are set (i.e. ``1``) in ``field``. + + .. include:: /includes/extracts/fact-query-bitsanyset-description.rst + +Behavior +-------- + +Floating Point Values +~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsanyset-floating-point.rst + +Sign Extension +~~~~~~~~~~~~~~ + +.. include:: /includes/extracts/fact-query-bitsallset-sign-extension.rst + +Examples +-------- + +.. include:: /includes/extracts/fact-query-bitwise-example-collection.rst + +Bit Position Array +~~~~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnySet` operator to test +whether field ``a`` has either bit position ``1`` or bit position ``5`` set, +where the least significant bit is position ``0``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnySet: [ 1, 5 ] } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } + + +Integer Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnySet` operator to test +whether field ``a`` has any bits set at positions ``0``, ``1``, and ``5``, +because the binary representation of the bitmask ``35`` is ``00100011``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnySet: 50 } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" } + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20.0, "binaryValueofA" : "00010100" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } + +BinData Bitmask +~~~~~~~~~~~~~~~ + +The following query uses the :query:`$bitsAnySet` operator to test +whether field ``a`` has any bits set at positions `1`, `4`, and `5`, because the +binary representation of ``BinData(0, "MC==")`` is ``00110010``. + +.. code-block:: javascript + + db.collection.find( { a: { $bitsAnySet: BinData(0, "MC==") } } ) + +The query matches the following documents: + +.. code-block:: javascript + + { "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" } + { "_id" : 2, "a" : 20, "binaryValueofA" : "00010100" } + { "_id" : 3, "a" : 20.0, "binaryValueofA" : "00010100" } + { "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" } diff --git a/source/release-notes/3.1-dev-series-reference.txt b/source/release-notes/3.1-dev-series-reference.txt index dfc88e0ec83..7fe3054604e 100644 --- a/source/release-notes/3.1-dev-series-reference.txt +++ b/source/release-notes/3.1-dev-series-reference.txt @@ -1760,432 +1760,6 @@ Behavior set for the number ``-5`` but we consider bit position ``200`` clear for the number ``+5``. -Operators -~~~~~~~~~ - -.. query:: $bitsAllSet - - Selects documents where the all the specified bits of a field are - set (i.e. ``1``). - - To use :query:`$bitsAllSet`, you can use one of - the following syntaxes: - - - To use bit positions to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllSet: [ , , ... ] } } - - The ```` can be any non-negative numerical BSON element - type and must be representable as a 32-bit signed integer. - - The bit position is ``0``-based, starting at the least significant - bit: - - .. code-block:: none - - 11111111 - -------- - 76543210 Position - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllSet` operator to test - whether field ``a`` has bits set at position ``1`` and position - ``5``, counting from the least significant bit as position ``0``: - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllSet: [ 1, 5 ] } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - - - To use a numeric bitmask to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllSet: } } - - :query:`$bitsAllSet` uses the positions of the ``1``'s in the - bitmask to test the bit in the corresponding position in the - ````. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllSet` operator to test - whether field ``a`` has bits set at positions that corresponds to - positions of ``1``'s in the numeric bitmask ``50`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllSet: 50 } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - - - To use BinData to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllSet: } } - - :query:`$bitsAllSet` uses the positions of the ``1``'s in the - BinData to test the bit in the corresponding position in the - ````. Bit position ``0`` is the first bit in the first byte - of a BinData element. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllSet` operator to test - whether field ``a`` has bits set at positions that corresponds to - positions of ``1``'s in the ``BinData(0, "MC==")`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllSet: BinData(0, "MC==") } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - -.. query:: $bitsAllClear - - Selects documents where the all the specified bits of a field are - clear (i.e. ``0``). To use :query:`$bitsAllClear`, you can use one - of the following syntaxes: - - - To use bit positions to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllClear: [ , , ... ] } } - - The ```` can be any non-negative numerical BSON element - type and must be representable as a 32-bit signed integer. - - The bit position is ``0``-based, starting at the least significant - bit: - - .. code-block:: none - - 11111111 - -------- - 76543210 Position - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllClear` operator to test - whether field ``a`` has bits cleared in position ``1`` and position - ``5``, counting from the least significant bit as position ``0``: - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllClear: [ 1, 5 ] } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id: 2, a: 20, binaryValueofA: "00010100" } - - - To use a numeric bitmask to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllClear: } } - - :query:`$bitsAllClear` uses the positions of the ``1``'s in the - bitmask to test the bit in the corresponding position in the - ````. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllClear` operator to test - whether field ``a`` has bits cleared at positions that corresponds to - positions of ``1``'s in the numeric bitmask ``35`` (i.e. ``00100011``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllClear: 35 } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:2, a: 20, binaryValueofA: "00010100" } - - - To use BinData to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAllClear: } } - - :query:`$bitsAllClear` uses the positions of the ``1``'s in the - BinData to test the bit in the corresponding position in the - ````. Bit position ``0`` is the first bit in the first byte - of a BinData element. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAllClear` operator to test - whether field ``a`` has bits cleared at positions that corresponds to - positions of ``1``'s in the ``BinData(0, "ID==")`` (i.e. ``00100011``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAllClear: BinData(0, "ID==") } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:2, a: 20, binaryValueofA: "00010100" } - -.. query:: $bitsAnySet - - Selects documents where at least one of the specified bits of a - field are set (i.e. ``1``). To use :query:`$bitsAnySet`, you can use - one of the following syntaxes: - - - To use bit positions to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnySet: [ , , ... ] } } - - The ```` can be any non-negative numerical BSON element - type and must be representable as a 32-bit signed integer. - - The bit position is ``0``-based, starting at the least significant - bit: - - .. code-block:: none - - 11111111 - -------- - 76543210 Position - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAnySet` operator to test - whether field ``a`` has any bits set in position ``1`` and position - ``5``, counting from the least significant bit as position ``0``: - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnySet: [ 1, 5 ] } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - - - To use a numeric bitmask to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnySet: } } - - :query:`$bitsAnySet` uses the positions of the ``1``'s in the - bitmask to test the bit in the corresponding position in the - ````. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAnySet` operator to test - whether field ``a`` has any bits set at positions that corresponds to - positions of ``1``'s in the numeric bitmask ``50`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnySet: 50 } } ) - - The query matches the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - - To use BinData to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnySet: } } - - :query:`$bitsAnySet` uses the positions of the ``1``'s in the - BinData to test the bit in the corresponding position in the - ````. Bit position ``0`` is the first bit in the first byte - of a BinData element. - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAnySet` operator to test - whether field ``a`` has any bits set at positions that corresponds to - positions of ``1``'s in the ``BinData(0, "MC==")`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnySet: BinData(0, "MC==") } } ) - - The query matches the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - -.. query:: $bitsAnyClear - - Selects documents where at least one of the specified bits of a - field are clear (i.e. ``0``). To use :query:`$bitsAnyClear`, you can - use one of the following syntaxes: - - - To use bit positions to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnyClear: [ , , ... ] } } - - The ```` can be any non-negative numerical BSON element - type and must be representable as a 32-bit signed integer. - - The bit position is ``0``-based, starting at the least significant - bit: - - .. code-block:: none - - 11111111 - -------- - 76543210 Position - - Consider a collection with the following documents: - - .. code-block:: javascript - - { _id:1, a: 54, binaryValueofA: "00110110" } - { _id:2, a: 20, binaryValueofA: "00010100" } - - The following query uses the :query:`$bitsAnyClear` operator to test - whether field ``a`` has any bits cleared in position ``1`` and - position ``5``, counting from the least significant bit as - position ``0``: - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnyClear: [ 1, 5 ] } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:2, a: 20, binaryValueofA: "00010100" } - - - To use a numeric bitmask to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnyClear: } } - - :query:`$bitsAnyClear` uses the positions of the ``1``'s in the - bitmask to test the bit in the corresponding position in the - ````. - - The following query uses the :query:`$bitsAnyClear` operator to test - whether field ``a`` has any bits cleared at positions that corresponds to - positions of ``1``'s in the numeric bitmask ``50`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnyClear: 50 } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:2, a: 20, binaryValueofA: "00010100" } - - - To use BinData to specify which bits to test: - - .. code-block:: javascript - - { : { $bitsAnyClear: } } - - :query:`$bitsAnyClear` uses the positions of the ``1``'s in the - BinData to test the bit in the corresponding position in the - ````. Bit position ``0`` is the first bit in the first byte - of a BinData element. - - The following query uses the :query:`$bitsAnyClear` operator to test - whether field ``a`` has any bits cleared at positions that corresponds to - positions of ``1``'s in the ``BinData(0, "MC==")`` (i.e. ``00110010``). - - .. code-block:: javascript - - db.collection.find( { a: { $bitsAnyClear: BinData(0, "MC==") } } ) - - The query matches the following document: - - .. code-block:: javascript - - { _id:2, a: 20, binaryValueofA: "00010100" } - .. _3.2-ref-case-sensitive-text-search: Case Sensitive Text Search Examples