refactor(api-server): Rename timestamp and results cache parameters for clarity. by hoophalab · Pull Request #1886 · y-scope/clp

hoophalab · 2026-01-19T19:04:48Z

…or clarity.

Description

This PR renames some parameters of the API server.

Checklist

The PR satisfies the contribution guidelines.
This is a breaking change and that has been indicated in the PR title, OR this isn't a
breaking change.
Necessary docs have been updated, OR no docs need to be updated.

Validation performed

All parameters still works.

Summary by CodeRabbit

Refactor
- Clarified API parameter names for time-range boundaries and renamed the result-buffering option to more explicitly indicate when results are stored in the database.
Documentation
- Updated API examples and user guide samples to reflect the new parameter naming, adjusted example timestamps, and show the new buffering behaviour in examples.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1212888442466800
- https://app.asana.com/0/0/1212888418564493

…or clarity.

coderabbitai · 2026-01-19T19:04:58Z

Walkthrough

Replaces begin_timestamp/end_timestamp with time_range_begin_millisecs/time_range_end_millisecs and renames write_to_file to buffer_results_in_mongodb on QueryConfig; updates the From<QueryConfig> for SearchJobConfig mapping (inverts buffer flag) and updates OpenAPI and docs examples accordingly.

Changes

Cohort / File(s)	Summary
QueryConfig changes `components/api-server/src/client.rs`	Added public fields `time_range_begin_millisecs: Option<i64>` and `time_range_end_millisecs: Option<i64>`; renamed `write_to_file` → `buffer_results_in_mongodb: bool` and updated documentation. Updated `impl From<QueryConfig> for SearchJobConfig` to map the new timestamp fields and compute `write_to_file = !buffer_results_in_mongodb`.
OpenAPI example update `components/api-server/src/routes.rs`	Replaced example request fields `begin_timestamp`/`end_timestamp` → `time_range_begin_millisecs`/`time_range_end_millisecs`, and `write_to_file` → `buffer_results_in_mongodb` in the POST /query OpenAPI example.
User docs example update `docs/src/user-docs/guides-using-the-api-server.md`	Updated example payload to remove `write_to_file`, add `buffer_results_in_mongodb`, and adjusted SSE example timestamps.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main changes: renaming timestamp fields (begin_timestamp → time_range_begin_millisecs, end_timestamp → time_range_end_millisecs) and results cache parameters (write_to_file → buffer_results_in_mongodb) across the API server codebase for improved clarity.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In `@components/api-server/src/client.rs`:
- Around line 51-54: The docstring for the struct field
buffer_results_in_mongodb (in client.rs) is contradictory — it currently says
“write the search results to files” but also says true stores results in
MongoDB; update the comment to accurately describe behavior (e.g., “Whether to
buffer/search results in MongoDB; if true, results are stored in MongoDB,
otherwise not”) so it clearly reflects that buffer_results_in_mongodb==true
writes results to MongoDB, and keep serde(default) behavior note if needed.
- Around line 63-66: The refactor inverted write_to_file ->
buffer_results_in_mongodb and unintentionally flipped the default for omitted
requests; update the deserialization for the input struct that contains
buffer_results_in_mongodb (the field used to set write_to_file:
!value.buffer_results_in_mongodb) so that the default preserves buffering to
MongoDB. Either add a serde default (e.g. #[serde(default = "default_true")] on
buffer_results_in_mongodb and implement default_true() -> bool { true }) or
change buffer_results_in_mongodb to Option<bool> and treat None as true when
computing write_to_file in the code path that constructs
begin_timestamp/end_timestamp/ignore_case/write_to_file. Ensure the change
targets the struct definition that defines buffer_results_in_mongodb and the
code that sets write_to_file: !value.buffer_results_in_mongodb.

In `@components/api-server/src/routes.rs`:
- Around line 85-93: Update the OpenAPI/example JSON so the
time_range_begin_millisecs and time_range_end_millisecs fields use 13‑digit
epoch millisecond values (not small integers that look like seconds); locate the
json!({...}) assigned to example in routes.rs and replace the values for
"time_range_begin_millisecs" and "time_range_end_millisecs" with proper epoch-ms
timestamps (e.g., 13‑digit integers consistent with your SSE sample) so the
example accurately reflects milliseconds.

