Important

Self-managed SingleStore will soon transition from version 9.1 RC to version 10. This new semantic versioning scheme will provide SingleStore with finer control over engine and feature releases that were not possible with the current versioning scheme.

In the interim, SingleStore 9.1 RC can be used to preview, evaluate, and provide feedback on the new and upcoming features in SingleStore 10 prior to its general availability. Ahead of this transition, SingleStore 9.0 is recommended for production workloads, which can later be upgraded to SingleStore 10.

BSON_INCLUDE_MASK and BSON_EXCLUDE_MASK

On this page

The BSON_INCLUDE_MASK() and BSON_EXCLUDE_MASK() functions apply a mask to a BSON document and returns the subset of the original document.

BSON_INCLUDE_MASK returns all the fields in the BSON document that match the specified mask, all other fields are excluded. Conversely, BSON_EXCLUDE_MASK returns all the fields that do not match the specified mask, and all the fields that match the specified mask are excluded.

Syntax

BSON_INCLUDE_MASK(<bson_input>,<mask>)

BSON_EXCLUDE_MASK(<bson_input>,<mask>)

Arguments

<bson_input>: A valid BSON document or an expression that evaluates to a valid BSON document.
<mask>: A JSON input in string format that represents the mask.

Return Type

A BSON document.

Remarks

Returns NULL, if the <bson_input> argument is NULL or not a valid BSON document.

Mask Behavior

`BSON_INCLUDE_MASK`

All fields in the document that do not match the mask are excluded from the result. For example, if the mask {"a": 1} is specified, only the field "a" from the input document is included.
For nested fields, if the value is a BSON document, it is included and the remainder of the mask is applied to the document. Consider the following nested field {"a": {"b": 1}},
- If "a" is an array, it is included and the mask is applied to all the elements of the array.
- If "a" is not an array, the mask only applies directly to "a".

`BSON_EXCLUDE_MASK`

All fields in the document that match the mask are excluded from the result. For example, if the mask {"a": 1} is specified, the field "a" from the input document is excluded.
For nested fields, the mask is only applied to the leaves (terminal nodes/values).

Examples

Note: The following examples explicitly cast string to BSON for clarity. Similarly, the output is cast to JSON.

`BSON_INCLUDE_MASK` Examples

SQL

SELECT BSON_INCLUDE_MASK('{"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1}':>BSON,'{"a":1,"b":1}'):>JSON AS Result;

+-------------------------------------------+
| Result                                    |
+-------------------------------------------+
| {"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}]} |
+-------------------------------------------+

SQL

SELECT BSON_INCLUDE_MASK('{"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1}':>BSON,'{"a":1,"b":{"c":1}}'):>JSON AS Result;

+-------------------------------+
| Result                        |
+-------------------------------+
| {"a":1,"b":[{"c":1},{"c":2}]} |
+-------------------------------+

SQL

SELECT '{"a":[{"x":"abc", "y":123}, {"x":"cde", "z":234}, {"y":true, "z":null}],"b":true}':>BSON INTO @bsonObj;

SELECT BSON_INCLUDE_MASK(@bsonObj, '{"a":{"x":1}}'):>JSON AS Result;

+------------------------------------+
| Result                             |
+------------------------------------+
| {"a":[{"x":"abc"},{"x":"cde"},{}]} |
+------------------------------------+

The following example specifies an empty mask.

SQL

SELECT BSON_INCLUDE_MASK('{"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1}':>BSON,'{}'):>JSON AS Result;

+--------+
| Result |
+--------+
| {}     |
+--------+

BSON_EXCLUDE_MASK Examples

SQL

SELECT '{"a":[{"x":"abc", "y":123}, {"x":"cde", "z":234}, {"y":true, "z":null}],"b":true}':>BSON INTO @bsonObj;

SELECT BSON_EXCLUDE_MASK(@bsonObj, '{"a":{"x":1}}'):>JSON AS Result;

+----------------------------------------------------------+
| Result                                                   |
+----------------------------------------------------------+
| {"a":[{"y":123},{"z":234},{"y":true,"z":null}],"b":true} |
+----------------------------------------------------------+

SQL

SELECT BSON_EXCLUDE_MASK('{"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1}':>BSON,'{"a":1,"b":1}'):>JSON AS Result;

+---------+
| Result  |
+---------+
| {"e":1} |
+---------+

The following example specifies an empty mask.

SQL

SELECT BSON_EXCLUDE_MASK('{"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1}':>BSON,'{}'):>JSON AS Result;

+-------------------------------------------------+
| Result                                          |
+-------------------------------------------------+
| {"a":1,"b":[{"c":1,"d":1},{"c":2,"d":2}],"e":1} |
+-------------------------------------------------+

Last modified: June 29, 2026

Was this article helpful?

Verification instructions

Note: You must install cosign to verify the authenticity of the SingleStore file.

Use the following steps to verify the authenticity of singlestoredb-server, singlestoredb-toolbox, singlestoredb-studio, and singlestore-client SingleStore files that have been downloaded.

You may perform the following steps on any computer that can run cosign, such as the main deployment host of the cluster.

(Optional) Run the following command to view the associated signature files.
Shell
```
curl undefined
```
Download the signature file from the SingleStore release server.
- Option 1: Click the Download Signature button next to the SingleStore file.
- Option 2: Copy and paste the following URL into the address bar of your browser and save the signature file.
- Option 3: Run the following command to download the signature file.
  Shell
```
curl -O undefined
```

After the signature file has been downloaded, run the following command to verify the authenticity of the SingleStore file.

Shell

echo -n undefined |
    cosign verify-blob --certificate-oidc-issuer https://oidc.eks.us-east-1.amazonaws.com/id/CCDCDBA1379A5596AB5B2E46DCA385BC \
      --certificate-identity https://kubernetes.io/namespaces/freya-production/serviceaccounts/job-worker \
      --bundle undefined \
      --new-bundle-format -

Verified OK