CSHARP-3400: Implemented support for creating time-series collections. (#559)

Author: JamesKovacs

src/MongoDB.Driver.Core/Core/Operations/CreateCollectionOperation.cs

@@ -21,7 +21,6 @@
 using MongoDB.Driver.Core.Bindings;
 using MongoDB.Driver.Core.Connections;
 using MongoDB.Driver.Core.Misc;
-using MongoDB.Driver.Core.Servers;
 using MongoDB.Driver.Core.WireProtocol.Messages.Encoders;
 
 namespace MongoDB.Driver.Core.Operations
@@ -36,12 +35,14 @@ public class CreateCollectionOperation : IWriteOperation<BsonDocument>
         private bool? _capped;
         private Collation _collation;
         private readonly CollectionNamespace _collectionNamespace;
+        private TimeSpan? _expireAfter;
         private BsonDocument _indexOptionDefaults;
         private long? _maxDocuments;
         private long? _maxSize;
         private readonly MessageEncoderSettings _messageEncoderSettings;
         private bool? _noPadding;
         private BsonDocument _storageEngine;
+        private TimeSeriesOptions _timeSeriesOptions;
         private bool? _usePowerOf2Sizes;
         private DocumentValidationAction? _validationAction;
         private DocumentValidationLevel? _validationLevel;
@@ -111,6 +112,18 @@ public CollectionNamespace CollectionNamespace
             get { return _collectionNamespace; }
         }
 
+        /// <summary>
+        /// Gets or sets the expiration timespan for time-series collections.
+        /// </summary>
+        /// <value>
+        /// The timespan after which to expire documents.
+        /// </value>
+        public TimeSpan? ExpireAfter
+        {
+            get { return _expireAfter; }
+            set { _expireAfter = value; }
+        }
+
         /// <summary>
         /// Gets or sets the index option defaults.
         /// </summary>
@@ -179,11 +192,23 @@ public BsonDocument StorageEngine
             set { _storageEngine = value; }
         }
 
+        /// <summary>
+        /// Gets or sets the <see cref="TimeSeriesOptions"/> to use when creating a time series collection.
+        /// </summary>
+        /// <value>
+        /// The time series options.
+        /// </value>
+        public TimeSeriesOptions TimeSeriesOptions
+        {
+            get { return _timeSeriesOptions; }
+            set { _timeSeriesOptions = value; }
+        }
+
         /// <summary>
         /// Gets or sets a value indicating whether the collection should use power of 2 sizes.
         /// </summary>
         /// <value>
-        /// A value indicating whether the collection should use power of 2 sizes..
+        /// A value indicating whether the collection should use power of 2 sizes.
         /// </value>
         public bool? UsePowerOf2Sizes
         {
@@ -261,7 +286,9 @@ internal BsonDocument CreateCommand(ICoreSessionHandle session, ConnectionDescri
                 { "validationAction", () => _validationAction.Value.ToString().ToLowerInvariant(), _validationAction.HasValue },
                 { "validationLevel", () => _validationLevel.Value.ToString().ToLowerInvariant(), _validationLevel.HasValue },
                 { "collation", () => _collation.ToBsonDocument(), _collation != null },
-                { "writeConcern", writeConcern, writeConcern != null }
+                { "writeConcern", writeConcern, writeConcern != null },
+                { "expireAfterSeconds", () => _expireAfter.Value.TotalSeconds, _expireAfter.HasValue },
+                { "timeseries", () => _timeSeriesOptions.ToBsonDocument(), _timeSeriesOptions != null }
             };
         }
 

src/MongoDB.Driver.Core/TimeSeriesGranularity.cs

@@ -0,0 +1,36 @@
+/* Copyright 2021-present MongoDB Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Specifies the granularity of time series collection bucketing.
+    /// </summary>
+    public enum TimeSeriesGranularity
+    {
+        /// <summary>
+        /// Seconds.
+        /// </summary>
+        Seconds,
+        /// <summary>
+        /// Minutes.
+        /// </summary>
+        Minutes,
+        /// <summary>
+        /// Hours.
+        /// </summary>
+        Hours
+    }
+}

src/MongoDB.Driver.Core/TimeSeriesOptions.cs

@@ -0,0 +1,72 @@
+/* Copyright 2021-present MongoDB Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+using MongoDB.Bson;
+using MongoDB.Driver.Core.Misc;
+
+namespace MongoDB.Driver
+{
+    /// <summary>
+    /// Defines the time series options to use when creating a time-series collection.
+    /// </summary>
+    public class TimeSeriesOptions
+    {
+        private readonly TimeSeriesGranularity? _granularity;
+        private readonly string _metaField;
+        private readonly string _timeField;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TimeSeriesOptions"/> class.
+        /// </summary>
+        /// <param name="timeField">The name of the top-level field to be used for time.</param>
+        /// <param name="metaField">The name of the top-level field describing the series upon which related data will be grouped.</param>
+        /// <param name="granularity">The <see cref="TimeSeriesGranularity"/> for the time series.</param>
+        public TimeSeriesOptions(string timeField, Optional<string> metaField = default, Optional<TimeSeriesGranularity?> granularity = default)
+        {
+            _timeField = Ensure.IsNotNullOrEmpty(timeField, nameof(timeField));
+            _metaField = metaField.WithDefault(null);
+            _granularity = granularity.WithDefault(null);
+        }
+
+        /// <summary>
+        /// The coarse granularity of time-series data.
+        /// </summary>
+        public TimeSeriesGranularity? Granularity => _granularity;
+
+        /// <summary>
+        /// The name of the field which contains metadata in each time-series document.
+        /// </summary>
+        public string MetaField => _metaField;
+
+        /// <summary>
+        /// The name of the field which contains the date and time in each time-series document.
+        /// </summary>
+        public string TimeField => _timeField;
+
+        /// <summary>
+        /// The BSON representation of the time-series options.
+        /// </summary>
+        /// <returns>A BsonDocument.</returns>
+        public BsonDocument ToBsonDocument()
+        {
+            return new BsonDocument
+            {
+                { "timeField", _timeField },
+                { "metaField", _metaField, _metaField != null },
+                { "granularity", () => _granularity.Value.ToString().ToLowerInvariant(), _granularity.HasValue }
+            };
+        }
+    }
+}

src/MongoDB.Driver/CreateCollectionOptions.cs

@@ -28,11 +28,13 @@ public class CreateCollectionOptions
         private bool? _autoIndexId;
         private bool? _capped;
         private Collation _collation;
+        private TimeSpan? _expireAfter;
         private IndexOptionDefaults _indexOptionDefaults;
         private long? _maxDocuments;
         private long? _maxSize;
         private bool? _noPadding;
         private BsonDocument _storageEngine;
+        private TimeSeriesOptions _timeSeriesOptions;
         private bool? _usePowerOf2Sizes;
         private IBsonSerializerRegistry _serializerRegistry;
         private DocumentValidationAction? _validationAction;
@@ -67,6 +69,16 @@ public bool? Capped
             set { _capped = value; }
         }
 
+
+        /// <summary>
+        /// Gets or sets a timespan indicating how long documents in a time series collection should be retained.
+        /// </summary>
+        public TimeSpan? ExpireAfter
+        {
+            get { return _expireAfter; }
+            set { _expireAfter = value; }
+        }
+
         /// <summary>
         /// Gets or sets the index option defaults.
         /// </summary>
@@ -124,6 +136,15 @@ public BsonDocument StorageEngine
             set { _storageEngine = value; }
         }
 
+        /// <summary>
+        /// Gets or sets the <see cref="TimeSeriesOptions"/> to use when creating a time series collection.
+        /// </summary>
+        public TimeSeriesOptions TimeSeriesOptions
+        {
+            get { return _timeSeriesOptions; }
+            set { _timeSeriesOptions = value; }
+        }
+
         /// <summary>
         /// Gets or sets a value indicating whether to use power of 2 sizes.
         /// </summary>
@@ -186,12 +207,14 @@ internal static CreateCollectionOptions<TDocument> CoercedFrom(CreateCollectionO
                     AutoIndexId = options.AutoIndexId,
                     Capped = options.Capped,
                     Collation = options.Collation,
+                    ExpireAfter = options.ExpireAfter,
                     IndexOptionDefaults = options.IndexOptionDefaults,
                     MaxDocuments = options.MaxDocuments,
                     MaxSize = options.MaxSize,
                     NoPadding = options.NoPadding,
                     SerializerRegistry = options.SerializerRegistry,
                     StorageEngine = options.StorageEngine,
+                    TimeSeriesOptions = options.TimeSeriesOptions,
                     UsePowerOf2Sizes = options.UsePowerOf2Sizes,
                     ValidationAction = options.ValidationAction,
                     ValidationLevel = options.ValidationLevel

src/MongoDB.Driver/MongoDatabaseImpl.cs

@@ -626,27 +626,6 @@ private Task CreateCollectionHelperAsync<TDocument>(IClientSessionHandle session
             return ExecuteWriteOperationAsync(session, operation, cancellationToken);
         }
 
-        private CreateCollectionOperation CreateCreateCollectionOperation(string name, CreateCollectionOptions options)
-        {
-            options = options ?? new CreateCollectionOptions();
-            var messageEncoderSettings = GetMessageEncoderSettings();
-
-#pragma warning disable 618
-            return new CreateCollectionOperation(new CollectionNamespace(_databaseNamespace, name), messageEncoderSettings)
-            {
-                AutoIndexId = options.AutoIndexId,
-                Collation = options.Collation,
-                Capped = options.Capped,
-                MaxDocuments = options.MaxDocuments,
-                MaxSize = options.MaxSize,
-                NoPadding = options.NoPadding,
-                StorageEngine = options.StorageEngine,
-                UsePowerOf2Sizes = options.UsePowerOf2Sizes,
-                WriteConcern = _settings.WriteConcern
-            };
-#pragma warning restore
-        }
-
         private CreateCollectionOperation CreateCreateCollectionOperation<TDocument>(string name, CreateCollectionOptions<TDocument> options)
         {
             var messageEncoderSettings = GetMessageEncoderSettings();
@@ -664,11 +643,13 @@ private CreateCollectionOperation CreateCreateCollectionOperation<TDocument>(str
                 AutoIndexId = options.AutoIndexId,
                 Capped = options.Capped,
                 Collation = options.Collation,
+                ExpireAfter = options.ExpireAfter,
                 IndexOptionDefaults = options.IndexOptionDefaults?.ToBsonDocument(),
                 MaxDocuments = options.MaxDocuments,
                 MaxSize = options.MaxSize,
                 NoPadding = options.NoPadding,
                 StorageEngine = options.StorageEngine,
+                TimeSeriesOptions = options.TimeSeriesOptions,
                 UsePowerOf2Sizes = options.UsePowerOf2Sizes,
                 ValidationAction = options.ValidationAction,
                 ValidationLevel = options.ValidationLevel,

tests/MongoDB.Driver.Core.Tests/TimeSeriesOptionsTests.cs

@@ -0,0 +1,65 @@
+/* Copyright 2021-present MongoDB Inc.
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+* http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+
+using System;
+using FluentAssertions;
+using Xunit;
+
+namespace MongoDB.Driver
+{
+    public class TimeSeriesOptionsTests
+    {
+        [Fact]
+        public void constructor_with_timeField_should_initialize_instance()
+        {
+            const string timeField = "time";
+            var result = new TimeSeriesOptions(timeField);
+
+            result.TimeField.Should().Be(timeField);
+            result.MetaField.Should().BeNull();
+            result.Granularity.Should().BeNull();
+        }
+
+        [Fact]
+        public void constructor_with_null_timeField_should_throw()
+        {
+            const string timeField = null;
+            var exception = Record.Exception(() => new TimeSeriesOptions(timeField));
+            exception.Should().BeOfType<ArgumentNullException>();
+        }
+
+        [Fact]
+        public void constructor_with_empty_string_timeField_should_throw()
+        {
+            const string timeField = "";
+            var exception = Record.Exception(() => new TimeSeriesOptions(timeField));
+            exception.Should().BeOfType<ArgumentException>();
+        }
+
+        [Fact]
+        public void constructor_with_all_parameters_should_initialize_instance()
+        {
+            const string timeField = "time";
+            const string metaField = "meta";
+            const TimeSeriesGranularity granularity = TimeSeriesGranularity.Hours;
+
+            var result = new TimeSeriesOptions(timeField, metaField, granularity);
+
+            result.TimeField.Should().Be(timeField);
+            result.MetaField.Should().Be(metaField);
+            result.Granularity.Should().Be(granularity);
+        }
+    }
+}