From 6c414fa995d862dda4f40382d49b8726edb9be54 Mon Sep 17 00:00:00 2001 From: Kyle Suarez Date: Mon, 7 Dec 2015 15:05:05 -0500 Subject: [PATCH 1/2] DOCS-6679 add documentation for Compass A new section, "Additional Products", has been added to the table of contents. This is the (temporary) home of documentation for non-server products, including Compass. --- .gitignore | 1 + config/build_conf.yaml | 3 + source/contents.txt | 1 + source/includes/fact-compass-platforms.rst | 17 + .../steps-compass-manual-queries.yaml | 32 ++ .../includes/steps-compass-query-builder.yaml | 44 +++ source/includes/steps-starting-compass.yaml | 58 +++ source/products.txt | 39 ++ source/products/compass.txt | 344 ++++++++++++++++++ 9 files changed, 539 insertions(+) create mode 100644 source/includes/fact-compass-platforms.rst create mode 100644 source/includes/steps-compass-manual-queries.yaml create mode 100644 source/includes/steps-compass-query-builder.yaml create mode 100644 source/includes/steps-starting-compass.yaml create mode 100644 source/products.txt create mode 100644 source/products/compass.txt diff --git a/.gitignore b/.gitignore index 31df2751040..93f6aacc984 100644 --- a/.gitignore +++ b/.gitignore @@ -27,6 +27,7 @@ source/reference/*/*/*.rst source/reference/*.rst source/images/*.png source/images/*.rst +source/compass/images/* giza.log pdfs.yaml intersphinx.yaml diff --git a/config/build_conf.yaml b/config/build_conf.yaml index c872a8a3e68..dcc54f3e27c 100644 --- a/config/build_conf.yaml +++ b/config/build_conf.yaml @@ -33,6 +33,9 @@ assets: - branch: master path: build/docs-tools repository: https://github.com/mongodb/docs-tools.git + - branch: compass + path: source/compass/images + repository: https://github.com/mongodb/docs-assets.git paths: output: 'build' source: 'source' diff --git a/source/contents.txt b/source/contents.txt index dd3fe8fbc2a..57c331d775f 100644 --- a/source/contents.txt +++ b/source/contents.txt @@ -21,4 +21,5 @@ project, this Manual and additional editions of this text. /faq /reference /release-notes + /products /contributors diff --git a/source/includes/fact-compass-platforms.rst b/source/includes/fact-compass-platforms.rst new file mode 100644 index 00000000000..9131e5ca1ef --- /dev/null +++ b/source/includes/fact-compass-platforms.rst @@ -0,0 +1,17 @@ +.. list-table:: + :header-rows: 1 + :stub-columns: 1 + :class: compatibility + + * - Platform + - Mac OS X + - Windows + - Linux + * - Supported? + - |checkmark| + - |checkmark| + - + * - OS Version + - 10.10+ + - 7+ + - N/A diff --git a/source/includes/steps-compass-manual-queries.yaml b/source/includes/steps-compass-manual-queries.yaml new file mode 100644 index 00000000000..8a3bb80556d --- /dev/null +++ b/source/includes/steps-compass-manual-queries.yaml @@ -0,0 +1,32 @@ +title: Enter a query in the query bar +level: 4 +ref: enter-query +action: + pre: | + Queries entered in the query bar must be valid MongoDB syntax. Only + :dbcommand:`finds ` will be executed. + + This example manually selects documents whose ``departureAirportFsCode`` is + "JFK". + + .. figure:: /compass/images/manual-query.png + + When a valid query is entered, the bar is colored green and can be + executed. Invalid queries are colored red. The UI will automatically update + to indicate which fields and values are selected in the query. +--- +title: Apply the query +level: 4 +ref: apply +action: + pre: | + After entering a query, run it by clicking the Apply button. To clear the + query, use the Reset button. + + Continuing with the example, executing the query displays information on the + matching documents. + + .. figure:: /compass/images/manual-query-results.png + + To clear a query, use the Reset button. +... diff --git a/source/includes/steps-compass-query-builder.yaml b/source/includes/steps-compass-query-builder.yaml new file mode 100644 index 00000000000..2e3a70f226c --- /dev/null +++ b/source/includes/steps-compass-query-builder.yaml @@ -0,0 +1,44 @@ +title: Select values from charts +level: 4 +ref: select-values +action: + pre: | + Charts in Compass are fully interactive. Clicking on a chart value or bar + will automatically build a MongoDB query that matches the documents + pertaining to that section of the chart. + + In the example below, clicking on the "JFK" bar builds a query matching all + documents whose ``departureAirportFsCode`` field matches "JFK". + + .. figure:: /compass/images/query-builder-jfk.png + + Clicking on other field values adds them to the selection, creating a more + complex query. + + Continuing with the example, this selects a particular ``flightId`` in + addition to departures from JFK Airport. + + .. figure:: /compass/images/query-builder-jfk-flight-code.png + + To select multiple values within the same field, click and drag the mouse + over a selection of values. Alternatively, hold the Shift key while + selecting the desired values. + + .. figure:: /compass/images/query-builder-multi-select.png + + To deselect a previously-selected value, hold the Shift key while clicking + on the selection. + + .. figure:: /compass/images/query-builder-deselect.png +--- +title: Apply the query +level: 4 +ref: apply +action: + pre: | + After building a query, run it by clicking the Apply button. To clear the + query, use the Reset button. + + Note that composing "OR" queries is **not yet possible** with the automatic + query builder. +... diff --git a/source/includes/steps-starting-compass.yaml b/source/includes/steps-starting-compass.yaml new file mode 100644 index 00000000000..ccec81a5d46 --- /dev/null +++ b/source/includes/steps-starting-compass.yaml @@ -0,0 +1,58 @@ +title: Run and connect to MongoDB +level: 4 +ref: run-connect +action: + pre: | + When Compass is run for the first time, it presents the following initial + connection dialog: + + .. figure:: /compass/images/new-connection-form.png + + The following information is requested: + + a. Hostname: The hostname of the machine where :program:`mongod` is running. + b. Port: The port of the machine where :program:`mongod` is running. + c. Authentication: The authentication mechanism to connect to the target + host. Supported authentication mechanisms include: + + - MongoDB-CR + - SCRAM-SHA-1 + - Kerberos + - LDAP + + d. SSL: Whether or not Compass should connect to the target host with SSL. + Several SSL options are available: + + - Unvalidated: If this option is used, the server cerficiate is not + validated and no client certificate will be provided. The server must be + set up to allow connections without valid certificates. + - Server Validation: The server certificate will be validated, but no + client certificate will be provided. The server must be set up to allow + connections without valid certificates. + - Server and Client Validation: The server certificate will be validated + and a client certificate must be provided. + + e. Favorite Name (Optional): A nickname for the connection. Previous + connections are saved in Compass; a descriptive name simplifies + re-establishing the connection on future runs. + + .. figure:: /compass/images/favorite-connections.png + + After providing the requested information, click "Connect" to launch the + main Compass window. +--- +title: Select a database and collection +level: 4 +ref: select-db-coll +action: + pre: | + Use the navigation pane to select a database and collection to analyze. + + .. figure:: /compass/images/select-collection.png + + After making a selection, Compass will begin analyzing documents and present + a summary screen. Below is an example; results will vary based on the + contents of the collection. + + .. figure:: /compass/images/analysis-page.png +... diff --git a/source/products.txt b/source/products.txt new file mode 100644 index 00000000000..f80a70de60e --- /dev/null +++ b/source/products.txt @@ -0,0 +1,39 @@ +=================== +Additional Products +=================== + +.. default-domain:: mongodb + +MongoDB provides several products that make it easy to manage and +analyze data in a MongoDB deployment. + +.. class:: toc + + `MongoDB Ops Manager `_ + The easiest way to run MongoDB: includes Automation, Backup, and + Monitoring. For more information, see the `Ops Manager + documentation `_. + + |mms-home| + A cloud-based service for monitoring and backing up MongoDB + deployments. Also consider the |mms-docs|. + + :doc:`/products/compass` + A sophisticated GUI that simplifies collection analysis with data + visualization and an easy-to-use query builder. + + :doc:`/products/bi-connector` + A specialized server that connects MongoDB to Business + Intelligence Tools like `Tableau `_. + +.. class:: hidden + + .. toctree:: + :titlesonly: + + /products/ops-manager + /products/cloud-manager + /products/compass + /products/bi-connector + +.. include:: /includes/replacement-mms.rst diff --git a/source/products/compass.txt b/source/products/compass.txt new file mode 100644 index 00000000000..5247fb2bf04 --- /dev/null +++ b/source/products/compass.txt @@ -0,0 +1,344 @@ +=============== +MongoDB Compass +=============== + +.. default-domain:: mongodb + +.. important:: Do not run MongoDB Compass in production or on + mission-critical data. + +Overview +-------- + +Data in MongoDB has a flexible schema. :term:`Collections ` +do not enforce a rigidly-defined :term:`document` structure and the +schema of a collection is not defined or available for inspection within +the database. MongoDB's flexible schema and rich document structure make +developers more productive, but they also make it difficult to explore +and understand the underlying data and its structure without first +executing queries in the shell against the database. + +MongoDB Compass is a tool designed to allow users to easily analyze and +understand their schema within MongoDB without having to connect to a +shell or be familiar with the query syntax. It provides users with a +graphical view of their MongoDB schema by randomly sampling a subset of +documents from the entire collection. By sampling a subset of documents, +MongoDB Compass has minimal impact on the performance of the database +and can produce results to the user very quickly. For more information +on sampling, see the :ref:`compass-faq` section. + +Getting Started +--------------- + +MongoDB Compass currently runs on Mac OS X and Windows. Software +requirements to run Compass are listed below: + +.. include:: /includes/fact-compass-platforms.rst + +On Windows, Compass also requires .NET 4.5+. + +To download Compass, see the `downloads page +`_. + +Installing on OS X +~~~~~~~~~~~~~~~~~~ + +The Compass package is downloaded as a .dmg disk image. After the +download, open the disk image and drag the Compass application to the +Applications folder. + +.. figure:: /compass/images/osx-install-dialog.png + +The installation is now complete and the disk image can be safely +unmounted. Compass can be launched from the Applications directory. + +Installing on Windows +~~~~~~~~~~~~~~~~~~~~~ + +The Compass setup application is downloaded as a .exe executable file. +Run the program to begin the setup process, which will automatically +install Compass. + +Compass requires the **Microsoft .NET Framework version 4.5 or later**. +If it is not already installed on the system, the setup program will +prompt to automatically install .NET. + +Starting Compass +~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/starting-compass.rst + +Data Types +---------- + +Types and Missing Fields +~~~~~~~~~~~~~~~~~~~~~~~~ + +Compass displays the data types of fields in a collection's schema. The +example below reports that there are documents in the collection that +contain a field ``last_login`` with the type ``date``: + +.. figure:: /compass/images/field-example.png + :figwidth: 330px + +Compass also displays a percentage breakdown for fields with varying +data types across documents. In this example, 81% of documents store +``phone_no`` as a ``string``, and the remaining 19% store it as a +``number``: + +.. figure:: /compass/images/field-percentage-breakdown.png + :figwidth: 330px + +For sparse fields, where some documents omit a value, Compass displays +the percentage of missing values as ``undefined``. Here, the ``age`` +field is missing in 40% of the sampled documents. + +.. figure:: /compass/images/field-sparsity.png + :figwidth: 330px + +Understanding Charts +~~~~~~~~~~~~~~~~~~~~ + +Compass displays different charts for data fields depending on their :term:`BSON +type `. + +Strings +******* + +:term:`Strings ` can be displayed in three different ways. +If all the documents in the collection have unique strings for a given +field, Compass will display a random selection of string values. Click +on the refresh icon to generate a new set of random strings sampled from +the values for that field. + +.. figure:: /compass/images/string-random-sample.png + +If there are only a handful of unique string values, Compass will show the +strings in a single graded bar, indicating the percentage breakdown of string +values. + +.. figure:: /compass/images/string-percentage-breakdown.png + +When there are many different string values with some duplication, +Compass displays a histogram indicating the frequency of each string +found for that field. Hover the mouse on each histogram bar to see a +tool tip indicating the value of the string. + +.. figure:: /compass/images/string-histogram.png + +Numbers +******* + +:term:`Numbers ` are displayed in a similar manner to strings. A +randomly-sampled subset of data is shown for an entirely unique data set. + +.. figure:: /compass/images/number-random-sample.png + +For a data set of numbers containing duplicates, a histogram is shown to +indicate frequency. + +.. figure:: /compass/images/number-histogram.png + +Sub-documents +************* + +:term:`Sub-document ` fields are displayed with a small +triangle next to the field name, along with some additional data. + +.. figure:: /compass/images/subdocument.png + +Click on the triangle to expand the field and view the sub-documents contained +within. + +.. figure:: /compass/images/subdocument-expanded.png + +Arrays +****** + +Fields containing an :term:`array ` are displayed with the +type distribution of the array's elements. A second type distribution +bar is displayed beneath the ``array`` type. + +.. figure:: /compass/images/array-subtypes-array.png + +Click on an array sub-type to view a chart of the data for that specific +type. + +.. figure:: /compass/images/array-subtypes-boolean.png + +Dates and ObjectIDs +******************* + +Bar charts are used to represent :term:`dates `. They are also used +for fields containing an :term:`ObjectID `, from which a date can be +extracted. + +The two charts on the top row visualize the date's data: the first is the day of +the week of the timestamp, and the second is the hour of day. The third chart in +the bottom row displays the range of timestamps: the earliest date, the most +recent date and the distribution of all timestamps in between. + +.. figure:: /compass/images/dates-chart.png + +Coordinates +*********** + +When Compass detects values that look like geographical coordinates, it +displays the data in a scatter plot. Both :term:`GeoJSON` documents and +:term:`legacy coordinate pairs` are supported. + +Hover over points in the scatter plot with the mouse cursor to see a +tooltip displaying latitude and longitude coordinates. + +.. figure:: /compass/images/coordinate-scatter-plot.png + +Mixed Types +*********** + +When a field has mixed types throughout a collection, the type of chart +displayed can be changed by clicking on a specific data type underneath +the field name. + +As an example, this ``phone_no`` field is a mix of strings and numbers. +The chart displayed shows the values that are strings. + +.. figure:: /compass/images/mixed-types-string.png + +Click on the ``number`` data type to view the values that are numbers +instead. + +.. figure:: /compass/images/mixed-types-number.png + +Building Queries +---------------- + +There are two methods of building queries in Compass: automatic +generation with the query builder, or manual entry in the query bar. + +Using the Query Builder +~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/compass-query-builder.rst + +Manual Queries +~~~~~~~~~~~~~~ + +In addition to the automatic query builder, queries can be manually +entered into the query bar. It is also possible to manually edit queries +built from the automatic query builder for further refining. + +.. include:: /includes/steps/compass-manual-queries.rst + +Query Results +~~~~~~~~~~~~~ + +The query is executed on the full collection. If the result set is +larger than the ``sampleSize`` threshold (100 documents), then a random +subset of ``sampleSize`` documents is chosen from the result set and +displayed in the UI. + +Viewing Documents +----------------- + +Documents can be examined in the document viewing pane. This can be +expanded by clicking on the Document Viewer icon on the right-hand side +of the page. + +.. figure:: /compass/images/document-viewer-icon.png + +By default, the pane displays all of the documents sampled by Compass. +If a query is specified in the query bar, only documents that match the +query are shown. + +.. figure:: /compass/images/document-viewer-search-results.png + +.. _compass-faq: + +Frequently Asked Questions +-------------------------- + +What is the performance impact of running this tool? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Testing has shown that Compass has minimal impact in prototype +deployments, though additional performance testing and monitoring is in +progress. + +For best results, use MongoDB 3.2, which includes the +:pipeline:`$sample` operator for efficient sampling on a collection. On +older versions of MongoDB, Compass falls back on a :ref:`less efficient +sampling method `. + +It is recommended to only execute queries that are appropriately indexed +in the database to avoid scanning the entire collection. + +What is sampling and why is it used? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sampling in Compass is the procedure of selecting a subset of data from +a particular collection and analyzing the documents within the sample +set. + +Sampling is a common technique in statistical analysis because analyzing +a subset of the data gives similar results to analyzing all of it. In +addition, sampling allows results to be generated quickly rather than +performing a computationally-expensive collection scan. + +How does sampling work? +~~~~~~~~~~~~~~~~~~~~~~~ + +Compass employs two distinct sampling mechanisms. + +In MongoDB 3.2, collections are sampled with the :pipeline:`$sample` +operator via the :doc:`/core/aggregation-pipeline`. This provides +efficient random sampling without replacement over the entire +collection, or over the subset of documents specified by a query. + +.. _compass_fallback_sampling: + +In MongoDB 3.0 and 2.6, collections are sampled via a +backwards-compatible algorithm executed entirely within Compass. It +takes place in three stages: + +1. Compass opens a cursor on the desired collection, limited to at most + 10000 documents sorted in descending order of the ``_id`` field. +2. ``sampleSize`` documents are randomly selected from the stream. To + do this efficiently, Compass employs `reservoir sampling + `_. +3. Compass performs a query to select the chosen documents directly via + ``_id``. + +``sampleSize`` is set to 100 documents. + +Note that the choice of sampling method is done transparently in the +background, with no changes required by the user. + +Won't sampling miss documents? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sampling is chosen for its efficiency: the amount of time required to +perform a sample is minimal, on the order of a few seconds. Increasing +the sample confidence will demand more processing power and time. +Furthermore, sophisticated outlier detection requires an inspection of +every document in a MongoDB deployment, which would be unfeasible for +large data sets. The MongoDB team is in the process of conducting user +tests on large data sets to find a reasonable balance. + +Known Issues +------------ +For a list of known issues, please see the `MongoDB Compass JIRA +project`_. + +.. _`MongoDB Compass JIRA project`: https://jira.mongodb.com/issues/?jql=project%20%3D%20COMPASS%20AND%20resolution%20%3D%20Unresolved + +Contact +------- + +Any questions, concerns or feedback on MongoDB Compass is appreciated. +To report a bug, submit a ticket to the MongoDB `Commercial Support +JIRA`_. To submit a feature request, use the `Compass JIRA`_. + +.. _`Commercial Support JIRA`: https://jira.mongodb.com +.. _`Compass JIRA`: https://jira.mongodb.com + +.. include:: /includes/unicode-checkmark.rst From 6d9a38d3bc46c79e41f9d6d6b4a8ada961fa1bcd Mon Sep 17 00:00:00 2001 From: Kyle Suarez Date: Fri, 4 Dec 2015 15:54:14 -0500 Subject: [PATCH 2/2] add cloud/ops manager to additional products This adds short blurbs about Cloud Manager and Ops Manager to the "Additional Products" section, but their main purpose is to redirect users to the actual documentation hosted elsewhere. --- source/products.txt | 5 ----- source/products/cloud-manager.txt | 10 ++++++++++ source/products/ops-manager.txt | 11 +++++++++++ 3 files changed, 21 insertions(+), 5 deletions(-) create mode 100644 source/products/cloud-manager.txt create mode 100644 source/products/ops-manager.txt diff --git a/source/products.txt b/source/products.txt index f80a70de60e..b61bcd6ea60 100644 --- a/source/products.txt +++ b/source/products.txt @@ -22,10 +22,6 @@ analyze data in a MongoDB deployment. A sophisticated GUI that simplifies collection analysis with data visualization and an easy-to-use query builder. - :doc:`/products/bi-connector` - A specialized server that connects MongoDB to Business - Intelligence Tools like `Tableau `_. - .. class:: hidden .. toctree:: @@ -34,6 +30,5 @@ analyze data in a MongoDB deployment. /products/ops-manager /products/cloud-manager /products/compass - /products/bi-connector .. include:: /includes/replacement-mms.rst diff --git a/source/products/cloud-manager.txt b/source/products/cloud-manager.txt new file mode 100644 index 00000000000..baa997cd1ea --- /dev/null +++ b/source/products/cloud-manager.txt @@ -0,0 +1,10 @@ +===================== +MongoDB Cloud Manager +===================== + +|mms-home| is a cloud-based service for managing MongoDB deployments. +It provides useful tools including automation, monitoring and backup. + +For more information, please consult the |mms-docs|. + +.. include:: /includes/replacement-mms.rst diff --git a/source/products/ops-manager.txt b/source/products/ops-manager.txt new file mode 100644 index 00000000000..58784b2b408 --- /dev/null +++ b/source/products/ops-manager.txt @@ -0,0 +1,11 @@ +=================== +MongoDB Ops Manager +=================== + +`MongoDB Ops Manager` is the best way to run and manage MongoDB. It +includes automation, backup and monitoring tools. + +For more information, please consult the `Ops Manager documentation +`_. + +.. _`MongoDB Ops Manager`: https://mongodb.com/products/ops-manager