data_acquisition_store.proto

// Copyright (c) 2023 Boston Dynamics, Inc.  All rights reserved.
//
// Downloading, reproducing, distributing or otherwise using the SDK Software
// is subject to the terms and conditions of the Boston Dynamics Software
// Development Kit License (20191101-BDSDK-SL).

syntax = "proto3";

package bosdyn.api;

option java_outer_classname = "DataAcquisitionStoreProto";

import "bosdyn/api/data_chunk.proto";
import "google/protobuf/timestamp.proto";
import "bosdyn/api/header.proto";
import "bosdyn/api/image.proto";
import "bosdyn/api/data_acquisition.proto";

// A query parameter which filters the possible set of data identifiers to those
// which contain the same action/group names matching any of the names in the
// set of CaptureActionIds.
message ActionIdQuery {
    // The action ids to filter with.
    repeated CaptureActionId action_ids = 1;
}

// A query parameter which filters the possible set of data identifiers to
// those with timestamps within the specified range.
message TimeRangeQuery {
    // Start of the time range to query.
    google.protobuf.Timestamp from_timestamp = 1;

    // End of the time range to query.
    google.protobuf.Timestamp to_timestamp = 2;
}

// The message containing the different query parameters which can be applied to
// the ListData requests.
message DataQueryParams {
    oneof query {
        // Time range to query.
        TimeRangeQuery time_range = 1;

        // List of action ids to query.
        ActionIdQuery action_ids = 2;
    }

}

message QueryParameters {
    // Time range to query.
    TimeRangeQuery time_range = 1;

    // List of action ids to query. The constructed query statement will have an OR relation
    // between the action_ids specified in this list, with an AND relation for the fields inside
    // each action_id. For example, specifying
    // [{action_name="action1", group_name="group1"}, {action_name="action2", group_name="group2"}]
    // will insert the following in the WHERE part of the query:
    // (action_name="action1" AND group_name="group1") OR (action_name="action2" AND
    // group_name="group2").
    repeated CaptureActionId action_ids = 2;

    // Channels to include in the query results. The constructed query statement will have an OR
    // relation for all the channel values listed in this field.
    repeated string channels = 3;

    // Query for captures with id higher or equal to this value. Specifying 0 means that the
    // Data Acquisition Store will return all captured data it has. Otherwise, it will return new
    // captures stored with an id greater than the value specified in this field.
    uint64 captures_from_id = 4;

    // Setting this field to true only returns the DataIdentifiers in the response and not the
    // actual captures.
    bool only_include_identifiers = 5;

    // The following fields specify which capture types to include in the results. If none of the
    // following fields is specified, then all capture types will be included in the results.
    bool include_images = 6;
    bool include_data = 7;
    bool include_metadata = 8;
    bool include_alerts = 9;

    // Setting this value will return results that are classified as large data. If this value is
    // not set these captures will not be returned even when none of the other captures types are
    // set.
    bool include_large = 11;

    // Boolean that specifies how to order the query results based on capture id field, ascending
    // (default) or descending.
    // Ascending: Captures with lowest id are first, meaning oldest stored captures are ordered
    // first.
    // Descending: Captures with highest id are first, meaning newest stored captures are
    // ordered first.
    bool order_descending = 10;
}


message StoreImageRequest {
    // Common request header.
    RequestHeader header = 1;

    // Image to store.
    ImageCapture image = 2;

    // Data identifier of the image.
    DataIdentifier data_id = 3;
}

message StoreImageResponse {
    // Common response header.
    ResponseHeader header = 1;

    uint64 id = 2;
}

message StoreMetadataRequest {
    // Common request header.
    RequestHeader header = 1;

    // Metadata to store.
    AssociatedMetadata metadata = 2;

    // Data identifier of the metadata.
    DataIdentifier data_id = 3;
}

message StoreMetadataResponse {
    // Common response header.
    ResponseHeader header = 1;

    uint64 id = 2;
}

