From 4d512736385415fddb8d059761bbcc073cd0cc9e Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 16 Nov 2012 16:42:24 -0500 Subject: [PATCH 1/2] DOCS-651 migrate collections page --- draft/core/collections.txt | 88 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 draft/core/collections.txt diff --git a/draft/core/collections.txt b/draft/core/collections.txt new file mode 100644 index 00000000000..c156b0f86f2 --- /dev/null +++ b/draft/core/collections.txt @@ -0,0 +1,88 @@ +=========== +Collections +=========== + +.. default-domain:: mongodb + +MongoDB :term:`collections` are named groupings of documents. You can +think of them as roughly equivalent to relational database tables. + +A MongoDB collection is a collection of :term:`BSON` :term:`documents +`. MongoDB is a schema-free database and does not predefine a +collection's fields. The documents within a collection may or may not +have the same structure. Any new document can add new fields to a +collection. + +Collections can be created explicitly using the +:method:`db.createCollection()` method but can also be created +implicitly by specifying a new collection name when creating a document +using the :method:`insert() ` method. + +Collection Names +---------------- + +A collection name can be any UTF-8 string that follows these standards: + +- Collection names should begin with a letter or an underscore (_). + +- Collection names can include numbers. + +- Collection names *cannot* include the ``$`` character, which is a + reserved character. + +- Collection names *cannot* include the null character. + +- Collection names *cannot* be an empty string (e.g. ``""``). + +- Collection names *cannot* begin with the ``system.`` prefix, which is + reserved for system collections. + +- The maximum size of a collection name is 128 characters, including the + name of the database. However, for maximum flexibility, collections + should have names less than 80 characters. + +Collections can be organized by namespaces. Namespaces are named groups +of collections defined using a dot notation. For example, the +collections ``blog.posts`` and ``blog.authors`` are in the ``blog`` +namespace. + +Namespaces are an organizational method for the database user and do not +imply an underlying organizational structure in the database itself. +From database perspective, there is no relationship between collections +in the same namespace. + +View a List of Collections +-------------------------- + +From the :program:`mongo` shell, you can view list of collections in a +database using the method:`getCollectionNames() +` method. + +Query a Collection +------------------ + +From the :program:`mongo` shell, you can query a collection's documents +using the MongoDB :method:`find() ` and +:method:`findOne() ` methods. For more +information, see :doc:`/applications/read`. + +If your collection name begins with an underscore, then to query the +collection's documents from the :program:`mongo` shell you must use the +:method:`getCollection() ` method along with the +query operator (e.g. :method:`find() `). + +Though underscores are allowed at the beginnings of collection names, +the :program:`mongo` shell considers the underscore character to be a +javascript value, not a collection name. The :method:`getCollection() +` method gets around this. Consider the following example: + +.. code-block:: javascript + + db.getCollection( "_mycollection" ).find() + +Capped Collections +------------------ + +MongoDB includes a special type of collection, called a :term:`capped +collection`, that is used for certain high-throughput operations, such +as journaling. See :doc:`/core/capped-collections`. From d3d02af29fc505102c4bf3738c0bf9e4bbf61101 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 16 Nov 2012 20:32:04 -0500 Subject: [PATCH 2/2] DOCS-651 migrate collections page to glossary --- draft/core/collections.txt | 88 ----------------------------------- source/faq/developers.txt | 12 +++++ source/reference/glossary.txt | 12 +++-- 3 files changed, 21 insertions(+), 91 deletions(-) delete mode 100644 draft/core/collections.txt diff --git a/draft/core/collections.txt b/draft/core/collections.txt deleted file mode 100644 index c156b0f86f2..00000000000 --- a/draft/core/collections.txt +++ /dev/null @@ -1,88 +0,0 @@ -=========== -Collections -=========== - -.. default-domain:: mongodb - -MongoDB :term:`collections` are named groupings of documents. You can -think of them as roughly equivalent to relational database tables. - -A MongoDB collection is a collection of :term:`BSON` :term:`documents -`. MongoDB is a schema-free database and does not predefine a -collection's fields. The documents within a collection may or may not -have the same structure. Any new document can add new fields to a -collection. - -Collections can be created explicitly using the -:method:`db.createCollection()` method but can also be created -implicitly by specifying a new collection name when creating a document -using the :method:`insert() ` method. - -Collection Names ----------------- - -A collection name can be any UTF-8 string that follows these standards: - -- Collection names should begin with a letter or an underscore (_). - -- Collection names can include numbers. - -- Collection names *cannot* include the ``$`` character, which is a - reserved character. - -- Collection names *cannot* include the null character. - -- Collection names *cannot* be an empty string (e.g. ``""``). - -- Collection names *cannot* begin with the ``system.`` prefix, which is - reserved for system collections. - -- The maximum size of a collection name is 128 characters, including the - name of the database. However, for maximum flexibility, collections - should have names less than 80 characters. - -Collections can be organized by namespaces. Namespaces are named groups -of collections defined using a dot notation. For example, the -collections ``blog.posts`` and ``blog.authors`` are in the ``blog`` -namespace. - -Namespaces are an organizational method for the database user and do not -imply an underlying organizational structure in the database itself. -From database perspective, there is no relationship between collections -in the same namespace. - -View a List of Collections --------------------------- - -From the :program:`mongo` shell, you can view list of collections in a -database using the method:`getCollectionNames() -` method. - -Query a Collection ------------------- - -From the :program:`mongo` shell, you can query a collection's documents -using the MongoDB :method:`find() ` and -:method:`findOne() ` methods. For more -information, see :doc:`/applications/read`. - -If your collection name begins with an underscore, then to query the -collection's documents from the :program:`mongo` shell you must use the -:method:`getCollection() ` method along with the -query operator (e.g. :method:`find() `). - -Though underscores are allowed at the beginnings of collection names, -the :program:`mongo` shell considers the underscore character to be a -javascript value, not a collection name. The :method:`getCollection() -` method gets around this. Consider the following example: - -.. code-block:: javascript - - db.getCollection( "_mycollection" ).find() - -Capped Collections ------------------- - -MongoDB includes a special type of collection, called a :term:`capped -collection`, that is used for certain high-throughput operations, such -as journaling. See :doc:`/core/capped-collections`. diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 44522cc188e..202ec13917e 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -32,6 +32,18 @@ occur in collection names, so that the ``acme.user.history`` is a valid namespace, with the ``acme`` database name, and the ``user.history`` collection name. +How do namespaces affect database internals? +-------------------------------------------- + +Namespaces do not affect database internals. Within a database, +collection namespaces have no hierarchy. + +Namespaces are an organizational method intended only for the database +user. Namespaces allow users to group related collections. For example, +the collections ``blog.posts`` and ``blog.authors`` are grouped together +as blogs. This is purely for the user's benefit and has no affect on +database organization. + How do you copy all objects from one collection to another? ----------------------------------------------------------- diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index d80544e15e1..5c30b52c30e 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -56,9 +56,15 @@ Glossary databases. collection - A namespace within a database for containing :term:`documents `. - Collections do not enforce a schema, but they are otherwise - mostly analogous to :term:`RDBMS` tables. + Collections are groupings of :term:`BSON` :term:`documents + `. Collections do not enforce a schema, but they are + otherwise mostly analogous to :term:`RDBMS` tables. + + The documents within a collection may or may not have the same + structure. Any new document can add new fields to a collection. + Collection names can have a dot, and you may use this to simulate + a hierarchical namespace; however, the collection namespace for + each database is itself flat. $cmd A virtual :term:`collection` that exposes :term:`MongoDB`'s