diff --git a/draft/tutorial/getting-started.txt b/draft/tutorial/getting-started.txt new file mode 100644 index 00000000000..1183990e319 --- /dev/null +++ b/draft/tutorial/getting-started.txt @@ -0,0 +1,472 @@ +================================================= +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, also referred to as the +:program:`mongo` shell. + +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`. + +.. contents:: The tutorial takes you through the following procedures: + :backlinks: none + :local: + :depth: 3 + +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: + +.. code-block:: sh + + mongo + +By default, :program:`mongo` looks for a database server listening on +port ``27017``. To connect to a server on a different port, use +the :option:`--port ` option. + +Select a Database +~~~~~~~~~~~~~~~~~ + +1. From the :program:`mongo` shell, 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 the ``mydb`` database is selected by + typing the following command, which returns the name of the current database: + + .. 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 + next in :ref:`getting-started-create-documents`. + +Display :program:`mongod` Help +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 + + help + +.. _getting-started-create-documents: + +Create a Collection and Insert Documents +---------------------------------------- + +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. + +MongoDB also does not require you to pre-define the structure of your +documents. MongoDB databases use dynamic schemas. See +:ref:`faq-schema-free`. + +Insert Individual Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 + + db + +#. If MongoDB does not return ``mydb``, issue the following command: + + .. code-block:: javascript + + use mydb + +#. Create two documents, named ``j`` and ``k``, by issuing the following + sequence of operations: + + .. code-block:: javascript + + j = { name : "mongo" } + k = { x : 3 } + +#. 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( k ) + + 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: + + .. code-block:: javascript + + show collections + + 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: + + .. code-block:: javascript + + db.things.find() + + MongoDB returns the following results. Your :doc:`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. + These operations do not explicitly specify a value for the ``_id`` + field, so :program:`mongo` creates a unique :doc:`ObjectId + ` value for the field. + +Insert Multiple Documents Using a 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 } ) + +#. Query the collection by issuing the following command: + + .. code-block:: javascript + + db.things.find() + + The :program:`mongo` shell displays the first 20 documents in the + collection. Your :doc:`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 } + +#. Type ``it`` to display more documents from the collection. + + MongoDB returns the following: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd868"), "x" : 4, "j" : 19 } + { "_id" : ObjectId("4c220a42f3924d31102bd869"), "x" : 4, "j" : 20 } + +For more information on inserting new documents, see :ref:`crud-create-insert`. + +Working with the Cursor +----------------------- + +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. + +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. + +The procedures in this section show other ways to work with a cursor. +For comprehensive documentation on cursors, see :ref:`crud-read-cursor`. + +Iterate over the Cursor with a Loop +``````````````````````````````````` + +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() + +#. Print the full result set by using 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 :doc:`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 } + +Use Array Operations with the Cursor +```````````````````````````````````` + +You can treat a cursor like an array. + +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 array index ``4``), + issue the following command: + + .. code-block:: javascript + + printjson( c [ 4 ] ) + + MongoDB returns the following: + + .. code-block:: javascript + + { "_id" : ObjectId("4c220a42f3924d31102bd858"), "x" : 4, "j" : 3 } + + 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. + + 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. + +For more information on the cursor, see :ref:`crud-read-cursor`. + +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 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: + +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 displays the one document that fits this criteria. Your + :doc:`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 result set. :doc:`ObjectId + ` values are always unique. + + .. 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`` (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: + + .. 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 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: + + .. code-block:: javascript + + db.things.findOne() + +For more information on querying for documents, see the +:doc:`/applications/read` and :doc:`/read-operations` documentation. + +Limit the Number of Documents in the Result Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Issue the following command: + +.. code-block:: javascript + + db.things.find().limit(3) + +MongoDB returns the following result. Your :doc:`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 } + +.. todo Add sections on Update and Remove + +Continuing to Use MongoDB +------------------------- + +To learn more about manipulating the documents in a database, see: + +- :ref:`crud-operations` + +- :doc:`/reference/sql-comparison` + +- :doc:`/applications/drivers` 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 ~~~~~~ diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index 6eb02d62ac1..020e5ddaa56 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -32,6 +32,47 @@ 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 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). + +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: + +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? --------------------------------------------------