diff --git a/source/data-formats.txt b/source/data-formats.txt index 5af1d6ef..442b2cae 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -24,6 +24,7 @@ Data Formats Time Series Data BSON + Extended JSON Overview -------- diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 00000000..9e9f47f5 --- /dev/null +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,103 @@ +.. _ruby-extended-json: + +============= +Extended JSON +============= + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, json, standard formatting + :description: Learn how to use extended JSON in the MongoDB Ruby Driver. + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: twocols + +.. sharedinclude:: dbx/extended-json.rst + +Read Extended JSON +------------------ + +You can read an Extended JSON string into an Ruby array by calling +the ``BSON::ExtJSON.parse`` method. This method parses an Extended +JSON string and returns an array containing the data. + +The following example shows how you can read an Extended JSON string into a +array of hashes by using the ``parse`` method: + +.. io-code-block:: + :copyable: + + .. input:: /includes/data-formats/extended-json.rb + :start-after: start-ex-json-read + :end-before: end-ex-json-read + :language: ruby + :dedent: + + .. output:: + :language: none + :visible: false + + {"foo" => [1, 2]} + {"bar" => {"hello" => "world"}} + {"code" => #} + {"bin" => } + +Write Extended JSON +------------------- + +You can write an Extended JSON string by using the ``as_extended_json`` +method. By default, this method returns the Extended JSON string in canonical +format, but you can specify relaxed or legacy formats by passing a ``mode`` argument. + +.. note:: Legacy Version + + The legacy format option tells the {+driver-short+} to serialize BSON types + with the MongoDB Extended JSON v1 format, which predates the current + relaxed and canonical formats. + + For more information see, the :manual:`MongoDB Extended JSON v1 + ` page in the Server manual. + +The ``as_extended_json`` method is available for several core and standard +library types, including ``Array`` and ``Hash``. The following example creates +Extended JSON strings in the canonical, relaxed, and legacy formats, from an +array of hashes: + +.. io-code-block:: + :copyable: + + .. input:: /includes/data-formats/extended-json.rb + :start-after: start-ex-json-write + :end-before: end-ex-json-write + :language: ruby + :dedent: + + .. output:: + :language: none + :visible: false + + canonical: [{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":{"$numberLong":"42"}}] + relaxed: [{"foo":[1,2]},{"bin":{"$binary":{"base64":"AQIDBA==","subType":"80"}}},{"number":42}] + legacy: [{"foo":[1,2]},{"bin":{"$binary":"AQIDBA==","$type":"80"}},{"number":42}] + +Additional Information +---------------------- + +For more information, see the following resources: + +API Documentation +~~~~~~~~~~~~~~~~~ + +- `BSON::ExtJSON.parse `__ +- `#as_extended_json `__ + +Server Manual Pages +~~~~~~~~~~~~~~~~~~~ + +- :manual:`MongoDB Extended JSON (v2)` \ No newline at end of file diff --git a/source/includes/data-formats/extended-json.rb b/source/includes/data-formats/extended-json.rb new file mode 100644 index 00000000..a93a59e5 --- /dev/null +++ b/source/includes/data-formats/extended-json.rb @@ -0,0 +1,39 @@ +# start-ex-json-read +require 'bson' + +ex_json = '''[ + {"foo": [1, 2]}, + {"bar": {"hello": "world"}}, + {"code": { + "$scope": {}, + "$code": "function x() { return 1; }" + }}, + {"bin": { + "$type": "80", + "$binary": "AQIDBA==" + }} + ]''' + +doc = BSON::ExtJSON.parse(ex_json) + +puts doc.class +puts doc +# end-ex-json-read + +# start-ex-json-write +require 'bson' + +hash_array = [ + { "foo" => [1, 2] }, + { "bin" => BSON::Binary.new("\x01\x02\x03\x04", :user) }, + { "number" => BSON::Int64.new(42) } +] + +json_string_canonical = hash_array.as_extended_json +json_string_relaxed = hash_array.as_extended_json(mode: :relaxed) +json_string_legacy = hash_array.as_extended_json(mode: :legacy) + +puts "canonical:\t #{json_string_canonical}" +puts "relaxed:\t #{json_string_relaxed}" +puts "legacy:\t\t #{json_string_legacy}" +# end-ex-json-write \ No newline at end of file