message StoreAlertDataRequest {
    // Common request header.
    RequestHeader header = 1;

    // AlertData to store.
    AssociatedAlertData alert_data = 2;

    // Data identifier of the alert.
    DataIdentifier data_id = 3;
}

message StoreAlertDataResponse {
    // Common response header.
    ResponseHeader header = 1;

    uint64 id = 2;
}

message StoreDataRequest {
    // Common request header.
    RequestHeader header = 1;

    // Data to store.
    bytes data = 2;

    // Data identifier of the data.
    DataIdentifier data_id = 3;

    // File extension to use when writing the data to file.
    string file_extension = 4;
}

message StoreDataResponse {
    // Common response header.
    ResponseHeader header = 1;

    uint64 id = 2;
}

message StoreStreamRequest {
    // Common request header.
    RequestHeader header = 1;

    // Data identifier of the data.
    DataIdentifier data_id = 2;

    // File extension to use when writing the data to file.
    string file_extension = 4;

    // The piece of the data to store.
    DataChunk chunk = 3;
}

message StoreStreamResponse {
    // Common response header.
    ResponseHeader header = 1;

    uint64 id = 2;
}

message ListCaptureActionsRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding action ids.
    DataQueryParams query = 2;
}

message ListCaptureActionsResponse {
    // Common response header.
    ResponseHeader header = 1;

    // List of action ids that satisfied the query parameters.
    repeated CaptureActionId action_ids = 2;
}

message ListStoredImagesRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding images.
    DataQueryParams query = 2;
}
message ListStoredImagesResponse {
    // Common response header.
    ResponseHeader header = 1;

    // List of image data identifiers that satisfied the query parameters.
    repeated DataIdentifier data_ids = 2;
}

message ListStoredMetadataRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding metadata.
    DataQueryParams query = 2;
}

message ListStoredMetadataResponse {
    // Common response header.
    ResponseHeader header = 1;

    // List of metadata data identifiers that satisfied the query parameters.
    repeated DataIdentifier data_ids = 2;
}

message ListStoredAlertDataRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding AlertData.
    DataQueryParams query = 2;
}

message ListStoredAlertDataResponse {
    // Common response header.
    ResponseHeader header = 1;

    // List of AlertData data identifiers that satisfied the query parameters.
    repeated DataIdentifier data_ids = 2;
}

message ListStoredDataRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding data.
    DataQueryParams query = 2;
}

message ListStoredDataResponse {
    // Common response header.
    ResponseHeader header = 1;

    // List of data identifiers that satisfied the query parameters.
    repeated DataIdentifier data_ids = 2;
}

message QueryStoredCapturesRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding data.
    QueryParameters query = 2;
}

message StoredCapturedData {
    bytes data = 1;

    // File extension to use for writing the data to a file.
    string file_extension = 2;
}

message StoredLargeCapturedData {
    // Data related to capture.
    DataChunk chunk = 1;

    // Start index of resulting bytes.
    uint64 offset = 2;

    // File extension to use for writing the data to a file.
    string file_extension = 3;

}
message QueryStoredCaptureResult {
    DataIdentifier data_id = 1;

    oneof result {
        ImageCapture image = 3;
        AssociatedMetadata metadata = 4;
        AssociatedAlertData alert_data = 5;
        StoredCapturedData data = 6;
        StoredLargeCapturedData large_data = 7;
    }
}

message QueryStoredCapturesResponse {
    // Common response header.
    ResponseHeader header = 1;

    // CaptureActionIds that match the query parameters and are included in the results.
    repeated CaptureActionId action_ids = 2;

    // Results that match the query parameters.
    repeated QueryStoredCaptureResult results = 3;

    // Max capture_id in the database matching the query parameters.
    uint64 max_capture_id = 4;
}

message QueryMaxCaptureIdRequest {
    // Common request header.
    RequestHeader header = 1;

    // Query parameters for finding data.
    QueryParameters query = 2;
}

message QueryMaxCaptureIdResponse {
    ResponseHeader header = 1;

    uint64 max_capture_id = 2;
}