Unify pagination and intervals

apis/datasets/v1/core.proto

@@ -21,38 +21,11 @@
 // https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp
 import "google/protobuf/timestamp.proto";
 import "tilebox/v1/id.proto";
+import "tilebox/v1/query.proto";
 
 option features.(pb.go).api_level = API_OPAQUE;
 option features.field_presence = IMPLICIT;
 
-// A time interval
-message TimeInterval {
-  google.protobuf.Timestamp start_time = 1; // Start time of the interval.
-  google.protobuf.Timestamp end_time = 2; // End time of the interval.
-
-  // We use exclusive for start and inclusive for end, because that way when both are false
-  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
-  // Flag indicating whether the start time is exclusive. If true, the start time is not included in the interval.
-  bool start_exclusive = 3;
-  // Flag indicating whether the end time is inclusive. If true, the end time is included in the interval.
-  bool end_inclusive = 4;
-}
-
-// A datapoint interval
-message DatapointInterval {
-  tilebox.v1.ID start_id = 1; // The id of the first data point in the interval.
-  tilebox.v1.ID end_id = 2; // The id of the last data point in the interval.
-
-  // We use exclusive for start and inclusive for end, because that way when both are false
-  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
-  // Flag indicating whether the start id is exclusive.
-  // If true, the datapoint with the given start id is not included in the interval.
-  bool start_exclusive = 3;
-  // Flag indicating whether the end id is inclusive.
-  // If true, the datapoint with the given end id is included in the interval.
-  bool end_inclusive = 4;
-}
-
 // LegacyPagination - used for backwards compatibility, will be removed as soon as all datasets are migrated
 message LegacyPagination {
   // The maximum number of entries to return.
@@ -62,15 +35,6 @@
   string starting_after = 2 [features.field_presence = EXPLICIT];
 }
 
