diff --git a/source/images/compass/export-modal.png b/source/images/compass/export-modal.png new file mode 100644 index 000000000..171e4ebba Binary files /dev/null and b/source/images/compass/export-modal.png differ diff --git a/source/images/compass/export-schema-button.png b/source/images/compass/export-schema-button.png new file mode 100644 index 000000000..b5e2bcc7d Binary files /dev/null and b/source/images/compass/export-schema-button.png differ diff --git a/source/includes/export-output-expanded.rst b/source/includes/export-output-expanded.rst new file mode 100644 index 000000000..d0171beb1 --- /dev/null +++ b/source/includes/export-output-expanded.rst @@ -0,0 +1,14 @@ +.. code-block:: json + :linenos: + :copyable: false + + "year": { + "type": "integer", + "x-bsonType": "int", + "x-metadata": { + "hasDuplicates": true, + "probability": 0.95, + "count": 950, + }, + "x-sampleValues": [ "2003", "2020", "2023" ] + }, diff --git a/source/includes/export-output-mongodb.rst b/source/includes/export-output-mongodb.rst new file mode 100644 index 000000000..3465bd782 --- /dev/null +++ b/source/includes/export-output-mongodb.rst @@ -0,0 +1,30 @@ +.. code-block:: json + :linenos: + :copyable: false + + { + $jsonSchema: { + bsonType: "object", + required: ["title", "year"], + properties: { + _id: { + bsonType: "objectId" + }, + title: { + bsonType: "string", + description: "Title must be a string", + }, + year: { + bsonType: "int", + description: "Year must be an integer" + }, + genres: { + bsonType: "array", + items: { + bsonType: "string" + }, + description: "Genres must be an array of strings" + }, + } + } + } diff --git a/source/includes/export-output-standard.rst b/source/includes/export-output-standard.rst new file mode 100644 index 000000000..3c81a55b2 --- /dev/null +++ b/source/includes/export-output-standard.rst @@ -0,0 +1,27 @@ +.. code-block:: json + :linenos: + :copyable: false + + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "required": ["title", "year"], + "properties": { + "_id": { + "type": "string", + "description": "MongoDB's ObjectId" + }, + "title": { + "type": "string" + }, + "year": { + "type": "number" + }, + "genres": { + "type": "array", + "items": { + "type": "string" + } + }, + } + } diff --git a/source/includes/schema-export-format-expanded.rst b/source/includes/schema-export-format-expanded.rst new file mode 100644 index 000000000..36a0c8339 --- /dev/null +++ b/source/includes/schema-export-format-expanded.rst @@ -0,0 +1,39 @@ +MongoDB format schema objects contain the following fields: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Property + - Data type + - Description + + * - ``type`` + - string + - Data type of the field. + + * - ``x-bsonType`` + - string or array + - |bson| type of this field. + + * - ``x-metadata`` + - document + - Document containing metadata about the field. + + * - ``x-metadata.hasDuplicates`` + - boolean + - ``true`` if a single value of this data type appears multiple + times in the corresponding field. Otherwise ``false``. + + * - ``x-metadata.probability`` + - float + - Probability that the value of the corresponding field is this + data type in a random document. + + * - ``x-metadata.count`` + - integer + - Number of documents sampled from the collection. + + * - ``x-sampleValues`` + - array + - Sample values as Expanded JSON. diff --git a/source/includes/schema-export-format-mongodb.rst b/source/includes/schema-export-format-mongodb.rst new file mode 100644 index 000000000..1333ed77b --- /dev/null +++ b/source/includes/schema-export-format-mongodb.rst @@ -0,0 +1 @@ +TODO diff --git a/source/includes/schema-export-format-standard.rst b/source/includes/schema-export-format-standard.rst new file mode 100644 index 000000000..23134bf7e --- /dev/null +++ b/source/includes/schema-export-format-standard.rst @@ -0,0 +1,44 @@ +Standard format schema objects contain the following fields: + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - Property + - Data type + - Description + + * - ``type`` + - string or array + - |bson| type of this data type. For details, see the `official JSON + docs `_. + + * - ``anyOf`` + - string + - For details, see the `official JSON docs + `_. + + * - ``required`` + - string or array + - Fields that must appear in the schema. For details, see the + `official JSON docs `_. + + * - ``properties`` + - document + - Properties for each field, such as ``type`` and ``description``. + For details, see the `official JSON docs + `_. + + * - ``properties..type`` + - string + - The data type of the ````. + + * - ``properties..description`` + - string + - Human-readable description of the ````. + + * - ``properties..items`` + - document + - Types of elements in array fields. For details, see the `official + JSON docs `_. + diff --git a/source/schema/export.txt b/source/schema/export.txt index 1275a517f..a16647642 100644 --- a/source/schema/export.txt +++ b/source/schema/export.txt @@ -10,6 +10,8 @@ Export Your Schema :depth: 1 :class: singlecol +.. |export-modal| replace:: *Export JSON Schema* modal + You can export your schema after analyzing it. This is useful for sharing your schema and comparing schemas across collections. @@ -24,133 +26,56 @@ If you have not already done so, analyze your schema: subset of documents from your collection. To learn more about sampling, see :ref:`Sampling `. -Once your schema has been analyzed, export your schema: - -1. In the top menu bar, click :guilabel:`Collection`. - -#. From the dropdown, click :guilabel:`Share Schema as JSON`. - -.. figure:: /images/compass/share-schema-json.png - :alt: Image showing Collection dropdown - -Your schema is copied to your clipboard as a |json| object. - -Schema Object Properties ------------------------- - -Schema objects have ``count`` and ``fields`` properties: - -- ``count`` is an integer that represents the number of documents - :ref:`sampled ` from the collection to generate the schema. - -- ``fields`` is an array of metadata objects that correspond to each - field in the documents analyzed during sampling. Each element in the - ``fields`` array contains the following fields: - -.. list-table:: - :header-rows: 1 - :widths: 25 35 40 - - * - Property - - Data type - - Description - - * - ``name`` - - String - - Name of the corresponding field, e.g. ``_id``. - - * - ``path`` - - String - - Path to the corresponding field within a document. - - * - ``count`` - - Integer - - Number of documents in which the corresponding field appears. - - * - ``types`` - - Array - - Array of metadata objects that represent each data type that - appears in the corresponding field. - - * - ``types[n].name`` - - String - - Name of this data type. - - * - ``types[n].bsonType`` - - String - - |bson| type of this data type. - - * - ``types[n].path`` - - String - - Path to the corresponding field within a document. - - * - ``types[n].count`` - - Integer - - Number of times this data type appears in the corresponding - field. - - * - ``types[n].values`` - - Array - - Array of the actual sampled values that - appear in the corresponding field and match this data type. - - * - ``types[n].total_count`` - - Integer - - If the corresponding field is an array, the number of elements - in that array. - - * - ``types[n].probability`` - - Number - - Probability that the value of the corresponding field is this - data type in a random document. - - * - ``types[n].unique`` - - Integer - - Number of unique values of this data type that appear in - the corresponding field. - - * - ``types[n].has_duplicates`` - - Boolean - - ``true`` if a single value of this data type appears multiple - times in the corresponding field. Otherwise ``false``. - - * - ``types[n].lengths`` - - Array - - If this data type is an array, an array of integers representing - the lengths of arrays found in the corresponding field. Not - present for other data types. - - * - ``types[n].average_length`` - - Number - - If this data type is an array, the average length of arrays in - the corresponding field across sampled documents. Not present - for other data types. - - * - ``total_count`` - - Integer - - Number of documents sampled from the collection. - - * - ``type`` - - String or Array - - String or array of strings representing possible types for - the corresponding field. - - * - ``has_duplicates`` - - Boolean - - ``true`` if a single value appears multiple times in - the corresponding field. Otherwise ``false``. - - * - ``probability`` - - Number - - Probability that a random document contains the corresponding - field. +Once your schema has been analyzed, export your schema. + +1. Click :guilabel:`Export Schema`. + + .. figure:: /images/compass/export-schema-button.png + :alt: Image showing Export Schema button` + + The :guilabel:`Export Schema` button appears in the top-left corner + of the viewport. + +#. In the |export-modal|, select the format to export to. + + .. figure:: /images/compass/export-modal.png + :alt: Image showing Collection dropdown + :figwidth: 400px + :width: 400px + +You can export your schema to the following formats: + +- :ref:`Standard ` format. +- :ref:`MongoDB ` format. +- :ref:`Expanded ` format. + +.. _export-format-standard: + +Standard Format Schema Object Properties +----------------------------------------- + +.. include:: /includes/schema-export-format-standard.rst + +.. _export-format-mongodb: + +MongoDB Format Schema Object Properties +--------------------------------------- + +.. include:: /includes/schema-export-format-mongodb.rst + +.. _export-format-expanded: + +Expanded Format Schema Object Properties +---------------------------------------- + +.. include:: /includes/schema-export-format-expanded.rst Example Schema -------------- The following example uses a collection of 3 documents, each with a ``sport`` field and unique information about that sport: - + .. code-block:: json :linenos: :copyable: true @@ -193,238 +118,20 @@ outputs. To import the example collection into |compass|: :guilabel:`Insert`. The example above outputs the following schema: + +.. tabs:: + + .. tab:: Standard Export Format + :tabid: standard-export-format -.. code-block:: json - :linenos: - :copyable: false - - { - "fields": [ - { - "name": "_id", - "path": "_id", - "count": 3, - "types": [ - { - "name": "ObjectID", - "bsonType": "ObjectID", - "path": "_id", - "count": 3, - "values": [ - "5e8359ba7782b98ba98c16fd", - "5e835a727782b98ba98c16fe", - "5e835ade7782b98ba98c16ff" - ], - "total_count": 0, - "probability": 1, - "unique": 3, - "has_duplicates": false - } - ], - "total_count": 3, - "type": "ObjectID", - "has_duplicates": false, - "probability": 1 - }, - { - "name": "equipment", - "path": "equipment", - "count": 1, - "types": [ - { - "name": "Undefined", - "type": "Undefined", - "path": "equipment", - "count": 2, - "total_count": 0, - "probability": 0.6666666666666666, - "unique": 1, - "has_duplicates": true - }, - { - "name": "Array", - "bsonType": "Array", - "path": "equipment", - "count": 1, - "types": [ - { - "name": "String", - "bsonType": "String", - "path": "equipment", - "count": 4, - "values": [ - "bat", - "baseball", - "glove", - "helmet" - ], - "total_count": 0, - "probability": 1, - "unique": 4, - "has_duplicates": false - } - ], - "lengths": [ - 4 - ], - "total_count": 4, - "probability": 0.3333333333333333, - "average_length": 4 - } - ], - "total_count": 3, - "type": [ - "Undefined", - "Array" - ], - "has_duplicates": true, - "probability": 0.3333333333333333 - }, - { - "name": "origin", - "path": "origin", - "count": 1, - "types": [ - { - "name": "Undefined", - "type": "Undefined", - "path": "origin", - "count": 2, - "total_count": 0, - "probability": 0.6666666666666666, - "unique": 1, - "has_duplicates": true - }, - { - "name": "String", - "bsonType": "String", - "path": "origin", - "count": 1, - "values": [ - "England" - ], - "total_count": 0, - "probability": 0.3333333333333333, - "unique": 1, - "has_duplicates": false - } - ], - "total_count": 3, - "type": [ - "Undefined", - "String" - ], - "has_duplicates": true, - "probability": 0.3333333333333333 - }, - { - "name": "sport", - "path": "sport", - "count": 3, - "types": [ - { - "name": "String", - "bsonType": "String", - "path": "sport", - "count": 3, - "values": [ - "Baseball", - "Football", - "Cricket" - ], - "total_count": 0, - "probability": 1, - "unique": 3, - "has_duplicates": false - } - ], - "total_count": 3, - "type": "String", - "has_duplicates": false, - "probability": 1 - }, - { - "name": "variants", - "path": "variants", - "count": 1, - "types": [ - { - "name": "Undefined", - "type": "Undefined", - "path": "variants", - "count": 2, - "total_count": 0, - "probability": 0.6666666666666666, - "unique": 1, - "has_duplicates": true - }, - { - "name": "Document", - "bsonType": "Document", - "path": "variants", - "count": 1, - "fields": [ - { - "name": "eu", - "path": "variants.eu", - "count": 1, - "types": [ - { - "name": "String", - "bsonType": "String", - "path": "variants.eu", - "count": 1, - "values": [ - "Football" - ], - "total_count": 0, - "probability": 1, - "unique": 1, - "has_duplicates": false - } - ], - "total_count": 1, - "type": "String", - "has_duplicates": false, - "probability": 1 - }, - { - "name": "us", - "path": "variants.us", - "count": 1, - "types": [ - { - "name": "String", - "bsonType": "String", - "path": "variants.us", - "count": 1, - "values": [ - "Soccer" - ], - "total_count": 0, - "probability": 1, - "unique": 1, - "has_duplicates": false - } - ], - "total_count": 1, - "type": "String", - "has_duplicates": false, - "probability": 1 - } - ], - "total_count": 0, - "probability": 0.3333333333333333 - } - ], - "total_count": 3, - "type": [ - "Undefined", - "Document" - ], - "has_duplicates": true, - "probability": 0.3333333333333333 - } - ], - "count": 3 - } + .. include:: /includes/export-output-standard.rst + + .. tab:: MongoDB Export Format + :tabid: mongodb-export-format + + .. include:: /includes/export-output-mongodb.rst + + .. tab:: Expanded Export Format + :tabid: expanded-export-format + + .. include:: /includes/export-output-expanded.rst