mgo

func (*BuildInfo) VersionAtLeast ¶

func (bi *BuildInfo) VersionAtLeast(version ...int) bool

VersionAtLeast returns whether the BuildInfo version is greater than or equal to the provided version number. If more than one number is provided, numbers will be considered as major, minor, and so on.

func (*Bulk) Insert ¶

func (b *Bulk) Insert(docs ...interface{})

Insert queues up the provided documents for insertion.

func (*Bulk) Remove ¶

func (b *Bulk) Remove(selectors ...interface{})

Remove queues up the provided selectors for removing matching documents. Each selector will remove only a single matching document.

func (*Bulk) RemoveAll ¶

func (b *Bulk) RemoveAll(selectors ...interface{})

RemoveAll queues up the provided selectors for removing all matching documents. Each selector will remove all matching documents.

func (*Bulk) Run ¶

func (b *Bulk) Run() (*BulkResult, error)

Run runs all the operations queued up.

If an error is reported on an unordered bulk operation, the error value may be an aggregation of all issues observed. As an exception to that, Insert operations running on MongoDB versions prior to 2.6 will report the last error only due to a limitation in the wire protocol.

func (*Bulk) Unordered ¶

func (b *Bulk) Unordered()

Unordered puts the bulk operation in unordered mode.

In unordered mode the indvidual operations may be sent out of order, which means latter operations may proceed even if prior ones have failed.

func (*Bulk) Update ¶

func (b *Bulk) Update(pairs ...interface{})

Update queues up the provided pairs of updating instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair matches exactly one document for updating at most.

func (*Bulk) UpdateAll ¶

func (b *Bulk) UpdateAll(pairs ...interface{})

UpdateAll queues up the provided pairs of updating instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair updates all documents matching the selector.

func (*Bulk) Upsert ¶

func (b *Bulk) Upsert(pairs ...interface{})

Upsert queues up the provided pairs of upserting instructions. The first element of each pair selects which documents must be updated, and the second element defines how to update it. Each pair matches exactly one document for updating at most.

func (*BulkError) Cases ¶

func (e *BulkError) Cases() []BulkErrorCase

Cases returns all individual errors found while attempting the requested changes.

See the documentation of BulkErrorCase for limitations in older MongoDB releases.

func (*BulkError) Error ¶

func (e *BulkError) Error() string

func (*ChangeStream) Close ¶

func (changeStream *ChangeStream) Close() error

Close kills the server cursor used by the iterator, if any, and returns nil if no errors happened during iteration, or the actual error otherwise.

func (*ChangeStream) Err ¶

func (changeStream *ChangeStream) Err() error

Err returns nil if no errors happened during iteration, or the actual error otherwise.

func (*ChangeStream) Next ¶

func (changeStream *ChangeStream) Next(result interface{}) bool

Next retrieves the next document from the change stream, blocking if necessary. Next returns true if a document was successfully unmarshalled into result, and false if an error occured. When Next returns false, the Err method should be called to check what error occurred during iteration. If there were no events available (ErrNotFound), the Err method returns nil so the user can retry the invocaton.

For example:

pipeline := []bson.M{}

changeStream := collection.Watch(pipeline, ChangeStreamOptions{})
for changeStream.Next(&changeDoc) {
    fmt.Printf("Change: %v\n", changeDoc)
}

if err := changeStream.Close(); err != nil {
    return err
}

If the pipeline used removes the _id field from the result, Next will error because the _id field is needed to resume iteration when an error occurs.

func (*ChangeStream) ResumeToken ¶

func (changeStream *ChangeStream) ResumeToken() *bson.Raw

ResumeToken returns a copy of the current resume token held by the change stream. This token should be treated as an opaque token that can be provided to instantiate a new change stream.

func (*ChangeStream) Timeout ¶

func (changeStream *ChangeStream) Timeout() bool

Timeout returns true if the last call of Next returned false because of an iterator timeout.

func (*Collection) Bulk ¶

func (c *Collection) Bulk() *Bulk

Bulk returns a value to prepare the execution of a bulk operation.

func (*Collection) Count ¶

func (c *Collection) Count() (n int, err error)

Count returns the total number of documents in the collection.

func (*Collection) Create ¶

func (c *Collection) Create(info *CollectionInfo) error

Create explicitly creates the c collection with details of info. MongoDB creates collections automatically on use, so this method is only necessary when creating collection with non-default characteristics, such as capped collections.

Relevant documentation:

http://www.mongodb.org/display/DOCS/createCollection+Command
http://www.mongodb.org/display/DOCS/Capped+Collections

func (*Collection) DropAllIndexes ¶

func (c *Collection) DropAllIndexes() error

DropAllIndexes drops all the indexes from the c collection

func (*Collection) DropCollection ¶

func (c *Collection) DropCollection() error

DropCollection removes the entire collection including all of its documents.

func (*Collection) DropIndex ¶

func (c *Collection) DropIndex(key ...string) error

DropIndex drops the index with the provided key from the c collection.

