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.

This route parameter may contain forward slashes. Alternatively you may also use URL-encoded characters, such as %2F

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.
  stop: string;  // RFC 3339 timestamp

  // Total number of parameter values in this range.
  //
  // This is the sum of the ``counts`` array, and ``otherCount``.
  count: number;

  // The ``minRange`` option on the request allows to specify
  // the minimum length of returned ranges.
  //
  // Practically we guarantee that stop-start >= minRange (mind the leap
  // seconds!).
  //
  // If ``minRange`` was set, the returned ranges may include multiple
  // values. These are given by ``engValues`` and ``counts``.
  //
  // The ``maxValues`` option on the request allows to limit the number
  // of distinct values returned across all the ranges.
  //
  // The counts correspond one to one to the engValues, the two arrays have
  // the same length.
  engValues: Value[];

  // Array of same length as ``engValues``, with respective value counts
  // within this range.
  counts: number[];

  // Values in this range that do not match one of the returned
  // ``engValues``.
  otherCount: 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",
}