coderabbitai · 2026-01-19T19:11:09Z

+            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,


⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

cd components/api-server/src && head -80 client.rs | tail -30

Repository: y-scope/clp

Length of output: 936

🏁 Script executed:

wc -l components/api-server/src/client.rs

Repository: y-scope/clp

Length of output: 94

🏁 Script executed:

cat -n components/api-server/src/client.rs | sed -n '50,80p'

Repository: y-scope/clp

Length of output: 1154

🏁 Script executed:

rg "buffer_results_in_mongodb" components/api-server/src/client.rs -A 2 -B 2

Repository: y-scope/clp

Length of output: 349

🏁 Script executed:

rg "struct.*Request" components/api-server/src/client.rs -A 20 | head -50

Repository: y-scope/clp

Length of output: 37

🏁 Script executed:

rg "struct SearchJobConfig" components/api-server/src/client.rs -A 30

Repository: y-scope/clp

Length of output: 37

🏁 Script executed:

rg "write_to_file" components/api-server/src/client.rs -B 2 -A 2

Repository: y-scope/clp

Length of output: 516

🏁 Script executed:

rg "write_to_file" components/api-server/ -l

Repository: y-scope/clp

Length of output: 90

🏁 Script executed:

rg "struct SearchJobConfig" components/ -A 20

Repository: y-scope/clp

Length of output: 1820

🏁 Script executed:

fd -e rs -path "*" | xargs grep -l "struct SearchJobConfig" 2>/dev/null

Repository: y-scope/clp

Length of output: 225

🏁 Script executed:

cat -n components/clp-rust-utils/src/job_config/search.rs | sed -n '1,50p'

Repository: y-scope/clp

Length of output: 1875

🏁 Script executed:

rg "#\[derive" components/clp-rust-utils/src/job_config/search.rs -A 1 | head -20

Repository: y-scope/clp

Length of output: 368

🏁 Script executed:

rg "impl.*Default.*SearchJobConfig" components/clp-rust-utils/src/job_config/search.rs -A 20

Repository: y-scope/clp

Length of output: 37

🏁 Script executed:

git -C components/ log --oneline --all -- "*client.rs" | head -20

Repository: y-scope/clp

Length of output: 285

🏁 Script executed:

rg "buffer_results_in_mongodb" components/ -B 3 -A 3

Repository: y-scope/clp

Length of output: 1516

🏁 Script executed:

git log --oneline --all -S "write_to_file" -- "components/" | head -10

Repository: y-scope/clp

Length of output: 285

🏁 Script executed:

cat -n components/api-server/src/client.rs | sed -n '45,70p'

Repository: y-scope/clp

Length of output: 1085

🏁 Script executed:

rg "QueryConfig" components/api-server/src/client.rs -B 5 -A 10 | head -60

Repository: y-scope/clp

Length of output: 2024

🏁 Script executed:

git log --all -p -- components/api-server/src/client.rs | grep -A 20 -B 5 "buffer_results_in_mongodb" | head -100

Repository: y-scope/clp

Length of output: 1242

🏁 Script executed:

git show 278ca3c:components/api-server/src/client.rs 2>/dev/null | grep -A 10 -B 5 "buffer_results_in_mongodb"

Repository: y-scope/clp

Length of output: 927

🏁 Script executed:

git log --all --oneline -- components/api-server/src/client.rs

Repository: y-scope/clp

Length of output: 285

🏁 Script executed:

git log --all --format="%H %ai" -- components/api-server/src/client.rs | head -5

Repository: y-scope/clp

Length of output: 188

🏁 Script executed:

git show 278ca3c^:components/api-server/src/client.rs 2>/dev/null | grep -A 15 "write_to_file"

Repository: y-scope/clp

Length of output: 37

🏁 Script executed:

git show 278ca3c^ -- components/api-server/src/client.rs 2>/dev/null | head -100

Repository: y-scope/clp

Length of output: 37

🏁 Script executed:

git log --all --diff-filter=A -- components/api-server/src/client.rs

Repository: y-scope/clp

Length of output: 664

🏁 Script executed:

