From e78cd9650cdefcd939c76a9da1e9394d5951ee7b Mon Sep 17 00:00:00 2001 From: sahej Date: Fri, 20 Nov 2026 22:57:22 +0000 Subject: [PATCH 1/4] Document query response shapes in README Co-Authored-By: Claude Opus 5.5 --- README.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 46 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f541e71..fa266c4 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,16 @@ them with a separate HTTP client without attaching Chalk credentials. the offline job. Environment and branch overrides should be carried from submission to subsequent status calls. +### Result files + +Each Parquet file has one row per input row, with output columns named by feature. +The files also include `__ts__` (the input row's as-of time) and +`.__chalk_observed_at__`. You can ignore the internal `__index__` and +`__chalk__.__metadata__.*` columns. Join results to your inputs on the primary key. + +`OfflineQueryResult` contains metadata only, including `datasetId`, `revisions`, and `errors`. +Each revision includes `revisionId`, `outputs`, `numRows`, `dashboardUrl`, and `errors`. + ## Memory management Chalk uses Arrow objects during serialization of requests and deserialization of responses. These objects need to be closed to free up memory. @@ -197,7 +207,7 @@ public class Main { var userIds = Arrays.asList(1, 2, 3); var params = OnlineQueryParams.builder() .withInput("card_user.id", userIds) - .withOutputs("card_user.full_name") + .withOutputs("card_user.spending_mean_30d") .build(); try (OnlineQueryResult result = client.onlineQuery(params)) { @@ -400,7 +410,7 @@ public class Main { try (OnlineQueryResult result = client.onlineQuery(params)) { for (Row row : result.getScalarsTable()) { - long userId = row.getVarCharObj("card_user.id"); + long userId = row.getInt64("card_user.id"); double meanSpent = row.getFloat8("card_user.spending_mean_30d"); System.out.println( "User " + userId + " spent an average of $" + meanSpent + " per day in the last 30 days" @@ -431,6 +441,40 @@ public class Main { } ``` +### Reading results + +Use these `OnlineQueryResult` getters to read the response. + +| Getter | Returns | +| --- | --- | +| `getScalarsTable()` | An Arrow `Table` with one row per input row and one column per scalar output, named by its fully qualified feature name (for example, `user.full_name`). Rows come back in input order. Include the primary key in `withOutputs` to match rows by key. | +| `getGroupsTables()` | A `Map` with one Arrow table per has-many output, keyed by feature name. The map is empty if none were requested. | +| `getErrors()` | A `ServerError[]` that is empty on success. | +| `getMeta()` | `QueryMeta` with `queryId`, `deploymentId`, `environmentId`, `executionDurationS`, `queryTimestamp`, `queryHash`, and `traceId`. | + +For a request with `withInput("user.id", List.of(1, 2, 3))` and +`withOutputs("user.id", "user.full_name")`, the scalars table contains the following rows. + +```text +schema: [user.id: Int64, user.full_name: LargeUtf8] +user.id user.full_name +1 Donna Davis +2 William Johnson +3 Jasmine Perry +``` + +A `ServerError` has `code` (for example, `RESOLVER_FAILED`), `category` (for +example, `FIELD`), `message`, `resolver`, `feature`, and `exception` (with `kind`, +`message`, and `stacktrace`). + +**Check errors first.** When a resolver fails for a row, the scalars table can +contain nulls for that row, even for features that resolved successfully. The +result reports one error per affected row. Check `getErrors()` before reading +values, and query features separately when a failure in one should leave the +others' results available. + +`onlineQuery` already batches inputs (pass many primary keys). See [Multi-query](#multi-query) for unrelated queries in one request. + ### Multi-query `onlineQueryMulti` runs several *independent* queries in parallel, using a single request. Reach for From 354c8c3749b2501b5b4be1f4f730dcb958136e9e Mon Sep 17 00:00:00 2001 From: sahej Date: Fri, 20 Nov 2026 22:58:24 +0000 Subject: [PATCH 2/4] Request card_user.id in README examples that read it Co-Authored-By: Claude Opus 5.5 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fa266c4..fc0a91b 100644 --- a/README.md +++ b/README.md @@ -207,7 +207,7 @@ public class Main { var userIds = Arrays.asList(1, 2, 3); var params = OnlineQueryParams.builder() .withInput("card_user.id", userIds) - .withOutputs("card_user.spending_mean_30d") + .withOutputs("card_user.id", "card_user.spending_mean_30d") .build(); try (OnlineQueryResult result = client.onlineQuery(params)) { @@ -405,7 +405,7 @@ public class Main { var userIds = Arrays.asList(1, 2, 3); var params = OnlineQueryParams.builder() .withInput("card_user.id", userIds) - .withOutputs("card_user.spending_mean_30d", "card_user.transactions") + .withOutputs("card_user.id", "card_user.spending_mean_30d", "card_user.transactions") .build(); try (OnlineQueryResult result = client.onlineQuery(params)) { From 69fda41b34df9c49e809b1bed465fd096b64180b Mon Sep 17 00:00:00 2001 From: sahej Date: Fri, 20 Nov 2026 23:03:14 +0000 Subject: [PATCH 3/4] Fix README Row getter, null errors and offline join key Co-Authored-By: Claude Opus 5.5 --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index fc0a91b..17155b7 100644 --- a/README.md +++ b/README.md @@ -136,7 +136,7 @@ submission to subsequent status calls. Each Parquet file has one row per input row, with output columns named by feature. The files also include `__ts__` (the input row's as-of time) and `.__chalk_observed_at__`. You can ignore the internal `__index__` and -`__chalk__.__metadata__.*` columns. Join results to your inputs on the primary key. +`__chalk__.__metadata__.*` columns. Join results to your inputs on the primary key and `__ts__`, since the same key can appear at several as-of times. `OfflineQueryResult` contains metadata only, including `datasetId`, `revisions`, and `errors`. Each revision includes `revisionId`, `outputs`, `numRows`, `dashboardUrl`, and `errors`. @@ -212,7 +212,7 @@ public class Main { try (OnlineQueryResult result = client.onlineQuery(params)) { for (Row row : result.getScalarsTable()) { - long userId = row.getInt64("card_user.id"); + long userId = row.getBigInt("card_user.id"); double meanSpent = row.getFloat8("card_user.spending_mean_30d"); System.out.println("User " + userId + " spent an average of $" + meanSpent + " per day in the last 30 days"); } @@ -410,7 +410,7 @@ public class Main { try (OnlineQueryResult result = client.onlineQuery(params)) { for (Row row : result.getScalarsTable()) { - long userId = row.getInt64("card_user.id"); + long userId = row.getBigInt("card_user.id"); double meanSpent = row.getFloat8("card_user.spending_mean_30d"); System.out.println( "User " + userId + " spent an average of $" + meanSpent + " per day in the last 30 days" @@ -448,8 +448,8 @@ Use these `OnlineQueryResult` getters to read the response. | Getter | Returns | | --- | --- | | `getScalarsTable()` | An Arrow `Table` with one row per input row and one column per scalar output, named by its fully qualified feature name (for example, `user.full_name`). Rows come back in input order. Include the primary key in `withOutputs` to match rows by key. | -| `getGroupsTables()` | A `Map` with one Arrow table per has-many output, keyed by feature name. The map is empty if none were requested. | -| `getErrors()` | A `ServerError[]` that is empty on success. | +| `getGroupsTables()` | A `Map` with one Arrow table per has-many output, keyed by feature name. The map is empty if none were requested, and on the HTTP client when any input is a has-many feature. | +| `getErrors()` | A `ServerError[]` that is empty or `null` on success (the HTTP client can return `null`), so null-check it. | | `getMeta()` | `QueryMeta` with `queryId`, `deploymentId`, `environmentId`, `executionDurationS`, `queryTimestamp`, `queryHash`, and `traceId`. | For a request with `withInput("user.id", List.of(1, 2, 3))` and From 92de27a7168f4bb333e3e5906902c8ae0e196098 Mon Sep 17 00:00:00 2001 From: sahej Date: Fri, 20 Nov 2026 23:06:20 +0000 Subject: [PATCH 4/4] Check errors and null scalars table in README examples Co-Authored-By: Claude Opus 5.5 --- README.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 17155b7..c20b71f 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ submission to subsequent status calls. ### Result files -Each Parquet file has one row per input row, with output columns named by feature. +Results can span several Parquet files; together, they hold one row per input row, with output columns named by feature. The files also include `__ts__` (the input row's as-of time) and `.__chalk_observed_at__`. You can ignore the internal `__index__` and `__chalk__.__metadata__.*` columns. Join results to your inputs on the primary key and `__ts__`, since the same key can appear at several as-of times. @@ -211,6 +211,13 @@ public class Main { .build(); try (OnlineQueryResult result = client.onlineQuery(params)) { + if (result.getErrors() != null && result.getErrors().length > 0) { + System.err.println(Arrays.toString(result.getErrors())); + return; + } + if (result.getScalarsTable() == null) { + return; // no data came back + } for (Row row : result.getScalarsTable()) { long userId = row.getBigInt("card_user.id"); double meanSpent = row.getFloat8("card_user.spending_mean_30d"); @@ -409,6 +416,13 @@ public class Main { .build(); try (OnlineQueryResult result = client.onlineQuery(params)) { + if (result.getErrors() != null && result.getErrors().length > 0) { + System.err.println(Arrays.toString(result.getErrors())); + return; + } + if (result.getScalarsTable() == null) { + return; // no data came back + } for (Row row : result.getScalarsTable()) { long userId = row.getBigInt("card_user.id"); double meanSpent = row.getFloat8("card_user.spending_mean_30d"); @@ -447,10 +461,10 @@ Use these `OnlineQueryResult` getters to read the response. | Getter | Returns | | --- | --- | -| `getScalarsTable()` | An Arrow `Table` with one row per input row and one column per scalar output, named by its fully qualified feature name (for example, `user.full_name`). Rows come back in input order. Include the primary key in `withOutputs` to match rows by key. | +| `getScalarsTable()` | An Arrow `Table`, or `null` when no data comes back (for example, when the query fails), with one row per input row and one column per scalar output, named by its fully qualified feature name (for example, `user.full_name`). Rows come back in input order. Include the primary key in `withOutputs` to match rows by key. | | `getGroupsTables()` | A `Map` with one Arrow table per has-many output, keyed by feature name. The map is empty if none were requested, and on the HTTP client when any input is a has-many feature. | | `getErrors()` | A `ServerError[]` that is empty or `null` on success (the HTTP client can return `null`), so null-check it. | -| `getMeta()` | `QueryMeta` with `queryId`, `deploymentId`, `environmentId`, `executionDurationS`, `queryTimestamp`, `queryHash`, and `traceId`. | +| `getMeta()` | `QueryMeta` with `queryId`, `deploymentId`, `environmentId`, `executionDurationS`, `queryTimestamp`, `queryHash`, `traceId`, and `environmentName`. | For a request with `withInput("user.id", List.of(1, 2, 3))` and `withOutputs("user.id", "user.full_name")`, the scalars table contains the following rows.