-// Pagination information for paginated queries
-message Pagination {
-  // The maximum number of entries to return.
-  int64 limit = 1 [features.field_presence = EXPLICIT];
-  // Return entries starting after this entry.
-  // This is the id of the last entry returned in the previous page as the next parameter in each paginated query.
-  tilebox.v1.ID starting_after = 2 [features.field_presence = EXPLICIT];
-}
-
 // Any is a message that can hold any other message as bytes.
 // We don't use google.protobuf.Any because we want the JSON representation of the value field to be bytes.
 message Any {
@@ -128,7 +92,7 @@
 // CollectionInfo contains information about the data available in a dataset collection
 message CollectionInfo {
   Collection collection = 1;
-  TimeInterval availability = 2 [features.field_presence = EXPLICIT]; // The time interval for which data is available.
+  tilebox.v1.TimeInterval availability = 2 [features.field_presence = EXPLICIT]; // The time interval for which data is available.
   uint64 count = 3 [features.field_presence = EXPLICIT]; // Number of entries in the dataset.
 }
 

apis/datasets/v1/data_access.proto

@@ -8,6 +8,7 @@
 import "datasets/v1/well_known_types.proto";
 import "google/protobuf/go_features.proto";
 import "tilebox/v1/id.proto";
+import "tilebox/v1/query.proto";
 
 option features.(pb.go).api_level = API_OPAQUE;
 option features.field_presence = IMPLICIT;
@@ -18,8 +19,8 @@
   string collection_id = 1; // The collection id.
 
   // Either time interval or datapoint interval must be set, but not both.
-  TimeInterval time_interval = 2; // The time interval for which data is requested.
-  DatapointInterval datapoint_interval = 6; // The datapoint interval for which data is requested.
+  tilebox.v1.TimeInterval time_interval = 2; // The time interval for which data is requested.
+  tilebox.v1.IDInterval datapoint_interval = 6; // The datapoint interval for which data is requested.
 
   LegacyPagination page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for this request.
   bool skip_data = 4; // If true, the datapoint data is not returned.
@@ -48,8 +49,8 @@
 message QueryFilters {
   // Either a time interval or datapoint interval must be set, but not both.
   oneof temporal_extent {
-    TimeInterval time_interval = 1;
-    DatapointInterval datapoint_interval = 2;
+    tilebox.v1.TimeInterval time_interval = 1;
+    tilebox.v1.IDInterval datapoint_interval = 2;
   }
 
   SpatialFilter spatial_extent = 3;
@@ -82,14 +83,14 @@
   repeated tilebox.v1.ID collection_ids = 1; // collection ids to query.
   QueryFilters filters = 2; // Filters to apply to the query.
 
-  Pagination page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for this request.
+  tilebox.v1.Pagination page = 3 [features.field_presence = EXPLICIT]; // The pagination parameters for this request.
   bool skip_data = 4; // If true, only datapoint metadata, such as id, time and ingestion_time are returned.
 }
 
 // QueryResultPage is a single page of data points of a Tilebox dataset
 message QueryResultPage {
   RepeatedAny data = 1; // The datapoints.
-  Pagination next_page = 2 [features.field_presence = EXPLICIT]; // The pagination parameters for the next page.
+  tilebox.v1.Pagination next_page = 2 [features.field_presence = EXPLICIT]; // The pagination parameters for the next page.
 }
 
 // DataAccessService provides data access and querying capabilities for Tilebox datasets.

apis/datasets/v1/timeseries.proto

@@ -4,10 +4,10 @@
 
 package datasets.v1;
 
-import "datasets/v1/core.proto";
 import "google/protobuf/duration.proto";
 import "google/protobuf/go_features.proto";
 import "tilebox/v1/id.proto";
+import "tilebox/v1/query.proto";
 
 option features.(pb.go).api_level = API_OPAQUE;
 option features.field_presence = IMPLICIT;
@@ -17,8 +17,8 @@
 message TimeseriesDatasetChunk {
   tilebox.v1.ID dataset_id = 1;
   tilebox.v1.ID collection_id = 2;
-  TimeInterval time_interval = 3;
-  DatapointInterval datapoint_interval = 4;
+  tilebox.v1.TimeInterval time_interval = 3;
+  tilebox.v1.IDInterval datapoint_interval = 4;
   int32 branch_factor = 5;
   int32 chunk_size = 6;
   int64 datapoints_per_365_days = 7;
@@ -29,6 +29,6 @@
 // e.g. for a time interval of 100 days, and a chunk size of 1 day, such a workflow will spawn a tree of
 // eventually 100 leaf tasks
 message TimeChunk {
-  TimeInterval time_interval = 1;
+  tilebox.v1.TimeInterval time_interval = 1;
   google.protobuf.Duration chunk_size = 2;
 }

apis/tilebox/v1/query.proto

@@ -0,0 +1,51 @@
+edition = "2023";
+
+package tilebox.v1;
+
+import "google/protobuf/go_features.proto";
+import "google/protobuf/timestamp.proto";
+import "tilebox/v1/id.proto";
+
+option features.(pb.go).api_level = API_OPAQUE;
+option features.field_presence = IMPLICIT;
+
+// A time interval
+message TimeInterval {
+  // Start time of the interval.
+  google.protobuf.Timestamp start_time = 1;
+  // End time of the interval.
+  google.protobuf.Timestamp end_time = 2;
+
+  // We use exclusive for start and inclusive for end, because that way when both are false
+  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
+  // Flag indicating whether the start time is exclusive. If true, the start time is not included in the interval.
+  bool start_exclusive = 3;
+  // Flag indicating whether the end time is inclusive. If true, the end time is included in the interval.
+  bool end_inclusive = 4;
+}
+
+// An ID interval
+message IDInterval {
+  // The id of the first data point in the interval.
+  tilebox.v1.ID start_id = 1;
+  // The id of the last data point in the interval.
+  tilebox.v1.ID end_id = 2;
+
+  // We use exclusive for start and inclusive for end, because that way when both are false
+  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
+  // Flag indicating whether the start id is exclusive.
+  // If true, the datapoint with the given start id is not included in the interval.
+  bool start_exclusive = 3;
+  // Flag indicating whether the end id is inclusive.
+  // If true, the datapoint with the given end id is included in the interval.
+  bool end_inclusive = 4;
+}
+
+// Pagination information for paginated queries
+message Pagination {
+  // The maximum number of entries to return.
+  int64 limit = 1 [features.field_presence = EXPLICIT];
+  // Return entries starting after this entry.
+  // This is the id of the last entry returned in the previous page as the next parameter in each paginated query.
+  tilebox.v1.ID starting_after = 2 [features.field_presence = EXPLICIT];
+}

apis/workflows/v1/core.proto

@@ -115,40 +115,3 @@ message TaskLease {
   google.protobuf.Duration lease = 1;
   google.protobuf.Duration recommended_wait_until_next_extension = 2;
 }
-
-// A time interval
-message TimeInterval {
-  google.protobuf.Timestamp start_time = 1; // Start time of the interval.
-  google.protobuf.Timestamp end_time = 2; // End time of the interval.
-
-  // We use exclusive for start and inclusive for end, because that way when both are false
-  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
-  // Flag indicating whether the start time is exclusive. If true, the start time is not included in the interval.
-  bool start_exclusive = 3;
-  // Flag indicating whether the end time is inclusive. If true, the end time is included in the interval.
-  bool end_inclusive = 4;
-}
-
-// An ID interval
-message IDInterval {
-  tilebox.v1.ID start_id = 1; // The id of the first data point in the interval.
-  tilebox.v1.ID end_id = 2; // The id of the last data point in the interval.
-
-  // We use exclusive for start and inclusive for end, because that way when both are false
-  // we have a half-open interval [start, end) which is the default behaviour we want to achieve.
-  // Flag indicating whether the start id is exclusive.
-  // If true, the datapoint with the given start id is not included in the interval.
-  bool start_exclusive = 3;
-  // Flag indicating whether the end id is inclusive.
-  // If true, the datapoint with the given end id is included in the interval.
-  bool end_inclusive = 4;
-}
-
-// Pagination information for paginated queries
-message Pagination {
-  // The maximum number of entries to return.
-  int64 limit = 1 [features.field_presence = EXPLICIT];
-  // Return entries starting after this entry.
-  // This is the id of the last entry returned in the previous page as the next parameter in each paginated query.
-  tilebox.v1.ID starting_after = 2 [features.field_presence = EXPLICIT];
-}

apis/workflows/v1/job.proto

@@ -6,6 +6,7 @@ package workflows.v1;
 
 import "google/protobuf/go_features.proto";
 import "tilebox/v1/id.proto";
+import "tilebox/v1/query.proto";
 import "workflows/v1/core.proto";
 import "workflows/v1/diagram.proto";
 
@@ -81,8 +82,8 @@ message VisualizeJobRequest {
 message QueryFilters {
   // Either a time interval or ID interval must be set, but not both.
   oneof temporal_extent {
-    TimeInterval time_interval = 1;
-    IDInterval id_interval = 2;
+    tilebox.v1.TimeInterval time_interval = 1;
+    tilebox.v1.IDInterval id_interval = 2;
   }
 
   // Filter jobs by automation id.
@@ -94,15 +95,15 @@ message QueryJobsRequest {
   // Filters to apply to the query.
   QueryFilters filters = 1;
   // The pagination parameters for this request.
-  Pagination page = 2 [features.field_presence = EXPLICIT];
+  tilebox.v1.Pagination page = 2 [features.field_presence = EXPLICIT];
 }
 
 // A list of jobs.
 message QueryJobsResponse {
   // The jobs.
   repeated Job jobs = 1;
   // The pagination parameters for the next page.
-  Pagination next_page = 3 [features.field_presence = EXPLICIT];
+  tilebox.v1.Pagination next_page = 3 [features.field_presence = EXPLICIT];
 }
 
 // GetJobPrototypeRequest requests a clone prototype of a job.