@pythia-software/query-table-core 0.7.1 → 0.8.0

package/dist/index.js

@@ -16,7 +16,7 @@ var options = {
   number: numberOptions,
   percent: numberOptions,
   chip: { labels: "labels", tones: "tones" },
-  text: { truncate: "boolean" }
+  text: { truncate: "boolean", lines: [1, 20] }
 };
 function parseCellDisplay(raw, context = "cell display") {
   const fail = (reason) => {
@@ -385,42 +385,63 @@ function normalizeAliases(rawAliases, rawAlias) {
 }
 
 // src/itemPage.ts
-function itemPageFields(template) {
+var MAX_TEMPLATE_LENGTH = 8e3;
+var BASE = "https://query-table.invalid/";
+var ITEM_PAGE_TOKENS = ["id", "query"];
+function placeholders(tokens) {
+  return new RegExp(`\\{(${[...tokens, "field:[^{}]+"].join("|")})\\}`, "g");
+}
+function httpOrRelative(href) {
+  try {
+    return ["http:", "https:"].includes(new URL(href, BASE).protocol);
+  } catch {
+    return false;
+  }
+}
+function templateFields(template) {
   return [...new Set(Array.from(template.matchAll(/\{field:([^{}]+)\}/g), (match) => match[1]))];
 }
-function validateItemPageTemplate(template, schema) {
-  if (template.length > 8e3) return "Use a URL template of at most 8,000 characters.";
+function urlTemplateProblem(template, tokens, hasField) {
+  if (template.length > MAX_TEMPLATE_LENGTH) return "Use a URL template of at most 8,000 characters.";
   if (!template.trim()) return null;
-  const remainder = template.replace(/\{(id|query|field:[^{}]+)\}/g, "value");
-  if (/[{}]/.test(remainder)) return "Use {id}, {query}, or {field:field_name} placeholders.";
-  for (const name of itemPageFields(template)) {
-    if (!schema.fields.some((field) => field.name === name)) return `Unknown URL field: ${name}.`;
+  const remainder = template.replace(placeholders(tokens), "value");
+  if (/[{}]/.test(remainder)) {
+    const names = [...tokens.map((token) => `{${token}}`), "{field:field_name}"];
+    const list = names.length > 1 ? `${names.slice(0, -1).join(", ")}${names.length > 2 ? "," : ""} or ${names.at(-1)}` : names[0];
+    return `Use ${list} placeholders.`;
+  }
+  for (const name of templateFields(template)) {
+    if (!hasField(name)) return `Unknown URL field: ${name}.`;
   }
   try {
-    if (!["http:", "https:"].includes(new URL(remainder, "https://query-table.invalid/").protocol))
+    if (!["http:", "https:"].includes(new URL(remainder, BASE).protocol))
       return "Use an HTTP, HTTPS, or relative page URL.";
   } catch {
     return "Enter a valid page URL.";
   }
   return null;
 }
-function renderItemPageTemplate(template, schema, row, id, query) {
-  if (!template.trim() || validateItemPageTemplate(template, schema)) return null;
+function fillUrlTemplate(template, tokens, read) {
   let missing = false;
-  const href = template.replace(/\{(id|query|field:[^{}]+)\}/g, (_match, token) => {
-    const value = token === "id" ? id : token === "query" ? query : readFieldValue(schema.fields.find((field) => field.name === token.slice(6)), row);
+  const href = template.replace(placeholders(tokens), (_match, token) => {
+    const value = read(token);
     if (value == null || !["string", "number", "boolean"].includes(typeof value)) {
       missing = true;
       return "";
     }
     return encodeURIComponent(String(value));
   });
-  try {
-    if (missing || !["http:", "https:"].includes(new URL(href, "https://query-table.invalid/").protocol)) return null;
-  } catch {
-    return null;
-  }
-  return href;
+  return missing || !httpOrRelative(href) ? null : href;
+}
+function itemPageFields(template) {
+  return templateFields(template);
+}
+function validateItemPageTemplate(template, schema) {
+  return urlTemplateProblem(template, ITEM_PAGE_TOKENS, (name) => schema.fields.some((field) => field.name === name));
+}
+function renderItemPageTemplate(template, schema, row, id, query) {
+  if (!template.trim() || validateItemPageTemplate(template, schema)) return null;
+  return fillUrlTemplate(template, ITEM_PAGE_TOKENS, (token) => token === "id" ? id : token === "query" ? query : readFieldValue(schema.fields.find((field) => field.name === token.slice(6)), row));
 }
 
 // src/metricNormalize.ts
@@ -444,7 +465,8 @@ function normalizeMetricOptions(raw) {
       expression: "string",
       expressionY: "string",
       scope: ["allMatching", "shownRows"],
-      groupLimit: "integer"
+      groupLimit: "integer",
+      minCount: "positiveInteger"
     })
   );
   if (raw.dateGrouping !== void 0) {
@@ -666,7 +688,50 @@ function normalizeSetFilter(item) {
   if (item.values.length > MAX_WHERE_CLAUSES || !item.values.every((value) => typeof value === "string" && value.length <= MAX_FILTER_VALUE_LENGTH)) return void 0;
   return { id, mode: item.mode, values: [...item.values] };
 }
+function normalizeWhereTerms(input) {
+  const where = [];
+  let literalBudget = MAX_WHERE_CLAUSES;
+  for (const item of input) {
+    if (literalBudget <= 0) break;
+    const start = where.length;
+    if (isRecord(item) && Array.isArray(item.any)) {
+      const members = [];
+      for (const inner of item.any) {
+        if (literalBudget <= 0) break;
+        const clause = normalizeWhereClause(inner);
+        if (clause) {
+          members.push(clause);
+          literalBudget--;
+        }
+      }
+      if (members.length === 1) where.push(members[0]);
+      else if (members.length > 1) where.push({ any: members });
+    } else {
+      const clause = normalizeWhereClause(item);
+      if (clause) {
+        where.push(clause);
+        literalBudget--;
+      }
+    }
+    if (where.length > start && isRecord(item)) {
+      const metadata = normalizeSetFilter(item.setFilter);
+      if (metadata) where[start].setFilter = metadata;
+    }
+  }
+  return where;
+}
+function normalizeMetricWhere(value) {
+  if (value === void 0) return { invalid: false };
+  if (!Array.isArray(value)) return { invalid: true };
+  const where = normalizeWhereTerms(value);
+  const supplied = value.reduce((count, term) => count + (isRecord(term) && Array.isArray(term.any) ? term.any.length : 1), 0);
+  const kept = where.reduce((count, term) => count + predicatesOf(term).length, 0);
+  return { ...where.length ? { where } : {}, invalid: supplied !== kept };
+}
 function normalizeQueryState(input, fallback = EMPTY_QUERY) {
+  return normalizeQuery(input, fallback, true);
+}
+function normalizeQuery(input, fallback, links) {
   const raw = isRecord(input) ? input : {};
   const select = [];
   if (Array.isArray(raw.select)) {
@@ -678,44 +743,18 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
       if (typeof item.width === "number" && Number.isFinite(item.width)) {
         column.width = boundedInteger(item.width, MIN_COLUMN_WIDTH, MIN_COLUMN_WIDTH, MAX_COLUMN_WIDTH);
       }
-      select.push(column);
-    }
-  } else {
-    select.push(...fallback.select.map((column) => ({ ...column })));
-  }
-  const where = [];
-  if (Array.isArray(raw.where)) {
-    let literalBudget = MAX_WHERE_CLAUSES;
-    for (const item of raw.where) {
-      if (literalBudget <= 0) break;
-      const start = where.length;
-      if (isRecord(item) && Array.isArray(item.any)) {
-        const members = [];
-        for (const inner of item.any) {
-          if (literalBudget <= 0) break;
-          const clause = normalizeWhereClause(inner);
-          if (clause) {
-            members.push(clause);
-            literalBudget--;
-          }
-        }
-        if (members.length === 1) where.push(members[0]);
-        else if (members.length > 1) where.push({ any: members });
-      } else {
-        const clause = normalizeWhereClause(item);
-        if (clause) {
-          where.push(clause);
-          literalBudget--;
+      if (item.display !== void 0) {
+        try {
+          column.display = parseCellDisplay(item.display, `column ${field} display`);
+        } catch {
         }
       }
-      if (where.length > start && isRecord(item)) {
-        const metadata = normalizeSetFilter(item.setFilter);
-        if (metadata) where[start].setFilter = metadata;
-      }
+      select.push(column);
     }
   } else {
-    where.push(...fallback.where.map(cloneWhereTerm));
+    select.push(...fallback.select.map((column) => ({ ...column, ...column.display ? { display: JSON.parse(JSON.stringify(column.display)) } : {} })));
   }
+  const where = Array.isArray(raw.where) ? normalizeWhereTerms(raw.where) : fallback.where.map(cloneWhereTerm);
   const orderBy = [];
   if (Array.isArray(raw.orderBy)) {
     for (const item of raw.orderBy.slice(0, MAX_ORDER_BY_TERMS)) {
@@ -742,7 +781,7 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
     offset: boundedInteger(raw.offset, fallback.offset, 0, MAX_QUERY_OFFSET)
   };
   if (raw.fitToScreen === true) out.fitToScreen = true;
-  if (raw.grouping != null) out.grouping = normalizeGroupingState(raw.grouping);
+  if (raw.grouping != null) out.grouping = normalizeGroupingState(raw.grouping, links);
   if (Array.isArray(raw.aggregations)) {
     const aggregations = [];
     for (const item of raw.aggregations.slice(0, MAX_AGGREGATIONS)) {
@@ -758,6 +797,9 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
       if (field) aggregation.field = field;
       if (label) aggregation.label = label;
       Object.assign(aggregation, normalizeMetricOptions(item));
+      const metricWhere = normalizeMetricWhere(item.where);
+      if (metricWhere.where) aggregation.where = metricWhere.where;
+      if (metricWhere.invalid) aggregation.diagnostics = [...aggregation.diagnostics ?? [], "Invalid metric filter."];
       if (!Array.isArray(item.groupBy) || rawGroups.length > MAX_GROUP_BY_FIELDS || groupBy.length !== rawGroups.length) aggregation.diagnostics = [...aggregation.diagnostics ?? [], "Invalid metric grouping fields or grouping budget exceeded."];
       const unsupportedOp = boundedString(item.unsupportedOp ?? (!validOp ? item.op : void 0), MAX_FIELD_NAME_LENGTH);
       if (unsupportedOp) aggregation.unsupportedOp = unsupportedOp;
@@ -804,60 +846,147 @@ function normalizeQueryState(input, fallback = EMPTY_QUERY) {
   }
   return out;
 }
-function normalizeGroupingState(value) {
+function normalizeGroupingState(value, links) {
   const raw = isRecord(value) ? value : {};
   const diagnostics = [];
-  const fail = () => {
-    diagnostics.push("Invalid grouping definition.");
+  const fail = (message) => {
+    diagnostics.push(`Invalid grouping: ${message}`);
   };
   const keys = Array.isArray(raw.keys) ? raw.keys.slice(0, MAX_GROUP_BY_FIELDS).filter((key) => !!boundedString(key, MAX_FIELD_NAME_LENGTH)) : [];
-  if (!Array.isArray(raw.keys) || !keys.length || keys.length !== raw.keys.length || new Set(keys).size !== keys.length) fail();
+  if (!Array.isArray(raw.keys) || !keys.length || keys.length !== raw.keys.length || new Set(keys).size !== keys.length)
+    fail(`keys must list 1\u2013${MAX_GROUP_BY_FIELDS} distinct field names.`);
   const summaries = [];
-  if (!Array.isArray(raw.summaries) || raw.summaries.length > 64) fail();
-  for (const item of Array.isArray(raw.summaries) ? raw.summaries.slice(0, 64) : []) {
-    if (!isRecord(item) || !boundedString(item.id, MAX_FIELD_NAME_LENGTH) || typeof item.op !== "string" || !AGG_OPS.has(item.op) && item.op !== "row" && item.op !== "formula") {
-      fail();
+  if (!Array.isArray(raw.summaries) || raw.summaries.length > 64) fail("summaries must be a list of at most 64 columns.");
+  const summaryIds = /* @__PURE__ */ new Set();
+  for (const [index, item] of (Array.isArray(raw.summaries) ? raw.summaries.slice(0, 64) : []).entries()) {
+    const name = isRecord(item) && boundedString(item.id, MAX_FIELD_NAME_LENGTH) ? `summary "${item.id}"` : `summary ${index + 1}`;
+    if (!isRecord(item) || !boundedString(item.id, MAX_FIELD_NAME_LENGTH)) {
+      fail(`${name} needs an id of 1\u2013${MAX_FIELD_NAME_LENGTH} characters.`);
+      continue;
+    }
+    if (typeof item.op !== "string" || !AGG_OPS.has(item.op) && item.op !== "row" && item.op !== "formula" && (item.op !== "link" || !links)) {
+      fail(item.op === "link" ? `${name} is a link column; a link's patch cannot contain link columns.` : `${name} has unsupported op ${JSON.stringify(String(item.op).slice(0, 40))}; use count, count_distinct, sum, avg, min, max, row, formula, or link${String(item.op).toLowerCase() === "median" ? ' (for a median, use op "formula" with expression "MEDIAN([field])")' : ""}.`);
       continue;
     }
     const column = { id: item.id, op: item.op };
+    if (summaryIds.has(column.id)) fail(`${name} uses the same id as another summary column.`);
+    else if (keys.includes(column.id)) fail(`${name} uses the same id as group key "${column.id}"; summary ids must differ from source field names.`);
+    summaryIds.add(column.id);
+    if (item.op === "link") {
+      const link = normalizeLinkSpec(item.link);
+      if (link) column.link = link;
+      if (item.label !== void 0) {
+        if (typeof item.label !== "string" || item.label.length > MAX_LABEL_LENGTH) fail(`${name} label must be text of at most ${MAX_LABEL_LENGTH.toLocaleString("en-US")} characters.`);
+        else column.label = item.label;
+      }
+      summaries.push(column);
+      continue;
+    }
     if (item.field !== void 0) {
-      if (!boundedString(item.field, MAX_FIELD_NAME_LENGTH)) fail();
+      if (!boundedString(item.field, MAX_FIELD_NAME_LENGTH)) fail(`${name} has an invalid field name.`);
       else column.field = item.field;
     }
     if (item.op === "formula") {
-      if (typeof item.expression !== "string" || item.expression.length > 1e4) fail();
+      if (typeof item.expression !== "string" || item.expression.length > 1e4) fail(`${name} needs an expression of at most 10,000 characters.`);
       else column.expression = item.expression;
     }
     if (item.label !== void 0) {
-      if (typeof item.label !== "string" || item.label.length > MAX_LABEL_LENGTH) fail();
+      if (typeof item.label !== "string" || item.label.length > MAX_LABEL_LENGTH) fail(`${name} label must be text of at most ${MAX_LABEL_LENGTH.toLocaleString("en-US")} characters.`);
       else column.label = item.label;
     }
+    if (item.display !== void 0) {
+      try {
+        column.display = parseCellDisplay(item.display, `${name} display`);
+      } catch (error) {
+        fail(`${error instanceof Error ? error.message : String(error)}.`);
+      }
+    }
     summaries.push(column);
   }
   let representative = null;
   if (raw.representative != null) {
     const ordering = isRecord(raw.representative) ? raw.representative.orderBy : void 0;
     const orderBy = [];
-    if (!Array.isArray(ordering) || !ordering.length || ordering.length > 8) fail();
+    if (!Array.isArray(ordering) || !ordering.length || ordering.length > 8) fail("representative ordering must list 1\u20138 fields.");
     for (const term of Array.isArray(ordering) ? ordering.slice(0, 8) : []) {
       if (!isRecord(term) || !boundedString(term.field, MAX_FIELD_NAME_LENGTH) || !["asc", "desc"].includes(String(term.dir)) || term.nulls !== void 0 && !["first", "last"].includes(String(term.nulls))) {
-        fail();
+        fail('each representative ordering term needs a field, dir "asc" or "desc", and optional nulls "first" or "last".');
         continue;
       }
       orderBy.push({ field: term.field, dir: term.dir, nulls: term.nulls === "first" ? "first" : "last" });
     }
     representative = { orderBy };
   }
-  if (!isRecord(raw.source) || raw.source.grouping != null) fail();
+  if (!isRecord(raw.source)) fail("source must be the record query that is grouped.");
+  else if (raw.source.grouping != null) fail("only one grouping stage is supported; the source query cannot itself be grouped.");
   const { grouping: _nested, ...source } = isRecord(raw.source) ? raw.source : {};
-  if (Array.isArray(raw.diagnostics) && raw.diagnostics.length) fail();
+  if (Array.isArray(raw.diagnostics))
+    for (const message of raw.diagnostics.slice(0, 20))
+      diagnostics.push(typeof message === "string" && message ? message.slice(0, MAX_LABEL_LENGTH) : "Invalid grouping definition.");
   const normalizedSource = normalizeQueryState(source);
   if (Array.isArray(source.where)) {
     const supplied = source.where.reduce((count, term) => count + (isRecord(term) && Array.isArray(term.any) ? term.any.length : 1), 0);
-    if (supplied !== normalizedSource.where.reduce((count, term) => count + predicatesOf(term).length, 0)) fail();
+    if (supplied !== normalizedSource.where.reduce((count, term) => count + predicatesOf(term).length, 0)) fail("source filters contain malformed predicates or exceed the predicate budget.");
   }
   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 MAX_LINK_PARAMS = 50;
+function normalizeLinkSpec(value) {
+  if (!isRecord(value) || !isRecord(value.to)) return void 0;
+  let label;
+  if (typeof value.label === "string" && value.label.length <= MAX_LABEL_LENGTH) label = value.label;
+  else if (isRecord(value.label) && boundedString(value.label.column, MAX_FIELD_NAME_LENGTH)) label = { column: value.label.column };
+  else return void 0;
+  const to = value.to;
+  if (to.kind === "template") {
+    if (typeof to.template !== "string" || to.template.length > 8e3) return void 0;
+    return { label, to: { kind: "template", template: to.template } };
+  }
+  if (to.kind !== "query" || !boundedString(to.target, MAX_FIELD_NAME_LENGTH)) return void 0;
+  const destination = { kind: "query", target: to.target };
+  if (to.base !== void 0) {
+    if (to.base !== "source" && to.base !== "empty") return void 0;
+    destination.base = to.base;
+  }
+  if (to.keyFilters !== void 0) {
+    if (typeof to.keyFilters !== "boolean") return void 0;
+    destination.keyFilters = to.keyFilters;
+  }
+  if (to.patch !== void 0) {
+    const patch = normalizeLinkPatch(to.patch);
+    if (!patch) return void 0;
+    destination.patch = patch;
+  }
+  if (to.params !== void 0) {
+    if (!isRecord(to.params)) return void 0;
+    const entries = Object.entries(to.params);
+    if (entries.length > MAX_LINK_PARAMS || entries.some(([key, item]) => !boundedString(key, MAX_FIELD_NAME_LENGTH) || typeof item !== "string" || item.length > MAX_FILTER_VALUE_LENGTH))
+      return void 0;
+    destination.params = Object.fromEntries(entries);
+  }
+  return { label, to: destination };
+}
+function keptEveryTerm(supplied, kept) {
+  if (!Array.isArray(supplied)) return false;
+  const count = supplied.reduce((total, term) => total + (isRecord(term) && Array.isArray(term.any) ? Math.max(1, term.any.length) : 1), 0);
+  return count === kept.reduce((total, term) => total + predicatesOf(term).length, 0);
+}
+function normalizeLinkPatch(value) {
+  if (!isRecord(value) || !boundedString(value.id, MAX_FIELD_NAME_LENGTH) || !Array.isArray(value.owns) || !isRecord(value.query)) return void 0;
+  if (value.owns.length > QUERY_FACETS.size || value.owns.some((facet) => typeof facet !== "string" || !QUERY_FACETS.has(facet))) return void 0;
+  const raw = value.query;
+  const normalized = normalizeQuery(raw, EMPTY_QUERY, false);
+  if (normalized.grouping?.diagnostics) return void 0;
+  if (raw.where !== void 0 && !keptEveryTerm(raw.where, normalized.where)) return void 0;
+  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];
+  }
+  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;
@@ -1051,15 +1180,26 @@ function isGroupable(field) {
 import { deflateSync, Inflate } from "fflate";
 
 // src/setFilter.ts
-function createSetFilter(field, mode, values, id) {
+function setFilterTarget(field) {
+  if (field.filter?.editor !== "set") return null;
+  if (field.type === "textarray") return "array";
+  if (field.type === "enum" || field.type === "text" && filterValues(field).source === "static") return "scalar";
+  return null;
+}
+function setFilterModes(target) {
+  return target === "array" ? ["any", "all", "none", "empty"] : ["any", "none"];
+}
+function createSetFilter(field, mode, values, id, target = "array") {
+  if (!setFilterModes(target).includes(mode)) throw new Error(`${mode.toUpperCase()} set filters require a textarray field.`);
   const keys = [...new Set(values)];
   if (mode !== "empty" && keys.length === 0) return [];
-  const includes = keys.map((value) => ({ field, op: "includes", value }));
+  const members = keys.map((value) => ({ field, op: target === "array" ? "includes" : "=", value }));
+  const isNull = { field, op: "is_null", value: "" };
   let terms;
-  if (mode === "empty") terms = [{ field, op: "is_null", value: "" }];
-  else if (mode === "any") terms = includes.length === 1 ? includes : [{ any: includes }];
-  else if (mode === "all") terms = includes;
-  else terms = includes.map((clause) => ({ any: [{ field, op: "is_null", value: "" }, { ...clause, negated: true }] }));
+  if (mode === "empty") terms = [isNull];
+  else if (mode === "any") terms = members.length === 1 ? members : [{ any: members }];
+  else if (mode === "all") terms = members;
+  else terms = members.map((clause) => ({ any: [isNull, target === "array" ? { ...clause, negated: true } : { ...clause, op: "!=" }] }));
   return terms.map((term) => ({ ...term, setFilter: { id, mode, values: mode === "empty" ? [] : [...keys] } }));
 }
 function stripSetFilter(term) {
@@ -1072,14 +1212,15 @@ function readSetFilter(where, index) {
   if (!term || !metadata || where[index - 1]?.setFilter?.id === metadata.id) return null;
   const field = predicatesOf(term)[0]?.field;
   if (!field) return null;
-  const expected = createSetFilter(field, metadata.mode, metadata.values, metadata.id);
+  const target = predicatesOf(term).some((clause) => clause.op === "includes") || !setFilterModes("scalar").includes(metadata.mode) ? "array" : "scalar";
+  const expected = createSetFilter(field, metadata.mode, metadata.values, metadata.id, target);
   if (expected.length === 0) return null;
   for (let offset = 0; offset < expected.length; offset++) {
     const actual = where[index + offset];
     if (!actual || JSON.stringify(actual.setFilter) !== JSON.stringify(expected[offset].setFilter) || JSON.stringify(stripSetFilter(actual)) !== JSON.stringify(stripSetFilter(expected[offset]))) return null;
   }
   if (where[index + expected.length]?.setFilter?.id === metadata.id) return null;
-  return { field, metadata, count: expected.length };
+  return { field, metadata, count: expected.length, target };
 }
 function mapSetFilterValues(where, canonicalize) {
   const result = [];
@@ -1089,7 +1230,7 @@ function mapSetFilterValues(where, canonicalize) {
       result.push(where[index]);
       continue;
     }
-    result.push(...createSetFilter(set.field, set.metadata.mode, set.metadata.values.map((value) => canonicalize(set.field, value)), set.metadata.id));
+    result.push(...createSetFilter(set.field, set.metadata.mode, set.metadata.values.map((value) => canonicalize(set.field, value)), set.metadata.id, set.target));
     index += set.count - 1;
   }
   return result;
@@ -1119,7 +1260,7 @@ function compactQuery(q) {
   q = normalizeQueryState(q);
   const c = {};
   if (q.select.length)
-    c.s = q.select.map((col) => col.width != null ? [col.field, col.width] : [col.field]);
+    c.s = q.select.map((col) => col.display ? [col.field, col.width ?? null, col.display] : col.width != null ? [col.field, col.width] : [col.field]);
   if (q.where.length) c.w = q.where;
   if (q.orderBy.length) c.o = q.orderBy;
   c.l = q.limit;
@@ -1145,7 +1286,7 @@ function packQuery(c) {
     const terms = [];
     for (let i = 0; i < c.w.length; i++) {
       const set = readSetFilter(c.w, i);
-      if (set) {
+      if (set?.target === "array") {
         terms.push(["set", set.field, set.metadata.mode, set.metadata.values, set.metadata.id]);
         i += set.count - 1;
       } else terms.push(c.w[i]);
@@ -1283,7 +1424,10 @@ function normalizeSelect(s) {
   return s.map((item) => {
     if (typeof item === "string") return { field: item };
     if (Array.isArray(item) && typeof item[0] === "string") {
-      return typeof item[1] === "number" ? { field: item[0], width: item[1] } : { field: item[0] };
+      const column = { field: item[0] };
+      if (typeof item[1] === "number") column.width = item[1];
+      if (item[2] !== void 0) column.display = item[2];
+      return column;
     }
     return null;
   }).filter((x) => x != null);
@@ -1337,7 +1481,7 @@ function toAggregationQuery(q, schema) {
   const suppliedPredicateCount = 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)) throw new Error("Metric definition requires the version 2 metric transport.");
+  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);
@@ -1830,6 +1974,15 @@ var FORMULA_FUNCTIONS = [
   f("LENGTH", "LENGTH(text)", "Count Unicode code points.", 1, 1, "number", [
     "text"
   ]),
+  f(
+    "URL_ENCODE",
+    "URL_ENCODE(text)",
+    "Percent-encode UTF-8 text for a URL. Only letters, digits and - . _ ~ are kept.",
+    1,
+    1,
+    "text",
+    ["text"]
+  ),
   ...["LOWER", "UPPER", "TRIM", "LTRIM", "RTRIM"].map(
     (n) => f(
       n,
@@ -2202,6 +2355,14 @@ function compileFormula(source, fields, resolve, extension) {
       } catch {
         throw new FormulaError("Invalid JSON string literal.", from, pos);
       }
+    } else if (source[pos] === "'") {
+      const end = source.indexOf("'", pos + 1);
+      const text = end < 0 ? "" : source.slice(pos + 1, end);
+      throw new FormulaError(
+        end < 0 || text.length > 40 || /["\\\n]/.test(text) ? 'Text literals use double quotes ("text"), not single quotes.' : `Text literals use double quotes: write "${text}" instead of '${text}'.`,
+        from,
+        end < 0 ? pos + 1 : end + 1
+      );
     } else if (match = source.slice(pos).match(/^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?/)) {
       pos += match[0].length;
       tokens.push({ kind: "number", text: match[0], from, to: pos });
@@ -2295,6 +2456,12 @@ function compileFormula(source, fields, resolve, extension) {
       const op = take();
       const p = priority[op.text];
       if (op.text === "IN") {
+        if (peek().text !== "(")
+          throw new FormulaError(
+            'IN takes a parenthesized list, e.g. [status] IN ("a", "b"). To test array membership, use ARRAY_CONTAINS([tags], "a").',
+            op.from,
+            peek().to
+          );
         expect("(");
         const args = [node];
         do {
@@ -2313,6 +2480,12 @@ function compileFormula(source, fields, resolve, extension) {
         node = call(`op:${op.text}`, [node, right], node.from, right.to);
       }
     }
+    if (peek().text === "NOT" && tokens[i + 1]?.text === "IN")
+      throw new FormulaError(
+        'NOT IN is not supported. Write NOT ([status] IN ("a", "b")), or combine != comparisons with AND.',
+        peek().from,
+        tokens[i + 1].to
+      );
     depth--;
     return node;
   }
@@ -2376,6 +2549,12 @@ function compileFormula(source, fields, resolve, extension) {
         ts.forEach((_, j) => need(j, "number"));
         return "number";
       }
+      if (op === "IN" && ts.some((t) => t === "textarray"))
+        throw new FormulaError(
+          'IN compares one value with a list of values. For arrays, use ARRAY_CONTAINS([tags], "a"), or OR several ARRAY_CONTAINS calls.',
+          n.from,
+          n.to
+        );
       same(ts, n);
       return "bool";
     }
@@ -2630,6 +2809,14 @@ function formulaRuntime(ast, inputs, extension) {
       case "LENGTH":
         out = Array.from(str(a)).length;
         break;
+      case "URL_ENCODE":
+        if (!/^(?:[^\ud800-\udfff]|[\ud800-\udbff][\udc00-\udfff])*$/.test(str(a)))
+          fail("Text is not valid Unicode.");
+        out = encodeURIComponent(str(a)).replace(
+          /[!'()*]/g,
+          (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`
+        );
+        break;
       case "LOWER":
         out = str(a).toLowerCase();
         break;
@@ -2907,7 +3094,40 @@ function formulaRuntime(ast, inputs, extension) {
   }
 }
 
+// src/groupKeys.ts
+function datetimeValue(value) {
+  const time = value instanceof Date ? value.getTime() : typeof value === "number" ? value : typeof value === "string" && value !== "" ? Date.parse(value) : NaN;
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+}
+function keyClause(field, value) {
+  if (!field || field.type === "textarray" || !isFilterable(field)) return null;
+  if (value == null) return { field: field.name, op: "is_null", value: "" };
+  if (field.type === "datetime") {
+    const iso = datetimeValue(value);
+    return iso === null ? null : { field: field.name, op: "=", value: iso };
+  }
+  if (typeof value === "number" ? !Number.isFinite(value) : typeof value !== "string" && typeof value !== "boolean")
+    return null;
+  return { field: field.name, op: "=", value: String(value) };
+}
+function groupKeyTerms(keys, group, schema) {
+  const terms = [];
+  for (const key of keys) {
+    const term = keyClause(resolveField(schema, key), group[key]);
+    if (!term) return null;
+    terms.push(term);
+  }
+  return terms;
+}
+
 // src/grouping.ts
+var GROUP_LINK_RENDER = "qt_group_link";
+function isGroupLinkValue(value) {
+  return value != null && typeof value === "object" && value.kind === "group-link";
+}
+function isGroupLinkField(field) {
+  return field?.render === GROUP_LINK_RENDER;
+}
 var GROUP_ID_FIELD = "__qt_group_id__";
 var MAX_REPRESENTATIVE_SORTS = 8;
 var MAX_SUMMARY_COLUMNS = 64;
@@ -2916,6 +3136,38 @@ function withoutGrouping(query) {
   const { grouping: _grouping, ...result } = query;
   return result;
 }
+function exitGrouping(query) {
+  return query.grouping ? query.grouping.source : query;
+}
+function withGroupingKeys(query, keys) {
+  const before = query.grouping;
+  if (!keys.length) return exitGrouping(query);
+  if (!before)
+    return {
+      select: keys.map((field) => ({ field })),
+      where: [],
+      orderBy: [],
+      limit: query.limit,
+      offset: 0,
+      grouping: { keys, summaries: [], representative: null, source: query }
+    };
+  const removed = new Set(before.keys.filter((key) => !keys.includes(key)));
+  const columns = query.select.length ? query.select : before.keys.map((field) => ({ field }));
+  return {
+    ...query,
+    grouping: { ...before, keys },
+    offset: 0,
+    aggregations: [],
+    select: [
+      ...keys.filter((key) => !before.keys.includes(key)).map((field) => ({ field })),
+      ...columns.filter((c) => !removed.has(c.field))
+    ],
+    where: query.where.filter(
+      (term) => !predicatesOf(term).some((p) => removed.has(p.field))
+    ),
+    orderBy: query.orderBy.filter((term) => !removed.has(term.field))
+  };
+}
 var OP_LABEL = {
   count: "COUNT",
   count_distinct: "DISTINCT",
@@ -2924,7 +3176,8 @@ var OP_LABEL = {
   min: "MIN",
   max: "MAX",
   row: "ROW",
-  formula: "\u0192x"
+  formula: "\u0192x",
+  link: "LINK"
 };
 function createGroupingModel(inputSchema) {
   const sourceField = (name) => inputSchema.fields.find((f2) => f2.name === name);
@@ -2949,6 +3202,7 @@ function createGroupingModel(inputSchema) {
   }
   function summaryExpression(column) {
     if (column.op === "formula") return column.expression ?? "";
+    if (column.op === "link") return "";
     const field = column.field ? `[${column.field.replace(/\]/g, "]]")}]` : "";
     return `${column.op === "row" ? "COUNT" : column.op.toUpperCase()}(${field})`;
   }
@@ -2970,6 +3224,8 @@ function createGroupingModel(inputSchema) {
   function summaryLabel(column) {
     if (column.op === "formula")
       return column.label?.trim() || "Custom aggregate";
+    if (column.op === "link")
+      return column.label?.trim() || typeof column.link?.label === "string" && column.link.label.trim() || "Link";
     if (!column.field) return "Row count";
     const label = sourceField(column.field)?.label ?? column.field;
     const prefix = {
@@ -2980,10 +3236,70 @@ function createGroupingModel(inputSchema) {
       min: "Min",
       max: "Max",
       row: "Representative \xB7",
-      formula: ""
+      formula: "",
+      link: ""
     };
     return `${prefix[column.op]} ${label}`;
   }
+  function linkReferences(column, keys) {
+    const link = column.link;
+    if (!link) return [];
+    const names = /* @__PURE__ */ new Set();
+    if (typeof link.label === "object") names.add(link.label.column);
+    if (link.to.kind === "template")
+      for (const name of templateFields(link.to.template)) names.add(name);
+    else if (link.to.keyFilters !== false)
+      for (const key of keys) names.add(key);
+    return [...names];
+  }
+  function linkProblem(column, keys, summaries) {
+    const link = column.link;
+    if (column.op !== "link") return null;
+    if (!link) return "Invalid link definition.";
+    const readable = (name) => keys.includes(name) || summaries.some((other) => other.id === name && other.op !== "link");
+    if (typeof link.label === "object" && !readable(link.label.column))
+      return `Unknown link label column: ${link.label.column}.`;
+    if (link.to.kind === "template") {
+      if (!link.to.template.trim()) return "Enter a link URL template.";
+      return urlTemplateProblem(link.to.template, [], readable);
+    }
+    if (link.to.keyFilters !== false)
+      for (const key of keys) {
+        const field = sourceField(key);
+        if (field?.type === "textarray")
+          return `Key filters cannot match the textarray key ${field.label}.`;
+        if (!field || !isFilterable(field))
+          return `Key filters cannot match the key ${field?.label ?? key}.`;
+      }
+    return null;
+  }
+  function linkDiagnostics(definition) {
+    return definition.summaries.flatMap((column) => {
+      const problem = linkProblem(column, definition.keys, definition.summaries);
+      return problem ? [`${summaryLabel(column)}: ${problem}`] : [];
+    });
+  }
+  function linkValue(column, problem, keys, schema, row) {
+    const link = column.link;
+    const read = (name) => {
+      const field = schema.fields.find((f2) => f2.name === name);
+      const value2 = field ? readFieldValue(field, row) : void 0;
+      if (value2 == null || isComputedCellError(value2)) return null;
+      if (field?.type === "datetime" || value2 instanceof Date)
+        return datetimeValue(value2) ?? value2;
+      return Array.isArray(value2) ? value2.join(", ") : value2;
+    };
+    const label = !link ? summaryLabel(column) : typeof link.label === "string" ? link.label : String(read(link.label.column) ?? "");
+    const value = { kind: "group-link", label, to: link?.to ?? null };
+    if (problem || !link) return { ...value, problem: problem ?? "Invalid link definition." };
+    if (link.to.kind === "template") {
+      const href = fillUrlTemplate(link.to.template, [], (token) => read(token.slice(6)));
+      return href === null ? { ...value, problem: "A value in this link is empty." } : { ...value, href };
+    }
+    if (link.to.keyFilters === false) return value;
+    const terms = groupKeyTerms(keys, row, inputSchema);
+    return terms ? { ...value, terms } : { ...value, problem: "This group cannot be matched exactly." };
+  }
   function resultSchema(keys, summaries) {
     const fields = [
       {
@@ -3014,7 +3330,28 @@ function createGroupingModel(inputSchema) {
         }];
       })
     ];
+    let schema;
     for (const column of summaries) {
+      if (column.op === "link") {
+        const problem = linkProblem(column, keys, summaries);
+        fields.push({
+          name: column.id,
+          label: summaryLabel(column),
+          type: "text",
+          source: {
+            kind: "derived",
+            dependencies: linkReferences(column, keys),
+            accessor: (row) => linkValue(column, problem, keys, schema, row)
+          },
+          select: { align: "left" },
+          filter: { enabled: false },
+          sort: { enabled: false },
+          aggregate: { measure: false, groupable: false },
+          render: GROUP_LINK_RENDER,
+          group: "Links"
+        });
+        continue;
+      }
       if (column.op === "formula") {
         let type = "number";
         try {
@@ -3031,7 +3368,8 @@ function createGroupingModel(inputSchema) {
           type,
           source: { kind: "backend" },
           group: "Aggregates",
-          select: { align: type === "number" ? "right" : "left" }
+          select: { align: type === "number" ? "right" : "left" },
+          ...column.display ? { display: column.display } : {}
         });
         continue;
       }
@@ -3049,17 +3387,21 @@ function createGroupingModel(inputSchema) {
         },
         group: example ? "Representative row" : "Summaries",
         ...!numeric && input?.aggregate?.groupable !== void 0 ? { aggregate: { groupable: input.aggregate.groupable } } : {},
-        ...typeof input?.render === "string" && !counting ? { render: input.render } : {},
-        ...input?.display && !counting ? { display: input.display } : {}
+        // An explicit summary format replaces the inherited source presentation.
+        ...column.display ? { display: column.display } : {
+          ...typeof input?.render === "string" && !counting ? { render: input.render } : {},
+          ...input?.display && !counting ? { display: input.display } : {}
+        }
       });
     }
-    return {
+    schema = {
       name: `${inputSchema.name}:groups`,
       idField: GROUP_ID_FIELD,
       fields,
       defaultSelect: keys.filter((key) => sourceField(key)).map((field) => ({ field })),
       defaultLimit: 25
     };
+    return schema;
   }
   function keyValue(value) {
     if (value == null) return null;
@@ -3160,7 +3502,7 @@ function createGroupingModel(inputSchema) {
       }
     }
     const formulas = new Map(
-      summaries.filter((c) => c.op !== "row").map((column) => {
+      summaries.filter((c) => c.op !== "row" && c.op !== "link").map((column) => {
         try {
           const problem = summaryProblem(column);
           if (problem) throw new Error(problem);
@@ -3194,6 +3536,7 @@ function createGroupingModel(inputSchema) {
         );
       const chosen = rule && summaries.some((column) => column.op === "row") ? representative(members, rule, schema) : null;
       for (const column of summaries) {
+        if (column.op === "link") continue;
         if (column.op !== "row") {
           const compiled = formulas.get(column.id);
           if (!compiled.plan) {
@@ -3301,12 +3644,22 @@ function createGroupingModel(inputSchema) {
       GROUP_ID_FIELD,
       ...inputSchema.fields.map((field) => field.name)
     ]);
+    const sourceNames = new Set(inputSchema.fields.map((field) => field.name));
     for (const column of definition.summaries) {
+      if (sourceNames.has(column.id))
+        throw new Error(
+          `Aggregate column ID "${column.id}" is already a source field name. Choose a different id, such as "${column.op === "formula" || column.op === "row" ? "summary" : column.op}_${column.id}".`
+        );
+      if (ids.has(column.id) && column.id !== GROUP_ID_FIELD)
+        throw new Error(
+          `Aggregate column ID "${column.id}" is used by more than one column.`
+        );
       if (!column.id || column.id.length > 256 || ids.has(column.id) || isComputedField(column.id) || ["__proto__", "constructor", "prototype"].includes(column.id))
         throw new Error(
-          "Aggregate column IDs must be unique and distinct from source fields."
+          "Aggregate column IDs must be 1\u2013256 characters and cannot be reserved names or @computed/ references."
         );
       ids.add(column.id);
+      if (column.op === "link") continue;
       if (column.op === "formula") {
         const error = summaryProblem(column);
         if (error) throw new Error(error);
@@ -3330,6 +3683,8 @@ function createGroupingModel(inputSchema) {
     summaryExpression,
     summaryProblem,
     summaryLabel,
+    linkProblem,
+    linkDiagnostics,
     resultSchema,
     groupRows,
     filteredInput,
@@ -3707,10 +4062,15 @@ function metricDateRange(config, query, observed, now, canonical) {
     if (term.op === "<" || term.op === "<=" || term.op === "=")
       end = Math.min(end, time - (term.op === "<" ? 1 : 0));
   }
-  if (!Number.isFinite(start) || !Number.isFinite(end))
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    const missing = [
+      ...Number.isFinite(start) ? [] : ["a lower bound (>= or >)"],
+      ...Number.isFinite(end) ? [] : ["an upper bound (<= or <)"]
+    ].join(" and ");
     throw Error(
-      "Include empty dates needs a bounded date filter. Choose observed dates or a custom range."
+      `Include empty dates with range "query" needs a bounded date filter on ${config.field}: add ${missing} as top-level filters (bounds inside OR groups do not count). Otherwise use range "observed" to fill from the first to the last observed date, or range "custom" with start and end.`
     );
+  }
   if (end < start) return void 0;
   return [
     metricDateFloor(start, config.interval, config.timeZone),
@@ -4039,6 +4399,15 @@ function validateMetric(c, schema, resolve) {
     }
     if (c.groupLimit !== void 0 && (!Number.isInteger(c.groupLimit) || c.groupLimit < 1 || c.groupLimit > 1e4))
       throw new FormulaError("Group limit must be 1\u201310,000.");
+    if (c.minCount !== void 0) {
+      if (!Number.isInteger(c.minCount) || c.minCount < 1 || c.minCount > 1e6)
+        throw new FormulaError("Minimum rows per group must be 1\u20131,000,000.");
+      if (!c.groupBy.length)
+        throw new FormulaError(
+          "Minimum rows per group requires at least one grouping field."
+        );
+    }
+    validateMetricWhere(c.where, schema);
     for (const s of c.sort ?? []) {
       if (s.key === "y" && c.display?.kind !== "scatter")
         throw new FormulaError("Y sorting requires a scatter metric.");
@@ -4063,6 +4432,35 @@ function validateMetric(c, schema, resolve) {
     ];
   }
 }
+function validateMetricWhere(where, schema) {
+  if (where === void 0) return;
+  if (!Array.isArray(where)) throw new FormulaError("Invalid metric filter.");
+  const predicates = where.flatMap((term) => predicatesOf(term));
+  if (predicates.length > MAX_WHERE_CLAUSES)
+    throw new FormulaError(
+      `A metric filter allows at most ${MAX_WHERE_CLAUSES} predicates.`
+    );
+  const fields = indexFields(schema);
+  for (const p of predicates) {
+    const name = resolveFieldName(schema, p.field) ?? p.field;
+    const field = fields.get(name);
+    if (!field || !isFilterable(field) || isComputedField(name) && !computedInputAllowed(schema, name, "filter"))
+      throw new FormulaError(`Field ${p.field} cannot filter metrics.`);
+    if (p.op === "matches_regex" || p.op === "not_matches_regex")
+      throw new FormulaError("Regex is unavailable in metric filters.");
+    if (!opsForField(field).includes(p.op))
+      throw new FormulaError(
+        `Field ${p.field} does not support the ${p.op} filter.`
+      );
+  }
+}
+function metricPopulationError(clause, support) {
+  if (clause.where?.length && !support.filters)
+    return "This server does not support metric filters.";
+  if (clause.minCount !== void 0 && !support.minCount)
+    return "This server does not support a minimum rows per group.";
+  return void 0;
+}
 function metricDependencies(c, schema, resolve) {
   return [
     .../* @__PURE__ */ new Set([
@@ -4084,6 +4482,8 @@ function metricComputationKey(clauses) {
       dateGrouping: c.dateGrouping,
       sort: c.sort,
       groupLimit: c.groupLimit,
+      where: c.where,
+      minCount: c.minCount,
       distribution: distributionActive(c) ? c.distribution : void 0
     })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
   );
@@ -4119,6 +4519,12 @@ function toMetricQuery(q, schema, execution) {
   const raw = q;
   q = normalizeQueryState(q);
   const server = toServerQuery(q, schema);
+  const metricWhere = /* @__PURE__ */ new Map();
+  for (const c of q.aggregations ?? [])
+    if (c.where?.length) {
+      const pushed = toServerQuery({ ...EMPTY_QUERY, where: c.where }, schema).where;
+      metricWhere.set(c.id, pushed);
+    }
   const metrics = (q.aggregations ?? []).map((c) => {
     const {
       label,
@@ -4128,10 +4534,12 @@ function toMetricQuery(q, schema, execution) {
       expression,
       expressionY,
       dateGrouping,
+      where,
       ...rest
     } = c;
     return {
       ...rest,
+      ...where?.length ? { where: metricWhere.get(c.id) ?? [] } : {},
       ...!distributionActive(c) && expression !== void 0 ? { expression } : {},
       ...display?.kind === "scatter" ? {
         display: { kind: "scatter" },
@@ -4147,6 +4555,15 @@ function toMetricQuery(q, schema, execution) {
       code: "invalid_metric"
     }))
   );
+  for (const c of q.aggregations ?? [])
+    if (c.where?.length && metricWhere.get(c.id)?.length !== c.where.length)
+      diagnostics.push({
+        metricId: c.id,
+        code: "residual_metric_filter",
+        from: 0,
+        to: 1,
+        message: "Metric filters must use server-filterable fields."
+      });
   for (const c of q.aggregations ?? [])
     if (c.dateGrouping)
       diagnostics.push({
@@ -4401,6 +4818,18 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
         }
         if (inputRows.length > (options2.maxRows ?? 1e6))
           throw Error("Metric row budget exceeded.");
+        const population = inputRows.length;
+        if (c.where?.length)
+          inputRows = applyQuery(
+            inputRows,
+            {
+              ...EMPTY_QUERY,
+              where: c.where,
+              limit: Number.MAX_SAFE_INTEGER
+            },
+            schema,
+            { now }
+          ).rows;
         const groups = /* @__PURE__ */ new Map();
         const keyLimit = options2.maxGroupKeyLength ?? 65536, byteLimit = options2.maxGroupBytes ?? 16e6;
         if (![keyLimit, byteLimit].every((v) => Number.isSafeInteger(v) && v >= 0))
@@ -4663,6 +5092,14 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
             }
           }
         }
+        let hiddenGroups;
+        if (c.minCount !== void 0) {
+          const kept = buckets.filter(
+            (b) => b.count === 0 || b.count >= c.minCount
+          );
+          hiddenGroups = buckets.length - kept.length;
+          buckets = kept;
+        }
         const ordering = c.sort?.length ? c.sort : c.dateGrouping ? [{ key: "group0", dir: "asc", nulls: "last" }] : [{ key: "value", dir: "desc", nulls: "last" }];
         const target = (b, s) => s.key === "samples" ? b.count - (b.nullCount ?? 0) - (b.inputErrorCount ?? 0) : s.key.startsWith("group") ? b.keys[Number(s.key.slice(5))] ?? null : s.key === "count" ? b.count : s.key === "y" ? b.y ?? null : b.value;
         buckets.sort((a, b) => {
@@ -4701,9 +5138,10 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           id: c.id,
           buckets,
           scope: c.scope ?? "allMatching",
-          processedRows: inputRows.length,
+          processedRows: population,
           groupCount,
           coverage: "exact",
+          ...hiddenGroups !== void 0 ? { hiddenGroups } : {},
           ...other ? { other } : {}
         };
       } catch (e) {
@@ -4785,7 +5223,7 @@ function applyAggregations(rows, q, schema, options2 = {}) {
   ))
     return evaluateMetrics(rows, q, schema, options2);
   const advanced = (q.aggregations ?? []).filter(
-    (a) => a.dateGrouping || a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.scope !== void 0 || a.distribution || a.sort || a.groupLimit !== void 0
+    (a) => a.dateGrouping || a.diagnostics?.length || a.expression !== void 0 || a.expressionY !== void 0 || a.scope !== void 0 || a.distribution || a.sort || a.groupLimit !== void 0 || a.where !== void 0 || a.minCount !== void 0
   );
   if (advanced.length) {
     if ((q.aggregations?.length ?? 0) > 20 || normalizeQueryState(q).aggregations?.length !== q.aggregations?.length)
@@ -5390,6 +5828,7 @@ function sourceDependencies(query, schema, resolveComputed) {
     model.validate(query.grouping);
     for (const key of query.grouping.keys) fields.add(key);
     for (const summary of query.grouping.summaries) {
+      if (summary.op === "link") continue;
       if (summary.op === "row") fields.add(summary.field);
       else for (const dependency of compileMetric(model.summaryExpression(summary), schema, resolveComputed).dependencies) fields.add(dependency);
     }
@@ -5424,6 +5863,242 @@ function sourceDependencies(query, schema, resolveComputed) {
   return { fields: [...fields].sort(), baseFields: [...base].sort(), identity: schema.idField, paths };
 }
 
+// src/queryPatch.ts
+function clauseKey(clause) {
+  return JSON.stringify([
+    clause.field,
+    clause.op,
+    NULLARY_OPS.has(clause.op) ? "" : clause.value,
+    clause.negated === true
+  ]);
+}
+function whereTermKey(term) {
+  if (!isOrGroup(term)) return clauseKey(term);
+  return `any:${JSON.stringify(term.any.map(clauseKey).sort())}`;
+}
+function appendWhereTerms(where, terms) {
+  const present = new Set(where.map(whereTermKey));
+  const out = [...where];
+  for (const term of terms) {
+    const key = whereTermKey(term);
+    if (present.has(key)) continue;
+    present.add(key);
+    out.push(term);
+  }
+  return out;
+}
+function filterUnits(where) {
+  const units = [];
+  for (const term of where) {
+    const last = units[units.length - 1];
+    const previous = last?.[last.length - 1];
+    if (last && previous && !isOrGroup(term) && !isOrGroup(previous) && term.op === "!=" && previous.op === "!=" && term.field === previous.field)
+      last.push(term);
+    else units.push([term]);
+  }
+  return units;
+}
+function unitPresent(unit, present) {
+  return unit.every((term) => present.has(whereTermKey(term)));
+}
+function removeUnits(where, units) {
+  const present = new Set(where.map(whereTermKey));
+  const remove = new Set(
+    units.filter((unit) => unitPresent(unit, present)).flatMap((unit) => unit.map(whereTermKey))
+  );
+  return where.filter((term) => !remove.has(whereTermKey(term)));
+}
+function sameTermSet(a, b) {
+  const keys = (where) => JSON.stringify(where.map(whereTermKey).sort());
+  return keys(a) === keys(b);
+}
+function patchParts(patch) {
+  const raw = patch.query ?? {};
+  const normalized = normalizeQueryState(raw);
+  const stage = normalized.grouping ? "groups" : "records";
+  const filters = normalized.grouping ? normalized.grouping.source.where : normalized.where;
+  const owns = new Set(patch.owns);
+  if (typeof raw.limit !== "number") owns.delete("limit");
+  return {
+    owns,
+    stage,
+    filters,
+    units: filterUnits(filters),
+    grouping: normalized.grouping ? {
+      keys: normalized.grouping.keys,
+      summaries: normalized.grouping.summaries,
+      representative: normalized.grouping.representative,
+      having: normalized.where
+    } : null,
+    select: normalized.select,
+    orderBy: normalized.orderBy,
+    limit: typeof raw.limit === "number" ? normalized.limit : void 0,
+    aggregations: normalized.aggregations ?? []
+  };
+}
+var recordStage = (query) => query.grouping?.source ?? query;
+function withRecordStage(query, next) {
+  return query.grouping ? { ...query, grouping: { ...query.grouping, source: next } } : next;
+}
+function stageOf(query, stage) {
+  if (stage === "records") return recordStage(query);
+  return query.grouping ? query : void 0;
+}
+function withStage(query, stage, update) {
+  if (stage === "records") return withRecordStage(query, update(recordStage(query)));
+  return query.grouping ? update(query) : query;
+}
+function withAggregations(query, aggregations) {
+  const { aggregations: _previous, ...rest } = query;
+  return aggregations.length ? { ...rest, aggregations } : rest;
+}
+var clone2 = (value) => structuredClone(value);
+var summaryMeaning = ({ id, op, field, expression, link }) => JSON.stringify(op === "link" ? [id, op, link ?? null] : [id, op, field, expression]);
+function summarySignature(summaries) {
+  return JSON.stringify(summaries.map(summaryMeaning));
+}
+function canonicalJson(value) {
+  return JSON.stringify(
+    value,
+    (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) : item
+  );
+}
+function metricSignature(metric) {
+  const { id: _id, label: _label, display: _display, layout: _layout, ...rest } = metric;
+  return canonicalJson(rest);
+}
+function facetMatches(query, parts, facet) {
+  switch (facet) {
+    case "filters": {
+      const present = new Set(recordStage(query).where.map(whereTermKey));
+      return parts.units.every((unit) => unitPresent(unit, present));
+    }
+    case "grouping": {
+      const grouping = query.grouping;
+      if (!parts.grouping || !grouping) return !parts.grouping && !grouping;
+      return JSON.stringify(grouping.keys) === JSON.stringify(parts.grouping.keys) && summarySignature(grouping.summaries) === summarySignature(parts.grouping.summaries) && JSON.stringify(grouping.representative) === JSON.stringify(parts.grouping.representative) && sameTermSet(query.where, parts.grouping.having);
+    }
+    case "columns": {
+      const stage = stageOf(query, parts.stage);
+      return !!stage && JSON.stringify(stage.select.map((c) => c.field)) === JSON.stringify(parts.select.map((c) => c.field));
+    }
+    case "order": {
+      const stage = stageOf(query, parts.stage);
+      return !!stage && JSON.stringify(stage.orderBy) === JSON.stringify(parts.orderBy);
+    }
+    case "limit": {
+      const stage = stageOf(query, parts.stage);
+      return !!stage && stage.limit === parts.limit;
+    }
+    case "metrics": {
+      const stage = stageOf(query, parts.stage);
+      const signatures = (metrics) => JSON.stringify(metrics.map(metricSignature).sort());
+      return !!stage && signatures(stage.aggregations ?? []) === signatures(parts.aggregations);
+    }
+  }
+}
+function matchPatch(query, patch) {
+  const normalized = normalizeQueryState(query);
+  const parts = patchParts(patch);
+  const owned = [...parts.owns];
+  const modified = owned.filter((facet) => !facetMatches(normalized, parts, facet));
+  if (!modified.length) return { status: "active", modified: [] };
+  const present = new Set(recordStage(normalized).where.map(whereTermKey));
+  const recognizable = owned.some((facet) => !modified.includes(facet) && (facet !== "filters" || parts.units.length > 0)) || parts.owns.has("filters") && parts.units.some((unit) => unitPresent(unit, present));
+  return recognizable ? { status: "modified", modified } : { status: "inactive", modified: [] };
+}
+function resetOffsets(query) {
+  return query.grouping ? { ...query, offset: 0, grouping: { ...query.grouping, source: { ...query.grouping.source, offset: 0 } } } : { ...query, offset: 0 };
+}
+function applyGrouping(query, grouping) {
+  if (!grouping) return exitGrouping(query);
+  const before = query.grouping;
+  const keyed = before && JSON.stringify(before.keys) === JSON.stringify(grouping.keys) ? query : withGroupingKeys(query, grouping.keys);
+  const previous = keyed.grouping;
+  const summaries = clone2(grouping.summaries);
+  const kept = new Set(summaries.map(summaryMeaning));
+  const changed = new Set(previous.summaries.filter((column) => !kept.has(summaryMeaning(column))).map((column) => column.id));
+  const next = {
+    ...keyed,
+    grouping: { ...previous, summaries, representative: clone2(grouping.representative) },
+    where: clone2(grouping.having),
+    select: keyed.select.filter((c) => !changed.has(c.field)),
+    orderBy: keyed.orderBy.filter((term) => !changed.has(term.field))
+  };
+  return changed.size ? withAggregations(next, []) : next;
+}
+function removePatch(query, patch) {
+  const parts = patchParts(patch);
+  const matches = (facet) => parts.owns.has(facet) && facetMatches(normalizeQueryState(query), parts, facet);
+  const reset = {
+    columns: matches("columns"),
+    order: matches("order"),
+    metrics: matches("metrics"),
+    grouping: matches("grouping")
+  };
+  let next = query;
+  if (parts.owns.has("filters")) {
+    const records = recordStage(next);
+    next = withRecordStage(next, { ...records, where: removeUnits(records.where, parts.units) });
+  }
+  next = withStage(next, parts.stage, (stage) => {
+    let out = stage;
+    if (reset.columns) out = { ...out, select: [] };
+    if (reset.order) out = { ...out, orderBy: [] };
+    if (reset.metrics) out = withAggregations(out, []);
+    return out;
+  });
+  if (reset.grouping) next = exitGrouping(next);
+  return resetOffsets(next);
+}
+function applyPatch(query, patch, options2 = {}) {
+  let next = options2.replacing ? removePatch(query, options2.replacing) : query;
+  const parts = patchParts(patch);
+  if (parts.owns.has("grouping")) next = applyGrouping(next, parts.grouping);
+  if (parts.owns.has("filters")) {
+    const records = recordStage(next);
+    next = withRecordStage(next, { ...records, where: appendWhereTerms(records.where, clone2(parts.filters)) });
+  }
+  next = withStage(next, parts.stage, (stage) => {
+    let out = stage;
+    if (parts.owns.has("columns")) out = { ...out, select: clone2(parts.select) };
+    if (parts.owns.has("order")) out = { ...out, orderBy: clone2(parts.orderBy) };
+    if (parts.owns.has("limit")) out = { ...out, limit: parts.limit ?? out.limit };
+    if (parts.owns.has("metrics")) out = withAggregations(out, clone2(parts.aggregations));
+    return out;
+  });
+  return resetOffsets(next);
+}
+
+// src/groupLinks.ts
+function withoutLinkSummaries(summaries) {
+  return summaries.filter((column) => column.op !== "link");
+}
+function groupLinkQuery(query, value) {
+  const to = value.to;
+  if (!query.grouping || to?.kind !== "query" || value.problem) return null;
+  const base = to.base === "empty" ? structuredClone(EMPTY_QUERY) : exitGrouping(query);
+  if (to.keyFilters !== false && !value.terms) return null;
+  const filtered = { ...base, where: appendWhereTerms(base.where, value.terms ?? []), offset: 0 };
+  return to.patch ? applyPatch(filtered, to.patch) : filtered;
+}
+function resolveGroupLink(query, value, targets = {}) {
+  const unresolved = (problem) => ({ label: value.label, href: null, problem });
+  if (value.problem) return unresolved(value.problem);
+  if (value.to?.kind === "template") return value.href ? { label: value.label, href: value.href } : unresolved("Invalid link.");
+  if (value.to?.kind !== "query") return unresolved("Invalid link definition.");
+  const route = Object.prototype.hasOwnProperty.call(targets, value.to.target) ? targets[value.to.target] : void 0;
+  if (typeof route !== "function") return unresolved(`Link target "${value.to.target}" is not registered.`);
+  const destination = groupLinkQuery(query, value);
+  if (!destination) return unresolved("This group cannot be matched exactly.");
+  try {
+    const href = route(destination, { ...value.to.params });
+    return typeof href === "string" && href.trim() ? { label: value.label, href } : unresolved(`Link target "${value.to.target}" returned no URL.`);
+  } catch (error) {
+    return unresolved(`Link target "${value.to.target}" failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 // src/queryV3.ts
 function sourceExecutionSchema(schema, execution, catalogue = []) {
   const fields = new Map(schema.fields.map((field) => [field.name, field]));
@@ -5473,7 +6148,9 @@ function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 =
     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.");
   }
-  const metrics = toMetricQuery(withoutGrouping(q), resultSchema, execution).metrics.map((metric) => {
+  const metricQuery = toMetricQuery(withoutGrouping(q), resultSchema, execution);
+  diagnostics.push(...metricQuery.diagnostics.filter((issue) => issue.code === "residual_metric_filter").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;
   });
@@ -5497,7 +6174,9 @@ function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 =
     result,
     ...q.grouping ? { grouping: {
       keys: q.grouping.keys,
-      summaries: q.grouping.summaries,
+      // 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 } : {}
     } } : {},
@@ -5520,6 +6199,68 @@ function validateQueryResultV3(result, request, schema) {
     seen.add(id);
   }
 }
+
+// src/drilldown.ts
+function metricSchema(query, schema) {
+  if (!query.grouping || schema.idField === GROUP_ID_FIELD) return schema;
+  return createGroupingModel(schema).resultSchema(query.grouping.keys, query.grouping.summaries);
+}
+function distributionActive2(clause) {
+  return !!clause.distribution && (!clause.display || clause.display.kind === "box" || clause.display.kind === "histogram");
+}
+function inspectBucketQuery(query, bucket, clause, schema) {
+  if (clause.scope === "shownRows" || bucket.keys.length !== clause.groupBy.length) return null;
+  const fields = metricSchema(query, schema);
+  const terms = [...clause.where ?? []];
+  for (const [index, name] of clause.groupBy.entries()) {
+    const field = resolveField(fields, name);
+    const key = bucket.keys[index] ?? null;
+    if (clause.dateGrouping && index === 0 && key !== null) {
+      if (!field || field.type !== "datetime" || !isFilterable(field)) return null;
+      let start;
+      try {
+        start = metricDateTime(key);
+      } catch {
+        return null;
+      }
+      const { interval, timeZone } = clause.dateGrouping;
+      const next = metricDateNext(start, interval, timeZone);
+      terms.push(
+        { field: field.name, op: ">=", value: new Date(start).toISOString() },
+        { field: field.name, op: "<", value: new Date(next).toISOString() }
+      );
+      continue;
+    }
+    const term = keyClause(field, key);
+    if (!term) return null;
+    terms.push(term);
+  }
+  if (bucket.bin) {
+    const { min, max, inclusiveMax } = bucket.bin;
+    if (!distributionActive2(clause) || clause.distribution.kind !== "histogram" || !Number.isFinite(min) || !Number.isFinite(max) || max < min)
+      return null;
+    let input;
+    try {
+      input = compileFormula(clause.distribution.input, fields.fields).ast;
+    } catch {
+      return null;
+    }
+    const field = input.kind === "field" ? resolveField(fields, input.name) : void 0;
+    if (!field || field.type !== "number" || !isFilterable(field)) return null;
+    terms.push(
+      { field: field.name, op: ">=", value: String(min) },
+      { field: field.name, op: inclusiveMax ? "<=" : "<", value: String(max) }
+    );
+  }
+  return { ...query, where: appendWhereTerms(query.where, terms), offset: 0 };
+}
+function groupSourceQuery(query, group, schema) {
+  if (!query.grouping) return null;
+  const terms = groupKeyTerms(query.grouping.keys, group, schema);
+  if (!terms) return null;
+  const source = exitGrouping(query);
+  return { ...source, where: appendWhereTerms(source.where, terms), offset: 0 };
+}
 export {
   AGG_OPS_BY_TYPE,
   AGG_OPS_NEEDING_FIELD,
@@ -5528,6 +6269,7 @@ export {
   FORMULA_FUNCTIONS,
   FormulaError,
   GROUP_ID_FIELD,
+  GROUP_LINK_RENDER,
   ITEM_DETAILS_COLUMN,
   MAX_AGGREGATIONS,
   MAX_GROUP_BY_FIELDS,
@@ -5554,6 +6296,7 @@ export {
   aggOpNeedsField,
   aggOpsForField,
   applyAggregations,
+  applyPatch,
   applyQuery,
   boxSummary,
   coerceValue,
@@ -5571,18 +6314,24 @@ export {
   encodeQuery,
   evaluateMetricReductions,
   evaluateMetrics,
+  exitGrouping,
   filterValues,
   formulaRuntime,
+  groupLinkQuery,
   groupPreview,
+  groupSourceQuery,
   hasRegex,
   histogramCounts,
   histogramEdges,
   httpComputedColumnStore,
   httpQuerySnapshotStore,
   indexFields,
+  inspectBucketQuery,
   isComputedCellError,
   isComputedField,
   isFilterable,
+  isGroupLinkField,
+  isGroupLinkValue,
   isGroupable,
   isMeasurable,
   isNegativePredicate,
@@ -5597,6 +6346,7 @@ export {
   localQuerySnapshotCache,
   localStorageAdapter,
   mapSetFilterValues,
+  matchPatch,
   matchesClause,
   memoryComputedColumnStore,
   memoryPropertyViewStorage,
@@ -5611,6 +6361,7 @@ export {
   metricDependencies,
   metricExpression,
   metricPlans,
+  metricPopulationError,
   negateClause,
   normalizePropertyFormat,
   normalizePropertyView,
@@ -5628,10 +6379,14 @@ export {
   readObjectReference,
   readSetFilter,
   reduceMetricValues,
+  removePatch,
   renderItemPageTemplate,
   resolveFieldName,
+  resolveGroupLink,
   selectMetricShownRows,
   selectedFields,
+  setFilterModes,
+  setFilterTarget,
   sourceDependencies,
   sourceExecutionSchema,
   stripSetFilter,
@@ -5646,6 +6401,8 @@ export {
   validateMetric,
   validateQueryResultV3,
   validateQuerySnapshot,
-  withoutGrouping
+  withGroupingKeys,
+  withoutGrouping,
+  withoutLinkSummaries
 };
 //# sourceMappingURL=index.js.map