refactor(api-server): Rename timestamp and results cache parameters for clarity. (y-scope#1886)

Co-authored-by: Lin Zhihao <59785146+LinZhihao-723@users.noreply.github.com>
Co-authored-by: Junhao Liao <junhao.liao@yscope.com>

Author: 3 people

components/api-server/src/client.rs

@@ -38,20 +38,21 @@ pub struct QueryConfig {
 
     /// The beginning timestamp (in epoch milliseconds) for the search range (inclusive).
     #[serde(default)]
-    pub begin_timestamp: Option<i64>,
+    pub time_range_begin_millisecs: Option<i64>,
 
     /// The ending timestamp (in epoch milliseconds) for the search range (inclusive).
     #[serde(default)]
-    pub end_timestamp: Option<i64>,
+    pub time_range_end_millisecs: Option<i64>,
 
     /// Whether the string match should be case-insensitive.
     #[serde(default)]
     pub ignore_case: bool,
 
-    /// Whether to write the search results to files. If `false`, results will be stored in
-    /// `MongoDB`.
+    /// Whether to buffer search results in `MongoDB`.
+    /// By default, search results are buffered in temporary files. When set to `true`, results
+    /// will be stored in `MongoDB` instead.
     #[serde(default)]
-    pub write_to_file: bool,
+    pub buffer_results_in_mongodb: bool,
 }
 
 impl From<QueryConfig> for SearchJobConfig {
@@ -60,10 +61,10 @@ impl From<QueryConfig> for SearchJobConfig {
             dataset: value.dataset,
             query_string: value.query_string,
             max_num_results: value.max_num_results,
-            begin_timestamp: value.begin_timestamp,
-            end_timestamp: value.end_timestamp,
+            begin_timestamp: value.time_range_begin_millisecs,
+            end_timestamp: value.time_range_end_millisecs,
             ignore_case: value.ignore_case,
-            write_to_file: value.write_to_file,
+            write_to_file: !value.buffer_results_in_mongodb,
             ..Default::default()
         }
     }

components/api-server/src/routes.rs

@@ -85,11 +85,11 @@ async fn health() -> String {
         example = json!({
             "query_string": "*",
             "dataset": "default",
-            "begin_timestamp": 0,
-            "end_timestamp": 17_356_896,
+            "time_range_begin_millisecs": 0,
+            "time_range_end_millisecs": 17_356_896,
             "ignore_case": true,
             "max_num_results": 0,
-            "write_to_file": false
+            "buffer_results_in_mongodb": true
         })),
     responses(
         (

docs/src/_static/generated/api-server-openapi.json

@@ -44,11 +44,11 @@
               "example": {
                 "query_string": "*",
                 "dataset": "default",
-                "begin_timestamp": 0,
-                "end_timestamp": 17356896,
+                "time_range_begin_millisecs": 0,
+                "time_range_end_millisecs": 17356896,
                 "ignore_case": true,
                 "max_num_results": 0,
-                "write_to_file": false
+                "buffer_results_in_mongodb": true
               }
             }
           },
@@ -119,13 +119,9 @@
           "query_string"
         ],
         "properties": {
-          "begin_timestamp": {
-            "type": [
-              "integer",
-              "null"
-            ],
-            "format": "int64",
-            "description": "The beginning timestamp (in epoch milliseconds) for the search range (inclusive)."
+          "buffer_results_in_mongodb": {
+            "type": "boolean",
+            "description": "Whether to buffer search results in `MongoDB`.\nBy default, search results are buffered in temporary files. When set to `true`, results\nwill be stored in `MongoDB` instead."
           },
           "dataset": {
             "type": [
@@ -134,14 +130,6 @@
             ],
             "description": "The dataset to search within. If not provided, only `default` dataset will be searched."
           },
-          "end_timestamp": {
-            "type": [
-              "integer",
-              "null"
-            ],
-            "format": "int64",
-            "description": "The ending timestamp (in epoch milliseconds) for the search range (inclusive)."
-          },
           "ignore_case": {
             "type": "boolean",
             "description": "Whether the string match should be case-insensitive."
@@ -156,9 +144,21 @@
             "type": "string",
             "description": "The search query as a KQL string."
           },
-          "write_to_file": {
-            "type": "boolean",
-            "description": "Whether to write the search results to files. If `false`, results will be stored in\n`MongoDB`."
+          "time_range_begin_millisecs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "The beginning timestamp (in epoch milliseconds) for the search range (inclusive)."
+          },
+          "time_range_end_millisecs": {
+            "type": [
+              "integer",
+              "null"
+            ],
+            "format": "int64",
+            "description": "The ending timestamp (in epoch milliseconds) for the search range (inclusive)."
           }
         },
         "additionalProperties": false

docs/src/user-docs/guides-using-the-api-server.md

@@ -35,7 +35,6 @@ following commands to submit a query to clp-json and stream the results.
           "dataset": "default",
           "ignore_case": false,
           "max_num_results": 100,
-          "write_to_file": false
        }'
    ```
 
@@ -57,11 +56,11 @@ following commands to submit a query to clp-json and stream the results.
    Example streamed output:
 
    ```text
-   data: {"timestamp": 1633036800, "message": "Example log message"}
+   data: {"timestamp": 1767225600000, "message": "Example log message"}
 
-   data: {"timestamp": 1633036810, "message": "Another matched log line"}
+   data: {"timestamp": 1767225600010, "message": "Another matched log line"}
 
-   data: {"timestamp": 1633036820, "message": "No logs found" }
+   data: {"timestamp": 1767225600020, "message": "No logs found" }
    ```
 
 [OpenAPI]: https://swagger.io/specification/