From ce9663de5a44c6e385cd19710b2053ec19b45fd0 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 23 Jul 2024 16:16:27 -0400 Subject: [PATCH 1/7] DOCPS-41150: Specialized Data Formats + BSON --- snooty.toml | 3 +- source/data-formats.txt | 42 +++++++++ source/data-formats/bson.txt | 85 +++++++++++++++++++ .../data-formats/bson-gradle-versioned.rst | 5 ++ .../data-formats/bson-maven-versioned.rst | 9 ++ source/index.txt | 13 +++ 6 files changed, 156 insertions(+), 1 deletion(-) create mode 100644 source/data-formats.txt create mode 100644 source/data-formats/bson.txt create mode 100644 source/includes/data-formats/bson-gradle-versioned.rst create mode 100644 source/includes/data-formats/bson-maven-versioned.rst diff --git a/snooty.toml b/snooty.toml index f9e67736..195c5fe7 100644 --- a/snooty.toml +++ b/snooty.toml @@ -11,6 +11,7 @@ toc_landing_pages = [ "/connect", "/indexes", "work-with-indexes", + "/data-formats" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" @@ -21,7 +22,7 @@ driver-short = "Kotlin Sync driver" language = "Kotlin" version-number = "5.1" version = "v{+version-number+}" -patch-version-number = "{+version-number+}.0" +patch-version-number = "{+version-number+}.2" mdb-server = "MongoDB Server" stable-api = "Stable API" api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 00000000..a74176c7 --- /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 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:`kotlin-sync-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 00000000..bb5232f0 --- /dev/null +++ b/source/data-formats/bson.txt @@ -0,0 +1,85 @@ +.. _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 it, 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, ObjectIds, and +binary data. For a complete list of supported types, see the +:manual:`BSON Types ` server manual page. + +The binary format 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 use BSON data with your {+driver-short+} application by using one of the +following object types that implements the `BSON interface <{+api+}/apidocs/bson/org/bson/conversions/Bson.html>`__: + +- `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package) +- `BsonDocument <{+api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package) +- `RawBsonDocument <{+api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package) +- `JsonObject <{+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. If you added the MongoDB Kotlin driver as a dependency to your +project, you can skip this step since 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 project's +dependencies. Select from the following tabs to see the dependency declaration +for that tool: + +.. 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 one of the preceding tools, you can include it 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 00000000..6262ade7 --- /dev/null +++ b/source/includes/data-formats/bson-gradle-versioned.rst @@ -0,0 +1,5 @@ +.. code-block:: kotlin + + dependencies { + implementation("org.mongodb:bson:{+patch-version-number+}") + } 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 00000000..7ed4f152 --- /dev/null +++ b/source/includes/data-formats/bson-maven-versioned.rst @@ -0,0 +1,9 @@ +.. code-block:: xml + + + + org.mongodb + bson + {+patch-version-number+} + + diff --git a/source/index.txt b/source/index.txt index c89afcbf..54012ed5 100644 --- a/source/index.txt +++ b/source/index.txt @@ -17,6 +17,7 @@ /write-operations /read /indexes + /data-formats /faq /connection-troubleshooting /issues-and-help @@ -76,6 +77,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 --- From 9018d9672c2e52e8e0aaa98d2948834ef818515c Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 24 Jul 2024 11:33:55 -0400 Subject: [PATCH 2/7] Fix --- source/data-formats.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/data-formats.txt b/source/data-formats.txt index a74176c7..57c2b693 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -21,7 +21,7 @@ Specialized Data Formats :titlesonly: :maxdepth: 1 - /data-formats/bson + /data-formats/bson .. TODO: /data-formats/data-class .. TODO: /data-formats/extended-json @@ -34,7 +34,7 @@ You can use several types of specialized 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:`kotlin-sync-bson` guide. +- 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. From 22b4198cf1a3b9cc3673069363319a5629afe9da Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 24 Jul 2024 11:49:28 -0400 Subject: [PATCH 3/7] Fixes --- snooty.toml | 3 ++- source/data-formats/bson.txt | 28 ++++++++++++++++------------ 2 files changed, 18 insertions(+), 13 deletions(-) diff --git a/snooty.toml b/snooty.toml index 195c5fe7..38f9305f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -26,4 +26,5 @@ patch-version-number = "{+version-number+}.2" mdb-server = "MongoDB Server" stable-api = "Stable API" api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-kotlin-sync" -core-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}/apidocs/mongodb-driver-core/" +java-api = "https://mongodb.github.io/mongo-java-driver/{+version-number+}" +core-api = "{+java-api+}/apidocs/mongodb-driver-core/" \ No newline at end of file diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index bb5232f0..239ceebe 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -35,12 +35,12 @@ MongoDB and BSON ---------------- You can use BSON data with your {+driver-short+} application by using one of the -following object types that implements the `BSON interface <{+api+}/apidocs/bson/org/bson/conversions/Bson.html>`__: +following object types that implements the `BSON interface <{+java-api+}/apidocs/bson/org/bson/conversions/Bson.html>`__: -- `Document <{+api+}/apidocs/bson/org/bson/Document.html>`__ (BSON library package) -- `BsonDocument <{+api+}/apidocs/bson/org/bson/BsonDocument.html>`__ (BSON library package) -- `RawBsonDocument <{+api+}/apidocs/bson/org/bson/RawBsonDocument.html>`__ (BSON library package) -- `JsonObject <{+api+}/apidocs/bson/org/bson/json/JsonObject.html>`__ (BSON library package) +- `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: @@ -48,9 +48,13 @@ Install the BSON Library ------------------------ These instructions detail how to add the BSON library as a dependency to -your project. If you added the MongoDB Kotlin driver as a dependency to your -project, you can skip this step since the BSON library is already included -as a required dependency of the driver. +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 @@ -58,8 +62,8 @@ as a required dependency of the driver. .. guide. We recommend that you use the `Maven `__ or -`Gradle `__ build automation tool to manage your project's -dependencies. Select from the following tabs to see the dependency declaration +`Gradle `__ build automation tool to manage your {+language+} +project's dependencies. Select from the following tabs to see the dependency declaration for that tool: .. tabs:: @@ -80,6 +84,6 @@ for that tool: .. include:: /includes/data-formats/bson-gradle-versioned.rst -If you are not using one of the preceding tools, you can include it in -your project by downloading the JAR file directly from the +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 `__. From 8a80fee0af82e8033e77363de5f0f743a89eea91 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Wed, 24 Jul 2024 11:55:48 -0400 Subject: [PATCH 4/7] Kick off autobuild From b06fb85573b69447a0a6d0c47db8f6f862066d0b Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Thu, 25 Jul 2024 09:15:02 -0400 Subject: [PATCH 5/7] AS Feedback --- source/data-formats.txt | 2 +- source/data-formats/bson.txt | 17 ++++++++--------- 2 files changed, 9 insertions(+), 10 deletions(-) diff --git a/source/data-formats.txt b/source/data-formats.txt index 57c2b693..660332d3 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -30,7 +30,7 @@ Specialized Data Formats Overview -------- -You can use several types of specialized data formats in your {+driver-short+} +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: diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index 239ceebe..d66a43e9 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -14,19 +14,19 @@ Overview -------- In this guide, you can learn about the BSON data format, how MongoDB -uses it, and how to install the BSON library independently of the -{+driver-short+}. +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, ObjectIds, and -binary data. For a complete list of supported types, see the -:manual:`BSON Types ` server manual page. +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. -The binary format is not human-readable, but you can use the +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. @@ -34,7 +34,7 @@ formats in the :website:`JSON and BSON ` guide on the MongoDB we MongoDB and BSON ---------------- -You can use BSON data with your {+driver-short+} application by using one of the +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) @@ -63,8 +63,7 @@ your project. We recommend that you use the `Maven `__ or `Gradle `__ build automation tool to manage your {+language+} -project's dependencies. Select from the following tabs to see the dependency declaration -for that tool: +project's dependencies. .. tabs:: From 9a99acdde1e91c1a681dc6a21e064f22de35bbc5 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 26 Jul 2024 11:01:26 -0400 Subject: [PATCH 6/7] Tweak --- source/data-formats/bson.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/data-formats/bson.txt b/source/data-formats/bson.txt index d66a43e9..0e64c563 100644 --- a/source/data-formats/bson.txt +++ b/source/data-formats/bson.txt @@ -63,7 +63,8 @@ your project. We recommend that you use the `Maven `__ or `Gradle `__ build automation tool to manage your {+language+} -project's dependencies. +project's dependencies. The following instructions detail the dependency declarations for +both Maven and Gradle: .. tabs:: From 19d1abf98d66982ce0628e2676aa38370071651d Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Fri, 26 Jul 2024 11:18:13 -0400 Subject: [PATCH 7/7] Fix --- source/includes/data-formats/bson-gradle-versioned.rst | 2 +- source/includes/data-formats/bson-maven-versioned.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/data-formats/bson-gradle-versioned.rst b/source/includes/data-formats/bson-gradle-versioned.rst index 6262ade7..d565e2ea 100644 --- a/source/includes/data-formats/bson-gradle-versioned.rst +++ b/source/includes/data-formats/bson-gradle-versioned.rst @@ -1,5 +1,5 @@ .. code-block:: kotlin dependencies { - implementation("org.mongodb:bson:{+patch-version-number+}") + 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 index 7ed4f152..581ba0e2 100644 --- a/source/includes/data-formats/bson-maven-versioned.rst +++ b/source/includes/data-formats/bson-maven-versioned.rst @@ -4,6 +4,6 @@ org.mongodb bson - {+patch-version-number+} + {+full-version+}