value_service.proto

/* Service to fetch time series data from our system.
 *
 * Time series data is produced by the device and sent in the form of messages.
 * Messages are parsed to a number of values (depending on the parser), which can be retrieved using this service.
 */
syntax = "proto3";

package hiber.value;

import "base.proto";
import "asset.proto";
import "modem.proto";
import "value.proto";

option java_multiple_files = false;
option java_package = "global.hiber.api.grpc.value";
option java_outer_classname = "ValueServiceApi";
option go_package = ".;hiber";

service ValueService {
    rpc List (ListValues.Request) returns (ListValues.Response);
    rpc Downsampled (DownsampledValues.Request) returns (DownsampledValues.Response);
}

/* Select the values to return. */
message ValueSelection {
    /* Select the data by numeric value type.
     * If the list is empty, all fields are returned.
     */
    message ByField {
        repeated string fields = 1;
    }

    /* Select the data by (numeric) value type.
     * If the selection is empty, all values with all types are returned.
     */
    message ByValueType {
        repeated Value.Type value_type = 2;
        repeated Value.Numeric.Type numeric_value_type = 1;
    }

    /* Select the owners (either assets or devices) to get the values for. */
    oneof owner_selection {
        /* Select the devices(s) to get the values for. */
        modem.ModemSelection devices = 1;

        /* Select the asset(s) to get the values for. */
        asset.AssetSelection assets = 7;
    }

    /* Select the type of values (either by field or by numeric value type) to get.
     * If no option is picked, ByField is assumed.
     */
    oneof data_selection {
        /* Get the values that are of the given numeric value types. */
        ByValueType value_type = 8;

        /* Get the values for the selected fields. */
        ByField field = 9;
    }

    /* Get the values for the selected fields. */
    repeated string fields = 2 [deprecated = true];

    /* The time to view the values for. */
    optional TimeRange time_range = 3;

    /* Include the location (which is not a field). */
    optional bool include_location = 4;

    /* Filter the values for enum fields. */
    repeated Filter.FieldEnumValues filter_enum_values = 6;

    /* Whether to include values that have been marked as operational (i.e. device status).
     * Operational data is typically only available when selecting values for a device.
     */
    optional bool include_operational_data = 10;
}

/* A Value at a time, for a given modem and field. */
message ValueContext {
    /* The device that produced this value. */
    ValueDeviceContext device = 8;

    /* The device that produced this value. */
    string device_number = 1 [deprecated = true];

    /* The asset that owns this value, if any.
     * Assets own this value if they were assigned to the device that produced this value at the time it was produced.
     * If multiple assets were assigned at the same time, this value exists for each asset.
     */
    ValueAssetContext asset = 7;

    /* The field that this value was produced for. */
    string field = 2;

    /* The time for this value. */
    Timestamp time = 3;

    oneof value_type {
        /* The value at this time, if no ValueTransformation was specified for this field. */
        Value value = 4;

        /* The output of the DURATION ValueTransformation, if it was specified for this field. */
        ValueDurations value_durations = 5;

        /* The output of the DELTA ValueTransformation, if it was specified for this field. */
        ValueDelta delta = 6;
    }

    /* Information about the asset that owns the value. */
    message ValueAssetContext {
        string identifier = 1;
        string name = 2;
        asset.Asset.Type type = 3;
    }

    /* The device data for this value. */
    message ValueDeviceContext {
        string number = 1;
        string identifier = 2;
        string name = 3;
    }

    /* The amount of time a field for a modem was at different values. */
    message ValueDurations {
        repeated ValueDuration durations = 1;
    }

    /* The amount of time a field for a modem was in this value. */
    message ValueDuration {
        /* The value the duration is for. */
        Value value = 1;

        /* The aggregated duration the field was this value. */
        Duration duration = 2;
    }

    /* The delta of a value: the difference between a value and the previous value. */
    message ValueDelta {
        /* The delta of the two values. */
        Value delta = 1;

        /* The value at this time. */
        Value current = 2;

        /* The previous value to compare it with. */
        Value previous = 3;
    }
}

/* List values for a (set of) modem(s), filtering by field and time. */
message ListValues {
    /* How to sort the values. */
    enum Sort {
        TIME_ASCENDING = 0;
        TIME_DESCENDING = 1;
    }

    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;
        ValueSelection selection = 2;
        optional Pagination pagination = 3;
        Sort sort = 4;

        /* Transform the values for a field into a derived value.
         * Fields specified here must have been specified in the selection.
         */
        map<string, ValueTransformation> transform_fields = 5;
    }

    message Response {
        repeated ValueContext values = 1;
        Pagination.Result pagination = 2;
        Request request = 3;
    }
}

/* Downsampled values for a (set of) modem(s), filtering by field and time. */
message DownsampledValues {
    /* Request downsampled values, reducing the selected time range to a single value per field. */
    message Request {
        /* Pick the organization to use (/impersonate). If unset, your default organization is used. */
        optional string organization = 1;

        /* The values to downsample.
         * When multiple modems are given, the data is downsampled separately and merged together in the response,
         * sorted by time.
         */
        ValueSelection selection = 2;

        /* Downsample the values to the given amount of data points. */
        optional uint32 points = 3;

        /* Paginate the downsampled values, if needed. */
        optional Pagination pagination = 4;

        /* How to sort the downsampled values. */
        ListValues.Sort sort = 5;
    }

    message Response {
        repeated ValueContext downsampled_values = 1;
        Pagination.Result pagination = 2;
        Request request = 3;
    }
}