From 86241ca88976729419a89aa3ce842f8bff020016 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 3 Oct 2012 16:22:45 -0400 Subject: [PATCH 1/4] DOCS-564 added collection-naming conventions --- source/release-notes/2.2.txt | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 8f1951d10da..9db4e5abc0a 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -303,6 +303,30 @@ See: :issue:`SERVER-6961` for more information. Behavioral Changes ~~~~~~~~~~~~~~~~~~ +Restrictions on Collection Names +```````````````````````````````` + +Collection names can no longer contain the ``$`` character. + +The following is a full list of collection-name restrictions. Collection +names can be any UTF-8 string with the following exceptions: + +- A collection name should begin with a letter or an underscore. + +- The empty string ("") is not a valid collection name. + +- Collection names cannot contain the ``$`` character. + +- Collection names cannot contain the null character: ``\0`` + +- Do not name a collection using the ``system.`` prefix. The ``system.`` + prefix is reserved for system collections, such as the + ``system.indexes`` collection that stores index keys. + +- The maximum size of a collection name is 128 characters, including the + name of the db and indexes. A best practice is to keep your collection + names below 80 characters. + Restrictions on Database Names for Windows `````````````````````````````````````````` From 284b338528662f3ed7dda6f5527a375e4f7f760a Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 4 Oct 2012 13:08:25 -0400 Subject: [PATCH 2/4] DOCS-564 add more info on collection-naming conventions --- source/release-notes/2.2.txt | 33 +++++++++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 9db4e5abc0a..374322b2633 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -306,7 +306,9 @@ Behavioral Changes Restrictions on Collection Names ```````````````````````````````` -Collection names can no longer contain the ``$`` character. +Collection names cannot contain the ``$`` character in version 2.2. The +character is still allowed for collection names in MongoDB versions +prior to 2.2. The following is a full list of collection-name restrictions. Collection names can be any UTF-8 string with the following exceptions: @@ -315,7 +317,7 @@ names can be any UTF-8 string with the following exceptions: - The empty string ("") is not a valid collection name. -- Collection names cannot contain the ``$`` character. +- Collection names cannot contain the ``$`` character. (version 2.2 only) - Collection names cannot contain the null character: ``\0`` @@ -327,6 +329,33 @@ names can be any UTF-8 string with the following exceptions: name of the db and indexes. A best practice is to keep your collection names below 80 characters. +If your collection name includes special characters, such as the +underscore character, then to access the collection use the +:method:`db.getCollection()` method or a similar :api:`method for your +driver <>`. + +.. example:: For example, to create a collection ``_foo`` and populate it + with document ``{ a : 1 }``, you issue the following command: + + .. code-block:: javascript + + db.getCollection("_foo").insert( { a : 1 } ) + + To query the collection you issue the following command and get the + following result: + + .. code-block:: javascript + + db.getCollection("_foo").find() + { "_id" : ObjectId("506dbf800f70bf70d1ca613b"), "a" : 1 } + + You *cannot* query the ``_foo`` collection with this command: + + .. code-block:: javascript + + db._foo.find() + Thu Oct 4 12:56:01 TypeError: db._foo has no properties (shell):1 + Restrictions on Database Names for Windows `````````````````````````````````````````` From 9e17c9234ddf45d12e7f9f2defe9aab3ba612072 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 4 Oct 2012 13:52:00 -0400 Subject: [PATCH 3/4] DOCS-564 minor edits --- source/release-notes/2.2.txt | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 374322b2633..8e6b4772d6b 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -306,7 +306,7 @@ Behavioral Changes Restrictions on Collection Names ```````````````````````````````` -Collection names cannot contain the ``$`` character in version 2.2. The +In version 2.2, collection names cannot contain the ``$`` character. The character is still allowed for collection names in MongoDB versions prior to 2.2. @@ -323,7 +323,7 @@ names can be any UTF-8 string with the following exceptions: - Do not name a collection using the ``system.`` prefix. The ``system.`` prefix is reserved for system collections, such as the - ``system.indexes`` collection that stores index keys. + ``system.indexes`` collection. - The maximum size of a collection name is 128 characters, including the name of the db and indexes. A best practice is to keep your collection @@ -331,25 +331,26 @@ names can be any UTF-8 string with the following exceptions: If your collection name includes special characters, such as the underscore character, then to access the collection use the -:method:`db.getCollection()` method or a similar :api:`method for your +:method:`db.getCollection()` method or a :api:`similar method for your driver <>`. -.. example:: For example, to create a collection ``_foo`` and populate it - with document ``{ a : 1 }``, you issue the following command: +.. example:: To create a collection ``_foo`` and populate it with + document ``{ a : 1 }``, you would issue the following command: .. code-block:: javascript db.getCollection("_foo").insert( { a : 1 } ) - To query the collection you issue the following command and get the - following result: + To query the collection, you would issue the following command and + get the following result: .. code-block:: javascript db.getCollection("_foo").find() { "_id" : ObjectId("506dbf800f70bf70d1ca613b"), "a" : 1 } - You *cannot* query the ``_foo`` collection with this command: + If you were to query the ``_foo`` collection with dot notation, you + would receive an error, as shown here: .. code-block:: javascript From 5fd7205f46564b3e2dda9cde6ed56b7d4c984915 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 4 Oct 2012 17:17:26 -0400 Subject: [PATCH 4/4] DOCS-564 collection names: minor edits --- source/release-notes/2.2.txt | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 8e6b4772d6b..89a07d4ad27 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -315,7 +315,7 @@ names can be any UTF-8 string with the following exceptions: - A collection name should begin with a letter or an underscore. -- The empty string ("") is not a valid collection name. +- The empty string (``""``) is not a valid collection name. - Collection names cannot contain the ``$`` character. (version 2.2 only) @@ -349,14 +349,6 @@ driver <>`. db.getCollection("_foo").find() { "_id" : ObjectId("506dbf800f70bf70d1ca613b"), "a" : 1 } - If you were to query the ``_foo`` collection with dot notation, you - would receive an error, as shown here: - - .. code-block:: javascript - - db._foo.find() - Thu Oct 4 12:56:01 TypeError: db._foo has no properties (shell):1 - Restrictions on Database Names for Windows ``````````````````````````````````````````