diff --git a/snooty.toml b/snooty.toml index 9e1e3f4..a952ef4 100644 --- a/snooty.toml +++ b/snooty.toml @@ -12,6 +12,7 @@ toc_landing_pages = [ "/connect", "/indexes", "work-with-indexes", + "/data-formats" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" @@ -26,5 +27,6 @@ version = "v{+version-number+}" mdb-server = "MongoDB Server" stable-api = "Stable API" api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" +java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}" +core-api = "{+java-api+}/apidocs/mongodb-driver-core/" kotlin-docs = "https://kotlinlang.org" -core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core" diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 0000000..660332d --- /dev/null +++ b/source/data-formats.txt @@ -0,0 +1,42 @@ +.. _kotlin-sync-data-formats: + +======================== +Specialized Data Formats +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: bson, data, class, date, time + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /data-formats/bson + +.. TODO: /data-formats/data-class +.. TODO: /data-formats/extended-json +.. TODO: /data-formats/time-series + +Overview +-------- + +You can use several types of specialized document data formats in your {+driver-short+} +application. To learn how to work with these data formats, see the following +sections: + +- Learn how to work with the BSON data format in the :ref:`BSON ` guide. + +.. TODO: Uncomment these as pages get built +.. - Learn how to store and retrieve data using {+language+} data classes in the :ref:`data-classes` guide. +.. - Learn how to use the Extended JSON format in the :ref:`kotlin-sync-extended-json` guide. +.. - Learn how to store and interact with time series data in the :ref:`kotlin-sync-time-series` guide. diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt new file mode 100644 index 0000000..0e64c56 --- /dev/null +++ b/source/data-formats/bson.txt @@ -0,0 +1,89 @@ +.. _kotlin-sync-bson: + +========================== +Document Data Format: BSON +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn about the BSON data format, how MongoDB +uses BSON to organize and store data, and how to install the BSON library independently of +the {+driver-short+}. + +BSON Data Format +---------------- + +**BSON**, or Binary JSON, is the data format that MongoDB uses to organize +and store data. This data format includes all JSON data structure types and +adds support for types including dates, differently-sized integers (32-bit and 64-bit), +ObjectIds, and binary data. For a complete list of supported types, see the +:manual:`BSON Types ` in the {+mdb-server+} documentation. + +BSON is not human-readable, but you can use the +:ref:`BSON library ` to convert it to the human-readable JSON +representation. You can read more about the relationship between these +formats in the :website:`JSON and BSON ` guide on the MongoDB website. + +MongoDB and BSON +---------------- + +You can work with BSON data in your {+driver-short+} application by using one of the +following object types that implements the `BSON interface <{+java-api+}/apidocs/bson/org/bson/conversions/Bson.html>`__: + +- `Document <{+java-api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package) +- `BsonDocument <{+java-api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package) +- `RawBsonDocument <{+java-api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package) +- `JsonObject <{+java-api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ (BSON library package) + +.. _install-bson-library: + +Install the BSON Library +------------------------ + +These instructions detail how to add the BSON library as a dependency to +your project. + +.. note:: + + If you have already added the {+driver-short+} as a dependency to your + project, then you can skip this step. This is because the BSON library is already + included as a required dependency of the driver. + +.. TODO: For instructions on how to add the +.. MongoDB Kotlin driver as a dependency to your project, see the +.. :ref:`driver installation ` section of our Get Started +.. guide. + +We recommend that you use the `Maven `__ or +`Gradle `__ build automation tool to manage your {+language+} +project's dependencies. The following instructions detail the dependency declarations for +both Maven and Gradle: + +.. tabs:: + + .. tab:: Maven + :tabid: maven-dependencies + + The following snippet shows the dependency declaration in the + ``dependencies`` section of your ``pom.xml`` file. + + .. include:: /includes/data-formats/bson-maven-versioned.rst + + .. tab:: Gradle + :tabid: gradle-dependencies + + The following snippet shows the dependency declaration in the + ``dependencies`` object in your ``build.gradle`` file. + + .. include:: /includes/data-formats/bson-gradle-versioned.rst + +If you are not using either of the preceding tools, then you can include the BSON dependency +in your project by downloading the JAR file directly from the +`sonatype repository `__. diff --git a/source/includes/data-formats/bson-gradle-versioned.rst b/source/includes/data-formats/bson-gradle-versioned.rst new file mode 100644 index 0000000..d565e2e --- /dev/null +++ b/source/includes/data-formats/bson-gradle-versioned.rst @@ -0,0 +1,5 @@ +.. code-block:: kotlin + + dependencies { + implementation("org.mongodb:bson:{+full-version+}") + } diff --git a/source/includes/data-formats/bson-maven-versioned.rst b/source/includes/data-formats/bson-maven-versioned.rst new file mode 100644 index 0000000..581ba0e --- /dev/null +++ b/source/includes/data-formats/bson-maven-versioned.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + org.mongodb + bson + {+full-version+} + + diff --git a/source/index.txt b/source/index.txt index bccb9eb..d4e5834 100644 --- a/source/index.txt +++ b/source/index.txt @@ -18,6 +18,7 @@ /write-operations /read /indexes + /data-formats /faq /connection-troubleshooting /issues-and-help @@ -77,6 +78,18 @@ Read Data from MongoDB Learn how you can retrieve data from MongoDB in the :ref:`kotlin-sync-read` section. +Optimize Queries with Indexes +----------------------------- + +Learn how to work with common types of indexes in the :ref:`kotlin-sync-indexes` +section. + +Specialized Data Formats +------------------------ + +Learn how to work with specialized data formats and custom types in the +:ref:`kotlin-sync-data-formats` section. + FAQ ---