nexus: Remove TimeseriesKey from timeseries output

Our external API timeseries endpoints currently return data as a
`BTreeMap<TimeseriesKey, Timeseries>`, which results in JSON output
with arbitrary numeric keys that have no meaning to API consumers:

```json
{
  "timeseries": {
    "2352746367989923131": { ... },
    "3940108470521992408": { ... }
  }
}
```

This commit introduces a new `TableOutput` struct that presents
timeseries data as an array instead of a map. The `TableOutput` type is
converted from the internal `Table` representation at the API boundary,
preserving the ordering from the original `BTreeMap` while providing a
cleaner JSON structure:

```json
{
  "timeseries": [ { ... }, { ... } ]
}
```

Closes #8108

Author: wfchandler

nexus/src/external_api/http_entrypoints.rs

@@ -6571,7 +6571,11 @@ impl NexusExternalApi for NexusExternalApiImpl {
             nexus
                 .timeseries_query(&opctx, &query)
                 .await
-                .map(|tables| HttpResponseOk(views::OxqlQueryResult { tables }))
+                .map(|tables| {
+                    HttpResponseOk(views::OxqlQueryResult {
+                        tables: tables.into_iter().map(Into::into).collect(),
+                    })
+                })
                 .map_err(HttpError::from)
         };
         apictx
@@ -6598,7 +6602,11 @@ impl NexusExternalApi for NexusExternalApiImpl {
             nexus
                 .timeseries_query_project(&opctx, &project_lookup, &query)
                 .await
-                .map(|tables| HttpResponseOk(views::OxqlQueryResult { tables }))
+                .map(|tables| {
+                    HttpResponseOk(views::OxqlQueryResult {
+                        tables: tables.into_iter().map(Into::into).collect(),
+                    })
+                })
                 .map_err(HttpError::from)
         };
         apictx

nexus/tests/integration_tests/metrics.rs

