$bitsAnySet¶

On this page

Behavior
Examples

$bitsAnySet¶

New in version 3.2.

$bitsAnySet matches documents where any of the bit positions given by the query are set (i.e. 1) in field.

{ <field>: { $bitsAnySet: <numeric bitmask> } }

{ <field>: { $bitsAnySet: < BinData bitmask> } }

{ <field>: { $bitsAnySet: [ <position1>, <position2>, ... ] } }

The field value must be either numerical or a BinData instance. Otherwise, $bitsAnySet 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, $bitsAnySet will return an error.
BinData Bitmask: You can also use an arbitrarily large BinData instance as a bitmask.
Position List: If querying a list of bit positions, each <position> 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:

Bit Value	1	1	1	1	1	1	1	0
Position	7	6	5	4	3	2	1	0

Behavior¶

Indexes¶

Queries cannot use indexes for the $bitsAnySet portion of a query, although the other portions of a query can use indexes, if applicable.

Floating Point Values¶

$bitsAnySet 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 too small to fit in a signed 64-bit integer, or if it has a fractional component.

Sign Extension¶

Numbers are sign extended. For example, $bitsAnySet 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, BinData instances are zero-extended. For example, given the following document:

copy

db.collection.save({ x: BinData(0, "ww=="), binaryValueofA: "11000011" })

$bitsAnySet will consider all bits outside of x to be clear.

Examples¶

The following examples will use a collection with the following documents:

copy

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" })

Bit Position Array¶

The following query uses the $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.

copy

db.collection.find( { a: { $bitsAnySet: [ 1, 5 ] } } )

The query matches the following documents:

copy

{ "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" }
{ "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" }

Integer Bitmask¶

The following query uses the $bitsAnySet operator to test whether field a has any bits set at positions 0, 1, and 5 (the binary representation of the bitmask 35 is 00100011).

copy

db.collection.find( { a: { $bitsAnySet: 35 } } )

The query matches the following documents:

copy

{ "_id" : 1, "a" : 54, "binaryValueofA" : "00110110" }
{ "_id" : 4, "a" : BinData(0,"Zg=="), "binaryValueofA" : "01100110" }

BinData Bitmask¶

The following query uses the $bitsAnySet operator to test whether field a has any bits set at positions 4, and 5 (the binary representation of BinData(0, "MC==") is 00110000).

copy

db.collection.find( { a: { $bitsAnySet: BinData(0, "MC==") } } )

The query matches the following documents:

copy

{ "_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" }

← $bitsAnyClear $comment →