BSON 文档

Type Operators¶

To determine the type of fields, the mongo shell provides the following operators:

• instanceof returns a boolean to test if a value has a specific type.
• typeof returns the type of a field.

Dot Notation¶

MongoDB uses the dot notation to access the elements of an array and to access the fields of a subdocument.

To access an element of an array by the zero-based index position, you concatenate the array name with the dot (.) and zero-based index position:

'<array>.<index>'

To access a field of a subdocument with dot-notation, you concatenate the subdocument name with the dot (.) and the field name:

'<subdocument>.<field>'

Record Documents¶

Most documents in MongoDB in collections store data from users’ applications.

These documents have the following attributes:

• The maximum BSON document size is 16 megabytes.

  The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See mongofiles and the documentation for your driver for more information about GridFS.

• Documents have the following restrictions on field names:

  • The field name _id is reserved for use as a primary key; its value must be unique in the collection, is immutable, and may be of any type other than an array.
  • The field names cannot start with the $ character.
  • The field names cannot contain the . character.

The following document specifies a record in a collection:

{
  _id: 1,
  name: { first: 'John', last: 'Backus' },
  birth: new Date('Dec 03, 1924'),
  death: new Date('Mar 17, 2007'),
  contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ],
  awards: [
            { award: 'National Medal of Science',
              year: 1975,
              by: 'National Science Foundation' },
            { award: 'Turing Award',
              year: 1977,
              by: 'ACM' }
          ]
}

The document contains the following fields:

• _id, which must hold a unique value and is immutable.
• name that holds another document. This sub-document contains the fields first and last, which both hold strings.
• birth and death that both have date types.
• contribs that holds an array of strings.
• awards that holds an array of documents.

Consider the following behavior and constraints of the _id field in MongoDB documents:

• In documents, the _id field is always indexed for regular collections.
• The _id field may contain values of any BSON data type other than an array.

Consider the following options for the value of an _id field:

• Use an ObjectId. See the ObjectId documentation.

  Although it is common to assign ObjectId values to _id fields, if your objects have a natural unique identifier, consider using that for the value of _id to save space and to avoid an additional index.

• Generate a sequence number for the documents in your collection in your application and use this value for the _id value. See the 创建一个自动递增的序列字段 tutorial for an implementation pattern.

• Generate a UUID in your application code. For efficiency, store the UUID as a value of the BSON BinData type to reduce the size of UUID values as stored in the collection and in the _id index.

• Use your driver’s BSON UUID facility to generate UUIDs. Be aware that driver implementations may implement UUID serialization and deserialization logic differently, which may not be fully compatible with other drivers. See your driver documentation for information concerning UUID interoperability.

Query Specification Documents¶

Query documents specify the conditions that determine which records to select for read, update, and delete operations. You can use <field>:<value> expressions to specify the equality condition and query operator expressions to specify additional conditions.

When passed as an argument to methods such as the find() method, the remove() method, or the update() method, the query document selects documents for MongoDB to return, remove, or update, as in the following:

db.bios.find( { _id: 1 } )
db.bios.remove( { _id: { $gt: 3 } } )
db.bios.update( { _id: 1, name: { first: 'John', last: 'Backus' } },
                <update>,
                <options> )

Update Specification Documents¶

Update documents specify the data modifications to perform during an update() operation to modify existing records in a collection. You can use update operators to specify the exact actions to perform on the document fields.

Consider the update document example:

{
  $set: { 'name.middle': 'Warner' },
  $push: { awards: { award: 'IBM Fellow',
                     year: '1963',
                     by: 'IBM' }
         }
}

When passed as an argument to the update() method, the update actions document:

• Modifies the field name whose value is another document. Specifically, the $set operator updates the middle field in the name subdocument. The document uses dot notation to access a field in a subdocument.
• Adds an element to the field awards whose value is an array. Specifically, the $push operator adds another document as element to the field awards.

db.bios.update(
   { _id: 1 },
   {
     $set: { 'name.middle': 'Warner' },
     $push: { awards: {
                        award: 'IBM Fellow',
                        year: '1963',
                        by: 'IBM'
                      }
            }
   }
)

For additional examples of updates that involve array elements, including where the elements are documents, see the $ positional operator.

Index Specification Documents¶

Index specification documents describe the fields to index on during the index creation. See indexes for an overview of indexes. [1]

Index documents contain field and value pairs, in the following form:

{ field: value }

• field is the field in the documents to index.
• value is either 1 for ascending or -1 for descending.

The following document specifies the multi-key index on the _id field and the last field contained in the subdocument name field. The document uses dot notation to access a field in a subdocument:

{ _id: 1, 'name.last': 1 }

When passed as an argument to the ensureIndex() method, the index documents specifies the index to create:

db.bios.ensureIndex( { _id: 1, 'name.last': 1 } )

Sort Order Specification Documents¶

Sort order documents specify the order of documents that a query() returns. Pass sort order specification documents as an argument to the sort() method. See the sort() page for more information on sorting.

The sort order documents contain field and value pairs, in the following form:

{ field: value }

• field is the field by which to sort documents.
• value is either 1 for ascending or -1 for descending.

The following document specifies the sort order using the fields from a sub-document name first sort by the last field ascending, then by the first field also ascending:

{ 'name.last': 1, 'name.first': 1 }

When passed as an argument to the sort() method, the sort order document sorts the results of the find() method:

db.bios.find().sort( { 'name.last': 1, 'name.first': 1 } )

ObjectId¶

ObjectIds are: small, likely unique, fast to generate, and ordered. These values consists of 12-bytes, where the first 4-bytes is a timestamp that reflects the ObjectId’s creation. Refer to the ObjectId documentation for more information.

String¶

BSON strings are UTF-8. In general, drivers for each programming language convert from the language’s string format to UTF-8 when serializing and deserializing BSON. This makes it possible to store most international characters in BSON strings with ease. [2] In addition, MongoDB $regex queries support UTF-8 in the regex string.

Timestamps¶

BSON has a special timestamp type for internal MongoDB use and is not associated with the regular Date type. Timestamp values are a 64 bit value where:

• the first 32 bits are a time_t value (seconds since the Unix epoch)
• the second 32 bits are an incrementing ordinal for operations within a given second.

Within a single mongod instance, timestamp values are always unique.

In replication, the oplog has a ts field. The values in this field reflect the operation time, which uses a BSON timestamp value.

If you create a BSON Timestamp using the empty constructor (e.g. new Timestamp()), MongoDB will only generate a timestamp if you use the constructor in the first field of the document. [3] Otherwise, MongoDB will generate an empty timestamp value (i.e. Timestamp(0, 0).)

在 2.1 版更改: mongo shell displays the Timestamp value with the wrapper:

Timestamp(<time_t>, <ordinal>)

Prior to version 2.1, the mongo shell display the Timestamp value as a document:

{ t : <time_t>, i : <ordinal> }

db.bios.insert( { _id: 9, last_updated: new Timestamp() } )

Date¶

BSON Date is a 64-bit integer that represents the number of milliseconds since the Unix epoch (Jan 1, 1970). The official BSON specification refers to the BSON Date type as the UTC datetime.

在 2.0 版更改: BSON Date type is signed. [4] Negative values represent dates before 1970.

Consider the following examples of BSON Date:

• Construct a Date using the new Date() constructor in the mongo shell:

  var mydate1 = new Date()
  

• Construct a Date using the ISODate() constructor in the mongo shell:

  var mydate2 = ISODate()
  

• Return the Date value as string:

  mydate1.toString()
  

• Return the month portion of the Date value; months are zero-indexed, so that January is month 0:

  mydate1.getMonth()