@@ -270,7 +270,7 @@ async fn test_instance_watcher_metrics(
 
     #[track_caller]
     fn count_state(
-        table: &oxql_types::Table,
+        table: &oxql_types::TableOutput,
         instance_id: InstanceUuid,
         state: &'static str,
     ) -> Result<i64, MetricsNotYet> {

nexus/tests/integration_tests/metrics_querier.rs

@@ -93,7 +93,7 @@ impl<'a, N> MetricsQuerier<'a, N> {
         cond: F,
     ) -> T
     where
-        F: Fn(Vec<oxql_types::Table>) -> Result<T, MetricsNotYet>,
+        F: Fn(Vec<oxql_types::TableOutput>) -> Result<T, MetricsNotYet>,
     {
         self.timeseries_query_until("/v1/system/timeseries/query", query, cond)
             .await
@@ -108,7 +108,7 @@ impl<'a, N> MetricsQuerier<'a, N> {
         cond: F,
     ) -> T
     where
-        F: Fn(Vec<oxql_types::Table>) -> Result<T, MetricsNotYet>,
+        F: Fn(Vec<oxql_types::TableOutput>) -> Result<T, MetricsNotYet>,
     {
         self.timeseries_query_until(
             &format!("/v1/timeseries/query?project={project}"),
@@ -128,7 +128,7 @@ impl<'a, N> MetricsQuerier<'a, N> {
         &self,
         project: &str,
         query: &str,
-    ) -> Vec<oxql_types::Table> {
+    ) -> Vec<oxql_types::TableOutput> {
         self.project_timeseries_query_until(project, query, |tables| Ok(tables))
             .await
     }
@@ -270,7 +270,7 @@ impl<'a, N> MetricsQuerier<'a, N> {
         cond: F,
     ) -> T
     where
-        F: Fn(Vec<oxql_types::Table>) -> Result<T, MetricsNotYet>,
+        F: Fn(Vec<oxql_types::TableOutput>) -> Result<T, MetricsNotYet>,
     {
         let result = wait_for_condition(
             || async {
@@ -389,5 +389,5 @@ impl<'a, N> MetricsQuerier<'a, N> {
 
 enum TimeseriesQueryResult {
     TimeseriesNotFound,
-    Ok(Vec<oxql_types::Table>),
+    Ok(Vec<oxql_types::TableOutput>),
 }

nexus/types/src/external_api/views.rs

@@ -1117,7 +1117,7 @@ pub struct AllowList {
 #[derive(Clone, Debug, Deserialize, JsonSchema, Serialize)]
 pub struct OxqlQueryResult {
     /// Tables resulting from the query, each containing timeseries.
-    pub tables: Vec<oxql_types::Table>,
+    pub tables: Vec<oxql_types::TableOutput>,
 }
 
 // ALERTS

openapi/nexus.json

@@ -22275,7 +22275,7 @@
             "description": "Tables resulting from the query, each containing timeseries.",
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/Table"
+              "$ref": "#/components/schemas/TableOutput"
             }
           }
         },
@@ -25523,16 +25523,16 @@
           "vlan_id"
         ]
       },
-      "Table": {
-        "description": "A table represents one or more timeseries with the same schema.\n\nA table is the result of an OxQL query. It contains a name, usually the name of the timeseries schema from which the data is derived, and any number of timeseries, which contain the actual data.",
+      "TableOutput": {
+        "description": "A table represents one or more timeseries with the same schema.\n\nA table is the result of an OxQL query. It contains a name, usually the name of the timeseries schema from which the data is derived, and any number of timeseries, which contain the actual data. A table representation for external API responses.",
         "type": "object",
         "properties": {
           "name": {
             "type": "string"
           },
           "timeseries": {
-            "type": "object",
-            "additionalProperties": {
+            "type": "array",
+            "items": {
               "$ref": "#/components/schemas/Timeseries"
             }
           }

oximeter/oxql-types/src/lib.rs

@@ -11,6 +11,7 @@ pub mod point;
 pub mod table;
 
 pub use self::table::Table;
+pub use self::table::TableOutput;
 pub use self::table::Timeseries;
 
 /// Describes the time alignment for an OxQL query.

oximeter/oxql-types/src/table.rs

@@ -360,3 +360,61 @@ impl Table {
         }
     }
 }
+
+/// A table represents one or more timeseries with the same schema.
+///
+/// A table is the result of an OxQL query. It contains a name, usually the name
+/// of the timeseries schema from which the data is derived, and any number of
+/// timeseries, which contain the actual data.
+//
+// # Motivation
+//
+// This struct is derived from [`Table`] but presents timeseries data as a `Vec`
+// rather than a map keyed by [`TimeseriesKey`]. This provides a cleaner JSON
+// representation for external consumers, as these numeric keys are ephemeral
+// identifiers that have no meaning to API consumers. Key ordering is retained
+// as this is contructed from the already sorted values present in [`Table`].
+//
+// When serializing a [`Table`] to JSON, the `BTreeMap<TimeseriesKey, Timeseries>`
+// structure produces output with numeric keys like:
+// ```json
+// {
+//   "timeseries": {
+//     "2352746367989923131": { ... },
+//     "3940108470521992408": { ... }
+//   }
+// }
+// ```
+//
+// `TableOutput` instead serializes timeseries as an array:
+// ```json
+// {
+//   "timeseries": [ { ... }, { ... } ]
+// }
+// ```
+#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+pub struct TableOutput {
+    // The name of the table.
+    pub name: String,
+    // The set of timeseries in the table, ordered by key.
+    timeseries: Vec<Timeseries>,
+}
+
+impl From<Table> for TableOutput {
+    fn from(table: Table) -> Self {
+        let timeseries: Vec<_> = table.timeseries.into_values().collect();
+        TableOutput { name: table.name, timeseries }
+    }
+}
+
+impl TableOutput {
+    /// Return the name of the table.
+    pub fn name(&self) -> &str {
+        self.name.as_str()
+    }
+
+    /// Return the list of timeseries in this table, ordered by key.
+    pub fn timeseries(&self) -> impl ExactSizeIterator<Item = &Timeseries> {
+        self.timeseries.iter()
+    }
+}