git show ff6f76a:components/api-server/src/client.rs 2>/dev/null | grep -A 15 "write_to_file"

Repository: y-scope/clp

Length of output: 1501

🏁 Script executed:

git show 278ca3c:components/api-server/src/client.rs 2>/dev/null | grep -B 10 -A 5 "write_to_file\|QueryConfig"

Repository: y-scope/clp

Length of output: 2869

🏁 Script executed:

git show ff6f76a:components/api-server/src/client.rs 2>/dev/null | grep -B 5 -A 15 "pub struct QueryConfig"

Repository: y-scope/clp

Length of output: 775

🏁 Script executed:

git diff 278ca3c ff6f76a -- components/api-server/src/client.rs | grep -A 10 -B 10 "buffer_results\|write_to_file"

Repository: y-scope/clp

Length of output: 1195

🏁 Script executed:

git show ff6f76a:components/api-server/src/client.rs 2>/dev/null | grep -A 50 "pub struct QueryConfig" | tail -30

Repository: y-scope/clp

Length of output: 923

Confirm default behaviour when the field is omitted—this refactoring changed the default.

The refactoring from write_to_file: bool to buffer_results_in_mongodb: bool with inversion (!value.buffer_results_in_mongodb) flipped the default behaviour. Previously, the omitted field defaulted to write_to_file: false (buffering to MongoDB); now it defaults to buffer_results_in_mongodb: false, making write_to_file: true (writing to files).

This is a breaking change for callers that omit the field. To preserve the MongoDB-buffering default, either set #[serde(default = "default_true")] on buffer_results_in_mongodb or use Option<bool> to handle the case explicitly.

Example of preserving MongoDB default

+fn default_true() -> bool { true } + /// Defines the request configuration for submitting a search query. @@ - #[serde(default)] + #[serde(default = "default_true")] pub buffer_results_in_mongodb: bool,

🤖 Prompt for AI Agents

In `@components/api-server/src/client.rs` around lines 63 - 66, The refactor inverted write_to_file -> buffer_results_in_mongodb and unintentionally flipped the default for omitted requests; update the deserialization for the input struct that contains buffer_results_in_mongodb (the field used to set write_to_file: !value.buffer_results_in_mongodb) so that the default preserves buffering to MongoDB. Either add a serde default (e.g. #[serde(default = "default_true")] on buffer_results_in_mongodb and implement default_true() -> bool { true }) or change buffer_results_in_mongodb to Option<bool> and treat None as true when computing write_to_file in the code path that constructs begin_timestamp/end_timestamp/ignore_case/write_to_file. Ensure the change targets the struct definition that defines buffer_results_in_mongodb and the code that sets write_to_file: !value.buffer_results_in_mongodb.

yes. This is intended.

@hoophalab, understood—thank you for confirming the default behavior change is intentional. I've noted this for future reference.

✏️ Learnings added

Learnt from: hoophalab Repo: y-scope/clp PR: 1886 File: components/api-server/src/client.rs:63-66 Timestamp: 2026-01-19T19:28:08.087Z Learning: In `components/api-server/src/client.rs`, the refactoring from `write_to_file` to `buffer_results_in_mongodb` intentionally changed the default behavior: when the field is omitted, the system now defaults to writing results to files (`write_to_file: true`) instead of buffering to MongoDB. This breaking change was a deliberate design decision.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

It might be better if we rename write_to_file to buffer_results_in_mongodb as well. The reason to rename the API is because write_to_file is not descriptive and sounds confusing, which is arguably the same when appearing as a struct member.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

coderabbitai · 2026-01-19T19:11:09Z

        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
        })),


⚠️ Potential issue | 🟡 Minor

Use epoch‑millis values in the OpenAPI example.

Line 88–89 shows small values that read like seconds, but the field name is explicitly in milliseconds. Consider using 13‑digit epoch‑ms values to avoid confusion and align with the docs SSE sample.

Proposed example update

- "time_range_begin_millisecs": 0, - "time_range_end_millisecs": 17_356_896, + "time_range_begin_millisecs": 1_767_225_600_000, + "time_range_end_millisecs": 1_767_225_600_020,

🤖 Prompt for AI Agents

