Skip to content

Commit 6bb165f

Browse files
mcmorisimcmorisi
authored
DOCPS-41150: Specialized Data Formats + BSON (#19)
1 parent b5dbc5b commit 6bb165f

File tree

6 files changed

+161
-1
lines changed

6 files changed

+161
-1
lines changed

‎snooty.toml

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ toc_landing_pages = [
1212
"/connect",
1313
"/indexes",
1414
"work-with-indexes",
15+
"/data-formats"
1516
]
1617

1718
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
@@ -26,5 +27,6 @@ version = "v{+version-number+}"
2627
mdb-server = "MongoDB Server"
2728
stable-api = "Stable API"
2829
api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync"
30+
java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}"
31+
core-api = "{+java-api+}/apidocs/mongodb-driver-core/"
2932
kotlin-docs = "https://kotlinlang.org"
30-
core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core"

‎source/data-formats.txt

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
.. _kotlin-sync-data-formats:
2+
3+
========================
4+
Specialized Data Formats
5+
========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: bson, data, class, date, time
19+
20+
.. toctree::
21+
:titlesonly:
22+
:maxdepth: 1
23+
24+
/data-formats/bson
25+
26+
.. TODO: /data-formats/data-class
27+
.. TODO: /data-formats/extended-json
28+
.. TODO: /data-formats/time-series
29+
30+
Overview
31+
--------
32+
33+
You can use several types of specialized document data formats in your {+driver-short+}
34+
application. To learn how to work with these data formats, see the following
35+
sections:
36+
37+
- Learn how to work with the BSON data format in the :ref:`BSON <kotlin-sync-bson>` guide.
38+
39+
.. TODO: Uncomment these as pages get built
40+
.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide.
41+
.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide.
42+
.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide.

‎source/data-formats/bson.txt

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _kotlin-sync-bson:
2+
3+
==========================
4+
Document Data Format: BSON
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn about the BSON data format, how MongoDB
17+
uses BSON to organize and store data, and how to install the BSON library independently of
18+
the {+driver-short+}.
19+
20+
BSON Data Format
21+
----------------
22+
23+
**BSON**, or Binary JSON, is the data format that MongoDB uses to organize
24+
and store data. This data format includes all JSON data structure types and
25+
adds support for types including dates, differently-sized integers (32-bit and 64-bit),
26+
ObjectIds, and binary data. For a complete list of supported types, see the
27+
:manual:`BSON Types </reference/bson-types>` in the {+mdb-server+} documentation.
28+
29+
BSON is not human-readable, but you can use the
30+
:ref:`BSON library <install-bson-library>` to convert it to the human-readable JSON
31+
representation. You can read more about the relationship between these
32+
formats in the :website:`JSON and BSON </json-and-bson>` guide on the MongoDB website.
33+
34+
MongoDB and BSON
35+
----------------
36+
37+
You can work with BSON data in your {+driver-short+} application by using one of the
38+
following object types that implements the `BSON interface <{+java-api+}/apidocs/bson/org/bson/conversions/Bson.html>`__:
39+
40+
- `Document <{+java-api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package)
41+
- `BsonDocument <{+java-api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package)
42+
- `RawBsonDocument <{+java-api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package)
43+
- `JsonObject <{+java-api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ (BSON library package)
44+
45+
.. _install-bson-library:
46+
47+
Install the BSON Library
48+
------------------------
49+
50+
These instructions detail how to add the BSON library as a dependency to
51+
your project.
52+
53+
.. note::
54+
55+
If you have already added the {+driver-short+} as a dependency to your
56+
project, then you can skip this step. This is because the BSON library is already
57+
included as a required dependency of the driver.
58+
59+
.. TODO: For instructions on how to add the
60+
.. MongoDB Kotlin driver as a dependency to your project, see the
61+
.. :ref:`driver installation <kotlin-sync-download-install>` section of our Get Started
62+
.. guide.
63+
64+
We recommend that you use the `Maven <https://maven.apache.org/>`__ or
65+
`Gradle <https://gradle.org/>`__ build automation tool to manage your {+language+}
66+
project's dependencies. The following instructions detail the dependency declarations for
67+
both Maven and Gradle:
68+
69+
.. tabs::
70+
71+
.. tab:: Maven
72+
:tabid: maven-dependencies
73+
74+
The following snippet shows the dependency declaration in the
75+
``dependencies`` section of your ``pom.xml`` file.
76+
77+
.. include:: /includes/data-formats/bson-maven-versioned.rst
78+
79+
.. tab:: Gradle
80+
:tabid: gradle-dependencies
81+
82+
The following snippet shows the dependency declaration in the
83+
``dependencies`` object in your ``build.gradle`` file.
84+
85+
.. include:: /includes/data-formats/bson-gradle-versioned.rst
86+
87+
If you are not using either of the preceding tools, then you can include the BSON dependency
88+
in your project by downloading the JAR file directly from the
89+
`sonatype repository <https://repo1.maven.org/maven2/org/mongodb/bson/>`__.

‎source/includes/data-formats/bson-gradle-versioned.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. code-block:: kotlin
2+
3+
dependencies {
4+
implementation("org.mongodb:bson:{+full-version+}")
5+
}

‎source/includes/data-formats/bson-maven-versioned.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. code-block:: xml
2+
3+
<dependencies>
4+
<dependency>
5+
<groupId>org.mongodb</groupId>
6+
<artifactId>bson</artifactId>
7+
<version>{+full-version+}</version>
8+
</dependency>
9+
</dependencies>

‎source/index.txt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
/write-operations
1919
/read
2020
/indexes
21+
/data-formats
2122
/faq
2223
/connection-troubleshooting
2324
/issues-and-help
@@ -77,6 +78,18 @@ Read Data from MongoDB
7778

7879
Learn how you can retrieve data from MongoDB in the :ref:`kotlin-sync-read` section.
7980

81+
Optimize Queries with Indexes
82+
-----------------------------
83+
84+
Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes`
85+
section.
86+
87+
Specialized Data Formats
88+
------------------------
89+
90+
Learn how to work with specialized data formats and custom types in the
91+
:ref:`kotlin-sync-data-formats` section.
92+
8093
FAQ
8194
---
8295

0 commit comments

Comments
 (0)