See EnsureIndex for details on the accepted key variants.

For example:

err1 := collection.DropIndex("firstField", "-secondField")
err2 := collection.DropIndex("customIndexName")

func (*Collection) DropIndexName ¶

func (c *Collection) DropIndexName(name string) error

DropIndexName removes the index with the provided index name.

For example:

err := collection.DropIndex("customIndexName")

func (*Collection) EnsureIndex ¶

func (c *Collection) EnsureIndex(index Index) error

EnsureIndex ensures an index with the given key exists, creating it with the provided parameters if necessary. EnsureIndex does not modify a previously existent index with a matching key. The old index must be dropped first instead.

Once EnsureIndex returns successfully, following requests for the same index will not contact the server unless Collection.DropIndex is used to drop the same index, or Session.ResetIndexCache is called.

For example:

index := Index{
    Key: []string{"lastname", "firstname"},
    Unique: true,
    DropDups: true,
    Background: true, // See notes.
    Sparse: true,
}
err := collection.EnsureIndex(index)

The Key value determines which fields compose the index. The index ordering will be ascending by default. To obtain an index with a descending order, the field name should be prefixed by a dash (e.g. []string{"-time"}). It can also be optionally prefixed by an index kind, as in "$text:summary" or "$2d:-point". The key string format is:

[$<kind>:][-]<field name>

If the Unique field is true, the index must necessarily contain only a single document per Key. With DropDups set to true, documents with the same key as a previously indexed one will be dropped rather than an error returned.

If Background is true, other connections will be allowed to proceed using the collection without the index while it's being built. Note that the session executing EnsureIndex will be blocked for as long as it takes for the index to be built.

If Sparse is true, only documents containing the provided Key fields will be included in the index. When using a sparse index for sorting, only indexed documents will be returned.

If ExpireAfter is non-zero, the server will periodically scan the collection and remove documents containing an indexed time.Time field with a value older than ExpireAfter. See the documentation for details:

http://docs.mongodb.org/manual/tutorial/expire-data

Other kinds of indexes are also supported through that API. Here is an example:

index := Index{
    Key: []string{"$2d:loc"},
    Bits: 26,
}
err := collection.EnsureIndex(index)

The example above requests the creation of a "2d" index for the "loc" field.

The 2D index bounds may be changed using the Min and Max attributes of the Index value. The default bound setting of (-180, 180) is suitable for latitude/longitude pairs.

The Bits parameter sets the precision of the 2D geohash values. If not provided, 26 bits are used, which is roughly equivalent to 1 foot of precision for the default (-180, 180) index bounds.

Relevant documentation:

http://www.mongodb.org/display/DOCS/Indexes
http://www.mongodb.org/display/DOCS/Indexing+Advice+and+FAQ
http://www.mongodb.org/display/DOCS/Indexing+as+a+Background+Operation
http://www.mongodb.org/display/DOCS/Geospatial+Indexing
http://www.mongodb.org/display/DOCS/Multikeys

func (*Collection) EnsureIndexKey ¶

func (c *Collection) EnsureIndexKey(key ...string) error

EnsureIndexKey ensures an index with the given key exists, creating it if necessary.

This example:

err := collection.EnsureIndexKey("a", "b")

Is equivalent to:

err := collection.EnsureIndex(mgo.Index{Key: []string{"a", "b"}})

See the EnsureIndex method for more details.

func (*Collection) Find ¶

func (c *Collection) Find(query interface{}) *Query

Find prepares a query using the provided document. The document may be a map or a struct value capable of being marshalled with bson. The map may be a generic one using interface{} for its key and/or values, such as bson.M, or it may be a properly typed map. Providing nil as the document is equivalent to providing an empty document such as bson.M{}.

Further details of the query may be tweaked using the resulting Query value, and then executed to retrieve results using methods such as One, For, Iter, or Tail.

In case the resulting document includes a field named $err or errmsg, which are standard ways for MongoDB to return query errors, the returned err will be set to a *QueryError value including the Err message and the Code. In those cases, the result argument is still unmarshalled into with the received document so that any other custom values may be obtained if desired.

Relevant documentation:

http://www.mongodb.org/display/DOCS/Querying
http://www.mongodb.org/display/DOCS/Advanced+Queries

func (*Collection) FindId ¶

func (c *Collection) FindId(id interface{}) *Query

FindId is a convenience helper equivalent to:

query := collection.Find(bson.M{"_id": id})

See the Find method for more details.

func (*Collection) Indexes ¶

func (c *Collection) Indexes() (indexes []Index, err error)

Indexes returns a list of all indexes for the collection.

See the EnsureIndex method for more details on indexes.

func (*Collection) Insert ¶

func (c *Collection) Insert(docs ...interface{}) error

Insert inserts one or more documents in the respective collection. In case the session is in safe mode (see the SetSafe method) and an error happens while inserting the provided documents, the returned error will be of type *LastError.

func (*Collection) NewIter ¶

func (c *Collection) NewIter(session *Session, firstBatch []