In `@components/api-server/src/routes.rs` around lines 85 - 93, Update the OpenAPI/example JSON so the time_range_begin_millisecs and time_range_end_millisecs fields use 13‑digit epoch millisecond values (not small integers that look like seconds); locate the json!({...}) assigned to example in routes.rs and replace the values for "time_range_begin_millisecs" and "time_range_end_millisecs" with proper epoch-ms timestamps (e.g., 13‑digit integers consistent with your SSE sample) so the example accurately reflects milliseconds.

junhaoliao

lgtm

let's wait for @LinZhihao-723 's review before merging

LinZhihao-723 · 2026-01-20T20:12:41Z

+            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,


It might be better if we rename write_to_file to buffer_results_in_mongodb as well. The reason to rename the API is because write_to_file is not descriptive and sounds confusing, which is arguably the same when appearing as a struct member.

Co-authored-by: Lin Zhihao <59785146+LinZhihao-723@users.noreply.github.com>

coderabbitai

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@components/api-server/src/client.rs`:
- Around line 39-45: The struct fields time_range_begin_millisecs and
time_range_end_millisecs currently only accept the new names and will break
clients sending legacy begin_timestamp / end_timestamp when
#[serde(deny_unknown_fields)] is used; add serde aliases to each field (e.g.,
add #[serde(alias = "begin_timestamp")] to time_range_begin_millisecs and
#[serde(alias = "end_timestamp")] to time_range_end_millisecs) so incoming JSON
using the old names continues to deserialize during a deprecation window while
keeping the new field names as primary.

coderabbitai · 2026-01-21T04:21:49Z

    /// 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>,


🧹 Nitpick | 🔵 Trivial

Consider serde aliases to keep legacy field names working.

With #[serde(deny_unknown_fields)], clients still sending begin_timestamp / end_timestamp will now be rejected. If you want a deprecation window, add aliases; otherwise confirm the breaking change is versioned and communicated.

♻️ Suggested compatibility tweak

- #[serde(default)] + #[serde(default, alias = "begin_timestamp")] pub time_range_begin_millisecs: Option<i64>, - #[serde(default)] + #[serde(default, alias = "end_timestamp")] pub time_range_end_millisecs: Option<i64>,

🤖 Prompt for AI Agents

In `@components/api-server/src/client.rs` around lines 39 - 45, The struct fields time_range_begin_millisecs and time_range_end_millisecs currently only accept the new names and will break clients sending legacy begin_timestamp / end_timestamp when #[serde(deny_unknown_fields)] is used; add serde aliases to each field (e.g., add #[serde(alias = "begin_timestamp")] to time_range_begin_millisecs and #[serde(alias = "end_timestamp")] to time_range_end_millisecs) so incoming JSON using the old names continues to deserialize during a deprecation window while keeping the new field names as primary.

hoophalab · 2026-01-21T16:18:33Z

It might be better if we rename write_to_file to buffer_results_in_mongodb as well. The reason to rename the API is because write_to_file is not descriptive and sounds confusing, which is arguably the same when appearing as a struct member.

This would require changing python definitions and query task code, and can be very erroneous. is this really necessary?

LinZhihao-723 · 2026-01-21T21:16:25Z

It might be better if we rename write_to_file to buffer_results_in_mongodb as well. The reason to rename the API is because write_to_file is not descriptive and sounds confusing, which is arguably the same when appearing as a struct member.

This would require changing python definitions and query task code, and can be very erroneous. is this really necessary?

Sure, we can defer that. Shall we create an issue to keep track of this?

LinZhihao-723

I don't have any more questions and hand it over to @junhaoliao
Don't forget to create the issue before merging.

hoophalab · 2026-01-22T00:26:07Z

@CodeRabbit Can you create an issue on this?

It might be better if we rename write_to_file to buffer_results_in_mongodb as well. The reason to rename the API is because write_to_file is not descriptive and sounds confusing, which is arguably the same when appearing as a struct member.

This would require changing python definitions and query task code, and can be very erroneous. is this really necessary?

Sure, we can defer that. Shall we create an issue to keep track of this?

coderabbitai · 2026-01-22T00:27:05Z

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

@hoophalab, I'll create an issue to track this refactoring task.

🏁 Script executed:

#!/bin/bash

# Create a GitHub issue to track the deferred refactoring
gh issue create \
  --title "Refactor: Rename internal write_to_file to buffer_results_in_mongodb" \
  --body "## Context

As discussed in PR `#1886` (https://github.com/y-scope/clp/pull/1886), we deferred renaming the internal \`write_to_file\` struct member to \`buffer_results_in_mongodb\` to match the API parameter rename.

