Skip to content

DOCSP-51805-bson-raw #549

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 29, 2025
Merged

DOCSP-51805-bson-raw #549

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eb00c66
bson raw
shuangela Jul 28, 2025
ecb45f0
melanie feedback
shuangela Jul 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 55 additions & 3 deletions source/fundamentals/bson.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,11 +348,63 @@
You can use the ``Raw`` type to retrieve elements from a BSON
document byte slice without unmarshalling it to a Go type. This type
allows you to look up individual elements without unmarshalling
the entire BSON document.
the entire BSON document. For more information about how to use the ``Raw`` type, see
the :ref:`golang-bson-raw` section.

To learn more about the marshalling and unmarshalling methods used with the
``Cursor`` type, see the `Cursor API documentation <{+api+}/mongo#Cursor>`__
``Cursor`` type, see the `Cursor API documentation <{+api+}/mongo#Cursor>`__.

To learn more about the marshalling and unmarshalling methods in the
``bson`` package, see the `bson API documentation
<{+api+}/bson#hdr-Marshalling_and_Unmarshalling>`_
<{+api+}/bson#hdr-Marshalling_and_Unmarshalling>`_.

.. _golang-bson-raw:

Work with Raw BSON Data
-----------------------

The {+driver-short+} supports working with raw BSON documents through the ``Raw`` type. The ``Raw``
type allows you to validate and retrieve elements from a slice of bytes without unmarshalling
the entire BSON document. This is useful in the following situations:

- Performing lookups on specific fields without converting the entire document
- Reducing memory overhead by avoiding full document unmarshalling
- Working directly with binary BSON data received from the database

The ``Raw`` type provides methods to validate the BSON document and look up individual
elements by their keys. The following example demonstrates how to validate a raw BSON document and retrieve
a specific field from it:

.. io-code-block::
:copyable: true

.. input::
:language: go

collection := client.Database("sample_restaurants").Collection("restaurants")
findOptions := options.FindOne()
var raw bson.Raw
err = collection.FindOne(
context.TODO(),
bson.D{{"name", "Mongo's Pizza"}},
findOptions,
).Decode(&raw)
if err != nil {
log.Fatalf("Failed to find document: %v", err)

Check failure on line 393 in source/fundamentals/bson.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.NegativeWords] Use 'serious' instead of the negative word 'Fatal'.

Raw Output:
{"message": "[MongoDB.NegativeWords] Use 'serious' instead of the negative word 'Fatal'.", "location": {"path": "source/fundamentals/bson.txt", "range": {"start": {"line": 393, "column": 15}}}, "severity": "ERROR"}
}

// Print the document type
fmt.Printf("Document type: %T\n", raw)

// Access a field from the raw document
name := raw.Lookup("name").StringValue()
fmt.Println("Restaurant name:", name)

.. output::
:language: none
:visible: false

Document type: bson.Raw
Restaurant name: Mongo's Pizza

To learn more about the ``Raw`` family of types, see the `Raw BSON API documentation <{+api+}/bson#hdr-Raw_BSON>`__.
Loading