Skip to content

chore(query-runs): clarify user_public_id documentation #103

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zfarrell merged 2 commits into from
Jul 30, 2026
+12 −29
Merged

chore(query-runs): clarify user_public_id documentation #103

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e8ddedb
chore(query-runs): clarify user_public_id documentation
hotdata-automation[bot] Jul 30, 2026
a3ad306
docs(changelog): describe user_public_id change for callers
zfarrell Jul 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- `QueryRunInfo::user_public_id` now reports the caller's stable account id (the
access token's subject) instead of a fingerprint of the bearer token, which
churned every few minutes as short-lived JWTs were reminted. Grouping a
caller's query history by this field now holds across token refreshes. A
request that carries no verified subject still records an opaque
`user_`-prefixed fingerprint — stable for that credential, but not resolvable
to an account. This is a server-side change; the SDK only carries the field.
- feat(databases): add search parameter to list endpoint

## [0.10.0] - 2026-07-23
Expand Down
2 changes: 1 addition & 1 deletion docs/QueryApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Name | Type | Description | Required | Notes

### Authorization

[WorkspaceId](../README.md#WorkspaceId), [SessionId](../README.md#SessionId), [BearerAuth](../README.md#BearerAuth)
[WorkspaceId](../README.md#WorkspaceId), [BearerAuth](../README.md#BearerAuth)

### HTTP request headers

Expand Down
2 changes: 1 addition & 1 deletion docs/QueryRunInfo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Name | Type | Description | Notes
**sql_text** | **String** | |
**status** | **String** | |
**trace_id** | Option<**String**> | | [optional]
**user_public_id** | Option<**String**> | Caller identity derived from the Authorization Bearer token (SHA-256 hash). Format: `user_{first_10_hex_chars}`. | [optional]
**user_public_id** | Option<**String**> | Who ran this query: the account id from the access token the request was made with. Use it to group a caller's query history. Requests made with a credential that identifies no account instead record an opaque `user_`-prefixed identifier, which is stable for that credential but cannot be resolved to an account. | [optional]
**warning_message** | Option<**String**> | | [optional]

[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
Expand Down
4 changes: 2 additions & 2 deletions docs/ResultsApi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Name | Type | Description | Required | Notes

### Authorization

[WorkspaceId](../README.md#WorkspaceId), [SessionId](../README.md#SessionId), [BearerAuth](../README.md#BearerAuth)
[WorkspaceId](../README.md#WorkspaceId), [BearerAuth](../README.md#BearerAuth)

### HTTP request headers

Expand Down Expand Up @@ -65,7 +65,7 @@ Name | Type | Description | Required | Notes

### Authorization

[WorkspaceId](../README.md#WorkspaceId), [SessionId](../README.md#SessionId), [BearerAuth](../README.md#BearerAuth)
[WorkspaceId](../README.md#WorkspaceId), [BearerAuth](../README.md#BearerAuth)

### HTTP request headers

Expand Down
8 changes: 0 additions & 8 deletions src/apis/query_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,14 +54,6 @@ pub async fn query(
};
req_builder = req_builder.header("X-Workspace-Id", value);
};
if let Some(apikey) = configuration.api_keys.get("X-Session-Id") {
let key = apikey.key.clone();
let value = match apikey.prefix {
Some(ref prefix) => format!("{} {}", prefix, key),
None => key,
};
req_builder = req_builder.header("X-Session-Id", value);
};
if let Some(token) = configuration.resolve_bearer_token().await {

@claude claude Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking — this drops the X-Session-Id header from query, and the same block is removed from get_result/list_results in src/apis/results_api.rs. After this PR, grep -rn "X-Session-Id" src/apis/ returns nothing: no generated operation sends the session header anymore.

That leaves the crate internally inconsistent, because the hand-written twins of these exact operations still send it:

  • src/client.rs:468 — Client::submit_query (the hand-written POST /v1/query) still emits X-Session-Id, so it now sends different auth headers than the generated query for the same endpoint.
  • src/query.rs:641-656 — apply_apikey_headers, whose doc comment says it is "mirroring the generated op's isKeyInHeader blocks". That statement is now false.
  • src/arrow.rs:301-321 — apply_apikey_headers, documented as "mirroring the generated get_result isKeyInHeader blocks so a session-scoped client ... behaves identically on the Arrow path". Also now false, and the unit test at src/arrow.rs:494-526 asserts the header is forwarded "matching the generated get_result" — the rationale that test encodes no longer holds.

Also, ClientBuilder::session_id (src/client.rs:126-131) still exists and still installs the API key, but it is now inert for every generated endpoint. A caller who builds a session-scoped client silently loses session scoping on query, get_result, and list_results with no compile-time or runtime signal.

Please resolve the divergence one way or the other before merging: either drop SESSION_ID_HEADER from the two hand-written apply_apikey_headers helpers and from submit_query (updating those doc comments and the arrow.rs tests), or keep it and rewrite the "mirrors the generated op" comments to state that the divergence is deliberate and why. If session_id is no longer meaningful anywhere, it should be deprecated rather than left as a silent no-op.

req_builder = req_builder.bearer_auth(token);
};
Expand Down
16 changes: 0 additions & 16 deletions src/apis/results_api.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,14 +76,6 @@ pub async fn get_result(
};
req_builder = req_builder.header("X-Workspace-Id", value);
};
if let Some(apikey) = configuration.api_keys.get("X-Session-Id") {
let key = apikey.key.clone();
let value = match apikey.prefix {
Some(ref prefix) => format!("{} {}", prefix, key),
None => key,
};
req_builder = req_builder.header("X-Session-Id", value);
};
if let Some(token) = configuration.resolve_bearer_token().await {
req_builder = req_builder.bearer_auth(token);
};
Expand Down Expand Up @@ -158,14 +150,6 @@ pub async fn list_results(
};
req_builder = req_builder.header("X-Workspace-Id", value);
};
if let Some(apikey) = configuration.api_keys.get("X-Session-Id") {
let key = apikey.key.clone();
let value = match apikey.prefix {
Some(ref prefix) => format!("{} {}", prefix, key),
None => key,
};
req_builder = req_builder.header("X-Session-Id", value);
};
if let Some(token) = configuration.resolve_bearer_token().await {
req_builder = req_builder.bearer_auth(token);
};
Expand Down
2 changes: 1 addition & 1 deletion src/models/query_run_info.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ pub struct QueryRunInfo {
skip_serializing_if = "Option::is_none"
)]
pub trace_id: Option<Option<String>>,
/// Caller identity derived from the Authorization Bearer token (SHA-256 hash). Format: `user_{first_10_hex_chars}`.
/// Who ran this query: the account id from the access token the request was made with. Use it to group a caller's query history. Requests made with a credential that identifies no account instead record an opaque `user_`-prefixed identifier, which is stable for that credential but cannot be resolved to an account.

@claude claude Bot Jul 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

super nit: the doc comment has a stray double space ("query history. Requests made") where the upstream description's paragraph break was flattened into a single line. It renders as one run-on paragraph in rustdoc. Worth fixing in the generator template / spec so the two sentences stay visually separated. (not blocking)

#[serde(
rename = "user_public_id",
default,
Expand Down
Loading