diff --git a/bin/builder_data.py b/bin/builder_data.py index 4a90a5518bf..e596d1c423a 100644 --- a/bin/builder_data.py +++ b/bin/builder_data.py @@ -87,6 +87,7 @@ ('$(rst-include)/table-sql-to-mongo-update-examples', 'sql'), ('$(rst-include)/table-sql-to-mongo-delete-examples', 'sql'), ('$(rst-include)/table-lock-behavior-per-operation', 'concurrency'), + ('$(rst-include)/table-mongodb-extended-json', 'json'), ] sphinx = [ diff --git a/bin/mongodb_domain.py b/bin/mongodb_domain.py index 76bc77402e0..51697a80ffb 100644 --- a/bin/mongodb_domain.py +++ b/bin/mongodb_domain.py @@ -136,6 +136,8 @@ def get_index_text(self, objectname, name_obj): return _('%s (JavaScript shell macro)') % (name) elif self.objtype == 'limit': return _('%s (MongoDB system limit)') % (name) + elif self.objtype == 'bsontype': + return _('%s (BSON type)') % (name) return '' def run(self): @@ -213,6 +215,7 @@ class MongoDBDomain(Domain): 'error': ObjType(l_('error'), 'error'), 'macro': ObjType(l_('macro'), 'macro'), 'limit': ObjType(l_('limit'), 'limit'), + 'bsontype': ObjType(l_('bsontype'), 'bsontype'), } directives = { @@ -230,6 +233,7 @@ class MongoDBDomain(Domain): 'error': MongoDBObject, 'macro': MongoDBObject, 'limit': MongoDBObject, + 'bsontype': MongoDBObject, } roles = { 'dbcommand': MongoDBXRefRole(), @@ -246,6 +250,7 @@ class MongoDBDomain(Domain): 'error': MongoDBXRefRole(), 'macro': MongoDBXRefRole(), 'limit': MongoDBXRefRole(), + 'bsontype': MongoDBXRefRole(), } initial_data = { 'objects': {}, # fullname -> docname, objtype diff --git a/source/includes/table-mongodb-extended-json.yaml b/source/includes/table-mongodb-extended-json.yaml new file mode 100644 index 00000000000..81349d95715 --- /dev/null +++ b/source/includes/table-mongodb-extended-json.yaml @@ -0,0 +1,197 @@ +# table structure. all content symbolic. +section: layout +header: [ meta.header1, meta.header2, meta.header3, meta.header4, meta.header5 ] +rows: + - 1: [ content.bson_bin, content.strict_bin, content.js_bin, content.mongo_bin, content.notes_bin ] + - 2: [ content.bson_date, content.strict_date, content.js_date, content.mongo_date, content.notes_date ] + - 3: [ content.bson_ts, content.strict_ts, content.js_ts, content.mongo_ts, content.notes_ts ] + - 4: [ content.bson_regex, content.strict_regex, content.js_regex, content.mongo_regex, content.notes_regex ] + - 5: [ content.bson_oid, content.strict_oid, content.js_oid, content.mongo_oid, content.notes_oid ] + - 6: [ content.bson_ref, content.strict_ref, content.js_ref, content.mongo_ref, content.notes_ref ] + - 7: [ content.bson_undef, content.strict_undef, content.js_undef, content.mongo_undef, content.notes_undef ] +--- +# table metadata, as meta. +section: meta +header1: "BSON Data Type" +header2: "Strict Mode" +header3: "JavaScript Mode" +header4: "mongo Shell Mode" +header5: "Notes" +--- +# table content, as content. +section: content +bson_bin: ".. bsontype:: data_binary" +strict_bin: | + .. code-block:: javascript + + { + "$binary": "", + "$type": "" + } +js_bin: | + .. code-block:: javascript + + { + "$binary": "", + "$type": "" + } +mongo_bin: | + .. code-block:: javascript + + { + "$binary": "", + "$type": "" + } +notes_bin: | + ```` is the base64 representation of a binary + string. + + ```` is the hexadecimal representation of a single byte + that indicates the data type. +bson_date: ".. bsontype:: data_date" +strict_date: | + .. code-block:: javascript + + { + "$date": + } +js_date: | + .. code-block:: javascript + + Date( ) +mongo_date: | + .. code-block:: javascript + + Date ( ) +notes_date: | + ```` is the JSON representation of a 64-bit signed + integer for milliseconds since epoch (unsigned before + version 1.9.1). +bson_ts: ".. bsontype:: data_timestamp" +strict_ts: | + .. code-block:: javascript + + { + "$timestamp": + { + "t": , + "i": + } + } +js_ts: | + .. code-block:: javascript + + { + "$timestamp": + { + "t": , + "i": + } + } +mongo_ts: | + .. code-block:: javascript + + Timestamp( , ) +notes_ts: | + ```` is the JSON representation + of a 32-bit unsigned integer + for seconds since epoch. + + ```` is a 32-bit unsigned + integer for the increment. +bson_regex: ".. bsontype:: data_regex" +strict_regex: | + .. code-block:: javascript + + { + "$regex": "", + "$options": "" + } +js_regex: | + .. code-block:: javascript + + // +mongo_regex: | + .. code-block:: javascript + + // +notes_regex: | + ```` is a string of valid JSON characters. + + ```` is a string that may contain valid JSON + characters and unescaped double quote (``"``) characters, but may not + contain unescaped forward slash (``/``) characters. + + ```` is a string containing the regex options + represented by the letters of the alphabet. + + ```` is a string that may contain only the + characters 'g', 'i', 'm' and 's' (added in v1.9). Because + the ``JavaScript`` and ``mongo Shell`` representations + support a limited range of options, any nonconforming + options will be dropped when converting to this + representation. +bson_oid: ".. bsontype:: data_oid" +strict_oid: | + .. code-block:: javascript + + { + "$oid": "" + } +js_oid: | + .. code-block:: javascript + + { + "$oid": "" + } +mongo_oid: | + .. code-block:: javascript + + ObjectId( "" ) +notes_oid: | + ```` is a 24-character hexadecimal string. +bson_ref: ".. bsontype:: data_ref" +strict_ref: | + .. code-block:: javascript + + { + "$ref": "", + "$id": "" + } +js_ref: | + .. code-block:: javascript + + { + "$ref" : "", + "$id" : "" + } +mongo_ref: | + .. code-block:: javascript + + DBRef("", "") +notes_ref: | + ```` is a string of valid JSON characters. + + ```` is a 24-character hexadecimal string. In the Strict + and JS representations, the Strict representation for a + :bsontype:`data_oid` can be used as the value. + +bson_undef: ".. bsontype:: data_undefined" +strict_undef: | + .. code-block:: javascript + + { + "$undefined": true + } +js_undef: | + .. code-block:: javascript + + undefined + +mongo_undef: | + .. code-block:: javascript + + undefined +notes_undef: | + The representation for the JavaScript/BSON undefined type. +... diff --git a/source/reference.txt b/source/reference.txt index 5ca0e513910..1f501cb8d02 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -92,6 +92,7 @@ General Reference :maxdepth: 1 reference/limits + reference/mongodb-extended-json reference/glossary .. seealso:: The :ref:`genindex` may provide useful insight into the diff --git a/source/reference/mongodb-extended-json.txt b/source/reference/mongodb-extended-json.txt new file mode 100644 index 00000000000..696dc5e89f6 --- /dev/null +++ b/source/reference/mongodb-extended-json.txt @@ -0,0 +1,30 @@ +===================== +MongoDB Extended BSON +===================== + +.. default-domain:: mongodb + +MongoDB :doc:`import and export utilities +` and MongoDB :wiki:`REST +Interfaces` support JSON-style access to MongoDB +:term:`BSON` documents. + +The REST interface supports three different modes for document output: + +- *Strict* mode that produces output that conforms to the `JSON RFC + specifications `_. + +- *JavaScript* mode that produces output that can be processed by most + JavaScript interpreters. + +- *mongo Shell* mode produces output that the :program:`mongo` shell + understands. This is basically an enhanced JavaScript format. + +MongoDB can understand all of these representations in REST input. + +Special representations are used for :term:`BSON types` that do not +have obvious JSON mappings, and multiple representations are allowed +for some of these types. These types are displayed in the following +table: + +.. include:: /includes/table-mongodb-extended-json.rst