## Rationale

The name \`write_to_file\` is not descriptive and sounds confusing, both as an API parameter and as a struct member. The API parameter has been renamed to \`buffer_results_in_mongodb\` for clarity, and the internal struct member should follow suit for consistency.

## Scope

This refactoring requires changes to:
- Python definitions
- Query task code

This change may be error-prone and requires careful testing.

## References

- PR `#1886`: https://github.com/y-scope/clp/pull/1886
- Requested by: `@hoophalab`" \
  --assignee hoophalab

Length of output: 42

@hoophalab, I've created issue #1890 to track this refactoring task: #1890

The issue includes the context from your discussion, the rationale for the change, and notes that it requires changes to Python definitions and query task code. I've assigned it to you as well.

🧠 Learnings used

Learnt from: hoophalab
Repo: y-scope/clp PR: 1886
File: components/api-server/src/client.rs:63-66
Timestamp: 2026-01-19T19:28:12.178Z
Learning: In `components/api-server/src/client.rs`, the refactoring from `write_to_file` to `buffer_results_in_mongodb` intentionally changed the default behavior: when the field is omitted, the system now defaults to writing results to files (`write_to_file: true`) instead of buffering to MongoDB. This breaking change was a deliberate design decision.

…or 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>

refactor(api-server): Rename timestamp and results cache parameters f…

278ca3c

…or clarity.

hoophalab requested a review from a team as a code owner January 19, 2026 19:04

coderabbitai Bot reviewed Jan 19, 2026

View reviewed changes

comment

1eb2c6a

hoophalab requested review from LinZhihao-723 and junhaoliao January 19, 2026 19:35

junhaoliao previously approved these changes Jan 19, 2026

View reviewed changes

junhaoliao added this to the Backlog milestone Jan 19, 2026

codegen

6ac402d

hoophalab dismissed junhaoliao’s stale review via 6ac402d January 20, 2026 01:16

LinZhihao-723 requested changes Jan 20, 2026

View reviewed changes

Update components/api-server/src/client.rs

d83ac60

Co-authored-by: Lin Zhihao <59785146+LinZhihao-723@users.noreply.github.com>

coderabbitai Bot reviewed Jan 21, 2026

View reviewed changes

junhaoliao modified the milestones: Backlog, February 2026 Jan 21, 2026

codegen

7d8685c

LinZhihao-723 approved these changes Jan 21, 2026

View reviewed changes

junhaoliao self-requested a review January 22, 2026 00:18

junhaoliao approved these changes Jan 22, 2026

View reviewed changes

Merge branch 'main' into apirename

af54bc1

coderabbitai Bot mentioned this pull request Jan 22, 2026

Refactor: Rename internal write_to_file to buffer_results_in_mongodb #1890

Open

Merge branch 'main' into apirename

87736ba

hoophalab merged commit 4058572 into y-scope:main Jan 22, 2026
22 checks passed

junhaoliao modified the milestones: February 2026, January 2026 Jan 23, 2026

Conversation

hoophalab commented Jan 19, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Validation performed

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hoophalab Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

LinZhihao-723 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

junhaoliao left a comment

Choose a reason for hiding this comment

Uh oh!

LinZhihao-723 Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

coderabbitai Bot Jan 21, 2026

Choose a reason for hiding this comment

Uh oh!

hoophalab commented Jan 21, 2026

Uh oh!

LinZhihao-723 commented Jan 21, 2026

Uh oh!

LinZhihao-723 left a comment

Choose a reason for hiding this comment

Uh oh!

hoophalab commented Jan 22, 2026

Uh oh!

coderabbitai Bot commented Jan 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hoophalab commented Jan 19, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jan 19, 2026 •

edited

Loading

coderabbitai Bot Jan 19, 2026 •

edited

Loading