@pythia-software/query-table-core 0.9.9 → 1.0.0

package/dist/index.js

@@ -1201,6 +1201,7 @@ function parseHostQueryState(input) {
   if (new TextEncoder().encode(JSON.stringify(state)).length > MAX_HOST_QUERY_STATE_BYTES) fail("payload too large.");
   return state;
 }
+var FIT_MODES = /* @__PURE__ */ new Set(["content", "screen"]);
 var EMPTY_QUERY = {
   select: [],
   where: [],
@@ -1390,7 +1391,11 @@ function normalizeQuery(input, fallback, links) {
     limit: boundedInteger(raw.limit, fallback.limit, 1, MAX_QUERY_LIMIT),
     offset: boundedInteger(raw.offset, fallback.offset, 0, MAX_QUERY_OFFSET)
   };
-  if (raw.fitToScreen === true) out.fitToScreen = true;
+  if (typeof raw.fit === "string" && FIT_MODES.has(raw.fit)) out.fit = raw.fit;
+  else if (raw.fitToScreen === true) {
+    out.fit = "screen";
+    for (const column of select) delete column.width;
+  }
   if (links && raw.hostState !== void 0) {
     try {
       out.hostState = parseHostQueryState(raw.hostState);
@@ -1561,7 +1566,7 @@ function normalizeGroupingState(value, links) {
   return { keys, summaries, representative, source: normalizedSource, ...diagnostics.length ? { diagnostics: [...new Set(diagnostics)] } : {} };
 }
 var QUERY_FACETS = /* @__PURE__ */ new Set(["filters", "columns", "order", "grouping", "metrics", "limit"]);
-var PATCH_QUERY_KEYS = ["select", "where", "orderBy", "limit", "aggregations", "grouping", "fitToScreen"];
+var PATCH_QUERY_KEYS = ["select", "where", "orderBy", "limit", "aggregations", "grouping", "fit"];
 var MAX_LINK_PARAMS = 50;
 function normalizeLinkSpec(value) {
   if (!isRecord(value) || !isRecord(value.to)) return void 0;
@@ -1613,14 +1618,15 @@ function normalizeLinkPatch(value) {
   if (raw.aggregations !== void 0 && (!Array.isArray(raw.aggregations) || raw.aggregations.length !== (normalized.aggregations?.length ?? 0) || normalized.aggregations?.some((clause) => clause.diagnostics?.length))) return void 0;
   const query = {};
   for (const key of PATCH_QUERY_KEYS) {
-    if (raw[key] !== void 0 && normalized[key] !== void 0) query[key] = normalized[key];
+    const supplied = raw[key] !== void 0 || key === "fit" && raw.fitToScreen !== void 0;
+    if (supplied && normalized[key] !== void 0) query[key] = normalized[key];
   }
   return { id: value.id, owns: [...new Set(value.owns)], query };
 }
 function queriesEqual(a, b) {
   if (a === b) return true;
   if (a.limit !== b.limit || a.offset !== b.offset) return false;
-  if (a.fitToScreen === true !== (b.fitToScreen === true)) return false;
+  if (a.fit !== b.fit) return false;
   if (!sameArray(a.where, b.where)) return false;
   if (!sameArray(a.orderBy, b.orderBy)) return false;
   if (!sameArray(a.select, b.select)) return false;
@@ -1679,6 +1685,183 @@ function isGroupable(field) {
 // src/encode.ts
 import { deflateSync, Inflate } from "fflate";
 
+// src/wire.generated.ts
+var ERROR_CODES = [
+  "invalid_json",
+  "invalid_request",
+  "method_not_allowed",
+  "forbidden",
+  "not_found",
+  "request_too_large",
+  "conflict",
+  "quota_exceeded",
+  "timeout",
+  "cancelled",
+  "unavailable",
+  "internal",
+  "version",
+  "invalid_query",
+  "profile_mismatch",
+  "definition_changed",
+  "execution_expired",
+  "definition_unavailable",
+  "definition_invalid",
+  "datetime_value",
+  "residual_query",
+  "dataset",
+  "schema",
+  "source_required",
+  "resolver_required",
+  "resolver_scope",
+  "snapshot_transaction_required",
+  "snapshot_validation_required",
+  "plan_token_validation_required",
+  "numeric_domain_required",
+  "unknown_field",
+  "select_required",
+  "filter",
+  "filter_disabled",
+  "sort",
+  "collation_required",
+  "unsupported_regex",
+  "unsupported_literal",
+  "unsupported_type",
+  "invalid_source_value",
+  "numeric_range",
+  "encoding",
+  "identity_required",
+  "duplicate_identity",
+  "scope",
+  "window_required",
+  "syntax",
+  "unsupported_syntax",
+  "unsupported_function",
+  "arity",
+  "type_error",
+  "aggregate_required",
+  "aggregate_context",
+  "aggregate_disabled",
+  "paired_expression_required",
+  "dependency_cycle",
+  "invalid_metric",
+  "duplicate_metric",
+  "metric_sort",
+  "distribution",
+  "date_grouping",
+  "unsupported_date_grouping",
+  "min_count_grouping",
+  "min_count_field",
+  "min_count_distribution",
+  "group_disabled",
+  "grouping",
+  "representative",
+  "resource_limit",
+  "complexity_limit",
+  "dependency_limit",
+  "expansion_limit",
+  "source_limit",
+  "stage_limit",
+  "schema_limit",
+  "capability_unsupported",
+  "unexpanded_series",
+  "invalid",
+  "too_large",
+  "unsupported_version"
+];
+
+// src/errors.ts
+var KNOWN = new Set(ERROR_CODES);
+var isErrorCode = (value) => typeof value === "string" && KNOWN.has(value);
+var QueryError = class extends Error {
+  constructor(code, message, options2 = {}) {
+    super(message);
+    this.name = "QueryError";
+    this.code = code;
+    for (const key of ["field", "offset", "metricId", "status", "capability", "cause"])
+      if (options2[key] !== void 0) this[key] = options2[key];
+  }
+  /** The QueryErrorDetail wire shape of this error. */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.field !== void 0 ? { field: this.field } : {},
+      ...this.offset !== void 0 ? { offset: this.offset } : {},
+      ...this.metricId !== void 0 ? { metricId: this.metricId } : {}
+    };
+  }
+};
+var isQueryError = (error) => error instanceof QueryError;
+function errorCodeForStatus(status) {
+  switch (status) {
+    case 400:
+      return "invalid_request";
+    case 401:
+    case 403:
+      return "forbidden";
+    case 404:
+      return "not_found";
+    case 405:
+      return "method_not_allowed";
+    case 408:
+      return "cancelled";
+    case 409:
+      return "conflict";
+    case 413:
+      return "request_too_large";
+    case 422:
+    case 429:
+      return "resource_limit";
+    case 502:
+    case 503:
+      return "unavailable";
+    case 504:
+      return "timeout";
+    case 507:
+      return "quota_exceeded";
+  }
+  return "internal";
+}
+function parseQueryErrorBody(body) {
+  const error = body?.error;
+  if (!error || typeof error !== "object" || typeof error.code !== "string" || !error.code || typeof error.message !== "string") return null;
+  return {
+    code: error.code,
+    message: error.message,
+    ...typeof error.field === "string" ? { field: error.field } : {},
+    ...Number.isSafeInteger(error.offset) ? { offset: error.offset } : {},
+    ...typeof error.metricId === "string" ? { metricId: error.metricId } : {}
+  };
+}
+function queryErrorFromBody(body, status) {
+  const detail = parseQueryErrorBody(body);
+  if (!detail) return null;
+  const { code, message, ...rest } = detail;
+  return new QueryError(code, message, { ...rest, ...status !== void 0 ? { status } : {} });
+}
+async function queryErrorFromResponse(response) {
+  let text2 = "";
+  try {
+    text2 = await response.text();
+  } catch {
+  }
+  let body;
+  try {
+    body = JSON.parse(text2);
+  } catch {
+    body = void 0;
+  }
+  const parsed = queryErrorFromBody(body, response.status);
+  if (parsed) return parsed;
+  const legacy = typeof body?.error === "string" ? body.error : text2.trim();
+  const message = legacy && legacy.length <= 500 && !/^\s*</.test(legacy) ? legacy : `Request failed with HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ""}.`;
+  return new QueryError(errorCodeForStatus(response.status), message, { status: response.status });
+}
+function failedMetric(id, error, fallback) {
+  const code = error instanceof QueryError ? error.code : fallback;
+  return { id, buckets: [], error: error instanceof Error ? error.message : String(error), errorCode: code };
+}
+
 // src/setFilter.ts
 function setFilterTarget(field) {
   if (field.filter?.editor !== "set") return null;
@@ -1768,16 +1951,15 @@ function compactQuery(q) {
   if (q.offset) c.f = q.offset;
   if (q.aggregations?.length) c.g = q.aggregations;
   if (q.itemDetails) c.d = q.itemDetails;
-  if (q.fitToScreen) c.fs = true;
+  if (q.fit) c.ft = q.fit;
   if (q.grouping) c.b = q.grouping;
   if (q.hostState) c.h = q.hostState;
   return c;
 }
 var MAX_QUERY_STATE_BYTES = 4 * 1024 * 1024;
-var QueryDecodeError = class extends Error {
+var QueryDecodeError = class extends QueryError {
   constructor(code, message) {
-    super(message);
-    this.code = code;
+    super(code, message);
     this.name = "QueryDecodeError";
   }
 };
@@ -1911,6 +2093,7 @@ function decodeToken(token, strict) {
       offset: c.f,
       aggregations: c.g,
       itemDetails: c.d,
+      fit: c.ft,
       fitToScreen: c.fs,
       grouping: c.b,
       hostState: c.h
@@ -1986,29 +2169,6 @@ function termIsPushdown(term, byName, resolveField2) {
     return f2 != null && isPushdownFilter(f2);
   });
 }
-function toAggregationQuery(q, schema) {
-  if (q.grouping) throw new Error("Metrics over grouped rows require grouped-query execution.");
-  const suppliedCount = q.where.reduce((n, t) => n + predicatesOf(t).length, 0);
-  q = normalizeQueryState(q);
-  if (q.aggregations?.some((a) => a.dateGrouping)) throw new Error("Date grouping currently requires local metric execution.");
-  if (q.aggregations?.some((a) => a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.distribution || a.scope === "shownRows" || a.sort?.length || a.groupLimit || a.where?.length || a.minCount !== void 0)) throw new Error("Metric definition requires the version 2 metric transport.");
-  const byName = indexFields(schema);
-  const resolveField2 = (name) => resolveFieldName(schema, name) ?? name;
-  const where = q.where.filter((term) => termIsPushdown(term, byName, resolveField2)).map(stripSetFilter);
-  const isBackend = (name) => {
-    if (name == null) return true;
-    const field = resolveField2(name);
-    const f2 = byName.get(field);
-    return f2 != null && f2.source.kind === "backend";
-  };
-  const aggregations = (q.aggregations ?? []).filter(
-    (a) => isBackend(a.field) && a.groupBy.every((g) => isBackend(g))
-  );
-  const diagnostics = [];
-  for (const c of q.aggregations ?? []) if (!aggregations.includes(c)) diagnostics.push({ metricId: c.id, code: "unsupported_metric", message: "Metric requires unavailable backend fields.", from: 0, to: 1 });
-  if (where.length !== q.where.length || suppliedCount !== q.where.reduce((n, t) => n + predicatesOf(t).length, 0)) diagnostics.push({ code: "residual_filter", message: "All-matching metrics are unavailable with residual client-only filters.", from: 0, to: 1 });
-  return { where, aggregations, ...diagnostics.length ? { diagnostics } : {} };
-}
 
 // src/queryLinks.ts
 var codePattern = /^[A-Za-z0-9_-]{22}$/;
@@ -2383,14 +2543,22 @@ function httpComputedColumnStore(base, fetcher = fetch) {
   const listeners = /* @__PURE__ */ new Map();
   const url = (dataset) => `${base}${base.includes("?") ? "&" : "?"}dataset=${encodeURIComponent(dataset)}`;
   async function read(response) {
-    if (response.status === 409)
-      throw new Error(
-        "This definition changed. Reload it before saving again."
-      );
-    if (!response.ok)
-      throw new Error(
-        `Computed column store request failed (${response.status}).`
+    if (!response.ok) {
+      const error = await queryErrorFromResponse(response);
+      if (response.status !== 409) throw error;
+      const { code, field, offset, metricId, status } = error;
+      throw new QueryError(
+        code,
+        "This definition changed. Reload it before saving again.",
+        {
+          ...field !== void 0 ? { field } : {},
+          ...offset !== void 0 ? { offset } : {},
+          ...metricId !== void 0 ? { metricId } : {},
+          ...status !== void 0 ? { status } : {},
+          cause: error
+        }
       );
+    }
     return response.json();
   }
   return {
@@ -4024,7 +4192,7 @@ function planMetricSeries(query, schema, options2 = {}) {
       return prepared.map((item) => {
         const c = item.clause;
         if (item.kind === "error")
-          return { id: c.id, buckets: [], error: item.error };
+          return { id: c.id, buckets: [], error: item.error, errorCode: "invalid_metric" };
         if (item.kind === "empty") {
           const none = {
             id: c.id,
@@ -4039,20 +4207,20 @@ function planMetricSeries(query, schema, options2 = {}) {
           (part) => byId.get(part.id) ?? {
             id: part.id,
             buckets: [],
-            error: "Server omitted this metric."
+            error: "Server omitted this metric.",
+            errorCode: "internal"
           }
         );
         if (item.kind === "plain") return { ...entries[0], id: c.id };
+        const failed = entries.find((entry) => entry.error);
+        if (failed)
+          return { id: c.id, buckets: [], error: failed.error, ...failed.errorCode ? { errorCode: failed.errorCode } : {} };
         try {
           if (item.kind === "occurrence")
             return combineOccurrences(c, entries[0]);
           return combineSeries(item, entries);
         } catch (e) {
-          return {
-            id: c.id,
-            buckets: [],
-            error: e instanceof Error ? e.message : String(e)
-          };
+          return failedMetric(c.id, e, "invalid_metric");
         }
       });
     }
@@ -5205,7 +5373,7 @@ function distinctAccumulator(options2) {
       if (v === null || values.has(v)) return;
       const size = 64 + (typeof v === "string" ? v.length * 2 : 8);
       if (values.size >= cardinality || size > byteLimit - bytes)
-        throw Error("Metric distinct retained-memory budget exceeded.");
+        throw new QueryError("resource_limit", "Metric distinct retained-memory budget exceeded.");
       values.add(v);
       bytes += size;
     },
@@ -5756,15 +5924,15 @@ function assertMetricQueryState(q, schema) {
     throw Error("Malformed metric query state cannot be executed exactly.");
 }
 function selectMetricShownRows(rows, q, schema, options2 = {}) {
-  if (options2.signal?.aborted) throw Error("Metric evaluation cancelled.");
+  if (options2.signal?.aborted) throw new QueryError("cancelled", "Metric evaluation cancelled.");
   assertMetricQueryState(q, schema);
   if (options2.shownRows) return options2.shownRows;
   const orderBy = q.orderBy.length ? q.orderBy : schema.defaultSort ?? [];
   assertMetricPopulation(q, schema, orderBy);
   if (rows.length > (options2.maxRows ?? 1e6))
-    throw Error("Metric row budget exceeded.");
+    throw new QueryError("resource_limit", "Metric row budget exceeded.");
   if ((options2.maxOperations ?? 1e7) <= 0)
-    throw Error("Metric operation budget exceeded.");
+    throw new QueryError("resource_limit", "Metric operation budget exceeded.");
   return applyQuery(
     rows,
     // Local tables use a stable sort: ties retain input order. An extra ID
@@ -5805,7 +5973,7 @@ var scalar = (v) => {
 function groupStringLength(value, limit) {
   let length = value.length + 2;
   if (length > limit)
-    throw Error("Metric grouping key length budget exceeded.");
+    throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
   for (let i = 0; i < value.length; i++) {
     const code = value.charCodeAt(i);
     if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13)
@@ -5815,7 +5983,7 @@ function groupStringLength(value, limit) {
       i++;
     else if (code >= 55296 && code <= 57343) length += 5;
     if (length > limit)
-      throw Error("Metric grouping key length budget exceeded.");
+      throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
   }
   return length;
 }
@@ -5855,8 +6023,8 @@ function sortMetricBuckets(buckets, c) {
 function evaluateMetrics(rows, q, schema, options2 = {}) {
   if (q.grouping) {
     try {
-      if (options2.signal?.aborted) throw new Error("Metric evaluation cancelled.");
-      if (rows.length > (options2.maxRows ?? 1e6)) throw new Error("Metric row budget exceeded.");
+      if (options2.signal?.aborted) throw new QueryError("cancelled", "Metric evaluation cancelled.");
+      if (rows.length > (options2.maxRows ?? 1e6)) throw new QueryError("resource_limit", "Metric row budget exceeded.");
       const now2 = evaluationTime(options2);
       const prepared = prepareGrouping(rows, schema, q.grouping, { now: now2 });
       return evaluateMetrics(prepared.rows, withoutGrouping(q), prepared.schema, {
@@ -5864,7 +6032,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
         now: now2
       });
     } catch (error) {
-      return { metrics: (q.aggregations ?? []).map((metric) => ({ id: metric.id, buckets: [], error: error instanceof Error ? error.message : String(error) })) };
+      return { metrics: (q.aggregations ?? []).map((metric) => failedMetric(metric.id, error, "grouping")) };
     }
   }
   const now = evaluationTime(options2), fields = indexFields(schema);
@@ -5886,19 +6054,19 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
     metrics: (q.aggregations ?? []).map((c) => {
       let budget = options2.maxOperations ?? 1e7;
       const tick = () => {
-        if (--budget < 0) throw Error("Metric operation budget exceeded.");
+        if (--budget < 0) throw new QueryError("resource_limit", "Metric operation budget exceeded.");
         if (options2.signal?.aborted)
-          throw Error("Metric evaluation cancelled.");
+          throw new QueryError("cancelled", "Metric evaluation cancelled.");
       };
       try {
         if (options2.signal?.aborted)
-          throw Error("Metric evaluation cancelled.");
+          throw new QueryError("cancelled", "Metric evaluation cancelled.");
         assertMetricQueryState(q, schema);
         if ((q.aggregations?.length ?? 0) > 20)
-          throw Error("At most 20 metrics are allowed.");
+          throw new QueryError("resource_limit", "At most 20 metrics are allowed.");
         const diagnostics = validateMetric(c, schema, options2.resolveComputed);
         if (diagnostics.length)
-          throw Error(diagnostics.map((d) => d.message).join(" "));
+          throw new QueryError("invalid_metric", diagnostics.map((d) => d.message).join(" "), { metricId: c.id });
         const ps = metricPlans(c, schema, options2.resolveComputed);
         if (ps.some(hasRegex) && !options2.evaluateInput)
           throw Error(
@@ -5911,7 +6079,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           if (!matching) {
             assertMetricPopulation(q, schema, []);
             if (rows.length > (options2.maxRows ?? 1e6))
-              throw Error("Metric row budget exceeded.");
+              throw new QueryError("resource_limit", "Metric row budget exceeded.");
             matching = applyQuery(
               rows,
               { ...q, orderBy: [], offset: 0, limit: Number.MAX_SAFE_INTEGER },
@@ -5922,7 +6090,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           inputRows = matching;
         }
         if (inputRows.length > (options2.maxRows ?? 1e6))
-          throw Error("Metric row budget exceeded.");
+          throw new QueryError("resource_limit", "Metric row budget exceeded.");
         const population = inputRows.length;
         if (c.where?.length)
           inputRows = applyQuery(
@@ -5942,11 +6110,11 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
         let groupBytes = 0;
         const reserve = (bytes) => {
           if (bytes > byteLimit - groupBytes)
-            throw Error("Metric grouping retained-memory budget exceeded.");
+            throw new QueryError("resource_limit", "Metric grouping retained-memory budget exceeded.");
         };
         if (!c.groupBy.length) {
           if (keyLimit < 2)
-            throw Error("Metric grouping key length budget exceeded.");
+            throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
           reserve(256);
           groupBytes = 256;
           groups.set("[]", { keys: [], rows: [] });
@@ -5995,7 +6163,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
             keyLength += 1 + (typeof value === "string" ? groupStringLength(value, keyLimit - keyLength - 1) : value === null ? 4 : typeof value === "boolean" ? value ? 4 : 5 : String(value).length);
             payloadBytes += typeof value === "string" ? 2 * value.length : 8;
             if (keyLength > keyLimit)
-              throw Error("Metric grouping key length budget exceeded.");
+              throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
           }
           const retainedBytes = 256 + 16 * keys.length + payloadBytes + 2 * keyLength;
           reserve(retainedBytes + 2 * keyLength + 16);
@@ -6003,7 +6171,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           let g = groups.get(key);
           if (!g) {
             if (groups.size >= (options2.maxGroups ?? 1e4))
-              throw Error("Metric group budget exceeded.");
+              throw new QueryError("resource_limit", "Metric group budget exceeded.");
             g = { keys, rows: [] };
             groups.set(key, g);
             groupBytes += retainedBytes;
@@ -6043,10 +6211,10 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
               const keys = [slot, ...tuple];
               const key = JSON.stringify(keys);
               if (key.length > keyLimit)
-                throw Error("Metric grouping key length budget exceeded.");
+                throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
               if (!groups.has(key)) {
                 if (groups.size >= (options2.maxGroups ?? 1e4))
-                  throw Error("Metric group budget exceeded.");
+                  throw new QueryError("resource_limit", "Metric group budget exceeded.");
                 const bytes = 256 + 16 * keys.length + 4 * key.length;
                 reserve(bytes);
                 groupBytes += bytes;
@@ -6071,10 +6239,10 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
                 ];
                 const key = JSON.stringify(keys);
                 if (key.length > keyLimit)
-                  throw Error("Metric grouping key length budget exceeded.");
+                  throw new QueryError("resource_limit", "Metric grouping key length budget exceeded.");
                 if (!groups.has(key)) {
                   if (groups.size >= (options2.maxGroups ?? 1e4))
-                    throw Error("Metric group budget exceeded.");
+                    throw new QueryError("resource_limit", "Metric group budget exceeded.");
                   const bytes = 256 + 16 * keys.length + 4 * key.length;
                   reserve(bytes);
                   groupBytes += bytes;
@@ -6087,7 +6255,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
                 config.timeZone
               );
               if (!Number.isFinite(next) || next <= time)
-                throw Error("Date grouping exceeds calendar limits.");
+                throw new QueryError("resource_limit", "Date grouping exceeds calendar limits.");
               time = next;
             }
         }
@@ -6258,11 +6426,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           ...other ? { other } : {}
         };
       } catch (e) {
-        return {
-          id: c.id,
-          buckets: [],
-          error: e instanceof Error ? e.message : String(e)
-        };
+        return failedMetric(c.id, e, "invalid_metric");
       }
     })
   };
@@ -6377,7 +6541,8 @@ function applyAggregations(rows, q, schema, options2 = {}) {
       return {
         id: agg.id,
         buckets: [],
-        error: `Field ${field.name} does not allow ${agg.op}.`
+        error: `Field ${field.name} does not allow ${agg.op}.`,
+        errorCode: "aggregate_disabled"
       };
     return {
       id: agg.id,
@@ -7205,6 +7370,8 @@ function resolveGroupLink(query, value, targets = {}) {
 }
 
 // src/queryV3.ts
+var MAX_DISTINCT_LIMIT = 500;
+var MAX_DISTINCT_SEARCH_LENGTH = 2e3;
 function sourceExecutionSchema(schema, execution, catalogue = []) {
   const fields = new Map(schema.fields.map((field) => [field.name, field]));
   for (const [name, capability] of Object.entries(execution?.fields ?? {})) {
@@ -7225,73 +7392,97 @@ function sourceExecutionSchema(schema, execution, catalogue = []) {
   }
   return { ...schema, fields: [...fields.values()] };
 }
+var profileUnavailable = (capabilities, execution) => capabilities.version !== 3 || !!execution && execution.profile !== capabilities.profile;
+var unsupported = (capability, message, field) => ({ code: "capability_unsupported", message, capability, ...field !== void 0 ? { field } : {} });
+function refuse(refusals) {
+  const [first] = refusals;
+  if (!first) return;
+  const { code, message: _message, ...details } = first;
+  throw new QueryError(code, [...new Set(refusals.map((refusal) => refusal.message))].join(" "), details);
+}
+function requestEnvelope(capabilities, execution, now, refusals) {
+  const revisions = /* @__PURE__ */ Object.create(null);
+  for (const [id, revision] of Object.entries(execution?.resolvedRevisions ?? {})) {
+    if (!revision || id.length > 256 || revision.length > 256) refusals.push({ code: "definition_changed", message: "Invalid computed revision envelope." });
+    else revisions[id.startsWith("@computed/") ? id.slice(10) : id] = revision;
+  }
+  return {
+    version: 3,
+    profile: capabilities.profile,
+    now,
+    expectedRevisions: revisions,
+    ...execution?.planToken ? { planToken: execution.planToken } : {},
+    ...execution?.snapshot !== void 0 ? { snapshot: execution.snapshot } : {}
+  };
+}
+var profileRefusal = { code: "profile_mismatch", message: "The negotiated query profile is unavailable." };
 function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 = {}) {
   const now = evaluationTime(options2), q = normalizeQueryState(query);
   const sourceSchema = sourceExecutionSchema(baseSchema, execution);
   const source = q.grouping?.source ?? withoutGrouping(q);
-  const diagnostics = [];
-  if ((query.aggregations?.length ?? 0) !== (q.aggregations?.length ?? 0)) diagnostics.push("The query exceeds its metric budget or contains malformed metric state.");
-  if (capabilities.version !== 3 || execution && execution.profile !== capabilities.profile) diagnostics.push("The negotiated query profile is unavailable.");
+  const refusals = [];
+  if ((query.aggregations?.length ?? 0) !== (q.aggregations?.length ?? 0))
+    refusals.push({ code: "invalid_metric", message: "The query exceeds its metric budget or contains malformed metric state." });
+  if (profileUnavailable(capabilities, execution)) refusals.push(profileRefusal);
   let resultSchema = sourceSchema;
   if (q.grouping) {
-    if (!capabilities.groupedRows) diagnostics.push("This server does not support grouped rows.");
+    if (!capabilities.groupedRows) refusals.push(unsupported("groupedRows", "This server does not support grouped rows."));
     else if (q.grouping.keys.some(isCalendarGroupKey) && !capabilities.calendarGroupKeys)
-      diagnostics.push("This server does not support grouping keys by calendar interval.");
+      refusals.push(unsupported("calendarGroupKeys", "This server does not support grouping keys by calendar interval."));
+    for (const message of q.grouping.diagnostics ?? []) refusals.push({ code: "grouping", message });
     try {
       const model = createGroupingModel(sourceSchema);
       model.validate(q.grouping);
       resultSchema = model.resultSchema(q.grouping.keys, q.grouping.summaries);
     } catch (error) {
-      diagnostics.push(error instanceof Error ? error.message : String(error));
+      refusals.push({ code: "grouping", message: error instanceof Error ? error.message : String(error) });
     }
   }
   const sourceRequest = toServerQuery(withoutGrouping(source), sourceSchema);
   for (const term of source.where) for (const predicate of predicatesOf(term)) if (["matches_regex", "not_matches_regex"].includes(predicate.op) && !capabilities.regexSourceFilters)
-    diagnostics.push("This server profile does not support isolated regex source filtering.");
+    refusals.push(unsupported("regexSourceFilters", "This server profile does not support isolated regex source filtering.", predicate.field));
   const result = toServerQuery(withoutGrouping(q), resultSchema);
-  if (sourceRequest.where.length !== source.where.length || result.where.length !== q.where.length) diagnostics.push("The query contains unsupported source or result predicates.");
-  if (result.orderBy.length !== q.orderBy.length) diagnostics.push("The query contains unsupported result ordering.");
+  if (sourceRequest.where.length !== source.where.length || result.where.length !== q.where.length)
+    refusals.push({ code: "residual_query", message: "The query contains unsupported source or result predicates." });
+  if (result.orderBy.length !== q.orderBy.length) refusals.push({ code: "residual_query", message: "The query contains unsupported result ordering." });
   if (q.grouping) {
     for (const term of q.grouping.source.where) for (const predicate of predicatesOf(term))
-      if (predicate.field.startsWith("@computed/") && !capabilities.computedSourceFilters) diagnostics.push("This server does not support computed source predicates.");
+      if (predicate.field.startsWith("@computed/") && !capabilities.computedSourceFilters)
+        refusals.push(unsupported("computedSourceFilters", "This server does not support computed source predicates.", predicate.field));
   }
   const metricQuery = toMetricQuery(withoutGrouping(q), resultSchema, execution);
-  diagnostics.push(...metricQuery.diagnostics.filter((issue) => issue.code === "residual_metric_filter" || issue.code === "unexpanded_series").map((issue) => issue.message));
-  const metrics = metricQuery.metrics.map((metric) => {
-    const dateGrouping = q.aggregations?.find((clause) => clause.id === metric.id)?.dateGrouping;
-    return dateGrouping ? { ...metric, dateGrouping } : metric;
-  });
-  for (const metric of metrics) {
-    diagnostics.push(...validateMetric(metric, resultSchema).map((issue) => issue.message));
-    if (metric.dateGrouping && !capabilities.calendarGrouping) diagnostics.push("This server does not support calendar grouping.");
-    else if (isMetricCycle(metric.dateGrouping?.interval) && !capabilities.calendarCycles)
-      diagnostics.push("This server does not support hour-of-day or day-of-week grouping.");
-  }
-  const revisions = /* @__PURE__ */ Object.create(null);
-  for (const [id, revision] of Object.entries(execution?.resolvedRevisions ?? {})) {
-    if (!revision || id.length > 256 || revision.length > 256) diagnostics.push("Invalid computed revision envelope.");
-    else revisions[id.startsWith("@computed/") ? id.slice(10) : id] = revision;
-  }
+  for (const issue of metricQuery.diagnostics)
+    if (issue.code === "residual_metric_filter" || issue.code === "unexpanded_series")
+      refusals.push({ code: issue.code === "unexpanded_series" ? "unexpanded_series" : "residual_query", message: issue.message, ...issue.metricId ? { metricId: issue.metricId } : {} });
+  const metrics = [];
+  for (const { unsupportedOp, ...clause } of metricQuery.metrics) {
+    const { diagnostics: _diagnostics, ...projected } = clause;
+    if (unsupportedOp)
+      refusals.push({ code: "invalid_metric", message: `Metric ${projected.id} uses an unsupported operation: ${unsupportedOp}.`, metricId: projected.id });
+    const dateGrouping = q.aggregations?.find((c) => c.id === projected.id)?.dateGrouping;
+    for (const issue of validateMetric({ ...clause, ...dateGrouping ? { dateGrouping } : {} }, resultSchema))
+      refusals.push({ code: "invalid_metric", message: issue.message, metricId: projected.id });
+    if (dateGrouping && !capabilities.calendarGrouping)
+      refusals.push({ ...unsupported("calendarGrouping", "This server does not support calendar grouping."), metricId: projected.id });
+    else if (isMetricCycle(dateGrouping?.interval) && !capabilities.calendarCycles)
+      refusals.push({ ...unsupported("calendarCycles", "This server does not support hour-of-day or day-of-week grouping."), metricId: projected.id });
+    metrics.push(dateGrouping ? { ...projected, dateGrouping } : projected);
+  }
+  const envelope = requestEnvelope(capabilities, execution, now, refusals);
+  refuse(refusals);
   return {
-    version: 3,
-    profile: capabilities.profile,
-    now,
-    expectedRevisions: revisions,
-    ...execution?.planToken ? { planToken: execution.planToken } : {},
-    ...execution?.snapshot !== void 0 ? { snapshot: execution.snapshot } : {},
+    ...envelope,
     source: sourceRequest,
     result,
     ...q.grouping ? { grouping: {
       keys: q.grouping.keys,
       // Summary display is presentation only and link columns are computed on
       // the client; the wire contract is unchanged.
-      summaries: withoutLinkSummaries(q.grouping.summaries).map(({ display: _display, ...summary }) => summary),
-      representative: q.grouping.representative,
-      ...q.grouping.diagnostics ? { diagnostics: q.grouping.diagnostics } : {}
+      summaries: withoutLinkSummaries(q.grouping.summaries).map(({ display: _display, link: _link, ...summary }) => summary),
+      representative: q.grouping.representative
     } } : {},
     rows: options2.rows !== false,
-    metrics,
-    diagnostics: [...new Set(diagnostics)]
+    metrics
   };
 }
 function validateQueryResultV3(result, request, schema) {
@@ -7301,6 +7492,11 @@ function validateQueryResultV3(result, request, schema) {
   if (!Array.isArray(result.schema.fields) || result.schema.fields.some((field) => expected.get(field.name) !== field.type) || request.rows && request.result.select.some((name) => !result.schema.fields.some((field) => field.name === name))) throw Error("The server returned a different projected schema.");
   for (const [id, revision] of Object.entries(request.expectedRevisions)) if (result.execution.resolvedRevisions[id] !== revision)
     throw Error("Computed definitions changed. Refresh the server execution handshake.");
+  if (request.distinct) {
+    const distinct = result.distinct;
+    if (!distinct || !Array.isArray(distinct.values) || distinct.values.length > request.distinct.limit || distinct.values.some((value) => typeof value !== "string") || typeof distinct.hasMore !== "boolean" || typeof distinct.hasNull !== "boolean")
+      throw Error("Invalid distinct values response.");
+  }
   const seen = /* @__PURE__ */ new Set();
   for (const row of result.rows) {
     const id = row[schema.idField];
@@ -7308,6 +7504,98 @@ function validateQueryResultV3(result, request, schema) {
     seen.add(id);
   }
 }
+var emptyStage = (where = []) => ({ select: [], where, orderBy: [], limit: 1, offset: 0 });
+function auxiliaryRequest(capabilities, source, result, options2, part, refusals = []) {
+  if (profileUnavailable(capabilities, options2.execution)) refusals.unshift(profileRefusal);
+  const envelope = requestEnvelope(capabilities, options2.execution, evaluationTime(options2), refusals);
+  refuse(refusals);
+  return {
+    ...envelope,
+    source,
+    result,
+    ...part,
+    ...options2.hostState ? { hostState: options2.hostState } : {}
+  };
+}
+async function execute(transport, request, signal) {
+  const result = await transport.fetchQueryV3(request, signal);
+  if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+  return result;
+}
+function toDistinctRequestV3(field, search, capabilities, options2 = {}) {
+  const limit = options2.limit ?? 50, refusals = [];
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_DISTINCT_LIMIT) refusals.push({ code: "invalid_query", message: `Distinct value limit must be between 1 and ${MAX_DISTINCT_LIMIT}.` });
+  if (search.length > MAX_DISTINCT_SEARCH_LENGTH) refusals.push({ code: "invalid_query", message: "Distinct search exceeds its budget." });
+  return auxiliaryRequest(capabilities, emptyStage(options2.where), emptyStage(), options2, { rows: false, metrics: [], distinct: { field, search, limit } }, refusals);
+}
+function readDistinctResultV3(result, request, schema) {
+  validateQueryResultV3(result, request, schema);
+  const { values, hasMore, hasNull } = result.distinct;
+  return { values: [...values], hasMore, hasNull };
+}
+async function fetchDistinctValuesV3(transport, schema, field, search, options2 = {}, signal) {
+  const request = toDistinctRequestV3(field, search, transport.queryCapabilities, options2);
+  return readDistinctResultV3(await execute(transport, request, signal), request, schema);
+}
+function rowLookupFields(schema) {
+  return [.../* @__PURE__ */ new Set([schema.idField, ...schema.fields.filter((field) => field.source.kind === "backend" && isSelectable(field) && !field.name.startsWith("@computed/")).map((field) => field.name)])].sort();
+}
+function toRowRequestV3(schema, id, capabilities, options2 = {}) {
+  const stage = {
+    select: options2.select ? [.../* @__PURE__ */ new Set([schema.idField, ...options2.select])].sort() : rowLookupFields(schema),
+    where: [{ field: schema.idField, op: "=", value: String(id) }],
+    orderBy: [],
+    limit: Math.max(1, Math.min(2, capabilities.maxRows)),
+    offset: 0
+  };
+  return auxiliaryRequest(capabilities, stage, stage, options2, { rows: true, metrics: [] });
+}
+function readRowResultV3(result, request, schema) {
+  if (Array.isArray(result?.rows) && result.rows.length > 1 || result?.total > 1) throw Error("Row identity must be unique.");
+  validateQueryResultV3(result, request, schema);
+  const row = result.rows[0];
+  if (row && String(row[schema.idField]) !== request.result.where[0]?.value)
+    throw Error("The server returned a different row.");
+  return row ?? null;
+}
+async function fetchRowV3(transport, schema, id, options2 = {}, signal) {
+  const request = toRowRequestV3(schema, id, transport.queryCapabilities, options2);
+  return readRowResultV3(await execute(transport, request, signal), request, schema);
+}
+var STAT_OPS = [{ op: "count_distinct", key: "distinct" }, { op: "min", key: "min" }, { op: "max", key: "max" }];
+function toFieldStatsRequestV3(schema, fields, capabilities, options2 = {}) {
+  const metrics = [];
+  for (const name of new Set(fields)) {
+    const field = schema.fields.find((f2) => f2.name === name);
+    if (!field || field.source.kind !== "backend" || !isMeasurable(field)) continue;
+    const ops = aggOpsForField(field);
+    for (const { op, key } of STAT_OPS) if (ops.includes(op)) metrics.push({ id: `${name}:${key}`, op, field: name, groupBy: [] });
+  }
+  return auxiliaryRequest(capabilities, emptyStage(), emptyStage(), options2, { rows: false, metrics });
+}
+function readFieldStatsResultV3(result, request, schema) {
+  validateQueryResultV3(result, request, schema);
+  const byId = new Map(result.metrics.map((metric) => [metric.id, metric]));
+  const stats = /* @__PURE__ */ new Map();
+  for (const metric of request.metrics) {
+    const entry = byId.get(metric.id), value = entry && !entry.error ? entry.buckets[0]?.value : void 0;
+    const key = metric.id.slice(metric.field.length + 1);
+    const item = stats.get(metric.field) ?? {};
+    stats.set(metric.field, item);
+    if (key === "distinct" ? typeof value === "number" : typeof value === "number" || typeof value === "string") item[key] = value;
+  }
+  return Object.fromEntries(stats);
+}
+async function fetchFieldStatsV3(transport, schema, fields, options2 = {}, signal) {
+  const all = toFieldStatsRequestV3(schema, fields, transport.queryCapabilities, options2);
+  const stats = /* @__PURE__ */ new Map();
+  for (let i = 0; i < all.metrics.length; i += MAX_AGGREGATIONS) {
+    const request = { ...all, metrics: all.metrics.slice(i, i + MAX_AGGREGATIONS) };
+    for (const [name, item] of Object.entries(readFieldStatsResultV3(await execute(transport, request, signal), request, schema)))
+      stats.set(name, { ...stats.get(name), ...item });
+  }
+  return Object.fromEntries(stats);
+}
 
 // src/drilldown.ts
 function metricSchema(query, schema) {
@@ -7551,6 +7839,7 @@ export {
   AGG_OPS_NEEDING_FIELD,
   COMPUTED_PREFIX,
   EMPTY_QUERY,
+  ERROR_CODES,
   FORMULA_FUNCTIONS,
   FormulaError,
   GROUP_ID_FIELD,
@@ -7558,6 +7847,8 @@ export {
   GROUP_LINK_RENDER,
   ITEM_DETAILS_COLUMN,
   MAX_AGGREGATIONS,
+  MAX_DISTINCT_LIMIT,
+  MAX_DISTINCT_SEARCH_LENGTH,
   MAX_GROUP_BY_FIELDS,
   MAX_HOST_QUERY_PARAMS,
   MAX_HOST_QUERY_STATE_BYTES,
@@ -7585,6 +7876,7 @@ export {
   OPS_BY_TYPE,
   OP_LABEL,
   QueryDecodeError,
+  QueryError,
   QuerySnapshotHttpError,
   aggOpAllowedForType,
   aggOpNeedsField,
@@ -7610,9 +7902,14 @@ export {
   decodeQueryStrict,
   discoverFieldRelationships,
   encodeQuery,
+  errorCodeForStatus,
   evaluateMetricReductions,
   evaluateMetrics,
   exitGrouping,
+  failedMetric,
+  fetchDistinctValuesV3,
+  fetchFieldStatsV3,
+  fetchRowV3,
   filterValues,
   formulaRuntime,
   groupKeyField,
@@ -7632,6 +7929,7 @@ export {
   isCalendarGroupKey,
   isComputedCellError,
   isComputedField,
+  isErrorCode,
   isFilterable,
   isGroupLinkField,
   isGroupLinkValue,
@@ -7646,6 +7944,7 @@ export {
   isOrOfAndsGroup,
   isPropertyFieldLoaded,
   isPushdownFilter,
+  isQueryError,
   isSelectable,
   isSortable,
   isWhereConjunction,
@@ -7696,20 +7995,27 @@ export {
   parseHostQueryState,
   parseJsonInspectionState,
   parseJsonInspections,
+  parseQueryErrorBody,
   parseRelativeDuration,
   percentile,
   planMetricSeries,
   predicatesOf,
   prepareGrouping,
   queriesEqual,
+  queryErrorFromBody,
+  queryErrorFromResponse,
+  readDistinctResultV3,
+  readFieldStatsResultV3,
   readFieldValue,
   readObjectReference,
+  readRowResultV3,
   readSetFilter,
   reduceMetricValues,
   removePatch,
   renderItemPageTemplate,
   resolveFieldName,
   resolveGroupLink,
+  rowLookupFields,
   selectMetricShownRows,
   selectedFields,
   setFilterModes,
@@ -7718,11 +8024,11 @@ export {
   sourceDependencies,
   sourceExecutionSchema,
   stripSetFilter,
-  toAggregationQuery,
-  toMetricQuery,
+  toDistinctRequestV3,
+  toFieldStatsRequestV3,
   toQueryRequestV3,
+  toRowRequestV3,
   toServerQuery,
-  toServerQueryV2,
   validateComputedColumn,
   validateDateGrouping,
   validateItemPageTemplate,