diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt index f718ac42005..6e2ba2ea8bc 100644 --- a/source/reference/operator/query.txt +++ b/source/reference/operator/query.txt @@ -1,3 +1,5 @@ +.. _query-projection-operators-top: + ============================== Query and Projection Operators ============================== diff --git a/source/tutorial/getting-started.txt b/source/tutorial/getting-started.txt index 0f7ae59c669..6992d11af0d 100644 --- a/source/tutorial/getting-started.txt +++ b/source/tutorial/getting-started.txt @@ -6,16 +6,21 @@ Getting Started .. default-domain:: mongodb - -The following page provides various examples for querying in the -MongoDB Shell. For examples using MongoDB drivers, refer to the links -in the :ref:`gs-additional-examples` section. +This tutorial walks you through inserting test data into a MongoDB +database and querying that data using the documentation's embedded +web shell. You do not need to deploy or install MongoDB to complete +this tutorial. + +The examples in this tutorial use a subset of the +:atlas:`Sample Mflix Dataset `, which is +part of the sample data included in MongoDB's cloud-hosted service, +`MongoDB Atlas `__. +Atlas requires no installation overhead and offers a free tier to get +started. After completing this tutorial, you can use Atlas to +explore additional sample data or host your own data. .. _mongo-web-shell: -Examples --------- - .. include:: /includes/fact-mws.rst Click inside the shell to connect. Once connected, you can run the @@ -23,7 +28,7 @@ examples in the shell above. .. tabs:: - .. tab:: Step 1 + .. tab:: 1. Switch Database :tabid: example-1 Switch Database @@ -60,7 +65,7 @@ examples in the shell above. To create a collection in the database, see the next tab. - .. tab:: Step 2 + .. tab:: 2. Insert :tabid: example-2 Populate a Collection (Insert) @@ -74,21 +79,75 @@ examples in the shell above. The following example uses the :method:`db.collection.insertMany()` method to insert new - :doc:`documents ` into the ``inventory`` + :doc:`documents ` into the ``movies`` collection. You can copy and paste the example into the :ref:`shell ` above. .. code-block:: javascript - db.inventory.insertMany([ - { item: "journal", qty: 25, status: "A", size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "notebook", qty: 50, status: "A", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] }, - { item: "paper", qty: 10, status: "D", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] }, - { item: "planner", qty: 0, status: "D", size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "postcard", qty: 45, status: "A", size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] } - ]); - - // MongoDB adds an _id field with an ObjectId value if the field is not present in the document + db.movies.insertMany([ + { + title: 'Titanic', + year: 1997, + genres: [ 'Drama', 'Romance' ], + rated: 'PG-13', + languages: [ 'English', 'French', 'German', 'Swedish', 'Italian', 'Russian' ], + released: ISODate("1997-12-19T00:00:00.000Z"), + awards: { + wins: 127, + nominations: 63, + text: 'Won 11 Oscars. Another 116 wins & 63 nominations.' + }, + cast: [ 'Leonardo DiCaprio', 'Kate Winslet', 'Billy Zane', 'Kathy Bates' ], + directors: [ 'James Cameron' ] + }, + { + title: 'The Dark Knight', + year: 2008, + genres: [ 'Action', 'Crime', 'Drama' ], + rated: 'PG-13', + languages: [ 'English', 'Mandarin' ], + released: ISODate("2008-07-18T00:00:00.000Z"), + awards: { + wins: 144, + nominations: 106, + text: 'Won 2 Oscars. Another 142 wins & 106 nominations.' + }, + cast: [ 'Christian Bale', 'Heath Ledger', 'Aaron Eckhart', 'Michael Caine' ], + directors: [ 'Christopher Nolan' ] + }, + { + title: 'Spirited Away', + year: 2001, + genres: [ 'Animation', 'Adventure', 'Family' ], + rated: 'PG', + languages: [ 'Japanese' ], + released: ISODate("2003-03-28T00:00:00.000Z"), + awards: { + wins: 52, + nominations: 22, + text: 'Won 1 Oscar. Another 51 wins & 22 nominations.' + }, + cast: [ 'Rumi Hiiragi', 'Miyu Irino', 'Mari Natsuki', 'Takashi Naitè' ], + directors: [ 'Hayao Miyazaki' ] + }, + { + title: 'Casablanca', + genres: [ 'Drama', 'Romance', 'War' ], + rated: 'PG', + cast: [ 'Humphrey Bogart', 'Ingrid Bergman', 'Paul Henreid', 'Claude Rains' ], + languages: [ 'English', 'French', 'German', 'Italian' ], + released: ISODate("1943-01-23T00:00:00.000Z"), + directors: [ 'Michael Curtiz' ], + awards: { + wins: 9, + nominations: 6, + text: 'Won 3 Oscars. Another 6 wins & 6 nominations.' + }, + lastupdated: '2015-09-04 00:22:54.600000000', + year: 1942 + } + ]) The operation returns a document that contains the acknowledgement indicator and an array that contains the @@ -97,7 +156,7 @@ examples in the shell above. To verify the insert, you can query the collection (See the next tab). - .. tab:: Step 3 + .. tab:: 3. Find All :tabid: example-3 Select All Documents @@ -109,105 +168,62 @@ examples in the shell above. filter document ` to the method. In the :ref:`shell `, copy and paste the - following to return all documents in the ``inventory`` + following to return all documents in the ``movies`` collection. .. code-block:: javascript - db.inventory.find({}) - - To format the results, append the ``.pretty()`` to the - ``find`` operation: - - .. code-block:: javascript - - db.inventory.find({}).pretty() - - .. note:: + db.movies.find( { } ) - The example assumes that you have populated the - ``inventory`` collection from the previous step. - - .. tab:: Step 4 + .. tab:: 4. Filter Data :tabid: example-4 - Specify Equality Matches - ~~~~~~~~~~~~~~~~~~~~~~~~ + Filter Data with Comparison Operators + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For an equality match (i.e. ```` equals ````), + For an equality match (```` equals ````), specify ``: `` in the :ref:`query filter document ` and pass to the :method:`db.collection.find()` method. - .. note:: - - The examples assume that you have populated the - ``inventory`` collection. - - - In the :ref:`shell `, copy and paste the - following to return documents where ``status`` field equals - ``"D"``: + - In the :ref:`shell `, run the following + query to find movies that were directed by + ``Christopher Nolan``: .. code-block:: javascript - db.inventory.find( { status: "D" } ); + db.movies.find( { "directors": "Christopher Nolan" } ); - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0``: + You can use :ref:`comparison operators ` + to perform more advanced queries: - .. code-block:: javascript - - db.inventory.find( { qty: 0 } ); - - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0`` and ``status`` field equals ``"D"``: + - Run the following query to return movies that were released + before the year ``2000``: .. code-block:: javascript - db.inventory.find( { qty: 0, status: "D" } ); + db.movies.find( { "released": { $lt: ISODate("2000-01-01") } } ); - - In the :ref:`shell `, copy and paste the - following to return document where the ``uom`` field, nested - inside the size document, equals ``"in"``: + - Run the following query to return movies that won more than + ``100`` awards: .. code-block:: javascript - db.inventory.find( { "size.uom": "in" } ) + db.movies.find( { "awards.wins": { $gt: 100 } } ); - - In the :ref:`shell `, copy and paste the - following to return document where the ``size`` field equals - the document ``{ h: 14, w: 21, uom: "cm" }``: + - Run the following query to return movies where the + ``languages`` array contains *either* ``Japanese`` or + ``Mandarin``: .. code-block:: javascript - db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) - - Equality matches on the embedded document require an exact - match, including the field order. + db.movies.find( { "languages": { $in: [ "Japanese", "Mandarin" ] } } ) + + .. seealso:: - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` array - contains ``"red"`` as one of its elements: + :ref:`query-projection-operators-top` - .. code-block:: javascript - - db.inventory.find( { tags: "red" } ) - - If the ``tags`` field is a string instead of an array, then - the query is just an equality match. - - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` field - matches the specified array exactly, including the order: - - .. code-block:: javascript - - db.inventory.find( { tags: [ "red", "blank" ] } ) - - - .. tab:: Step 5 + .. tab:: 5. Project Fields :tabid: example-5 Specify Fields to Return (Projection) @@ -222,24 +238,68 @@ examples in the shell above. - ``: 0`` to exclude a field in the returned documents - In the :ref:`shell `, copy and paste the - following to return the ``_id``, ``item``, and the ``status`` - fields from all documents in the ``inventory`` collection: + In the :ref:`shell `, run the following query to + return the ``id``, ``title``, ``directors``, and ``year`` fields + from all documents in the ``movies`` collection: .. code-block:: javascript - db.inventory.find( { }, { item: 1, status: 1 } ); + db.movies.find( { }, { "title": 1, "directors": 1, "year": 1 } ); - You do not have to specify the ``_id`` field to return the - field. It returns by default. To exclude the field, set it to - ``0`` in the projection document. For example, copy and paste - the following to return only the ``item``, and the ``status`` - fields in the matching documents: + You do not have to specify the ``_id`` field to return the field. + It returns by default. To exclude the field, set it to ``0`` in + the projection document. For example, run the following query to + return only the ``title``, and the ``genres`` fields in the + matching documents: .. code-block:: javascript - db.inventory.find( {}, { _id: 0, item: 1, status: 1 } ); + db.movies.find( { }, { "_id": 0, "title": 1, "genres": 1 } ); + + .. tab:: 6. Aggregate + :tabid: example-6 + + Aggregate Data (:pipeline:`$group`) + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can use aggregation to group values from multiple documents + together and return a single result. Aggregation in MongoDB + is performed with an :ref:`aggregation pipeline + `. + + While :method:`find()` operations are useful for data + retrieval, the aggregation pipeline allows you to manipulate + data, perform calculations, and write more expressive queries + than simple :ref:`CRUD operations `. + + In the :ref:`shell `, run the following + aggregation pipeline to count the number of occurrences + of each ``genre`` value: + + .. code-block:: javascript + db.movies.aggregate( [ + { $unwind: "$genres" }, + { + $group: { + _id: "$genres", + genreCount: { $count: { } } + } + }, + { $sort: { "genreCount": -1 } } + ] ) + + The pipeline uses: + + - :pipeline:`$unwind` to output a document for each element + in the ``genres`` array. + + - :pipeline:`$group` and the :group:`$count` accumulator + to count the number of occurrences of each ``genre``. This + value is stored in the ``genreCount`` field. + + - :pipeline:`$sort` to sort the resulting documents + by the ``genreCount`` field in descending order. Next Steps ----------