Get Parameter Ranges¶

Get parameter ranges

A range is a tuple (start, stop, value, count) that represents the time interval for which the parameter has been steadily coming in with the same value. This request is useful for retrieving an overview for parameters that change unfrequently in a large time interval. For example an on/off status of a device, or some operational status. Two consecutive ranges containing the same value will be returned if there was a gap in the data. The gap is determined according to the parameter expiration time configured in the Mission Database.

URI Template

GET /api/archive/{instance}/parameters/{name*}/ranges

{instance}: Yamcs instance name.
{name*}: Parameter name.

Query Parameters

start: Filter the lower bound of the parameter's generation time. Specify a date string in ISO 8601 format.
stop: Filter the upper bound of the parameter's generation time. Specify a date string in ISO 8601 format.
minGap: Time in milliseconds. Any gap (detected based on parameter expiration) smaller than this will be ignored. However if the parameter changes value, the ranges will still be split.
maxGap: Time in milliseconds. If the distance between two subsequent values of the parameter is bigger than this value (but smaller than the parameter expiration), then an artificial gap will be constructed. This also applies if there is no parameter expiration defined for the parameter.
norealtime: Disable loading of parameters from the parameter cache. Default: false.
processor: The name of the processor from which to use the parameter cache. Default: realtime.
source: Specifies how to retrieve the parameters. Either ParameterArchive or replay. If replay is specified, a replay processor will be created and data will be processed with the active Mission Database. Note that this is much slower than receiving data from the ParameterArchive.

Default: ParameterArchive.
minRange: Time in milliseconds of the minimum range to be returned. If the data changes more often, a new range will not be created but the data will be added to the old range.
maxValues: Maximum number of distinct values to be returned. The maximum number applies across all ranges and is meant to limit the amount of data that is being retrieved. The retrieved data has a count for each value as well as a total count. The difference between the total count and the sum of the individual counts can be used to compute the number of unsent values.

Response Type

interface Ranges {
  range: Range[];
}

Related Types

interface Range {

  // Generation time of a parameter value.
  start: string;  // RFC 3339 timestamp

  // If the value changes, ``stop`` is the generation time of the new value.
  // If the parameter expires or the ``maxGap`` has been set, ``stop`` is
  // the generation time of the last value plus the expiration time or the
  // ``maxGap``.
  stop: string;  // RFC 3339 timestamp

  // Number of parameter values received in the interval.
  // This is the total count of parameters in the interval.
  // If the count does not match the sum(counts), it means that not all the values have been sent
  count: number;

  // Since Yamcs 5.4.1 there is a new parameter minRange in the GetParameterRangesRequest which allows
  // specifying the minimum length of the range returned.
  // Practically we guarantee that stop-start >= minRange (mind the leap seconds!).
  //
  // If the minRange parameter is set, the returning ranges may include multiple values.
  // These are given by the engValues and counts below.
  //
  // Since Yamcs 5.4.2 there is a new parameter maxValues which allows to limit the number
  // of distinct values returned across all the ranges.
  // In order to not return ranges containing no value, each range will have at least one value even if
  // that will cause the total number of range values returned to exceed the maxValues parameter
  //
  // The counts correspond one to one to the engValues, the two arrays will always have the same length.
  engValues: Value[];

  // The counts correspond one to one to the engValues
  counts: number[];
}

// Union type for storing a value
interface Value {
  type: Type;
  floatValue: number;
  doubleValue: number;
  sint32Value: number;
  uint32Value: number;
  binaryValue: string;  // Base64
  stringValue: string;
  timestampValue: string;  // String decimal
  uint64Value: string;  // String decimal
  sint64Value: string;  // String decimal
  booleanValue: boolean;
  aggregateValue: AggregateValue;
  arrayValue: Value[];
}

// An aggregate value is an ordered list of (member name, member value).
// Two arrays are used in order to be able to send just the values (since
// the names will not change)
interface AggregateValue {
  name: string[];
  value: Value[];
}

enum Type {
  FLOAT = "FLOAT",
  DOUBLE = "DOUBLE",
  UINT32 = "UINT32",
  SINT32 = "SINT32",
  BINARY = "BINARY",
  STRING = "STRING",
  TIMESTAMP = "TIMESTAMP",
  UINT64 = "UINT64",
  SINT64 = "SINT64",
  BOOLEAN = "BOOLEAN",
  AGGREGATE = "AGGREGATE",
  ARRAY = "ARRAY",

  // Enumerated values have both an integer (sint64Value) and a string representation
  ENUMERATED = "ENUMERATED",
  NONE = "NONE",
}