diff --git a/mongo/options/aggregateoptions.go b/mongo/options/aggregateoptions.go index 5fdbd65952..c49951dc44 100644 --- a/mongo/options/aggregateoptions.go +++ b/mongo/options/aggregateoptions.go @@ -14,49 +14,18 @@ import ( // AggregateOptions represents arguments that can be used to configure an // Aggregate operation. +// +// See corresponding setter methods for documentation. type AggregateOptions struct { - // If true, the operation can write to temporary files in the _tmp subdirectory of the database directory path on - // the server. The default value is false. - AllowDiskUse *bool - - // The maximum number of documents to be included in each batch returned by the server. - BatchSize *int32 - - // If true, writes executed as part of the operation will opt out of document-level validation on the server. This - // option is valid for MongoDB versions >= 3.2 and is ignored for previous server versions. The default value is - // false. See https://www.mongodb.com/docs/manual/core/schema-validation/ for more information about document - // validation. + AllowDiskUse *bool + BatchSize *int32 BypassDocumentValidation *bool - - // Specifies a collation to use for string comparisons during the operation. This option is only valid for MongoDB - // versions >= 3.4. For previous server versions, the driver will return an error if this option is used. The - // default value is nil, which means the default collation of the collection will be used. - Collation *Collation - - // The maximum amount of time that the server should wait for new documents to satisfy a tailable cursor query. - // This option is only valid for MongoDB versions >= 3.2 and is ignored for previous server versions. - MaxAwaitTime *time.Duration - - // A string or document that will be included in server logs, profiling logs, - // and currentOp queries to help trace the operation. The default is nil, - // which means that no comment will be included in the logs. - Comment interface{} - - // The index to use for the aggregation. This should either be the index name as a string or the index specification - // as a document. The hint does not apply to $lookup and $graphLookup aggregation stages. The driver will return an - // error if the hint parameter is a multi-key map. The default value is nil, which means that no hint will be sent. - Hint interface{} - - // Specifies parameters for the aggregate expression. This option is only valid for MongoDB versions >= 5.0. Older - // servers will report an error for using this option. This must be a document mapping parameter names to values. - // Values must be constant or closed expressions that do not reference document fields. Parameters can then be - // accessed as variables in an aggregate expression context (e.g. "$$var"). - Let interface{} - - // Custom options to be added to aggregate expression. Key-value pairs of the BSON map should correlate with desired - // option names and values. Values must be Marshalable. Custom options may conflict with non-custom options, and custom - // options bypass client-side validation. Prefer using non-custom options where possible. - Custom bson.M + Collation *Collation + MaxAwaitTime *time.Duration + Comment interface{} + Hint interface{} + Let interface{} + Custom bson.M } // AggregateOptionsBuilder contains options to configure aggregate operations. @@ -76,7 +45,8 @@ func (ao *AggregateOptionsBuilder) List() []func(*AggregateOptions) error { return ao.Opts } -// SetAllowDiskUse sets the value for the AllowDiskUse field. +// SetAllowDiskUse sets the value for the AllowDiskUse field. If true, the operation can write to temporary +// files in the _tmp subdirectory of the database directory path on the server. The default value is false. func (ao *AggregateOptionsBuilder) SetAllowDiskUse(b bool) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.AllowDiskUse = &b @@ -87,7 +57,8 @@ func (ao *AggregateOptionsBuilder) SetAllowDiskUse(b bool) *AggregateOptionsBuil return ao } -// SetBatchSize sets the value for the BatchSize field. +// SetBatchSize sets the value for the BatchSize field. Specifies the maximum number of documents +// to be included in each batch returned by the server. func (ao *AggregateOptionsBuilder) SetBatchSize(i int32) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.BatchSize = &i @@ -98,7 +69,11 @@ func (ao *AggregateOptionsBuilder) SetBatchSize(i int32) *AggregateOptionsBuilde return ao } -// SetBypassDocumentValidation sets the value for the BypassDocumentValidation field. +// SetBypassDocumentValidation sets the value for the BypassDocumentValidation field. If true, writes +// executed as part of the operation will opt out of document-level validation on the server. This +// option is valid for MongoDB versions >= 3.2 and is ignored for previous server versions. The default value +// is false. See https://www.mongodb.com/docs/manual/core/schema-validation/ for more information about +// document validation. func (ao *AggregateOptionsBuilder) SetBypassDocumentValidation(b bool) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.BypassDocumentValidation = &b @@ -109,7 +84,10 @@ func (ao *AggregateOptionsBuilder) SetBypassDocumentValidation(b bool) *Aggregat return ao } -// SetCollation sets the value for the Collation field. +// SetCollation sets the value for the Collation field. Specifies a collation to use for string +// comparisons during the operation. This option is only valid for MongoDB versions >= 3.4. For previous +// server versions, the driver will return an error if this option is used. The default value is nil, +// which means the default collation of the collection will be used. func (ao *AggregateOptionsBuilder) SetCollation(c *Collation) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.Collation = c @@ -120,7 +98,9 @@ func (ao *AggregateOptionsBuilder) SetCollation(c *Collation) *AggregateOptionsB return ao } -// SetMaxAwaitTime sets the value for the MaxAwaitTime field. +// SetMaxAwaitTime sets the value for the MaxAwaitTime field. Specifies maximum amount of time +// that the server should wait for new documents to satisfy a tailable cursor query. This option is +// only valid for MongoDB versions >= 3.2 and is ignored for previous server versions. func (ao *AggregateOptionsBuilder) SetMaxAwaitTime(d time.Duration) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.MaxAwaitTime = &d @@ -131,7 +111,9 @@ func (ao *AggregateOptionsBuilder) SetMaxAwaitTime(d time.Duration) *AggregateOp return ao } -// SetComment sets the value for the Comment field. +// SetComment sets the value for the Comment field. Specifies a string or document that will be included in +// server logs, profiling logs, and currentOp queries to help trace the operation. The default is nil, +// which means that no comment will be included in the logs. func (ao *AggregateOptionsBuilder) SetComment(comment interface{}) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.Comment = comment @@ -142,7 +124,10 @@ func (ao *AggregateOptionsBuilder) SetComment(comment interface{}) *AggregateOpt return ao } -// SetHint sets the value for the Hint field. +// SetHint sets the value for the Hint field. Specifies the index to use for the aggregation. This should +// either be the index name as a string or the index specification as a document. The hint does not apply to +// $lookup and $graphLookup aggregation stages. The driver will return an error if the hint parameter +// is a multi-key map. The default value is nil, which means that no hint will be sent. func (ao *AggregateOptionsBuilder) SetHint(h interface{}) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.Hint = h @@ -153,7 +138,11 @@ func (ao *AggregateOptionsBuilder) SetHint(h interface{}) *AggregateOptionsBuild return ao } -// SetLet sets the value for the Let field. +// SetLet sets the value for the Let field. Specifies parameters for the aggregate expression. This +// option is only valid for MongoDB versions >= 5.0. Older servers will report an error for using this +// option. This must be a document mapping parameter names to values. Values must be constant or closed +// expressions that do not reference document fields. Parameters can then be accessed as variables in +// an aggregate expression context (e.g. "$$var"). func (ao *AggregateOptionsBuilder) SetLet(let interface{}) *AggregateOptionsBuilder { ao.Opts = append(ao.Opts, func(opts *AggregateOptions) error { opts.Let = let diff --git a/mongo/options/autoencryptionoptions.go b/mongo/options/autoencryptionoptions.go index 5bb299a9eb..180b90e676 100644 --- a/mongo/options/autoencryptionoptions.go +++ b/mongo/options/autoencryptionoptions.go @@ -25,6 +25,8 @@ import ( // // Enabling In-Use Encryption reduces the maximum document and message size (using a maxBsonObjectSize of 2MiB and // maxMessageSizeBytes of 6MB) and may have a negative performance impact. +// +// See corresponding setter methods for documentation. type AutoEncryptionOptions struct { KeyVaultClientOptions Lister[ClientOptions] KeyVaultNamespace string diff --git a/mongo/options/bulkwriteoptions.go b/mongo/options/bulkwriteoptions.go index 7b566f458d..11dd6c1b7c 100644 --- a/mongo/options/bulkwriteoptions.go +++ b/mongo/options/bulkwriteoptions.go @@ -11,25 +11,13 @@ var DefaultOrdered = true // BulkWriteOptions represents arguments that can be used to configure a // BulkWrite operation. +// +// See corresponding setter methods for documentation. type BulkWriteOptions struct { - // If true, writes executed as part of the operation will opt out of document-level validation on the server. This - // option is valid for MongoDB versions >= 3.2 and is ignored for previous server versions. The default value is - // false. See https://www.mongodb.com/docs/manual/core/schema-validation/ for more information about document - // validation. BypassDocumentValidation *bool - - // A string or document that will be included in server logs, profiling logs, and currentOp queries to help trace - // the operation. The default value is nil, which means that no comment will be included in the logs. - Comment interface{} - - // If true, no writes will be executed after one fails. The default value is true. - Ordered *bool - - // Specifies parameters for all update and delete commands in the BulkWrite. This option is only valid for MongoDB - // versions >= 5.0. Older servers will report an error for using this option. This must be a document mapping - // parameter names to values. Values must be constant or closed expressions that do not reference document fields. - // Parameters can then be accessed as variables in an aggregate expression context (e.g. "$$var"). - Let interface{} + Comment interface{} + Ordered *bool + Let interface{} } // BulkWriteOptionsBuilder contains options to configure bulk write operations. @@ -52,7 +40,9 @@ func (b *BulkWriteOptionsBuilder) List() []func(*BulkWriteOptions) error { return b.Opts } -// SetComment sets the value for the Comment field. +// SetComment sets the value for the Comment field. Specifies a string or document that will be included in +// server logs, profiling logs, and currentOp queries to help tracethe operation. The default value is nil, +// which means that no comment will be included in the logs. func (b *BulkWriteOptionsBuilder) SetComment(comment interface{}) *BulkWriteOptionsBuilder { b.Opts = append(b.Opts, func(opts *BulkWriteOptions) error { opts.Comment = comment @@ -63,7 +53,8 @@ func (b *BulkWriteOptionsBuilder) SetComment(comment interface{}) *BulkWriteOpti return b } -// SetOrdered sets the value for the Ordered field. +// SetOrdered sets the value for the Ordered field. If true, no writes will be executed after one fails. +// The default value is true. func (b *BulkWriteOptionsBuilder) SetOrdered(ordered bool) *BulkWriteOptionsBuilder { b.Opts = append(b.Opts, func(opts *BulkWriteOptions) error { opts.Ordered = &ordered @@ -74,7 +65,11 @@ func (b *BulkWriteOptionsBuilder) SetOrdered(ordered bool) *BulkWriteOptionsBuil return b } -// SetBypassDocumentValidation sets the value for the BypassDocumentValidation field. +// SetBypassDocumentValidation sets the value for the BypassDocumentValidation field. If true, writes +// executed as part of the operation will opt out of document-level validation on the server. This option +// is valid for MongoDB versions >= 3.2 and is ignored for previous server versions. The default value is +// false. See https://www.mongodb.com/docs/manual/core/schema-validation/ for more information about document +// validation. func (b *BulkWriteOptionsBuilder) SetBypassDocumentValidation(bypass bool) *BulkWriteOptionsBuilder { b.Opts = append(b.Opts, func(opts *BulkWriteOptions) error { opts.BypassDocumentValidation = &bypass diff --git a/mongo/options/changestreamoptions.go b/mongo/options/changestreamoptions.go index 2d023774bd..66f1899faa 100644 --- a/mongo/options/changestreamoptions.go +++ b/mongo/options/changestreamoptions.go @@ -13,62 +13,21 @@ import ( ) // ChangeStreamOptions represents arguments that can be used to configure a Watch operation. +// +// See corresponding setter methods for documentation. type ChangeStreamOptions struct { - // The maximum number of documents to be included in each batch returned by the server. - BatchSize *int32 - - // Specifies a collation to use for string comparisons during the operation. This option is only valid for MongoDB - // versions >= 3.4. For previous server versions, the driver will return an error if this option is used. The - // default value is nil, which means the default collation of the collection will be used. - Collation *Collation - - // A string or document that will be included in server logs, profiling logs, - // and currentOp queries to help trace the operation. The default is nil, - // which means that no comment will be included in the logs. - Comment interface{} - - // Specifies how the updated document should be returned in change notifications for update operations. The default - // is options.Default, which means that only partial update deltas will be included in the change notification. - FullDocument *FullDocument - - // Specifies how the pre-update document should be returned in change notifications for update operations. The default - // is options.Off, which means that the pre-update document will not be included in the change notification. + BatchSize *int32 + Collation *Collation + Comment interface{} + FullDocument *FullDocument FullDocumentBeforeChange *FullDocument - - // The maximum amount of time that the server should wait for new documents to satisfy a tailable cursor query. - MaxAwaitTime *time.Duration - - // A document specifying the logical starting point for the change stream. Only changes corresponding to an oplog - // entry immediately after the resume token will be returned. If this is specified, StartAtOperationTime and - // StartAfter must not be set. - ResumeAfter interface{} - - // ShowExpandedEvents specifies whether the server will return an expanded list of change stream events. Additional - // events include: createIndexes, dropIndexes, modify, create, shardCollection, reshardCollection and - // refineCollectionShardKey. This option is only valid for MongoDB versions >= 6.0. - ShowExpandedEvents *bool - - // If specified, the change stream will only return changes that occurred at or after the given timestamp. This - // option is only valid for MongoDB versions >= 4.0. If this is specified, ResumeAfter and StartAfter must not be - // set. - StartAtOperationTime *bson.Timestamp - - // A document specifying the logical starting point for the change stream. This is similar to the ResumeAfter - // option, but allows a resume token from an "invalidate" notification to be used. This allows a change stream on a - // collection to be resumed after the collection has been dropped and recreated or renamed. Only changes - // corresponding to an oplog entry immediately after the specified token will be returned. If this is specified, - // ResumeAfter and StartAtOperationTime must not be set. This option is only valid for MongoDB versions >= 4.1.1. - StartAfter interface{} - - // Custom options to be added to the initial aggregate for the change stream. Key-value pairs of the BSON map should - // correlate with desired option names and values. Values must be Marshalable. Custom options may conflict with - // non-custom options, and custom options bypass client-side validation. Prefer using non-custom options where possible. - Custom bson.M - - // Custom options to be added to the $changeStream stage in the initial aggregate. Key-value pairs of the BSON map should - // correlate with desired option names and values. Values must be Marshalable. Custom pipeline options bypass client-side - // validation. Prefer using non-custom options where possible. - CustomPipeline bson.M + MaxAwaitTime *time.Duration + ResumeAfter interface{} + ShowExpandedEvents *bool + StartAtOperationTime *bson.Timestamp + StartAfter interface{} + Custom bson.M + CustomPipeline bson.M } // ChangeStreamOptionsBuilder contains options to configure change stream @@ -88,7 +47,8 @@ func (cso *ChangeStreamOptionsBuilder) List() []func(*ChangeStreamOptions) error return cso.Opts } -// SetBatchSize sets the value for the BatchSize field. +// SetBatchSize sets the value for the BatchSize field. Specifies the maximum number of documents to +// be included in each batch returned by the server. func (cso *ChangeStreamOptionsBuilder) SetBatchSize(i int32) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.BatchSize = &i @@ -97,7 +57,10 @@ func (cso *ChangeStreamOptionsBuilder) SetBatchSize(i int32) *ChangeStreamOption return cso } -// SetCollation sets the value for the Collation field. +// SetCollation sets the value for the Collation field. Specifies a collation to use for string comparisons +// during the operation. This option is only valid for MongoDB versions >= 3.4. For previous server versions, +// the driver will return an error if this option is used. The default value is nil, which means the default +// collation of the collection will be used. func (cso *ChangeStreamOptionsBuilder) SetCollation(c Collation) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.Collation = &c @@ -106,7 +69,9 @@ func (cso *ChangeStreamOptionsBuilder) SetCollation(c Collation) *ChangeStreamOp return cso } -// SetComment sets the value for the Comment field. +// SetComment sets the value for the Comment field. Specifies a string or document that will be included in +// server logs, profiling logs, and currentOp queries to help trace the operation. The default is nil, +// which means that no comment will be included in the logs. func (cso *ChangeStreamOptionsBuilder) SetComment(comment interface{}) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.Comment = comment @@ -115,7 +80,9 @@ func (cso *ChangeStreamOptionsBuilder) SetComment(comment interface{}) *ChangeSt return cso } -// SetFullDocument sets the value for the FullDocument field. +// SetFullDocument sets the value for the FullDocument field. Specifies how the updated document should be +// returned in change notifications for update operations. The default is options.Default, which means that +// only partial update deltas will be included in the change notification. func (cso *ChangeStreamOptionsBuilder) SetFullDocument(fd FullDocument) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.FullDocument = &fd @@ -124,7 +91,9 @@ func (cso *ChangeStreamOptionsBuilder) SetFullDocument(fd FullDocument) *ChangeS return cso } -// SetFullDocumentBeforeChange sets the value for the FullDocumentBeforeChange field. +// SetFullDocumentBeforeChange sets the value for the FullDocumentBeforeChange field. Specifies how the +// pre-update document should be returned in change notifications for update operations. The default +// is options.Off, which means that the pre-update document will not be included in the change notification. func (cso *ChangeStreamOptionsBuilder) SetFullDocumentBeforeChange(fdbc FullDocument) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.FullDocumentBeforeChange = &fdbc @@ -133,7 +102,8 @@ func (cso *ChangeStreamOptionsBuilder) SetFullDocumentBeforeChange(fdbc FullDocu return cso } -// SetMaxAwaitTime sets the value for the MaxAwaitTime field. +// SetMaxAwaitTime sets the value for the MaxAwaitTime field. The maximum amount of time that the server should +// wait for new documents to satisfy a tailable cursor query. func (cso *ChangeStreamOptionsBuilder) SetMaxAwaitTime(d time.Duration) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.MaxAwaitTime = &d @@ -142,7 +112,9 @@ func (cso *ChangeStreamOptionsBuilder) SetMaxAwaitTime(d time.Duration) *ChangeS return cso } -// SetResumeAfter sets the value for the ResumeAfter field. +// SetResumeAfter sets the value for the ResumeAfter field. Specifies a document specifying the logical starting +// point for the change stream. Only changes corresponding to an oplog entry immediately after the resume token +// will be returned. If this is specified, StartAtOperationTime and StartAfter must not be set. func (cso *ChangeStreamOptionsBuilder) SetResumeAfter(rt interface{}) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.ResumeAfter = rt @@ -151,7 +123,10 @@ func (cso *ChangeStreamOptionsBuilder) SetResumeAfter(rt interface{}) *ChangeStr return cso } -// SetShowExpandedEvents sets the value for the ShowExpandedEvents field. +// SetShowExpandedEvents sets the value for the ShowExpandedEvents field. ShowExpandedEvents specifies whether +// the server will return an expanded list of change stream events. Additional events include: createIndexes, +// dropIndexes, modify, create, shardCollection, reshardCollection and refineCollectionShardKey. This option +// is only valid for MongoDB versions >= 6.0. func (cso *ChangeStreamOptionsBuilder) SetShowExpandedEvents(see bool) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.ShowExpandedEvents = &see @@ -160,7 +135,9 @@ func (cso *ChangeStreamOptionsBuilder) SetShowExpandedEvents(see bool) *ChangeSt return cso } -// SetStartAtOperationTime sets the value for the StartAtOperationTime field. +// SetStartAtOperationTime sets the value for the StartAtOperationTime field. If specified, the change stream +// will only return changes that occurred at or after the given timestamp. This MongoDB versions >= 4.0. +// If this is specified, ResumeAfter and StartAfter must not be set. func (cso *ChangeStreamOptionsBuilder) SetStartAtOperationTime(t *bson.Timestamp) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.StartAtOperationTime = t @@ -169,7 +146,12 @@ func (cso *ChangeStreamOptionsBuilder) SetStartAtOperationTime(t *bson.Timestamp return cso } -// SetStartAfter sets the value for the StartAfter field. +// SetStartAfter sets the value for the StartAfter field. Sets a document specifying the logical starting +// point for the change stream. This is similar to the ResumeAfter option, but allows a resume token from +// an "invalidate" notification to be used. This allows a change stream on a collection to be resumed after +// the collection has been dropped and recreated or renamed. Only changes corresponding to an oplog entry +// immediately after the specified token will be returned. If this is specified, ResumeAfter and +// StartAtOperationTime must not be set. This option is only valid for MongoDB versions >= 4.1.1. func (cso *ChangeStreamOptionsBuilder) SetStartAfter(sa interface{}) *ChangeStreamOptionsBuilder { cso.Opts = append(cso.Opts, func(opts *ChangeStreamOptions) error { opts.StartAfter = sa diff --git a/mongo/options/clientencryptionoptions.go b/mongo/options/clientencryptionoptions.go index 43f27780e8..2d6d5f0e61 100644 --- a/mongo/options/clientencryptionoptions.go +++ b/mongo/options/clientencryptionoptions.go @@ -15,6 +15,8 @@ import ( ) // ClientEncryptionOptions represents all possible arguments used to configure a ClientEncryption instance. +// +// See corresponding setter methods for documentation. type ClientEncryptionOptions struct { KeyVaultNamespace string KmsProviders map[string]map[string]interface{} diff --git a/mongo/options/collectionoptions.go b/mongo/options/collectionoptions.go index 66228d791c..9cc6d1360e 100644 --- a/mongo/options/collectionoptions.go +++ b/mongo/options/collectionoptions.go @@ -13,28 +13,15 @@ import ( "go.mongodb.org/mongo-driver/v2/mongo/writeconcern" ) -// CollectionOptions represents arguments that can be used to configure a -// Collection. +// CollectionOptions represents arguments that can be used to configure a Collection. +// +// See corresponding setter methods for documentation. type CollectionOptions struct { - // ReadConcern is the read concern to use for operations executed on the Collection. The default value is nil, which means that - // the read concern of the Database used to configure the Collection will be used. - ReadConcern *readconcern.ReadConcern - - // WriteConcern is the write concern to use for operations executed on the Collection. The default value is nil, which means that - // the write concern of the Database used to configure the Collection will be used. - WriteConcern *writeconcern.WriteConcern - - // ReadPreference is the read preference to use for operations executed on the Collection. The default value is nil, which means that - // the read preference of the Database used to configure the Collection will be used. + ReadConcern *readconcern.ReadConcern + WriteConcern *writeconcern.WriteConcern ReadPreference *readpref.ReadPref - - // BSONOptions configures optional BSON marshaling and unmarshaling - // behavior. - BSONOptions *BSONOptions - - // Registry is the BSON registry to marshal and unmarshal documents for operations executed on the Collection. The default value - // is nil, which means that the registry of the Database used to configure the Collection will be used. - Registry *bson.Registry + BSONOptions *BSONOptions + Registry *bson.Registry } // CollectionOptionsBuilder contains options to configure a Collection instance. @@ -54,7 +41,9 @@ func (c *CollectionOptionsBuilder) List() []func(*CollectionOptions) error { return c.Opts } -// SetReadConcern sets the value for the ReadConcern field. +// SetReadConcern sets the value for the ReadConcern field. ReadConcern is the read concern to use for +// operations executed on the Collection. The default value is nil, which means that the read concern +// of the Database used to configure the Collection will be used. func (c *CollectionOptionsBuilder) SetReadConcern(rc *readconcern.ReadConcern) *CollectionOptionsBuilder { c.Opts = append(c.Opts, func(opts *CollectionOptions) error { opts.ReadConcern = rc @@ -65,7 +54,9 @@ func (c *CollectionOptionsBuilder) SetReadConcern(rc *readconcern.ReadConcern) * return c } -// SetWriteConcern sets the value for the WriteConcern field. +// SetWriteConcern sets the value for the WriteConcern field. WriteConcern is the write concern to +// use for operations executed on the Collection. The default value is nil, which means that the write +// concern of the Database used to configure the Collection will be used. func (c *CollectionOptionsBuilder) SetWriteConcern(wc *writeconcern.WriteConcern) *CollectionOptionsBuilder { c.Opts = append(c.Opts, func(opts *CollectionOptions) error { opts.WriteConcern = wc @@ -76,7 +67,9 @@ func (c *CollectionOptionsBuilder) SetWriteConcern(wc *writeconcern.WriteConcern return c } -// SetReadPreference sets the value for the ReadPreference field. +// SetReadPreference sets the value for the ReadPreference field. ReadPreference is the read preference +// to use for operations executed on the Collection. The default value is nil, which means that the +// read preference of the Database used to configure the Collection will be used. func (c *CollectionOptionsBuilder) SetReadPreference(rp *readpref.ReadPref) *CollectionOptionsBuilder { c.Opts = append(c.Opts, func(opts *CollectionOptions) error { opts.ReadPreference = rp @@ -87,7 +80,8 @@ func (c *CollectionOptionsBuilder) SetReadPreference(rp *readpref.ReadPref) *Col return c } -// SetBSONOptions configures optional BSON marshaling and unmarshaling behavior. +// SetBSONOptions configures optional BSON marshaling and unmarshaling behavior. BSONOptions configures +// optional BSON marshaling and unmarshaling behavior. func (c *CollectionOptionsBuilder) SetBSONOptions(bopts *BSONOptions) *CollectionOptionsBuilder { c.Opts = append(c.Opts, func(opts *CollectionOptions) error { opts.BSONOptions = bopts @@ -98,7 +92,9 @@ func (c *CollectionOptionsBuilder) SetBSONOptions(bopts *BSONOptions) *Collectio return c } -// SetRegistry sets the value for the Registry field. +// SetRegistry sets the value for the Registry field. Registry is the BSON registry to marshal and +// unmarshal documents for operations executed on the Collection. The default value is nil, which +// means that the registry of the Database used to configure the Collection will be used. func (c *CollectionOptionsBuilder) SetRegistry(r *bson.Registry) *CollectionOptionsBuilder { c.Opts = append(c.Opts, func(opts *CollectionOptions) error { opts.Registry = r diff --git a/mongo/options/countoptions.go b/mongo/options/countoptions.go index d2f0f05769..8f92b62f73 100644 --- a/mongo/options/countoptions.go +++ b/mongo/options/countoptions.go @@ -8,27 +8,14 @@ package options // CountOptions represents arguments that can be used to configure a // CountDocuments operation. +// +// See corresponding setter methods for documentation. type CountOptions struct { - // Specifies a collation to use for string comparisons during the operation. This option is only valid for MongoDB - // versions >= 3.4. For previous server versions, the driver will return an error if this option is used. The - // default value is nil, which means the default collation of the collection will be used. Collation *Collation - - // A string or document that will be included in server logs, profiling logs, and currentOp queries to help trace - // the operation. The default is nil, which means that no comment will be included in the logs. - Comment interface{} - - // The index to use for the aggregation. This should either be the index name as a string or the index specification - // as a document. The driver will return an error if the hint parameter is a multi-key map. The default value is nil, - // which means that no hint will be sent. - Hint interface{} - - // The maximum number of documents to count. The default value is 0, which means that there is no limit and all - // documents matching the filter will be counted. - Limit *int64 - - // The number of documents to skip before counting. The default value is 0. - Skip *int64 + Comment interface{} + Hint interface{} + Limit *int64 + Skip *int64 } // CountOptionsBuilder contains options to configure count operations. Each @@ -48,7 +35,10 @@ func (co *CountOptionsBuilder) List() []func(*CountOptions) error { return co.Opts } -// SetCollation sets the value for the Collation field. +// SetCollation sets the value for the Collation field. Specifies a collation to use for string comparisons +// during the operation. This option is only valid for MongoDB versions >= 3.4. For previous server versions, +// the driver will return an error if this option is used. The default value is nil, which means the default +// collation of the collection will be used. func (co *CountOptionsBuilder) SetCollation(c *Collation) *CountOptionsBuilder { co.Opts = append(co.Opts, func(opts *CountOptions) error { opts.Collation = c @@ -59,7 +49,9 @@ func (co *CountOptionsBuilder) SetCollation(c *Collation) *CountOptionsBuilder { return co } -// SetComment sets the value for the Comment field. +// SetComment sets the value for the Comment field. Specifies a string or document that will be included +// in server logs, profiling logs, and currentOp queries to help trace the operation. The default is nil, +// which means that no comment will be included in the logs. func (co *CountOptionsBuilder) SetComment(comment interface{}) *CountOptionsBuilder { co.Opts = append(co.Opts, func(opts *CountOptions) error { opts.Comment = comment @@ -70,7 +62,10 @@ func (co *CountOptionsBuilder) SetComment(comment interface{}) *CountOptionsBuil return co } -// SetHint sets the value for the Hint field. +// SetHint sets the value for the Hint field. Specifies the index to use for the aggregation. This should +// either be the index name as a string or the index specification as a document. The driver will return +// an error if the hint parameter is a multi-key map. The default value is nil, which means that no hint +// will be sent. func (co *CountOptionsBuilder) SetHint(h interface{}) *CountOptionsBuilder { co.Opts = append(co.Opts, func(opts *CountOptions) error { opts.Hint = h @@ -81,7 +76,9 @@ func (co *CountOptionsBuilder) SetHint(h interface{}) *CountOptionsBuilder { return co } -// SetLimit sets the value for the Limit field. +// SetLimit sets the value for the Limit field. Specifies the maximum number of documents to count. The +// default value is 0, which means that there is no limit and all documents matching the filter will be +// counted. func (co *CountOptionsBuilder) SetLimit(i int64) *CountOptionsBuilder { co.Opts = append(co.Opts, func(opts *CountOptions) error { opts.Limit = &i @@ -92,7 +89,8 @@ func (co *CountOptionsBuilder) SetLimit(i int64) *CountOptionsBuilder { return co } -// SetSkip sets the value for the Skip field. +// SetSkip sets the value for the Skip field. Specifies the number of documents to skip before counting. +// The default value is 0. func (co *CountOptionsBuilder) SetSkip(i int64) *CountOptionsBuilder { co.Opts = append(co.Opts, func(opts *CountOptions) error { opts.Skip = &i diff --git a/mongo/options/createcollectionoptions.go b/mongo/options/createcollectionoptions.go index 7b2d2a418b..fd0aad57d0 100644 --- a/mongo/options/createcollectionoptions.go +++ b/mongo/options/createcollectionoptions.go @@ -13,10 +13,9 @@ import ( // DefaultIndexOptions represents the default arguments for a collection to // apply on new indexes. This type can be used when creating a new collection // through the CreateCollectionOptions.SetDefaultIndexOptions method. +// +// See corresponding setter methods for documentation. type DefaultIndexOptions struct { - // Specifies the storage engine to use for the index. The value must be a document in the form - // {: }. The default value is nil, which means that the default storage engine - // will be used. StorageEngine interface{} } @@ -37,7 +36,9 @@ func (d *DefaultIndexOptionsBuilder) List() []func(*DefaultIndexOptions) error { return d.Opts } -// SetStorageEngine sets the value for the StorageEngine field. +// SetStorageEngine sets the value for the StorageEngine field. Specifies the storage engine to use for +// the index. The value must be a document in the form {: }. The default +// value is nil, which means that the default storage engine will be used. func (d *DefaultIndexOptionsBuilder) SetStorageEngine(storageEngine interface{}) *DefaultIndexOptionsBuilder { d.Opts = append(d.Opts, func(opts *DefaultIndexOptions) error { opts.StorageEngine = storageEngine @@ -49,30 +50,13 @@ func (d *DefaultIndexOptionsBuilder) SetStorageEngine(storageEngine interface{}) } // TimeSeriesOptions specifies arguments on a time-series collection. +// +// See corresponding setter methods for documentation. type TimeSeriesOptions struct { - // TimeField is the top-level field to be used for time. Inserted documents must have this field, - // and the field must be of the BSON UTC datetime type (0x9). - TimeField string - - // MetaField is the name of the top-level field describing the series. This field is used to group - // related data and may be of any BSON type, except for array. This name may not be the same - // as the TimeField or _id. This field is optional. - MetaField *string - - // Granularity is the granularity of time-series data. Allowed granularity options are - // "seconds", "minutes" and "hours". This field is optional. - Granularity *string - - // BucketMaxSpan is the maximum range of time values for a bucket. The - // time.Duration is rounded down to the nearest second and applied as - // the command option: "bucketRoundingSeconds". This field is optional. - BucketMaxSpan *time.Duration - - // BucketRounding is used to determine the minimum time boundary when - // opening a new bucket by rounding the first timestamp down to the next - // multiple of this value. The time.Duration is rounded down to the - // nearest second and applied as the command option: - // "bucketRoundingSeconds". This field is optional. + TimeField string + MetaField *string + Granularity *string + BucketMaxSpan *time.Duration BucketRounding *time.Duration } @@ -93,7 +77,9 @@ func (tso *TimeSeriesOptionsBuilder) List() []func(*TimeSeriesOptions) error { return tso.Opts } -// SetTimeField sets the value for the TimeField. +// SetTimeField sets the value for the TimeField. TimeField is the top-level field to be used +// for time. Inserted documents must have this field, and the field must be of the BSON UTC +// datetime type (0x9). func (tso *TimeSeriesOptionsBuilder) SetTimeField(timeField string) *TimeSeriesOptionsBuilder { tso.Opts = append(tso.Opts, func(opts *TimeSeriesOptions) error { opts.TimeField = timeField @@ -104,7 +90,9 @@ func (tso *TimeSeriesOptionsBuilder) SetTimeField(timeField string) *TimeSeriesO return tso } -// SetMetaField sets the value for the MetaField. +// SetMetaField sets the value for the MetaField. MetaField is the name of the top-level field +// describing the series. This field is used to group related data and may be of any BSON type, +// except for array. This name may not be the same as the TimeField or _id. This field is optional. func (tso *TimeSeriesOptionsBuilder) SetMetaField(metaField string) *TimeSeriesOptionsBuilder { tso.Opts = append(tso.Opts, func(opts *TimeSeriesOptions) error { opts.MetaField = &metaField @@ -115,7 +103,8 @@ func (tso *TimeSeriesOptionsBuilder) SetMetaField(metaField string) *TimeSeriesO return tso } -// SetGranularity sets the value for Granularity. +// SetGranularity sets the value for Granularity. Granularity is the granularity of time-series data. +// Allowed granularity options are "seconds", "minutes" and "hours". This field is optional. func (tso *TimeSeriesOptionsBuilder) SetGranularity(granularity string) *TimeSeriesOptionsBuilder { tso.Opts = append(tso.Opts, func(opts *TimeSeriesOptions) error { opts.Granularity = &granularity @@ -126,7 +115,9 @@ func (tso *TimeSeriesOptionsBuilder) SetGranularity(granularity string) *TimeSer return tso } -// SetBucketMaxSpan sets the value for BucketMaxSpan. +// SetBucketMaxSpan sets the value for BucketMaxSpan. BucketMaxSpan is the maximum range of time +// values for a bucket. The time.Duration is rounded down to the nearest second and applied as +// the command option: "bucketRoundingSeconds". This field is optional. func (tso *TimeSeriesOptionsBuilder) SetBucketMaxSpan(dur time.Duration) *TimeSeriesOptionsBuilder { tso.Opts = append(tso.Opts, func(opts *TimeSeriesOptions) error { opts.BucketMaxSpan = &dur @@ -137,7 +128,10 @@ func (tso *TimeSeriesOptionsBuilder) SetBucketMaxSpan(dur time.Duration) *TimeSe return tso } -// SetBucketRounding sets the value for BucketRounding. +// SetBucketRounding sets the value for BucketRounding. BucketRounding is used to determine the +// minimum time boundary when opening a new bucket by rounding the first timestamp down to the next +// multiple of this value. The time.Duration is rounded down to the nearest second and applied as +// the command option: "bucketRoundingSeconds". This field is optional. func (tso *TimeSeriesOptionsBuilder) SetBucketRounding(dur time.Duration) *TimeSeriesOptionsBuilder { tso.Opts = append(tso.Opts, func(opts *TimeSeriesOptions) error { opts.BucketRounding = &dur @@ -150,81 +144,23 @@ func (tso *TimeSeriesOptionsBuilder) SetBucketRounding(dur time.Duration) *TimeS // CreateCollectionOptions represents arguments that can be used to configure a // CreateCollection operation. +// +// See corresponding setter methods for documentation. type CreateCollectionOptions struct { - // Specifies if the collection is capped (see https://www.mongodb.com/docs/manual/core/capped-collections/). If true, - // the SizeInBytes option must also be specified. The default value is false. - Capped *bool - - // Specifies the default collation for the new collection. This option is only valid for MongoDB versions >= 3.4. - // For previous server versions, the driver will return an error if this option is used. The default value is nil. - Collation *Collation - - // Specifies how change streams opened against the collection can return pre- and post-images of updated - // documents. The value must be a document in the form {