From 932cf1be9184b5d36a868cafd96a60db7935399b Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 27 Nov 2012 12:22:21 -0500 Subject: [PATCH 1/4] DOCS-648 migrate tutorial wiki to getting started page --- draft/core/schema-free.txt | 27 ++ draft/tutorial/getting-started.txt | 468 +++++++++++++++++++++++++++++ source/applications/read.txt | 2 + 3 files changed, 497 insertions(+) create mode 100644 draft/core/schema-free.txt create mode 100644 draft/tutorial/getting-started.txt diff --git a/draft/core/schema-free.txt b/draft/core/schema-free.txt new file mode 100644 index 00000000000..856f38c3093 --- /dev/null +++ b/draft/core/schema-free.txt @@ -0,0 +1,27 @@ +============================ +Dynamic Schema (Schema Free) +============================ + +.. default-domain:: mongodb + +MongoDB has :term:`databases `, :term:`collections +`, and :term:`indexes ` much like a traditional +RDBMS. In some cases (databases and collections), these can be +implicitly created. Once created, they exist in a system catalog +(for example, ``db.systems.collections``, ``db.system.indexes``). + +Collections contain :term:`BSON` :term:`documents `. Within +these documents are fields. In MongoDB there is no predefinition of +fields (what would be columns in an RDBMS). There is no schema for +fields within documents. The fields and their value datatypes can vary. +Thus there is no notion of an "alter table" operation that adds a +"column". + +In practice, it is highly common for a collection to have a homogenous +structure across documents. Hoowever this is not a requirement. This +flexibility means that schema migration and augmentation are very easy +in practice. Rarely will you need to write scripts that perform "alter +table" type operations. In addition to making schema migration flexible, +this facility makes iterative software development atop the database +easier. + diff --git a/draft/tutorial/getting-started.txt b/draft/tutorial/getting-started.txt new file mode 100644 index 00000000000..a1ce830a636 --- /dev/null +++ b/draft/tutorial/getting-started.txt @@ -0,0 +1,468 @@ +============================ +Getting Started with MongoDB +============================ + +.. default-domain:: mongodb + +This tutorial is a one-page introduction to creating a MongoDB database +and inserting and retrieving documents. + +The tutorial assumes MongoDB is installed on a Linux or OS X operating +system and that the database server is running. For instructions on +installing MongoDB and starting the database server, see +:doc:`installation`. + +The tutorial assumes you are accessing the database using a Linux or OS +X operation system. + +The tutorial takes you through the following procedures: + +.. contents:: + :backlinks: none + :local: + +Connect to the Database Server +------------------------------ + +This tutorial accesses the database server using the MongoDB JavaScript +shell. You also can access a database server using a MongoDB :doc:`driver +`, though this tutorial does not cover that approach. +To access a database through a driver, see :doc:`/applications/drivers`. + +The MongoDB JavaScript shell is a full JavaScript shell. Any JavaScript +function, syntax, or class can be used in the shell. In addition, +MongoDB defines additional classes and global variables. For the full +API, see ``_. + +To connect to the database server, do the following: + +1. Open a command-line shell. + +#. Start the MongoDB JavaScript shell by issuing the :program:`mongo` command: + + .. code-block:: sh + + mongo + + By default, :program:`mongo` looks for a database server listening on + port ``27017``. To look for a server listening on a different port, + use the ``--port`` option, as described in :doc:`/reference/mongo`. + +#. Display the list of available databases by issuing the following + command: + + .. code-block:: javascript + + show dbs + +#. Switch to a new database called ``mydb`` by typing the following command: + + .. code-block:: javascript + + use mydb + +#. Confirm that you are on the ``mydb`` database by typing the following + command, which returns the name of the database you are on: + + .. code-block:: javascript + + db + + If you issue the ``show dbs`` command again you will not yet see + ``mydb`` listed. MongoDB will not create the ``mydb`` database + permanently until you insert data to the database, as described in + the next procedure. + +#. To get a list of help pages for the MongoDB JavaScript shell, issue + the following command: + + .. code-block:: javascript + + help + +Create and Add to a Collection +------------------------------ + +In this procedure, you insert documents into a new collection named ``things`` +within the new database named ``mydb``. MongoDB does not require that +you predefine the collection or database. Instead, MongoDB creates both +the first time you insert data. + +MongoDB databases are schema-free and do not require you to pre-define +structure. For more information on MongoDB's schema-free approach, see +:doc:`core/schema-free`. + +1. Confirm that you are on the ``mydb`` database by typing the following + command: + + .. code-block:: javascript + + db + +#. If MongoDB does not return ``mydb``, issue the following command: + + .. code-block:: javascript + + use mydb + +#. Create the ``j`` and ``t`` documents by entering the following sequence + of commands: + + .. code-block:: javascript + + j = { name : "mongo" } + t = { x : 3 } + +#. Insert the ``j`` and ``t`` documents as documents in the collection + ``things`` by entering the following sequence of commands: + + .. code-block:: javascript + + db.things.insert(j) + db.things.insert(t) + + Once you insert the first document (in this case, the ``j`` + document), MongoDB creates both the ``mydb`` database and the ``things`` + collection. + +#. Confirm that the ``things`` collection has been created by issuing + the following command: + + .. code-block:: javascript + + show collections + + MongoDB lists the collections in ``mydb``, which in this case is just + the one collection, `` things``. + +#. Confirm that the documents have been inserted by querying the + ``things`` collection using the :method:`find() ` method: + + .. code-block:: javascript + + db.things.find() + + MongoDB returns the following results. Your :term:`ObjectId` values + will be different: + + .. code-block:: javascript + + { "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" } + { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } + + All MongoDB documents must have an ``_id`` field with a unique value. + In this tutorial you do not explicitly create an ``_id`` field, so + MongoDB creates one for you and assigns the field an :term:`ObjectId`. + + The two documents you inserted have different fields from each other. + In practice, you usually give documents within a collection the same + structure. + +#. To add some more documents to this collection, issue the following + ``for`` loop: + + .. code-block:: javascript + + for (var i = 1; i <= 20; i++) db.things.insert({x : 4, j : i}) + +#. Query the collection again by issuing the following command: + + .. code-block:: javascript + + db.things.find() + + MongoDB returns the first 20 documents in the collection. Your + :term:`ObjectId` values will be different: + + .. code-block:: javascript + + { "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" } + { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } + { "_id" : ObjectId("4c220a42f3924d31102bd857"), "x" : 4, "j" : 2 } + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd859"), "x" : 4, "j" : 4 } + { "_id" : ObjectId("4c220a42f3924d31102bd85a"), "x" : 4, "j" : 5 } + { "_id" : ObjectId("4c220a42f3924d31102bd85b"), "x" : 4, "j" : 6 } + { "_id" : ObjectId("4c220a42f3924d31102bd85c"), "x" : 4, "j" : 7 } + { "_id" : ObjectId("4c220a42f3924d31102bd85d"), "x" : 4, "j" : 8 } + { "_id" : ObjectId("4c220a42f3924d31102bd85e"), "x" : 4, "j" : 9 } + { "_id" : ObjectId("4c220a42f3924d31102bd85f"), "x" : 4, "j" : 10 } + { "_id" : ObjectId("4c220a42f3924d31102bd860"), "x" : 4, "j" : 11 } + { "_id" : ObjectId("4c220a42f3924d31102bd861"), "x" : 4, "j" : 12 } + { "_id" : ObjectId("4c220a42f3924d31102bd862"), "x" : 4, "j" : 13 } + { "_id" : ObjectId("4c220a42f3924d31102bd863"), "x" : 4, "j" : 14 } + { "_id" : ObjectId("4c220a42f3924d31102bd864"), "x" : 4, "j" : 15 } + { "_id" : ObjectId("4c220a42f3924d31102bd865"), "x" : 4, "j" : 16 } + { "_id" : ObjectId("4c220a42f3924d31102bd866"), "x" : 4, "j" : 17 } + { "_id" : ObjectId("4c220a42f3924d31102bd867"), "x" : 4, "j" : 18 } + has more + +#. To return the next set of documents, issue the iteration command: + + .. code-block:: javascript + + it + + MongoDB returns the following: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } + { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } + + When you issued the :method:`find() ` method, + MongoDB created a "cursor" object that contained all the documents + returned by the query. The shell iterated over the cursor and + returned the first 20 documents. You then continued to iterate over + the cursor when used the ``it`` command. + + The next procedure describes additional ways to work with the cursor + object. + +For more information on inserting new documents, see :ref:`crud-create-insert`. + +Retrieve Data from a Collection +------------------------------- + +When you query a collection, MongoDB returns a "cursor" object that +contains the results of the query. Cursor objects give you flexibility +in how to work with results. + +The previous procedure showed how to display results by iterating over a +cursor using the ``it`` command. This procedure shows several other ways +to work with a cursor. + +1. In the MongoDB JavaScript shell, query the ``things`` collection + and assign the resultant cursor object to the ``c`` variable: + + .. code-block:: javascript + + var c = db.things.find() + +#. To return the full result set, not limiting the results to 20 + documents, use a ``while`` loop to iterate over the ``c`` variable: + + .. code-block:: javascript + + while (c.hasNext()) printjson(c.next()) + + The ``hasNext()`` function tells if there are any more documents to + return. The ``next()`` function returns the next document. The + ``printjson()`` method renders the document in a JSON-style format. + + MongoDB returns the following result. Your :term:`ObjectId` values + will be different: + + .. code-block:: javascript + + { "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" } + { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } + { "_id" : ObjectId("4c220a42f3924d31102bd857"), "x" : 4, "j" : 2 } + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd859"), "x" : 4, "j" : 4 } + { "_id" : ObjectId("4c220a42f3924d31102bd85a"), "x" : 4, "j" : 5 } + { "_id" : ObjectId("4c220a42f3924d31102bd85b"), "x" : 4, "j" : 6 } + { "_id" : ObjectId("4c220a42f3924d31102bd85c"), "x" : 4, "j" : 7 } + { "_id" : ObjectId("4c220a42f3924d31102bd85d"), "x" : 4, "j" : 8 } + { "_id" : ObjectId("4c220a42f3924d31102bd85e"), "x" : 4, "j" : 9 } + { "_id" : ObjectId("4c220a42f3924d31102bd85f"), "x" : 4, "j" : 10 } + { "_id" : ObjectId("4c220a42f3924d31102bd860"), "x" : 4, "j" : 11 } + { "_id" : ObjectId("4c220a42f3924d31102bd861"), "x" : 4, "j" : 12 } + { "_id" : ObjectId("4c220a42f3924d31102bd862"), "x" : 4, "j" : 13 } + { "_id" : ObjectId("4c220a42f3924d31102bd863"), "x" : 4, "j" : 14 } + { "_id" : ObjectId("4c220a42f3924d31102bd864"), "x" : 4, "j" : 15 } + { "_id" : ObjectId("4c220a42f3924d31102bd865"), "x" : 4, "j" : 16 } + { "_id" : ObjectId("4c220a42f3924d31102bd866"), "x" : 4, "j" : 17 } + { "_id" : ObjectId("4c220a42f3924d31102bd867"), "x" : 4, "j" : 18 } + { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } + { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } + +#. You can treat a cursor like an array. To find the document at the + fifth position (i.e. at subscript ``4``), issue the following command: + + .. code-block:: javascript + + var c = db.things.find() + printjson(c[4]) + + MongoDB returns the following: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } + + When you use a cursor this way, MongoDB loads into RAM all the + documents prior to the highest subscript queried (for example, + subscript ``4`` above). For very large result sets, you can run out + of memory. For queries that return large result sets, it is better to + iterate over the cursor using any of the iteration approaches already + described. + +#. To convert the cursor to a true array, use ``toArray()``. Issue the + following command to create an array ``a`` and to find the + document at the sixth position: + + .. code-block:: javascript + + var a = db.things.find().toArray() + a[5] + + MongoDB returns the following: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd859"), "x" : 4, "j" : 4 } + +For more information on the cursor object, see :ref:`crud-read-cursor`. + +.. todo What should we do with this info: + MongoDB cursors are not snapshots. Use explicit locking to perform + a snapshotted query. + +Query for Specific Documents +---------------------------- + +In this procedure, you query for specific documents in the ``things`` +collection by passing a query document as a parameter to the +:method:`find() ` method. + +A query document specifies the field-and-value pair that must be matched +for a document to be returned. For more information, see +:ref:`read-operations-query-document`. + +To query for specific documents, do the following: + +1. In the MongoDB JavaScript shell, query for all documents where the + ``name`` field has a value of ``mongo`` by passing the + ``{ name : "mongo" }`` query document as a parameter to the + :method:`find() ` method: + + .. code-block:: javascript + + db.things.find( { name : "mongo" } ) + + MongoDB returns the one document that fits this criteria. Your + :term:`ObjectId` value will be different: + + .. code-block:: javascript + + { "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" } + +#. Query for all documents where ``x`` has a value of ``4`` by passing + the ``{ x : 4 }`` query document as a parameter to :method:`find() + `: + + .. code-block:: javascript + + db.things.find( { x : 4 } ) + + MongoDB returns the following. Your :term:`ObjectId` values will be + different: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } + { "_id" : ObjectId("4c220a42f3924d31102bd857"), "x" : 4, "j" : 2 } + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd859"), "x" : 4, "j" : 4 } + { "_id" : ObjectId("4c220a42f3924d31102bd85a"), "x" : 4, "j" : 5 } + { "_id" : ObjectId("4c220a42f3924d31102bd85b"), "x" : 4, "j" : 6 } + { "_id" : ObjectId("4c220a42f3924d31102bd85c"), "x" : 4, "j" : 7 } + { "_id" : ObjectId("4c220a42f3924d31102bd85d"), "x" : 4, "j" : 8 } + { "_id" : ObjectId("4c220a42f3924d31102bd85e"), "x" : 4, "j" : 9 } + { "_id" : ObjectId("4c220a42f3924d31102bd85f"), "x" : 4, "j" : 10 } + { "_id" : ObjectId("4c220a42f3924d31102bd860"), "x" : 4, "j" : 11 } + { "_id" : ObjectId("4c220a42f3924d31102bd861"), "x" : 4, "j" : 12 } + { "_id" : ObjectId("4c220a42f3924d31102bd862"), "x" : 4, "j" : 13 } + { "_id" : ObjectId("4c220a42f3924d31102bd863"), "x" : 4, "j" : 14 } + { "_id" : ObjectId("4c220a42f3924d31102bd864"), "x" : 4, "j" : 15 } + { "_id" : ObjectId("4c220a42f3924d31102bd865"), "x" : 4, "j" : 16 } + { "_id" : ObjectId("4c220a42f3924d31102bd866"), "x" : 4, "j" : 17 } + { "_id" : ObjectId("4c220a42f3924d31102bd867"), "x" : 4, "j" : 18 } + { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } + { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } + +#. Query for all documents where ``x`` has a value of ``4``, as in the + last step, but this time return only the value of ``j``. To do this, + you add the ``{ j : true }`` document as a second parameter to + :method:`find() `. The document lists the + fields to be returned. Issue the following command: + + .. code-block:: javascript + + db.things.find( { x : 4 } , { j : true } ) + + MongoDB returns the following results, excluding the ``x`` field. The + ``_id`` field is included by default: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd856"), "j" : 1 } + { "_id" : ObjectId("4c220a42f3924d31102bd857"), "j" : 2 } + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "j" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd859"), "j" : 4 } + { "_id" : ObjectId("4c220a42f3924d31102bd85a"), "j" : 5 } + { "_id" : ObjectId("4c220a42f3924d31102bd85b"), "j" : 6 } + { "_id" : ObjectId("4c220a42f3924d31102bd85c"), "j" : 7 } + { "_id" : ObjectId("4c220a42f3924d31102bd85d"), "j" : 8 } + { "_id" : ObjectId("4c220a42f3924d31102bd85e"), "j" : 9 } + { "_id" : ObjectId("4c220a42f3924d31102bd85f"), "j" : 10 } + { "_id" : ObjectId("4c220a42f3924d31102bd860"), "j" : 11 } + { "_id" : ObjectId("4c220a42f3924d31102bd861"), "j" : 12 } + { "_id" : ObjectId("4c220a42f3924d31102bd862"), "j" : 13 } + { "_id" : ObjectId("4c220a42f3924d31102bd863"), "j" : 14 } + { "_id" : ObjectId("4c220a42f3924d31102bd864"), "j" : 15 } + { "_id" : ObjectId("4c220a42f3924d31102bd865"), "j" : 16 } + { "_id" : ObjectId("4c220a42f3924d31102bd866"), "j" : 17 } + { "_id" : ObjectId("4c220a42f3924d31102bd867"), "j" : 18 } + { "_id" : ObjectId("4c220a42f3924d31102bd868"), "j" : 19 } + { "_id" : ObjectId("4c220a42f3924d31102bd869"), "j" : 20 } + +#. MongoDB lets you retrieve one document at a time via the + :method:`findOne() ` method. The + :method:`findOne() ` method takes all the + same parameters as :method:`find() `, but + instead of returning a cursor, it returns a document. + + To retrieve one document from the ``things`` collection, issue the + following command: + + .. code-block:: javascript + + db.things.findOne() + +For more information on querying for documents, see the +:doc:`/applications/read` documentation. + +Limit the Number of Documents in the Result Set +----------------------------------------------- + +You can specify the maximum number of documents a query should return. +This can greatly improve performance as it limits the work the database +does and limits the amount of data returned over the network. + +To specify the maximum number of documents in the result set, use the +:method:`limit() ` method. + +Issue the following command: + +.. code-block:: javascript + + db.things.find().limit(3) + +MongoDB returns the following result. Your :term:`ObjectId` values will +be different: + +.. code-block:: javascript + + { "_id" : ObjectId("4c2209f9f3924d31102bd84a"), "name" : "mongo" } + { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } + { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } + +What Next +--------- + +To learn more about manipulating the documents in a database, see +:ref:`crud-operations`. diff --git a/source/applications/read.txt b/source/applications/read.txt index 8b2ea9b58db..8c66bd64e0e 100644 --- a/source/applications/read.txt +++ b/source/applications/read.txt @@ -308,6 +308,8 @@ Consider the following examples that illustrate the use of the } ) +.. _crud-read-cursor: + Cursor ~~~~~~ From 30cd181986f433b322f8357439446a45737827b2 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Tue, 27 Nov 2012 16:50:59 -0500 Subject: [PATCH 2/4] DOCS-648 tutorial page edits --- draft/core/schema-free.txt | 27 --- draft/tutorial/getting-started.txt | 287 ++++++++++++++++------------- source/faq/fundamentals.txt | 36 ++++ 3 files changed, 198 insertions(+), 152 deletions(-) delete mode 100644 draft/core/schema-free.txt diff --git a/draft/core/schema-free.txt b/draft/core/schema-free.txt deleted file mode 100644 index 856f38c3093..00000000000 --- a/draft/core/schema-free.txt +++ /dev/null @@ -1,27 +0,0 @@ -============================ -Dynamic Schema (Schema Free) -============================ - -.. default-domain:: mongodb - -MongoDB has :term:`databases `, :term:`collections -`, and :term:`indexes ` much like a traditional -RDBMS. In some cases (databases and collections), these can be -implicitly created. Once created, they exist in a system catalog -(for example, ``db.systems.collections``, ``db.system.indexes``). - -Collections contain :term:`BSON` :term:`documents `. Within -these documents are fields. In MongoDB there is no predefinition of -fields (what would be columns in an RDBMS). There is no schema for -fields within documents. The fields and their value datatypes can vary. -Thus there is no notion of an "alter table" operation that adds a -"column". - -In practice, it is highly common for a collection to have a homogenous -structure across documents. Hoowever this is not a requirement. This -flexibility means that schema migration and augmentation are very easy -in practice. Rarely will you need to write scripts that perform "alter -table" type operations. In addition to making schema migration flexible, -this facility makes iterative software development atop the database -easier. - diff --git a/draft/tutorial/getting-started.txt b/draft/tutorial/getting-started.txt index a1ce830a636..ae36e1e82d1 100644 --- a/draft/tutorial/getting-started.txt +++ b/draft/tutorial/getting-started.txt @@ -1,55 +1,48 @@ -============================ -Getting Started with MongoDB -============================ +================================================= +Getting Started with the MongoDB JavaScript Shell +================================================= .. default-domain:: mongodb -This tutorial is a one-page introduction to creating a MongoDB database -and inserting and retrieving documents. +This tutorial is an introduction to creating and retrieving database +documents using the MongoDB JavaScript Shell. + +The MongoDB JavaScript shell, also referred to as the :program:`mongo` +shell, is a full JavaScript shell that gives you access to all create, +read, update, and delete operations in a MongoDB database. The shell +also allows you to use all JavaScript functions and syntax. See the +:api:`mongo JavaScript API ` documentation and the :program:`mongo` +shell :doc:`JavaScript Methods `. The tutorial assumes MongoDB is installed on a Linux or OS X operating system and that the database server is running. For instructions on installing MongoDB and starting the database server, see -:doc:`installation`. - -The tutorial assumes you are accessing the database using a Linux or OS -X operation system. - -The tutorial takes you through the following procedures: +:doc:`/installation`. -.. contents:: +.. contents:: The tutorial takes you through the following procedures: :backlinks: none :local: + :depth: 3 -Connect to the Database Server ------------------------------- - -This tutorial accesses the database server using the MongoDB JavaScript -shell. You also can access a database server using a MongoDB :doc:`driver -`, though this tutorial does not cover that approach. -To access a database through a driver, see :doc:`/applications/drivers`. - -The MongoDB JavaScript shell is a full JavaScript shell. Any JavaScript -function, syntax, or class can be used in the shell. In addition, -MongoDB defines additional classes and global variables. For the full -API, see ``_. +Connect to the :program:`mongod` +-------------------------------- -To connect to the database server, do the following: +From the command line, start the MongoDB JavaScript shell by issuing the +:program:`mongo` command: -1. Open a command-line shell. +.. code-block:: sh -#. Start the MongoDB JavaScript shell by issuing the :program:`mongo` command: + mongo - .. code-block:: sh +By default, :program:`mongo` looks for a database server listening on +port ``27017``. To look for a server listening on a different port, use +the :option:`--port ` option. - mongo +Select a Database +~~~~~~~~~~~~~~~~~ - By default, :program:`mongo` looks for a database server listening on - port ``27017``. To look for a server listening on a different port, - use the ``--port`` option, as described in :doc:`/reference/mongo`. - -#. Display the list of available databases by issuing the following - command: +1. From the :program:`mongo` shell, display the list of available +databases by issuing the following command: .. code-block:: javascript @@ -61,8 +54,9 @@ To connect to the database server, do the following: use mydb -#. Confirm that you are on the ``mydb`` database by typing the following - command, which returns the name of the database you are on: +#. Confirm that the ``mydb`` database is the context for your session by + typing the following command, which returns the name of the database + you are on: .. code-block:: javascript @@ -73,27 +67,33 @@ To connect to the database server, do the following: permanently until you insert data to the database, as described in the next procedure. -#. To get a list of help pages for the MongoDB JavaScript shell, issue - the following command: +Display :program:`mongod` Help +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: javascript +To return a list of help pages for the :program:`mongo` shell, issue the +following command: + +.. code-block:: javascript + + help - help +Create a Collection and Insert Documents +---------------------------------------- -Create and Add to a Collection ------------------------------- +In these procedures, you insert documents into a new :term:`collection` +named ``things`` within the new :term:`database` named ``mydb``. MongoDB +does not require that you predefine the collection or database. Instead, +MongoDB creates both the first time you insert data. -In this procedure, you insert documents into a new collection named ``things`` -within the new database named ``mydb``. MongoDB does not require that -you predefine the collection or database. Instead, MongoDB creates both -the first time you insert data. +MongoDB also does not require you to pre-define the structure of your +documents. MongoDB databases use dynamic schemas. See +:ref:`faq-schema-free`. -MongoDB databases are schema-free and do not require you to pre-define -structure. For more information on MongoDB's schema-free approach, see -:doc:`core/schema-free`. +Insert Individual Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. Confirm that you are on the ``mydb`` database by typing the following - command: +1. From the :program:`mongo` shell, confirm that the ``mydb`` database + is the context for your session by typing the following command: .. code-block:: javascript @@ -105,8 +105,8 @@ structure. For more information on MongoDB's schema-free approach, see use mydb -#. Create the ``j`` and ``t`` documents by entering the following sequence - of commands: +#. Create two documents, named ``j`` and ``t``, by issuing the following + sequence of operations: .. code-block:: javascript @@ -114,7 +114,7 @@ structure. For more information on MongoDB's schema-free approach, see t = { x : 3 } #. Insert the ``j`` and ``t`` documents as documents in the collection - ``things`` by entering the following sequence of commands: + ``things`` by entering the following sequence of operations: .. code-block:: javascript @@ -125,15 +125,15 @@ structure. For more information on MongoDB's schema-free approach, see document), MongoDB creates both the ``mydb`` database and the ``things`` collection. -#. Confirm that the ``things`` collection has been created by issuing +#. Confirm that the collection named ``things`` has been created by issuing the following command: .. code-block:: javascript show collections - MongoDB lists the collections in ``mydb``, which in this case is just - the one collection, `` things``. + The :program:`mongo` shell returns a list of the collections in + ``mydb``, which in this case is just the one collection, `` things``. #. Confirm that the documents have been inserted by querying the ``things`` collection using the :method:`find() ` method: @@ -142,8 +142,8 @@ structure. For more information on MongoDB's schema-free approach, see db.things.find() - MongoDB returns the following results. Your :term:`ObjectId` values - will be different: + MongoDB returns the following results. Your :doc:`ObjectId + ` values will be different: .. code-block:: javascript @@ -151,28 +151,31 @@ structure. For more information on MongoDB's schema-free approach, see { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } All MongoDB documents must have an ``_id`` field with a unique value. - In this tutorial you do not explicitly create an ``_id`` field, so - MongoDB creates one for you and assigns the field an :term:`ObjectId`. + These operations do not explicitly specify a value for the ``_id`` + field, so :program:`mongo` creates a unique :doc:`ObjectId + ` value for the field. - The two documents you inserted have different fields from each other. - In practice, you usually give documents within a collection the same - structure. + Unlike the documents in the ``things`` collection, most MongoDB + collections store documents with the same structure. -#. To add some more documents to this collection, issue the following - ``for`` loop: +Insert Multiple Documents Using a For Loop +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. From the :program:`mongo` shell, add more documents to the collection + named ``things`` by issuing the following ``for`` loop: .. code-block:: javascript for (var i = 1; i <= 20; i++) db.things.insert({x : 4, j : i}) -#. Query the collection again by issuing the following command: +#. Query the collection by issuing the following command: .. code-block:: javascript db.things.find() MongoDB returns the first 20 documents in the collection. Your - :term:`ObjectId` values will be different: + :doc:`ObjectId ` values will be different: .. code-block:: javascript @@ -198,11 +201,7 @@ structure. For more information on MongoDB's schema-free approach, see { "_id" : ObjectId("4c220a42f3924d31102bd867"), "x" : 4, "j" : 18 } has more -#. To return the next set of documents, issue the iteration command: - - .. code-block:: javascript - - it +#. Type ``it`` (for iterate) to return the next batch of results. MongoDB returns the following: @@ -211,11 +210,11 @@ structure. For more information on MongoDB's schema-free approach, see { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } - When you issued the :method:`find() ` method, - MongoDB created a "cursor" object that contained all the documents - returned by the query. The shell iterated over the cursor and - returned the first 20 documents. You then continued to iterate over - the cursor when used the ``it`` command. + When you issue the :method:`find() ` method, + MongoDB creates a "cursor" object that contains all the documents + returned by the query. The shell iterates over the cursor and + returns the first 20 documents. To continue to iterate over + the cursor, you type ``it``. The next procedure describes additional ways to work with the cursor object. @@ -225,33 +224,53 @@ For more information on inserting new documents, see :ref:`crud-create-insert`. Retrieve Data from a Collection ------------------------------- -When you query a collection, MongoDB returns a "cursor" object that +You have already returned documents from a collection by using the +:method:`find() ` method in its simplest form. + +In these procedures you will determine what is returned and displayed by +working with: + +- The cursor object created by :method:`find() ` + +- :ref:`Query documents ` + +- The :method:`limit() ` method + +Working with the Cursor Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you query a :term:`collection`, MongoDB returns a "cursor" object that contains the results of the query. Cursor objects give you flexibility in how to work with results. The previous procedure showed how to display results by iterating over a -cursor using the ``it`` command. This procedure shows several other ways -to work with a cursor. +cursor using the ``it`` command. This procedure shows other ways to work +with a cursor. + +For documentation on the cursor object, see :ref:`crud-read-cursor`. -1. In the MongoDB JavaScript shell, query the ``things`` collection - and assign the resultant cursor object to the ``c`` variable: +Return More than 20 Documents +````````````````````````````` + +1. In the MongoDB JavaScript shell, query the collection named ``things`` + and assign the resulting cursor object to the ``c`` variable: .. code-block:: javascript var c = db.things.find() -#. To return the full result set, not limiting the results to 20 +#. To return the full result set without limiting the results to 20 documents, use a ``while`` loop to iterate over the ``c`` variable: .. code-block:: javascript - while (c.hasNext()) printjson(c.next()) + while ( c.hasNext() ) printjson( c.next() ) The ``hasNext()`` function tells if there are any more documents to return. The ``next()`` function returns the next document. The ``printjson()`` method renders the document in a JSON-style format. - MongoDB returns the following result. Your :term:`ObjectId` values + MongoDB returns the following result. Your :doc:`ObjectId ` values will be different: .. code-block:: javascript @@ -279,13 +298,24 @@ to work with a cursor. { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } -#. You can treat a cursor like an array. To find the document at the - fifth position (i.e. at subscript ``4``), issue the following command: +Use Array Operations with the Cursor +```````````````````````````````````` + +You can treat a cursor like an array. You also can convert a cursor to an array. + +1. In the MongoDB JavaScript shell, query the collection named ``things`` + and assign the resulting cursor object to the ``c`` variable: .. code-block:: javascript var c = db.things.find() - printjson(c[4]) + +#. To find the document at the fifth position (i.e. at subscript ``4``), + issue the following command: + + .. code-block:: javascript + + printjson( c [ 4 ] ) MongoDB returns the following: @@ -293,21 +323,23 @@ to work with a cursor. { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } - When you use a cursor this way, MongoDB loads into RAM all the - documents prior to the highest subscript queried (for example, - subscript ``4`` above). For very large result sets, you can run out - of memory. For queries that return large result sets, it is better to - iterate over the cursor using any of the iteration approaches already - described. - -#. To convert the cursor to a true array, use ``toArray()``. Issue the - following command to create an array ``a`` and to find the + When you query based on a document's position in the cursor object, + :program:`mongo` loads into RAM all the documents prior to the + highest position queried. For example, if you query the document at + ``c[4]``, :program:`mongo` loads into RAM the documents at ``c[0]``, + ``c[1]``, ``c[2]`` and ``c[3]`` as well. For very large result sets, + you can run out of memory. For queries that return large result sets, + it is better to iterate over the cursor using any of the iteration + approaches already described. + +#. To convert the cursor to an array, use ``toArray()``. Issue the + following operations to create an array ``a`` and to find the document at the sixth position: .. code-block:: javascript var a = db.things.find().toArray() - a[5] + a [ 5 ] MongoDB returns the following: @@ -317,19 +349,19 @@ to work with a cursor. For more information on the cursor object, see :ref:`crud-read-cursor`. -.. todo What should we do with this info: +.. todo Add: MongoDB cursors are not snapshots. Use explicit locking to perform a snapshotted query. + And then link to kay's isolated operations document Query for Specific Documents ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In this procedure, you query for specific documents in the ``things`` -collection by passing a query document as a parameter to the -:method:`find() ` method. - -A query document specifies the field-and-value pair that must be matched -for a document to be returned. For more information, see +:term:`collection` by passing a "query document" as a parameter to the +:method:`find() ` method. A query document +specifies the field/value pair the query must match to return a +document. For more information, see :ref:`read-operations-query-document`. To query for specific documents, do the following: @@ -344,7 +376,7 @@ To query for specific documents, do the following: db.things.find( { name : "mongo" } ) MongoDB returns the one document that fits this criteria. Your - :term:`ObjectId` value will be different: + :doc:`ObjectId ` value will be different: .. code-block:: javascript @@ -358,8 +390,8 @@ To query for specific documents, do the following: db.things.find( { x : 4 } ) - MongoDB returns the following. Your :term:`ObjectId` values will be - different: + MongoDB returns the following result set. :doc:`ObjectId + ` values are always unique. .. code-block:: javascript @@ -420,11 +452,11 @@ To query for specific documents, do the following: { "_id" : ObjectId("4c220a42f3924d31102bd868"), "j" : 19 } { "_id" : ObjectId("4c220a42f3924d31102bd869"), "j" : 20 } -#. MongoDB lets you retrieve one document at a time via the - :method:`findOne() ` method. The - :method:`findOne() ` method takes all the - same parameters as :method:`find() `, but - instead of returning a cursor, it returns a document. +#. MongoDB lets you retrieve a single document via the :method:`findOne() + ` method. The :method:`findOne() + ` method takes all the same parameters as + :method:`find() `, but instead of returning a + cursor, it returns a document. To retrieve one document from the ``things`` collection, issue the following command: @@ -434,14 +466,14 @@ To query for specific documents, do the following: db.things.findOne() For more information on querying for documents, see the -:doc:`/applications/read` documentation. +:doc:`/applications/read` and :doc:`/read-operations` documentation. Limit the Number of Documents in the Result Set ------------------------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -You can specify the maximum number of documents a query should return. -This can greatly improve performance as it limits the work the database -does and limits the amount of data returned over the network. +You can constrain the size of the result set to increase performance by +limiting the amount of data your application must receive over the +network. To specify the maximum number of documents in the result set, use the :method:`limit() ` method. @@ -452,7 +484,7 @@ Issue the following command: db.things.find().limit(3) -MongoDB returns the following result. Your :term:`ObjectId` values will +MongoDB returns the following result. Your :doc:`ObjectId ` values will be different: .. code-block:: javascript @@ -461,8 +493,13 @@ be different: { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } -What Next ---------- +Continuing to Use MongoDB +------------------------- + +To learn more about manipulating the documents in a database, see: + +- :ref:`crud-operations` + +- :doc:`/reference/sql-comparison` -To learn more about manipulating the documents in a database, see -:ref:`crud-operations`. +- :doc:`/applications/drivers` diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index 6eb02d62ac1..7d98453bd08 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -32,6 +32,42 @@ partitioning. MongoDB uses :term:`BSON`, a binary object format similar to, but more expressive than, :term:`JSON`. +Do MongoDB Databases Have Tables? +--------------------------------- + +Instead of tables, a MongoDB database stores its data in +:term:`collections `, which are the rough equivalent of an +RDMS table but which have important difference. A collection is made up +of one or more :term:`documents `, and each document has one +or more fields. The documents are not required to have identical fields. + +You can add a field to some documents in a collection without adding it +to all documents in the collection. + +.. _faq-schema-free: + +Do MongoDB Databases have Schemas? +---------------------------------- + +MongoDB uses dynamic schemas. You can create documents and collections +without pre-defining their structure. You also can change the structure +of documents simply by adding new fields or deleting existing ones. +Documents in a collection are not required to have an identical set of +fields. + +Collections contain :term:`BSON` :term:`documents `. Within +these documents are fields. In MongoDB there is no predefinition of +fields (what would be columns in an RDBMS). There is no schema for +fields within documents. The fields and their value datatypes can vary. + +In practice, it is highly common for a collection to have a homogenous +structure across documents. However this is not a requirement. This +flexibility means that schema migration and augmentation are very easy +in practice. Rarely will you need to write scripts that perform "alter +table" type operations. In addition to making schema migration flexible, +this facility makes iterative software development atop the database +easier. + What languages can I use to work with the MongoDB? -------------------------------------------------- From c62ab19715cd7f04df7ab2fb5c0d83a9e9cecfe8 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 28 Nov 2012 15:58:01 -0500 Subject: [PATCH 3/4] DOCS-648 minor edit --- draft/tutorial/getting-started.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/draft/tutorial/getting-started.txt b/draft/tutorial/getting-started.txt index ae36e1e82d1..8d9d4da5e16 100644 --- a/draft/tutorial/getting-started.txt +++ b/draft/tutorial/getting-started.txt @@ -64,8 +64,8 @@ databases by issuing the following command: If you issue the ``show dbs`` command again you will not yet see ``mydb`` listed. MongoDB will not create the ``mydb`` database - permanently until you insert data to the database, as described in - the next procedure. + permanently until you insert data to the database, as described + next in :ref:`getting-started-create-documents`. Display :program:`mongod` Help ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -77,6 +77,8 @@ following command: help +.. _getting-started-create-documents: + Create a Collection and Insert Documents ---------------------------------------- From c5d0081eda91e97d69fdbe870527be62ae92f20c Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 30 Nov 2012 20:01:27 -0500 Subject: [PATCH 4/4] DOCS-648 review edits --- draft/tutorial/getting-started.txt | 177 ++++++++++++----------------- source/faq/fundamentals.txt | 17 ++- 2 files changed, 82 insertions(+), 112 deletions(-) diff --git a/draft/tutorial/getting-started.txt b/draft/tutorial/getting-started.txt index 8d9d4da5e16..1183990e319 100644 --- a/draft/tutorial/getting-started.txt +++ b/draft/tutorial/getting-started.txt @@ -5,9 +5,10 @@ Getting Started with the MongoDB JavaScript Shell .. default-domain:: mongodb This tutorial is an introduction to creating and retrieving database -documents using the MongoDB JavaScript Shell. +documents using the MongoDB JavaScript Shell, also referred to as the +:program:`mongo` shell. -The MongoDB JavaScript shell, also referred to as the :program:`mongo` +The :program:`mongo` shell, is a full JavaScript shell that gives you access to all create, read, update, and delete operations in a MongoDB database. The shell also allows you to use all JavaScript functions and syntax. See the @@ -24,8 +25,15 @@ installing MongoDB and starting the database server, see :local: :depth: 3 -Connect to the :program:`mongod` --------------------------------- +Connect to a Database +--------------------- + +In this section you connect to the database server, referred to as the +:program:`mongod` (pronounced "Mongo D"), and then you connect to a +database. This section also tells you how to access help. + +Connect to a :program:`mongod` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From the command line, start the MongoDB JavaScript shell by issuing the :program:`mongo` command: @@ -35,7 +43,7 @@ From the command line, start the MongoDB JavaScript shell by issuing the mongo By default, :program:`mongo` looks for a database server listening on -port ``27017``. To look for a server listening on a different port, use +port ``27017``. To connect to a server on a different port, use the :option:`--port ` option. Select a Database @@ -54,9 +62,8 @@ databases by issuing the following command: use mydb -#. Confirm that the ``mydb`` database is the context for your session by - typing the following command, which returns the name of the database - you are on: +#. Confirm that the ``mydb`` database is selected by + typing the following command, which returns the name of the current database: .. code-block:: javascript @@ -70,7 +77,8 @@ databases by issuing the following command: Display :program:`mongod` Help ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To return a list of help pages for the :program:`mongo` shell, issue the +As you go through this tutorial and work with the :program:`mongo` +shell, you can access help from the shell at any time by issuing the following command: .. code-block:: javascript @@ -107,25 +115,24 @@ Insert Individual Documents use mydb -#. Create two documents, named ``j`` and ``t``, by issuing the following +#. Create two documents, named ``j`` and ``k``, by issuing the following sequence of operations: .. code-block:: javascript j = { name : "mongo" } - t = { x : 3 } + k = { x : 3 } -#. Insert the ``j`` and ``t`` documents as documents in the collection +#. Insert the ``j`` and ``k`` documents into the collection ``things`` by entering the following sequence of operations: .. code-block:: javascript - db.things.insert(j) - db.things.insert(t) + db.things.insert( j ) + db.things.insert( k ) - Once you insert the first document (in this case, the ``j`` - document), MongoDB creates both the ``mydb`` database and the ``things`` - collection. + Once you insert the first document, MongoDB creates both the ``mydb`` + database and the ``things`` collection. #. Confirm that the collection named ``things`` has been created by issuing the following command: @@ -157,18 +164,15 @@ Insert Individual Documents field, so :program:`mongo` creates a unique :doc:`ObjectId ` value for the field. - Unlike the documents in the ``things`` collection, most MongoDB - collections store documents with the same structure. - Insert Multiple Documents Using a For Loop ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1. From the :program:`mongo` shell, add more documents to the collection - named ``things`` by issuing the following ``for`` loop: +1. From the :program:`mongo` shell, add more documents to the ``things`` + collection by issuing the following ``for`` loop: .. code-block:: javascript - for (var i = 1; i <= 20; i++) db.things.insert({x : 4, j : i}) + for (var i = 1; i <= 20; i++) db.things.insert( { x : 4 , j : i } ) #. Query the collection by issuing the following command: @@ -176,8 +180,9 @@ Insert Multiple Documents Using a For Loop db.things.find() - MongoDB returns the first 20 documents in the collection. Your - :doc:`ObjectId ` values will be different: + The :program:`mongo` shell displays the first 20 documents in the + collection. Your :doc:`ObjectId ` values will be + different: .. code-block:: javascript @@ -201,9 +206,8 @@ Insert Multiple Documents Using a For Loop { "_id" : ObjectId("4c220a42f3924d31102bd865"), "x" : 4, "j" : 16 } { "_id" : ObjectId("4c220a42f3924d31102bd866"), "x" : 4, "j" : 17 } { "_id" : ObjectId("4c220a42f3924d31102bd867"), "x" : 4, "j" : 18 } - has more -#. Type ``it`` (for iterate) to return the next batch of results. +#. Type ``it`` to display more documents from the collection. MongoDB returns the following: @@ -212,57 +216,39 @@ Insert Multiple Documents Using a For Loop { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } - When you issue the :method:`find() ` method, - MongoDB creates a "cursor" object that contains all the documents - returned by the query. The shell iterates over the cursor and - returns the first 20 documents. To continue to iterate over - the cursor, you type ``it``. - - The next procedure describes additional ways to work with the cursor - object. - For more information on inserting new documents, see :ref:`crud-create-insert`. -Retrieve Data from a Collection -------------------------------- - -You have already returned documents from a collection by using the -:method:`find() ` method in its simplest form. - -In these procedures you will determine what is returned and displayed by -working with: - -- The cursor object created by :method:`find() ` - -- :ref:`Query documents ` - -- The :method:`limit() ` method - -Working with the Cursor Object -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Working with the Cursor +----------------------- -When you query a :term:`collection`, MongoDB returns a "cursor" object that -contains the results of the query. Cursor objects give you flexibility -in how to work with results. +When you query a :term:`collection`, MongoDB returns a "cursor" object +that contains the results of the query. The :program:`mongo` shell then +iterates over the cursor to display the results. Instead of displaying +all the results at once, which could number into the thousands or more, +depending on your database, the shell iterates over the cursor 20 times +to display the first 20 results. -The previous procedure showed how to display results by iterating over a -cursor using the ``it`` command. This procedure shows other ways to work -with a cursor. +As you saw in the previous procedure, you can display more results using +the ``it`` command. The ``it`` command tells the shell to iterate 20 +more times over the cursor and display the next 20 results. In the +previous procedure, the cursor contained only two more documents, and so +only two more documents displayed. -For documentation on the cursor object, see :ref:`crud-read-cursor`. +The procedures in this section show other ways to work with a cursor. +For comprehensive documentation on cursors, see :ref:`crud-read-cursor`. -Return More than 20 Documents -````````````````````````````` +Iterate over the Cursor with a Loop +``````````````````````````````````` -1. In the MongoDB JavaScript shell, query the collection named ``things`` +1. In the MongoDB JavaScript shell, query the ``things`` collection and assign the resulting cursor object to the ``c`` variable: .. code-block:: javascript var c = db.things.find() -#. To return the full result set without limiting the results to 20 - documents, use a ``while`` loop to iterate over the ``c`` variable: +#. Print the full result set by using a ``while`` loop to iterate over + the ``c`` variable: .. code-block:: javascript @@ -303,16 +289,16 @@ Return More than 20 Documents Use Array Operations with the Cursor ```````````````````````````````````` -You can treat a cursor like an array. You also can convert a cursor to an array. +You can treat a cursor like an array. -1. In the MongoDB JavaScript shell, query the collection named ``things`` +1. In the MongoDB JavaScript shell, query the ``things`` collection and assign the resulting cursor object to the ``c`` variable: .. code-block:: javascript var c = db.things.find() -#. To find the document at the fifth position (i.e. at subscript ``4``), +#. To find the document at the fifth position (i.e. at array index ``4``), issue the following command: .. code-block:: javascript @@ -325,36 +311,14 @@ You can treat a cursor like an array. You also can convert a cursor to an array. { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } - When you query based on a document's position in the cursor object, - :program:`mongo` loads into RAM all the documents prior to the - highest position queried. For example, if you query the document at - ``c[4]``, :program:`mongo` loads into RAM the documents at ``c[0]``, - ``c[1]``, ``c[2]`` and ``c[3]`` as well. For very large result sets, - you can run out of memory. For queries that return large result sets, - it is better to iterate over the cursor using any of the iteration - approaches already described. - -#. To convert the cursor to an array, use ``toArray()``. Issue the - following operations to create an array ``a`` and to find the - document at the sixth position: - - .. code-block:: javascript - - var a = db.things.find().toArray() - a [ 5 ] - - MongoDB returns the following: - - .. code-block:: javascript + When you access a document based on its indexed position in the cursor object, + :program:`mongo` also loads into RAM all documents with lower index values. - { "_id" : ObjectId("4c220a42f3924d31102bd859"), "x" : 4, "j" : 4 } - -For more information on the cursor object, see :ref:`crud-read-cursor`. + For example, if you access the document at ``c[4]``, :program:`mongo` + loads into RAM the documents at ``c[0]`` through ``c[3]`` as well. + For very large result sets, you can run out of memory. -.. todo Add: - MongoDB cursors are not snapshots. Use explicit locking to perform - a snapshotted query. - And then link to kay's isolated operations document +For more information on the cursor, see :ref:`crud-read-cursor`. Query for Specific Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -362,9 +326,8 @@ Query for Specific Documents In this procedure, you query for specific documents in the ``things`` :term:`collection` by passing a "query document" as a parameter to the :method:`find() ` method. A query document -specifies the field/value pair the query must match to return a -document. For more information, see -:ref:`read-operations-query-document`. +specifies the criteria the query must match to return a document. For +more information, see :ref:`read-operations-query-document`. To query for specific documents, do the following: @@ -377,7 +340,7 @@ To query for specific documents, do the following: db.things.find( { name : "mongo" } ) - MongoDB returns the one document that fits this criteria. Your + MongoDB displays the one document that fits this criteria. Your :doc:`ObjectId ` value will be different: .. code-block:: javascript @@ -419,17 +382,17 @@ To query for specific documents, do the following: { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } #. Query for all documents where ``x`` has a value of ``4``, as in the - last step, but this time return only the value of ``j``. To do this, - you add the ``{ j : true }`` document as a second parameter to - :method:`find() `. The document lists the - fields to be returned. Issue the following command: + last step, but this time return only the value of ``j`` (and the + ``_id`` field, which is returned by default). To do this, you add the + ``{ j : true }`` document as a second parameter to :method:`find() + `. The document lists the fields to be + returned. Issue the following command: .. code-block:: javascript db.things.find( { x : 4 } , { j : true } ) - MongoDB returns the following results, excluding the ``x`` field. The - ``_id`` field is included by default: + MongoDB returns the following results: .. code-block:: javascript @@ -495,6 +458,8 @@ be different: { "_id" : ObjectId("4c2209fef3924d31102bd84b"), "x" : 3 } { "_id" : ObjectId("4c220a42f3924d31102bd856"), "x" : 4, "j" : 1 } +.. todo Add sections on Update and Remove + Continuing to Use MongoDB ------------------------- diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index 7d98453bd08..020e5ddaa56 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -36,13 +36,18 @@ Do MongoDB Databases Have Tables? --------------------------------- Instead of tables, a MongoDB database stores its data in -:term:`collections `, which are the rough equivalent of an -RDMS table but which have important difference. A collection is made up -of one or more :term:`documents `, and each document has one -or more fields. The documents are not required to have identical fields. +:term:`collections `, which are the rough equivalent of RDMS +tables. A collection is made up of one or more :term:`documents +` (the rough equivalent of a record), and each document has +one or more fields (the rough equivalents of columns). -You can add a field to some documents in a collection without adding it -to all documents in the collection. +Collections have some important differences from RDMS tables: + +- The documents in a collection can have different fields from each + other. They are not required to have identical fields. + +- You can add a field to some documents in a collection without adding + it to all documents in the collection. .. _faq-schema-free: