diff --git a/src/Raven.Client/Documents/Operations/Counters/CounterBatch.cs b/src/Raven.Client/Documents/Operations/Counters/CounterBatch.cs index 801298c3e599..d583e4d1befc 100644 --- a/src/Raven.Client/Documents/Operations/Counters/CounterBatch.cs +++ b/src/Raven.Client/Documents/Operations/Counters/CounterBatch.cs @@ -12,8 +12,22 @@ namespace Raven.Client.Documents.Operations.Counters /// public sealed class CounterBatch { - public bool ReplyWithAllNodesValues; + /// + /// Gets or sets a value indicating whether the response should include counter values from all nodes. + /// When set to true, the response includes the values of each counter from all nodes in the cluster. + /// + public bool ReplyWithAllNodesValues { get; set; } + + /// + /// Gets or sets the list of counter operations to be performed on the specified documents. + /// Each represents a set of counter operations for a single document. + /// public List Documents = new List(); + + /// + /// Gets or sets a value indicating whether the batch originated from an ETL process. + /// This is used internally to identify and manage counter operations triggered by ETL pipelines. + /// public bool FromEtl; } @@ -22,8 +36,24 @@ public sealed class CounterBatch /// public sealed class DocumentCountersOperation { - public List Operations; - public string DocumentId; + /// + /// Gets or sets the list of counter operations to be performed on the specified document. + /// Each operation in the list specifies an action, such as incrementing or deleting a counter. + /// + /// + /// The property is mandatory and must be populated before the batch operation is executed. + /// If it is not set or is empty, an exception will be thrown during parsing or execution. + /// + public List Operations { get; set; } + + /// + /// Gets or sets the ID of the document on which the counter operations are to be performed. + /// + /// + /// The property is mandatory and identifies the target document for the counter operations. + /// If it is not set, an exception will be thrown during parsing or execution. + /// + public string DocumentId { get; set; } public static DocumentCountersOperation Parse(BlittableJsonReaderObject input) { @@ -78,13 +108,39 @@ public DynamicJsonValue ToJson() } } + /// + /// Represents the types of operations that can be performed on counters in RavenDB. + /// public enum CounterOperationType { + /// + /// No operation. Represents the absence of any counter operation. + /// None, + + /// + /// Increases the value of the counter by a specified amount. If the counter does not exist, it will be created with the specified value. + /// Increment, + + /// + /// Deletes the counter, removing it from the database. + /// Delete, + + /// + /// Retrieves the value of a specific counter. + /// Get, + + /// + /// Used internally for sending counters by ETL + /// Put, + + /// + /// Retrieves all counters associated with a document. When using this type, 'CounterName' should not be specified. + /// GetAll } @@ -93,9 +149,38 @@ public enum CounterOperationType /// public sealed class CounterOperation { - public CounterOperationType Type; - public string CounterName; - public long Delta; + /// + /// Gets or sets the type of the counter operation to be performed. + /// Specifies the action, such as incrementing, deleting, or retrieving a counter value. + /// + /// + /// Valid types are defined in the enumeration, including: + /// - : Increments the counter by a specified value. + /// - : Deletes the counter. + /// - : Retrieves the value of the counter. + /// - : Retrieves all counters for a document. + /// + public CounterOperationType Type { get; set; } + + /// + /// Gets or sets the name of the counter to be operated on. + /// + /// + /// - The property is mandatory for operations of type , , and . + /// - For , the property is not used and can be null. + /// - If is required but not set, an exception will be thrown during parsing or execution. + /// + public string CounterName { get; set; } + + /// + /// Gets or sets the value by which the counter should be incremented or decremented. + /// + /// + /// - Used only for operations of type . + /// - For , this specifies the exact value to set for the counter but is used internally and not intended for external use. + /// - For other operation types, this property is ignored. + /// + public long Delta { get; set; } internal string ChangeVector; internal string DocumentId; diff --git a/src/Raven.Client/Documents/Operations/Counters/CountersDetail.cs b/src/Raven.Client/Documents/Operations/Counters/CountersDetail.cs index 53bd3db7dc23..8d38867f9ee8 100644 --- a/src/Raven.Client/Documents/Operations/Counters/CountersDetail.cs +++ b/src/Raven.Client/Documents/Operations/Counters/CountersDetail.cs @@ -7,8 +7,22 @@ namespace Raven.Client.Documents.Operations.Counters { + /// + /// Represents the result of executing a or , + /// containing details of counters associated with a document. + /// public sealed class CountersDetail { + /// + /// Gets or sets the list of counter details retrieved by the operation. + /// Each in the list provides information about a specific counter, + /// including its name and value. + /// + /// + /// This property contains the results of either: + /// - A : Retrieves details of counters for a document. + /// - A : Returns details of counters affected by a batch operation. + /// public List Counters { get; set; } public CountersDetail() @@ -25,14 +39,54 @@ public DynamicJsonValue ToJson() } } + /// + /// Represents detailed information about a counter associated with a document in RavenDB. + /// public sealed class CounterDetail { + /// + /// Gets or sets the ID of the document to which the counter belongs. + /// public string DocumentId { get; set; } + + /// + /// Gets or sets the name of the counter. + /// + /// + /// This identifies the specific counter within the document. + /// public string CounterName { get; set; } + + /// + /// Gets or sets the total value of the counter across all nodes. + /// + /// + /// This value is the aggregate of all per-node counter values stored in . + /// public long TotalValue { get; set; } + + /// + /// Gets or sets the ETag associated with the counter. + /// + /// + /// The ETag is a unique identifier used to track changes to the counter. + /// public long Etag { get; set; } + + /// + /// Gets or sets the dictionary of counter values for each node in the cluster. + /// + /// + /// The key is the node identifier, and the value is the counter value for that node. + /// public Dictionary CounterValues { get; set; } + /// + /// Gets or sets the change vector for the counter. + /// + /// + /// The change vector represents the version history of the counter and is used for concurrency control. + /// public string ChangeVector { get; set; } internal LazyStringValue CounterKey { get; set; } @@ -49,14 +103,38 @@ public DynamicJsonValue ToJson() } } + /// + /// Represents detailed information about a group of counters associated with a document in RavenDB. + /// public sealed class CounterGroupDetail : IDisposable { + /// + /// Gets or sets the ID of the document to which the counter group belongs. + /// + /// + /// This property identifies the document that holds the counters in this group. + /// public LazyStringValue DocumentId { get; set; } + /// + /// Gets or sets the change vector for the counter group. + /// + /// + /// The change vector represents the version history of the counter group and is used for concurrency control. + /// public LazyStringValue ChangeVector { get; set; } + /// + /// Gets or sets the raw Blittable JSON object containing the counter values in the group. + /// public BlittableJsonReaderObject Values { get; set; } + /// + /// Gets or sets the ETag for the counter group. + /// + /// + /// The ETag is a unique identifier used to track changes to the counter group. + /// public long Etag { get; set; } public DynamicJsonValue ToJson() diff --git a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesDetails.cs b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesDetails.cs index f71badff6e7f..3501f1507d6b 100644 --- a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesDetails.cs +++ b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesDetails.cs @@ -2,9 +2,29 @@ namespace Raven.Client.Documents.Operations.TimeSeries { + /// + /// Represents the result of executing a , + /// providing details of time series data associated with a document in RavenDB. + /// + public sealed class TimeSeriesDetails { + /// + /// Gets or sets the ID of the document to which the time series data belongs. + /// + /// + /// This property identifies the document that holds the time series data retrieved by the operation. + /// public string Id { get; set; } + + /// + /// Gets or sets a dictionary containing the time series data. + /// + /// + /// The dictionary maps the name of each time series to a list of objects, + /// where each range result represents a segment of the time series data. + /// The data is retrieved as part of the . + /// public Dictionary> Values { get; set; } } } diff --git a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesOperation.cs b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesOperation.cs index 951f3a585fec..056be7a0d9ed 100644 --- a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesOperation.cs +++ b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesOperation.cs @@ -17,7 +17,6 @@ public sealed class TimeSeriesOperation private SortedList _appends; private SortedList _increments; - internal IList Appends { get => _appends?.Values; @@ -45,6 +44,18 @@ private set } } + /// + /// Adds an incremental operation to the batch for the specified time series. + /// This operation increments the values at the given timestamp, supporting concurrent updates in a distributed environment. + /// + /// The increment operation to add, specifying the timestamp and values to increment. + /// + /// Incremental time series in RavenDB are designed to handle concurrent updates from multiple nodes. + /// Each node maintains its own local changes for the specified timestamp, which are aggregated to provide a unified view. + /// + /// + /// Thrown if the number of values in the new operation does not match the number in an existing operation for the same timestamp. + /// public void Increment(IncrementOperation incrementOperation) { _increments ??= new SortedList(); @@ -67,8 +78,21 @@ public void Increment(IncrementOperation incrementOperation) internal List Deletes; - public string Name; + /// + /// Gets or sets the name of the time series on which the operations are performed. + /// This property is mandatory and must be set before executing the that contains this . + /// + /// + /// The property identifies the time series within the document to which the batch operations apply. + /// If this property is not set, an exception will be thrown when attempting to execute the batch operation. + /// + public string Name { get; set; } + /// + /// Adds an append operation to the batch. + /// This operation adds new data points to the time series at a specific timestamp. + /// + /// The append operation to add. public void Append(AppendOperation appendOperation) { _appends ??= new SortedList(); @@ -76,6 +100,11 @@ public void Append(AppendOperation appendOperation) _appends[appendOperation.Timestamp.Ticks] = appendOperation; // on duplicate values the last one overrides } + /// + /// Adds a delete operation to the batch. + /// This operation removes data points within a specific range from the time series. + /// + /// The delete operation to add. public void Delete(DeleteOperation deleteOperation) { Deletes ??= new List(); @@ -284,6 +313,10 @@ private static void ThrowMissingProperty(string prop) throw new InvalidDataException($"Missing '{prop}' property on TimeSeriesOperation '{typeof(T).Name}'"); } + /// + /// Converts the time series operation into a JSON representation. + /// + /// A representing the operation. public DynamicJsonValue ToJson() { return new DynamicJsonValue @@ -300,10 +333,23 @@ public DynamicJsonValue ToJson() /// public sealed class AppendOperation { - public DateTime Timestamp; - public double[] Values; - public string Tag; - + /// + /// Gets or sets the timestamp of the data point to be appended. + /// This specifies when the data point occurred. + /// + public DateTime Timestamp { get; set; } + + /// + /// Gets or sets the values associated with the data point. + /// These are the numeric measurements recorded at the specified . + /// + public double[] Values { get; set; } + + /// + /// Gets or sets an optional tag for the data point. + /// The tag can provide additional context or metadata for the appended data, such as the source or a descriptive label. + /// + public string Tag { get; set; } internal static AppendOperation Parse(BlittableJsonReaderObject input) { if (input.TryGet(nameof(Timestamp), out DateTime ts) == false) @@ -350,7 +396,19 @@ public DynamicJsonValue ToJson() /// public sealed class DeleteOperation { - public DateTime? From, To; + /// + /// Gets or sets the start of the range for the delete operation. + /// Data points from this timestamp (inclusive) will be considered for deletion. + /// If null, the range starts from the beginning of the time series. + /// + public DateTime? From { get; set; } + + /// + /// Gets or sets the end of the range for the delete operation. + /// Data points up to this timestamp (inclusive) will be considered for deletion. + /// If null, the range extends to the end of the time series. + /// + public DateTime? To { get; set; } internal static DeleteOperation Parse(BlittableJsonReaderObject input) { @@ -379,8 +437,18 @@ public DynamicJsonValue ToJson() /// public sealed class IncrementOperation { - public DateTime Timestamp; - public double[] Values; + /// + /// Gets or sets the timestamp of the data point to be incremented. + /// This specifies the exact point in time where the values should be adjusted. + /// + public DateTime Timestamp { get; set; } + + /// + /// Gets or sets the values to increment at the specified . + /// Each value corresponds to a numeric field in the time series, and the increment operation adds the specified amount to the current values. + /// + public double[] Values { get; set; } + internal int? ValuesLength; internal static IncrementOperation Parse(BlittableJsonReaderObject input) diff --git a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesRange.cs b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesRange.cs index a4e9a190bb78..89fd8659da64 100644 --- a/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesRange.cs +++ b/src/Raven.Client/Documents/Operations/TimeSeries/TimeSeriesRange.cs @@ -3,9 +3,24 @@ namespace Raven.Client.Documents.Operations.TimeSeries { + /// + /// Represents a range of time series data based on specific start and end times. + /// public sealed class TimeSeriesRange : AbstractTimeSeriesRange { - public DateTime? From, To; + /// + /// Gets or sets the start time of the range. + /// Data points from this timestamp (inclusive) will be included in the range. + /// If null, the range starts from the beginning of the time series. + /// + public DateTime? From { get; set; } + + /// + /// Gets or sets the end time of the range. + /// Data points up to this timestamp (inclusive) will be included in the range. + /// If null, the range extends to the end of the time series. + /// + public DateTime? To { get; set; } } internal sealed class TimeSeriesTimeRange : AbstractTimeSeriesRange @@ -20,14 +35,33 @@ internal sealed class TimeSeriesCountRange : AbstractTimeSeriesRange public TimeSeriesRangeType Type; } + /// + /// Represents a base class for defining time series ranges. + /// public abstract class AbstractTimeSeriesRange { - public string Name; + /// + /// Gets or sets the name of the time series. + /// + /// + /// This property identifies the time series on which the range operations will be performed. + /// + public string Name { get; set; } } + /// + /// Specifies the type of time series range operation. + /// public enum TimeSeriesRangeType { + /// + /// No range type specified. + /// None, + + /// + /// Specifies a range that retrieves the last set of data points from the time series. + /// Last } } diff --git a/src/Raven.Client/Documents/Session/TimeSeries/TimeSeriesEntry.cs b/src/Raven.Client/Documents/Session/TimeSeries/TimeSeriesEntry.cs index d4d42a21e5e7..679144d9f5e1 100644 --- a/src/Raven.Client/Documents/Session/TimeSeries/TimeSeriesEntry.cs +++ b/src/Raven.Client/Documents/Session/TimeSeries/TimeSeriesEntry.cs @@ -1,5 +1,5 @@ //----------------------------------------------------------------------- -// +// // Copyright (c) Hibernating Rhinos LTD. All rights reserved. // //----------------------------------------------------------------------- @@ -28,12 +28,42 @@ namespace Raven.Client.Documents.Session.TimeSeries /// public class TimeSeriesEntry : ITimeSeriesQueryStreamEntry { + /// + /// Gets or sets the timestamp of the time series entry. + /// This represents the point in time at which the values were recorded. + /// public DateTime Timestamp { get; set; } + + /// + /// Gets or sets the values associated with the time series entry. + /// These values represent the numeric data points recorded at the specified . + /// public double[] Values { get; set; } + + /// + /// Gets or sets the tag for the time series entry. + /// This optional metadata provides additional context about the entry, such as the source or a descriptive label. + /// public string Tag { get; set; } + + /// + /// Gets or sets a value indicating whether the entry is part of a rollup time series. + /// A rollup aggregates data over a specific time range, as opposed to individual data points. + /// public bool IsRollup { get; set; } + + /// + /// Gets or sets a dictionary of node-specific values for the time series entry. + /// The key represents the node identifier, and the value is an array of numeric data points associated with that node. + /// public Dictionary NodeValues { get; set; } + /// + /// Gets or sets the value of the time series entry if it contains a single value. + /// + /// + /// Thrown if the entry contains more than one value. + /// [JsonDeserializationIgnore] public double Value { @@ -56,6 +86,10 @@ public double Value } } + /// + /// Returns a string representation of the time series entry, including the timestamp, values, and tag. + /// + /// A string in the format "[Timestamp] Values Tag". public override string ToString() { return $"[{Timestamp}] {string.Join(", ", Values)} {Tag}";