@pythia-software/query-table-core 0.9.4 → 0.9.6

package/dist/index.js

@@ -445,6 +445,101 @@ function renderItemPageTemplate(template, schema, row, id, query) {
 }
 
 // src/metricNormalize.ts
+var METRIC_OPTION_SPECS = {
+  top: {
+    expression: "string",
+    expressionY: "string",
+    scope: ["allMatching", "shownRows"],
+    groupLimit: "integer",
+    minCount: "positiveInteger",
+    share: ["total", "group0"]
+  },
+  window: {
+    reduce: ["total", "mean"],
+    partial: ["omit", "include"]
+  },
+  dateGrouping: {
+    field: "string",
+    interval: ["hour", "day", "week", "month", "year"],
+    timeZone: "string",
+    includeEmpty: "boolean",
+    range: ["query", "observed", "custom"],
+    start: "string",
+    end: "string",
+    partialIntervals: ["include", "exclude"]
+  },
+  display: {
+    kind: [
+      "auto",
+      "value",
+      "table",
+      "list",
+      "bar-horizontal",
+      "bar-vertical",
+      "line",
+      "pie",
+      "donut",
+      "scatter",
+      "box",
+      "histogram"
+    ],
+    valueLabel: "string",
+    xLabel: "string",
+    yLabel: "string",
+    legendPosition: ["left", "right", "top", "bottom", "none"],
+    maxGroups: "positiveInteger",
+    showOther: "boolean",
+    boxMean: "boolean"
+  },
+  scale: {
+    mode: ["linear", "log"],
+    min: "number",
+    max: "number"
+  },
+  format: {
+    kind: ["number", "percent", "duration", "date", "time", "datetime"],
+    decimals: "integer",
+    sourceUnit: [
+      "milliseconds",
+      "seconds",
+      "minutes",
+      "hours",
+      "days",
+      "iso",
+      "epochSeconds",
+      "epochMilliseconds",
+      "secondsOfDay",
+      "millisecondsOfDay"
+    ],
+    style: ["human", "long", "clock", "custom", "iso"],
+    pattern: "string",
+    timeZone: "string"
+  },
+  list: {
+    showBars: "boolean",
+    useGroupColors: "boolean",
+    showValues: "boolean",
+    barPosition: ["inline", "below"],
+    maxLabelLines: "positiveInteger"
+  },
+  pivot: {
+    swap: "boolean",
+    rowDir: ["asc", "desc"],
+    columnDir: ["asc", "desc"]
+  },
+  distribution: {
+    kind: ["box", "histogram"],
+    input: "string",
+    whiskers: ["minmax", "tukey"],
+    bins: "integer"
+  },
+  layout: {
+    widthRem: "integer",
+    heightRem: "integer",
+    minWidthRem: "integer",
+    minHeightRem: "integer"
+  }
+};
 function normalizeMetricOptions(raw) {
   const out = {}, diagnostics = [];
   const record2 = (x) => !!x && typeof x === "object" && !Array.isArray(x);
@@ -461,25 +556,21 @@ function normalizeMetricOptions(raw) {
   };
   Object.assign(
     out,
-    copy(raw, {
-      expression: "string",
-      expressionY: "string",
-      scope: ["allMatching", "shownRows"],
-      groupLimit: "integer",
-      minCount: "positiveInteger"
-    })
+    copy(raw, METRIC_OPTION_SPECS.top)
   );
+  if (raw.window !== void 0) {
+    if (record2(raw.window)) {
+      const w = copy(raw.window, METRIC_OPTION_SPECS.window);
+      const periods = raw.window.periods;
+      if (periods === "all" || Number.isSafeInteger(periods) && periods >= 0 && periods <= 1e6)
+        w.periods = periods;
+      else diagnostics.push("Invalid metric window.");
+      out.window = w;
+    } else diagnostics.push("Invalid metric window.");
+  }
   if (raw.dateGrouping !== void 0) {
     if (record2(raw.dateGrouping)) {
-      const d = copy(raw.dateGrouping, {
-        field: "string",
-        interval: ["hour", "day", "week", "month", "year"],
-        timeZone: "string",
-        includeEmpty: "boolean",
-        range: ["query", "observed", "custom"],
-        start: "string",
-        end: "string"
-      });
+      const d = copy(raw.dateGrouping, METRIC_OPTION_SPECS.dateGrouping);
       if (typeof d.field !== "string" || !d.field || d.field.length > 256 || !d.interval || typeof d.includeEmpty !== "boolean" || !d.range)
         diagnostics.push("Invalid metric date grouping.");
       out.dateGrouping = d;
@@ -489,94 +580,30 @@ function normalizeMetricOptions(raw) {
     if (record2(raw.display)) {
       if (typeof raw.display.kind !== "string")
         diagnostics.push("Invalid metric display kind.");
-      const d = copy(raw.display, {
-        kind: [
-          "auto",
-          "value",
-          "table",
-          "list",
-          "bar-horizontal",
-          "bar-vertical",
-          "line",
-          "pie",
-          "donut",
-          "scatter",
-          "box",
-          "histogram"
-        ],
-        valueLabel: "string",
-        xLabel: "string",
-        yLabel: "string",
-        legendPosition: ["left", "right", "top", "bottom", "none"],
-        maxGroups: "positiveInteger",
-        showOther: "boolean",
-        boxMean: "boolean"
-      });
+      const d = copy(raw.display, METRIC_OPTION_SPECS.display);
       for (const k of ["xScale", "yScale"]) {
         if (record2(raw.display[k]))
-          d[k] = copy(raw.display[k], {
-            mode: ["linear", "log"],
-            min: "number",
-            max: "number"
-          });
+          d[k] = copy(raw.display[k], METRIC_OPTION_SPECS.scale);
         else if (raw.display[k] !== void 0)
           diagnostics.push(`Invalid metric ${k}.`);
       }
       for (const k of ["format", "xFormat", "yFormat"])
         if (record2(raw.display[k]))
-          d[k] = copy(raw.display[k], {
-            kind: ["number", "percent", "duration", "date", "time", "datetime"],
-            decimals: "integer",
-            sourceUnit: [
-              "milliseconds",
-              "seconds",
-              "minutes",
-              "hours",
-              "days",
-              "iso",
-              "epochSeconds",
-              "epochMilliseconds",
-              "secondsOfDay",
-              "millisecondsOfDay"
-            ],
-            style: ["human", "long", "clock", "custom", "iso"],
-            pattern: "string",
-            timeZone: "string"
-          });
+          d[k] = copy(raw.display[k], METRIC_OPTION_SPECS.format);
       if (record2(raw.display.list))
-        d.list = copy(raw.display.list, {
-          showBars: "boolean",
-          useGroupColors: "boolean",
-          showValues: "boolean",
-          barPosition: ["inline", "below"],
-          maxLabelLines: "positiveInteger"
-        });
+        d.list = copy(raw.display.list, METRIC_OPTION_SPECS.list);
       if (record2(raw.display.pivot))
-        d.pivot = copy(raw.display.pivot, {
-          swap: "boolean",
-          rowDir: ["asc", "desc"],
-          columnDir: ["asc", "desc"]
-        });
+        d.pivot = copy(raw.display.pivot, METRIC_OPTION_SPECS.pivot);
       out.display = { kind: "auto", ...d };
     } else diagnostics.push("Invalid metric display.");
   }
   if (raw.distribution !== void 0) {
     if (record2(raw.distribution))
-      out.distribution = copy(raw.distribution, {
-        kind: ["box", "histogram"],
-        input: "string",
-        whiskers: ["minmax", "tukey"],
-        bins: "integer"
-      });
+      out.distribution = copy(raw.distribution, METRIC_OPTION_SPECS.distribution);
     else diagnostics.push("Invalid metric distribution.");
   }
   if (record2(raw.layout)) {
-    const l = copy(raw.layout, {
-      widthRem: "integer",
-      heightRem: "integer",
-      minWidthRem: "integer",
-      minHeightRem: "integer"
-    });
+    const l = copy(raw.layout, METRIC_OPTION_SPECS.layout);
     for (const k of ["widthRem", "heightRem", "minWidthRem", "minHeightRem"])
       l[k] = Math.max(1, Math.min(1e3, Number(l[k] ?? 1)));
     l.widthRem = Math.max(Number(l.widthRem), Number(l.minWidthRem));
@@ -684,7 +711,7 @@ function cloneWhereTerm(term) {
 function normalizeSetFilter(item) {
   if (!isRecord(item)) return void 0;
   const id = boundedString(item.id, MAX_FIELD_NAME_LENGTH);
-  if (!id || !["any", "all", "none", "empty"].includes(String(item.mode)) || !Array.isArray(item.values)) return void 0;
+  if (!id || typeof item.mode !== "string" || !["any", "all", "none", "empty"].includes(item.mode) || !Array.isArray(item.values)) return void 0;
   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] };
 }
@@ -1251,7 +1278,7 @@ function toBase64Url(json) {
 }
 function fromBase64Url(s) {
   const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
-  if (typeof Buffer !== "undefined") return Buffer.from(b64, "base64").toString("utf8");
+  if (typeof Buffer !== "undefined") return Buffer.from(b64, "base64").toString("utf8").replace(/^\uFEFF/, "");
   const bin = atob(b64);
   const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
   return new TextDecoder().decode(bytes);
@@ -3066,32 +3093,661 @@ function formulaRuntime(ast, inputs, extension) {
         out = Math.trunc((date(c).getTime() - date(b).getTime()) / ms);
         break;
       }
-      case "FORMAT_DATE": {
-        const d = date(a), pad = (n2) => String(n2).padStart(2, "0"), parts2 = {
-          YYYY: String(d.getUTCFullYear()).padStart(4, "0"),
-          MM: pad(d.getUTCMonth() + 1),
-          DD: pad(d.getUTCDate()),
-          HH: pad(d.getUTCHours()),
-          mm: pad(d.getUTCMinutes()),
-          ss: pad(d.getUTCSeconds())
-        };
-        out = str(b).replace(/YYYY|MM|DD|HH|mm|ss/g, (t) => parts2[t]);
-        break;
+      case "FORMAT_DATE": {
+        const d = date(a), pad = (n2) => String(n2).padStart(2, "0"), parts2 = {
+          YYYY: String(d.getUTCFullYear()).padStart(4, "0"),
+          MM: pad(d.getUTCMonth() + 1),
+          DD: pad(d.getUTCDate()),
+          HH: pad(d.getUTCHours()),
+          mm: pad(d.getUTCMinutes()),
+          ss: pad(d.getUTCSeconds())
+        };
+        out = str(b).replace(/YYYY|MM|DD|HH|mm|ss/g, (t) => parts2[t]);
+        break;
+      }
+      default:
+        return fail(`Unknown operation: ${name}`);
+    }
+    return bound(out);
+  }
+  try {
+    const value = run(ast);
+    return inspection ? { value, regex: inspection } : { value };
+  } catch (e) {
+    return {
+      value: null,
+      error: e instanceof Error ? e.message : "Formula evaluation failed."
+    };
+  }
+}
+
+// src/metricDates.ts
+import { Temporal } from "temporal-polyfill";
+var METRIC_DATE_INTERVALS = [
+  "hour",
+  "day",
+  "week",
+  "month",
+  "year"
+];
+function metricDateTime(value, timeZone = "UTC") {
+  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(
+    value
+  ))
+    throw Error(
+      "Date grouping requires ISO dates or timestamps with a timezone."
+    );
+  const time = Date.parse(value), month = Number(value.slice(5, 7)), day = Number(value.slice(8, 10));
+  const calendar = /* @__PURE__ */ new Date(0);
+  calendar.setUTCFullYear(Number(value.slice(0, 4)), month, 0);
+  if (!Number.isFinite(time) || month < 1 || month > 12 || day < 1 || day > calendar.getUTCDate())
+    throw Error("Invalid date grouping value.");
+  return value.length === 10 && timeZone !== "UTC" ? Temporal.PlainDate.from(value).toZonedDateTime(timeZone).epochMilliseconds : time;
+}
+function metricOffsetTransition(start, end, timeZone) {
+  if (end <= start) return void 0;
+  const offset = (time) => Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone).offsetNanoseconds;
+  const before = offset(start);
+  if (before === offset(end)) return void 0;
+  while (end - start > 1) {
+    const middle = Math.floor((start + end) / 2);
+    if (offset(middle) === before) start = middle;
+    else end = middle;
+  }
+  return end;
+}
+function metricDateFloor(time, interval, timeZone = "UTC") {
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const floor = time - zoned.minute * 6e4 - zoned.second * 1e3 - zoned.millisecond;
+      return metricOffsetTransition(floor, time, timeZone) ?? floor;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "week") date2 = date2.subtract({ days: date2.dayOfWeek - 1 });
+    if (interval === "month" || interval === "year")
+      date2 = date2.with({ day: 1 });
+    if (interval === "year") date2 = date2.with({ month: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  date.setUTCMinutes(0, 0, 0);
+  if (interval !== "hour") date.setUTCHours(0);
+  if (interval === "week")
+    date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
+  if (interval === "month" || interval === "year") date.setUTCDate(1);
+  if (interval === "year") date.setUTCMonth(0);
+  return date.getTime();
+}
+function metricDateNext(time, interval, timeZone = "UTC") {
+  if (timeZone !== "UTC") {
+    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
+    if (interval === "hour") {
+      const target = zoned.toPlainDateTime().with({
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+        microsecond: 0,
+        nanosecond: 0
+      }).add({ hours: 1 });
+      let next = target.toZonedDateTime(timeZone).epochMilliseconds;
+      if (next <= time)
+        next = target.toZonedDateTime(timeZone, {
+          disambiguation: "later"
+        }).epochMilliseconds;
+      return metricOffsetTransition(time, next, timeZone) ?? next;
+    }
+    let date2 = zoned.toPlainDate();
+    if (interval === "month") date2 = date2.with({ day: 1 }).add({ months: 1 });
+    else if (interval === "year")
+      date2 = date2.with({ month: 1, day: 1 }).add({ years: 1 });
+    else if (interval === "week")
+      date2 = date2.subtract({ days: date2.dayOfWeek - 1 }).add({ weeks: 1 });
+    else date2 = date2.add({ days: 1 });
+    return date2.toZonedDateTime(timeZone).epochMilliseconds;
+  }
+  const date = new Date(time);
+  if (interval === "hour") date.setUTCHours(date.getUTCHours() + 1);
+  else if (interval === "month") date.setUTCMonth(date.getUTCMonth() + 1);
+  else if (interval === "year") date.setUTCFullYear(date.getUTCFullYear() + 1);
+  else date.setUTCDate(date.getUTCDate() + (interval === "week" ? 7 : 1));
+  return date.getTime();
+}
+function metricCustomEndTime(value, timeZone = "UTC") {
+  const time = metricDateTime(value, timeZone);
+  return value.length === 10 ? metricDateNext(time, "day", timeZone) - 1 : time;
+}
+function validateDateGrouping(config) {
+  if (typeof config.field !== "string" || !config.field || config.field.length > 256 || !METRIC_DATE_INTERVALS.includes(config.interval) || typeof config.includeEmpty !== "boolean" || !["query", "observed", "custom"].includes(config.range) || config.partialIntervals !== void 0 && !["include", "exclude"].includes(config.partialIntervals))
+    throw Error("Invalid date grouping definition.");
+  if (config.timeZone !== void 0) {
+    if (typeof config.timeZone !== "string" || !config.timeZone || config.timeZone.length > 80 || /^[+-]/.test(config.timeZone))
+      throw Error(
+        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
+      );
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: config.timeZone });
+    } catch {
+      throw Error(
+        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
+      );
+    }
+  }
+  if (config.includeEmpty && config.range === "custom") {
+    const start = metricDateTime(config.start ?? "", config.timeZone), end = metricCustomEndTime(config.end ?? "", config.timeZone);
+    if (end < start)
+      throw Error("The end date must be on or after the start date.");
+  }
+}
+function metricDateRange(config, query, observed, now, canonical) {
+  let min = Infinity, max = -Infinity;
+  for (const time of observed) {
+    min = Math.min(min, time);
+    max = Math.max(max, time);
+  }
+  if (config.range === "observed")
+    return observed.length ? [min, max] : void 0;
+  if (config.range === "custom") {
+    const start2 = metricDateFloor(
+      metricDateTime(config.start ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    const end2 = metricDateFloor(
+      metricCustomEndTime(config.end ?? "", config.timeZone),
+      config.interval,
+      config.timeZone
+    );
+    if (observed.length && (start2 > min || end2 < max))
+      throw Error(
+        "Custom date bounds must include all observed buckets. Narrow the query filters to exclude data."
+      );
+    return [start2, end2];
+  }
+  let start = -Infinity, end = Infinity;
+  for (const term of query.where) {
+    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(config.field))
+      continue;
+    if (!["=", ">", ">=", "<", "<="].includes(term.op)) continue;
+    const time = Number(coerceValue("datetime", term.value, now));
+    if (term.op === ">" || term.op === ">=" || term.op === "=")
+      start = Math.max(start, time + (term.op === ">" ? 1 : 0));
+    if (term.op === "<" || term.op === "<=" || term.op === "=")
+      end = Math.min(end, time - (term.op === "<" ? 1 : 0));
+  }
+  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 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),
+    metricDateFloor(end, config.interval, config.timeZone)
+  ];
+}
+
+// src/metricPrecision.ts
+function assertMetricNumber(value) {
+  if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) {
+    throw Error("Aggregate exceeds finite safe numeric precision.");
+  }
+}
+function checkedMetricResult(result) {
+  if (result.error || typeof result.value !== "number") return result;
+  try {
+    assertMetricNumber(result.value);
+    return result;
+  } catch (e) {
+    return { value: null, error: e.message };
+  }
+}
+
+// src/metricSeries.ts
+var MAX_METRIC_WINDOW_PERIODS = 1e3;
+var MERGEABLE = ["SUM", "COUNT", "MIN", "MAX", "AVG"];
+function hasMetricSeries(c) {
+  return c.window !== void 0 || c.share !== void 0 || c.dateGrouping?.partialIntervals !== void 0;
+}
+var soleAggregate = (plan) => plan.ast.kind === "call" && plan.aggregates.includes(plan.ast) ? plan.ast.name : void 0;
+var partBudget = (c, plan) => (c.window && (c.window.reduce ?? "total") === "total" ? plan.aggregates.reduce((n, node) => n + (node.name === "AVG" ? 2 : 1), 0) : 1) * (c.share ? 2 : 1);
+function validateMetricSeries(c, plan) {
+  const { window, share } = c;
+  if (!window && share === void 0) return;
+  if (!("aggregates" in plan) || c.display?.kind === "scatter")
+    throw new FormulaError(
+      "Windows and shares apply to single-value metrics, not distributions or scatters."
+    );
+  const metric = plan, sole = soleAggregate(metric);
+  if (window) {
+    if (!c.dateGrouping)
+      throw new FormulaError(
+        "A window needs a calendar interval on the first grouping field."
+      );
+    if (!c.dateGrouping.includeEmpty)
+      throw new FormulaError(
+        "A window spans every interval, including empty ones: include empty dates."
+      );
+    const { periods, reduce = "total", partial = "omit" } = window;
+    if (periods !== "all" && !(Number.isInteger(periods) && periods >= 2 && periods <= MAX_METRIC_WINDOW_PERIODS))
+      throw new FormulaError(
+        "A window covers 2\u20131,000 intervals, or all of them."
+      );
+    if (!["total", "mean"].includes(reduce) || !["omit", "include"].includes(partial))
+      throw new FormulaError("Invalid metric window.");
+    if (reduce === "mean") {
+      if (!sole || !["SUM", "COUNT", "COUNT_DISTINCT"].includes(sole))
+        throw new FormulaError(
+          "A mean per interval needs a single SUM, COUNT or COUNT_DISTINCT; it would weight each interval's ratio or average equally. A window total pools them instead."
+        );
+    } else
+      for (const node of metric.aggregates)
+        if (!MERGEABLE.includes(node.name))
+          throw new FormulaError(
+            node.name === "COUNT_DISTINCT" ? "A window total cannot combine COUNT_DISTINCT across intervals, because one value can occur in several. Use a mean per interval." : `A window total cannot combine ${node.name} across intervals.`,
+            node.from,
+            node.to
+          );
+  }
+  if (share !== void 0) {
+    if (share !== "total" && share !== "group0")
+      throw new FormulaError("Invalid metric share.");
+    if (sole !== "SUM" && sole !== "COUNT")
+      throw new FormulaError(
+        "A share divides additive totals: use a single SUM or COUNT. Distinct counts, averages and ratios do not add up across groups."
+      );
+    if (share === "group0" ? c.groupBy.length < 2 : !c.groupBy.length)
+      throw new FormulaError(
+        share === "group0" ? "A share within the first grouping needs a second grouping field." : "A share of the total needs a grouping field."
+      );
+    if (share === "total" && window)
+      throw new FormulaError(
+        "A windowed share divides by each interval's own total: share within the first grouping."
+      );
+  }
+  if (partBudget(c, metric) > MAX_AGGREGATIONS)
+    throw new FormulaError(
+      `A window or share runs one metric per aggregate; this one needs more than ${MAX_AGGREGATIONS}.`
+    );
+}
+function wholeIntervalSpan(c, query, schema, now) {
+  const { field, interval, timeZone } = c.dateGrouping;
+  const canonical = (name) => resolveFieldName(schema, name) ?? name;
+  let lower = -Infinity, upper = Infinity;
+  for (const term of [...query.where, ...c.where ?? []]) {
+    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(field) || !["=", ">", ">=", "<", "<="].includes(term.op))
+      continue;
+    if (term.value === "") continue;
+    let time;
+    try {
+      time = Number(coerceValue("datetime", term.value, now));
+    } catch {
+      continue;
+    }
+    if (!Number.isFinite(time)) continue;
+    if (term.op === ">" || term.op === ">=" || term.op === "=")
+      lower = Math.max(lower, time + (term.op === ">" ? 1 : 0));
+    if (term.op === "<" || term.op === "<=" || term.op === "=")
+      upper = Math.min(upper, time + (term.op === "<" ? 0 : 1));
+  }
+  const floor = (time) => metricDateFloor(time, interval, timeZone);
+  const end = floor(Math.min(upper, now));
+  if (!Number.isFinite(lower)) return { end };
+  const first = floor(lower);
+  return {
+    start: first === lower ? lower : metricDateNext(first, interval, timeZone),
+    end
+  };
+}
+function planMetricSeries(query, schema, options2 = {}) {
+  const clauses = query.aggregations ?? [];
+  if (!clauses.some(hasMetricSeries)) return void 0;
+  const now = options2.now ?? Date.now();
+  const taken = new Set(clauses.map((c) => c.id));
+  let next = 0;
+  const id = () => {
+    let value;
+    do
+      value = `qt-series-${next++}`;
+    while (taken.has(value));
+    return value;
+  };
+  const prepared = clauses.map((c) => {
+    if (!hasMetricSeries(c)) return { kind: "plain", clause: c, parts: [c] };
+    try {
+      return prepare(c);
+    } catch (e) {
+      return {
+        kind: "error",
+        clause: c,
+        error: e instanceof Error ? e.message : String(e)
+      };
+    }
+  });
+  function prepare(c) {
+    const issue = validateMetric(c, schema, options2.resolveComputed)[0];
+    if (issue) return { kind: "error", clause: c, error: issue.message };
+    let where = c.where ?? [];
+    let dateGrouping;
+    if (c.dateGrouping) {
+      const { partialIntervals, ...config } = c.dateGrouping;
+      dateGrouping = config;
+      if (partialIntervals === "exclude") {
+        const span = wholeIntervalSpan(c, query, schema, now);
+        if (span.start !== void 0 && span.end <= span.start)
+          return { kind: "empty", clause: c };
+        const field = resolveFieldName(schema, config.field) ?? config.field;
+        const iso = (time) => new Date(time).toISOString();
+        where = [
+          ...where,
+          ...span.start !== void 0 ? [{ field, op: ">=", value: iso(span.start) }] : [],
+          { field, op: "<", value: iso(span.end) }
+        ];
+        if (config.includeEmpty && config.range !== "observed") {
+          const floor = (time) => metricDateFloor(time, config.interval, config.timeZone);
+          let from = span.start, through = span.end - 1;
+          if (config.range === "custom") {
+            const start = floor(
+              metricDateTime(config.start ?? "", config.timeZone)
+            );
+            from = Math.max(from ?? start, start);
+            through = Math.min(
+              through,
+              metricCustomEndTime(config.end ?? "", config.timeZone)
+            );
+          }
+          if (from !== void 0) {
+            if (through < from) return { kind: "empty", clause: c };
+            dateGrouping = {
+              ...config,
+              range: "custom",
+              start: iso(from),
+              end: iso(through)
+            };
+          }
+        }
+      }
+    }
+    const scoped = (groupBy) => ({
+      ...c.scope ? { scope: c.scope } : {},
+      ...where.length ? { where } : {},
+      ...dateGrouping && groupBy.length ? { dateGrouping } : {}
+    });
+    if (!c.window && c.share === void 0) {
+      const {
+        dateGrouping: _date,
+        where: _where,
+        scope: _scope,
+        ...rest
+      } = c;
+      return {
+        kind: "plain",
+        clause: c,
+        parts: [{ ...rest, id: id(), ...scoped(c.groupBy) }]
+      };
+    }
+    const source = metricExpression(
+      c.expression === void 0 && c.field ? { ...c, field: resolveFieldName(schema, c.field) ?? c.field } : c
+    );
+    const plan = compileMetric(source, schema, options2.resolveComputed);
+    const texts = [];
+    const at = (text) => {
+      const index = texts.indexOf(text);
+      return index < 0 ? texts.push(text) - 1 : index;
+    };
+    let reductions;
+    if (c.window && (c.window.reduce ?? "total") === "total")
+      reductions = plan.aggregates.map((node) => {
+        const text = source.slice(node.from, node.to);
+        if (node.name !== "AVG") return { name: node.name, part: at(text) };
+        const input = text.slice(text.indexOf("(") + 1, text.lastIndexOf(")"));
+        return { name: "AVG", sum: at(`SUM(${input})`), count: at(`COUNT(${input})`) };
+      });
+    else at(source);
+    const parts = (groupBy) => texts.map(
+      (text) => ({
+        id: id(),
+        // The whole legacy measure keeps its operation, so v1 servers run it.
+        ...text === source && c.expression === void 0 ? { op: c.op, ...c.field ? { field: c.field } : {} } : { op: "count", expression: text },
+        groupBy,
+        ...scoped(groupBy)
+      })
+    );
+    return {
+      kind: "series",
+      clause: c,
+      plan,
+      parts: [
+        ...parts(c.groupBy),
+        ...c.share === "group0" ? parts(c.groupBy.slice(0, 1)) : c.share === "total" ? parts([]) : []
+      ],
+      ...reductions ? { reductions } : {},
+      size: texts.length
+    };
+  }
+  const queries = [];
+  let batch = [];
+  for (const item of prepared) {
+    if (item.kind === "error" || item.kind === "empty") continue;
+    if (batch.length + item.parts.length > MAX_AGGREGATIONS) {
+      queries.push({ ...query, aggregations: batch });
+      batch = [];
+    }
+    batch.push(...item.parts);
+  }
+  if (batch.length) queries.push({ ...query, aggregations: batch });
+  return {
+    queries,
+    combine(results) {
+      const byId = new Map(results.map((r) => [r.id, r]));
+      return prepared.map((item) => {
+        const c = item.clause;
+        if (item.kind === "error")
+          return { id: c.id, buckets: [], error: item.error };
+        if (item.kind === "empty")
+          return {
+            id: c.id,
+            buckets: [],
+            scope: c.scope ?? "allMatching",
+            groupCount: 0,
+            coverage: "exact"
+          };
+        const entries = item.parts.map(
+          (part) => byId.get(part.id) ?? {
+            id: part.id,
+            buckets: [],
+            error: "Server omitted this metric."
+          }
+        );
+        if (item.kind === "plain") return { ...entries[0], id: c.id };
+        try {
+          return combineSeries(item, entries);
+        } catch (e) {
+          return {
+            id: c.id,
+            buckets: [],
+            error: e instanceof Error ? e.message : String(e)
+          };
+        }
+      });
+    }
+  };
+}
+var Accumulator = class {
+  constructor(name) {
+    this.name = name;
+    this.total = 0;
+    this.seen = false;
+    this.best = null;
+  }
+  add(bucket) {
+    if (!bucket || this.error) return;
+    if (bucket.error) {
+      this.error = bucket.error;
+      return;
+    }
+    const value = bucket.value;
+    if (value === null) return;
+    if (this.name === "SUM" || this.name === "COUNT") {
+      if (typeof value !== "number") {
+        this.error = `${this.name} returned a non-numeric value.`;
+        return;
+      }
+      this.total += value;
+      this.seen = true;
+    } else if (this.best === null || compareMetricValues(value, this.best) * (this.name === "MIN" ? 1 : -1) < 0)
+      this.best = value;
+  }
+  result() {
+    if (this.error) return { value: null, error: this.error };
+    if (this.name === "MIN" || this.name === "MAX") return { value: this.best };
+    return { value: this.name === "COUNT" || this.seen ? this.total : null };
+  }
+};
+function combineSeries(item, entries) {
+  const c = item.clause, window = c.window;
+  for (const entry of entries) {
+    if (entry.error) throw Error(entry.error);
+    if (entry.coverage === "partial" || (entry.groupCount ?? entry.buckets.length) > entry.buckets.length)
+      throw Error(
+        "A window or share needs every group, but the engine returned only some of them."
+      );
+  }
+  const numerator = entries.slice(0, item.size), denominator = c.share ? entries.slice(item.size) : [];
+  const dateOf = (keys) => keys[0] === null || keys[0] === void 0 ? void 0 : keys[0];
+  const times = /* @__PURE__ */ new Map();
+  if (window)
+    for (const entry of entries)
+      for (const bucket of entry.buckets) {
+        const date = dateOf(bucket.keys);
+        if (date !== void 0 && !times.has(date))
+          times.set(date, metricDateTime(date));
       }
-      default:
-        return fail(`Unknown operation: ${name}`);
+  const order = [...times.entries()].sort((a, b) => a[1] - b[1]);
+  const position = new Map(order.map(([date], index) => [date, index]));
+  const positionOf = (keys) => {
+    const date = dateOf(keys);
+    return date === void 0 ? void 0 : position.get(date);
+  };
+  const tracks = (part) => {
+    const byTail = /* @__PURE__ */ new Map();
+    for (const bucket of part.buckets) {
+      const at = positionOf(bucket.keys);
+      if (at === void 0) continue;
+      const tail = JSON.stringify(bucket.keys.slice(1));
+      const track = byTail.get(tail) ?? Array(order.length);
+      track[at] = bucket;
+      byTail.set(tail, track);
+    }
+    return byTail;
+  };
+  const exact = (part) => new Map(
+    part.buckets.map((bucket) => [JSON.stringify(bucket.keys), bucket])
+  );
+  const numeratorTracks = numerator.map(tracks), denominatorTracks = denominator.map(tracks);
+  const numeratorBuckets = numerator.map(exact), denominatorBuckets = denominator.map(exact);
+  const checked = (result, count) => {
+    if (!result.error && typeof result.value === "number")
+      try {
+        assertMetricNumber(result.value);
+      } catch (e) {
+        result = { value: null, error: e.message };
+      }
+    return result.error ? { value: null, count, error: result.error } : { value: result.value, count };
+  };
+  const evaluate = (members, mean) => {
+    const own = members[0], count = own.reduce((n, bucket) => n + (bucket?.count ?? 0), 0);
+    if (item.reductions) {
+      const reduce = (name, part) => {
+        const accumulator = new Accumulator(name);
+        for (const bucket of members[part]) accumulator.add(bucket);
+        return accumulator.result();
+      };
+      const reductions = item.reductions.map((r) => {
+        if (r.name !== "AVG") return reduce(r.name, r.part);
+        const sum = reduce("SUM", r.sum), rows = reduce("COUNT", r.count);
+        if (sum.error || rows.error)
+          return { value: null, error: sum.error ?? rows.error };
+        return {
+          value: sum.value === null || !rows.value ? null : Number(sum.value) / Number(rows.value)
+        };
+      });
+      return checked(evaluateMetricReductions(item.plan, reductions), count);
+    }
+    if (!mean)
+      return own[0]?.error ? { value: null, count, error: own[0].error } : checked({ value: own[0]?.value ?? null }, count);
+    let total = 0;
+    for (const bucket of own) {
+      if (bucket?.error) return { value: null, count, error: bucket.error };
+      if (bucket?.value === null || bucket?.value === void 0) continue;
+      if (typeof bucket.value !== "number")
+        return { value: null, count, error: "Expected a numeric metric value." };
+      total += bucket.value;
+    }
+    return checked({ value: total / own.length }, count);
+  };
+  const periods = window?.periods === "all" ? Infinity : window?.periods ?? 1;
+  const point = (keys, tracksOf, bucketsOf) => {
+    const at = positionOf(keys);
+    if (!window || at === void 0)
+      return evaluate(
+        bucketsOf.map((parts) => [parts.get(JSON.stringify(keys))]),
+        false
+      );
+    const from = Math.max(0, at - periods + 1), intervals = at - from + 1, tail = JSON.stringify(keys.slice(1));
+    const members = tracksOf.map((byTail) => {
+      const track = byTail.get(tail);
+      return Array.from({ length: intervals }, (_, i) => track?.[from + i]);
+    });
+    const result = evaluate(members, window.reduce === "mean");
+    return intervals < periods && periods !== Infinity && (window.partial ?? "omit") === "omit" ? { value: null, count: result.count, intervals } : { ...result, intervals };
+  };
+  const keyed = /* @__PURE__ */ new Map();
+  for (const entry of numerator)
+    for (const bucket of entry.buckets)
+      keyed.set(JSON.stringify(bucket.keys), bucket.keys);
+  let buckets = [...keyed.values()].map((keys) => {
+    const own = point(keys, numeratorTracks, numeratorBuckets);
+    let { value } = own, error = own.error;
+    if (c.share && !error) {
+      const total = c.share === "group0" ? keys.slice(0, 1) : [];
+      const whole = point(total, denominatorTracks, denominatorBuckets);
+      error = whole.error;
+      value = error || typeof value !== "number" || typeof whole.value !== "number" || whole.value === 0 ? null : value / whole.value;
     }
-    return bound(out);
-  }
-  try {
-    const value = run(ast);
-    return inspection ? { value, regex: inspection } : { value };
-  } catch (e) {
     return {
-      value: null,
-      error: e instanceof Error ? e.message : "Formula evaluation failed."
+      keys,
+      value: error ? null : value,
+      count: own.count,
+      ...error ? { error } : {},
+      ...own.intervals !== void 0 ? { intervals: own.intervals } : {}
     };
+  });
+  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;
   }
+  sortMetricBuckets(buckets, c);
+  const groupCount = buckets.length;
+  if (c.groupLimit) buckets = buckets.slice(0, c.groupLimit);
+  const first = entries[0];
+  return {
+    id: c.id,
+    buckets,
+    scope: first.scope ?? c.scope ?? "allMatching",
+    ...first.processedRows !== void 0 ? { processedRows: first.processedRows } : {},
+    groupCount,
+    coverage: "exact",
+    ...hiddenGroups !== void 0 ? { hiddenGroups } : {}
+  };
 }
 
 // src/groupKeys.ts
@@ -3793,22 +4449,6 @@ function toServerQueryV2(q, schema, execution) {
   };
 }
 
-// src/metricPrecision.ts
-function assertMetricNumber(value) {
-  if (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)) {
-    throw Error("Aggregate exceeds finite safe numeric precision.");
-  }
-}
-function checkedMetricResult(result) {
-  if (result.error || typeof result.value !== "number") return result;
-  try {
-    assertMetricNumber(result.value);
-    return result;
-  } catch (e) {
-    return { value: null, error: e.message };
-  }
-}
-
 // src/metricDistributions.ts
 function percentile(sorted, p) {
   if (!Number.isFinite(p) || p < 0 || p > 1)
@@ -3908,176 +4548,6 @@ function histogramCounts(values, edges) {
   return counts;
 }
 
-// src/metricDates.ts
-import { Temporal } from "temporal-polyfill";
-var METRIC_DATE_INTERVALS = [
-  "hour",
-  "day",
-  "week",
-  "month",
-  "year"
-];
-function metricDateTime(value, timeZone = "UTC") {
-  if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2}))?$/.test(
-    value
-  ))
-    throw Error(
-      "Date grouping requires ISO dates or timestamps with a timezone."
-    );
-  const time = Date.parse(value), month = Number(value.slice(5, 7)), day = Number(value.slice(8, 10));
-  const calendar = /* @__PURE__ */ new Date(0);
-  calendar.setUTCFullYear(Number(value.slice(0, 4)), month, 0);
-  if (!Number.isFinite(time) || month < 1 || month > 12 || day < 1 || day > calendar.getUTCDate())
-    throw Error("Invalid date grouping value.");
-  return value.length === 10 && timeZone !== "UTC" ? Temporal.PlainDate.from(value).toZonedDateTime(timeZone).epochMilliseconds : time;
-}
-function metricOffsetTransition(start, end, timeZone) {
-  if (end <= start) return void 0;
-  const offset = (time) => Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone).offsetNanoseconds;
-  const before = offset(start);
-  if (before === offset(end)) return void 0;
-  while (end - start > 1) {
-    const middle = Math.floor((start + end) / 2);
-    if (offset(middle) === before) start = middle;
-    else end = middle;
-  }
-  return end;
-}
-function metricDateFloor(time, interval, timeZone = "UTC") {
-  if (timeZone !== "UTC") {
-    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
-    if (interval === "hour") {
-      const floor = time - zoned.minute * 6e4 - zoned.second * 1e3 - zoned.millisecond;
-      return metricOffsetTransition(floor, time, timeZone) ?? floor;
-    }
-    let date2 = zoned.toPlainDate();
-    if (interval === "week") date2 = date2.subtract({ days: date2.dayOfWeek - 1 });
-    if (interval === "month" || interval === "year")
-      date2 = date2.with({ day: 1 });
-    if (interval === "year") date2 = date2.with({ month: 1 });
-    return date2.toZonedDateTime(timeZone).epochMilliseconds;
-  }
-  const date = new Date(time);
-  date.setUTCMinutes(0, 0, 0);
-  if (interval !== "hour") date.setUTCHours(0);
-  if (interval === "week")
-    date.setUTCDate(date.getUTCDate() - (date.getUTCDay() + 6) % 7);
-  if (interval === "month" || interval === "year") date.setUTCDate(1);
-  if (interval === "year") date.setUTCMonth(0);
-  return date.getTime();
-}
-function metricDateNext(time, interval, timeZone = "UTC") {
-  if (timeZone !== "UTC") {
-    const zoned = Temporal.Instant.fromEpochMilliseconds(time).toZonedDateTimeISO(timeZone);
-    if (interval === "hour") {
-      const target = zoned.toPlainDateTime().with({
-        minute: 0,
-        second: 0,
-        millisecond: 0,
-        microsecond: 0,
-        nanosecond: 0
-      }).add({ hours: 1 });
-      let next = target.toZonedDateTime(timeZone).epochMilliseconds;
-      if (next <= time)
-        next = target.toZonedDateTime(timeZone, {
-          disambiguation: "later"
-        }).epochMilliseconds;
-      return metricOffsetTransition(time, next, timeZone) ?? next;
-    }
-    let date2 = zoned.toPlainDate();
-    if (interval === "month") date2 = date2.with({ day: 1 }).add({ months: 1 });
-    else if (interval === "year")
-      date2 = date2.with({ month: 1, day: 1 }).add({ years: 1 });
-    else if (interval === "week")
-      date2 = date2.subtract({ days: date2.dayOfWeek - 1 }).add({ weeks: 1 });
-    else date2 = date2.add({ days: 1 });
-    return date2.toZonedDateTime(timeZone).epochMilliseconds;
-  }
-  const date = new Date(time);
-  if (interval === "hour") date.setUTCHours(date.getUTCHours() + 1);
-  else if (interval === "month") date.setUTCMonth(date.getUTCMonth() + 1);
-  else if (interval === "year") date.setUTCFullYear(date.getUTCFullYear() + 1);
-  else date.setUTCDate(date.getUTCDate() + (interval === "week" ? 7 : 1));
-  return date.getTime();
-}
-function customEndTime(value, timeZone = "UTC") {
-  const time = metricDateTime(value, timeZone);
-  return value.length === 10 ? metricDateNext(time, "day", timeZone) - 1 : time;
-}
-function validateDateGrouping(config) {
-  if (typeof config.field !== "string" || !config.field || config.field.length > 256 || !METRIC_DATE_INTERVALS.includes(config.interval) || typeof config.includeEmpty !== "boolean" || !["query", "observed", "custom"].includes(config.range))
-    throw Error("Invalid date grouping definition.");
-  if (config.timeZone !== void 0) {
-    if (typeof config.timeZone !== "string" || !config.timeZone || config.timeZone.length > 80 || /^[+-]/.test(config.timeZone))
-      throw Error(
-        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
-      );
-    try {
-      new Intl.DateTimeFormat("en-US", { timeZone: config.timeZone });
-    } catch {
-      throw Error(
-        "Use a valid IANA grouping timezone, such as America/Denver or UTC."
-      );
-    }
-  }
-  if (config.includeEmpty && config.range === "custom") {
-    const start = metricDateTime(config.start ?? "", config.timeZone), end = customEndTime(config.end ?? "", config.timeZone);
-    if (end < start)
-      throw Error("The end date must be on or after the start date.");
-  }
-}
-function metricDateRange(config, query, observed, now, canonical) {
-  let min = Infinity, max = -Infinity;
-  for (const time of observed) {
-    min = Math.min(min, time);
-    max = Math.max(max, time);
-  }
-  if (config.range === "observed")
-    return observed.length ? [min, max] : void 0;
-  if (config.range === "custom") {
-    const start2 = metricDateFloor(
-      metricDateTime(config.start ?? "", config.timeZone),
-      config.interval,
-      config.timeZone
-    );
-    const end2 = metricDateFloor(
-      customEndTime(config.end ?? "", config.timeZone),
-      config.interval,
-      config.timeZone
-    );
-    if (observed.length && (start2 > min || end2 < max))
-      throw Error(
-        "Custom date bounds must include all observed buckets. Narrow the query filters to exclude data."
-      );
-    return [start2, end2];
-  }
-  let start = -Infinity, end = Infinity;
-  for (const term of query.where) {
-    if (isOrGroup(term) || term.negated || canonical(term.field) !== canonical(config.field))
-      continue;
-    if (!["=", ">", ">=", "<", "<="].includes(term.op)) continue;
-    const time = Number(coerceValue("datetime", term.value, now));
-    if (term.op === ">" || term.op === ">=" || term.op === "=")
-      start = Math.max(start, time + (term.op === ">" ? 1 : 0));
-    if (term.op === "<" || term.op === "<=" || term.op === "=")
-      end = Math.min(end, time - (term.op === "<" ? 1 : 0));
-  }
-  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 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),
-    metricDateFloor(end, config.interval, config.timeZone)
-  ];
-}
-
 // src/metrics.ts
 var aggregates = /* @__PURE__ */ new Set([
   "COUNT",
@@ -4421,6 +4891,7 @@ function validateMetric(c, schema, resolve) {
     const compiled = metricPlans(c, schema, resolve);
     if (c.scope !== "shownRows" && compiled.some(hasRegex))
       throw new FormulaError("Regex is unavailable for all-matching metrics.");
+    validateMetricSeries(c, compiled[0]);
     return [];
   } catch (e) {
     return [
@@ -4484,6 +4955,8 @@ function metricComputationKey(clauses) {
       groupLimit: c.groupLimit,
       where: c.where,
       minCount: c.minCount,
+      window: c.window,
+      share: c.share,
       distribution: distributionActive(c) ? c.distribution : void 0
     })).sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0)
   );
@@ -4535,6 +5008,8 @@ function toMetricQuery(q, schema, execution) {
       expressionY,
       dateGrouping,
       where,
+      window: _window,
+      share: _share,
       ...rest
     } = c;
     return {
@@ -4564,6 +5039,15 @@ function toMetricQuery(q, schema, execution) {
         to: 1,
         message: "Metric filters must use server-filterable fields."
       });
+  for (const c of q.aggregations ?? [])
+    if (hasMetricSeries(c))
+      diagnostics.push({
+        metricId: c.id,
+        code: "unexpanded_series",
+        from: 0,
+        to: 1,
+        message: "Windows, shares and whole intervals are computed from plain metrics; expand the query with planMetricSeries first."
+      });
   for (const c of q.aggregations ?? [])
     if (c.dateGrouping)
       diagnostics.push({
@@ -4759,6 +5243,24 @@ function compareMetricValues(a, b) {
   }
   return a < b ? -1 : 1;
 }
+function sortMetricBuckets(buckets, c) {
+  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;
+  return buckets.sort((a, b) => {
+    if (!!(a.error || a.yError) !== !!(b.error || b.yError))
+      return a.error || a.yError ? 1 : -1;
+    for (const s of ordering) {
+      const av = target(a, s), bv = target(b, s);
+      const cmp = av === null || bv === null ? av === bv ? 0 : (av === null ? 1 : -1) * (s.nulls === "first" ? -1 : 1) : compareMetricValues(av, bv) * (s.dir === "asc" ? 1 : -1);
+      if (cmp) return cmp;
+    }
+    for (let i = 0; i < a.keys.length; i++) {
+      const cmp = compareMetricValues(a.keys[i], b.keys[i]);
+      if (cmp) return cmp;
+    }
+    return 0;
+  });
+}
 function evaluateMetrics(rows, q, schema, options2 = {}) {
   if (q.grouping) {
     try {
@@ -4775,6 +5277,18 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
     }
   }
   const now = evaluationTime(options2), fields = indexFields(schema);
+  const series = planMetricSeries(q, schema, {
+    now,
+    ...options2.resolveComputed ? { resolveComputed: options2.resolveComputed } : {}
+  });
+  if (series)
+    return {
+      metrics: series.combine(
+        series.queries.flatMap(
+          (part) => evaluateMetrics(rows, part, schema, { ...options2, now }).metrics
+        )
+      )
+    };
   let matching;
   let shown;
   return {
@@ -4909,7 +5423,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
         if (c.dateGrouping?.includeEmpty) {
           const config = c.dateGrouping;
           const observed = [];
-          const series = /* @__PURE__ */ new Map();
+          const series2 = /* @__PURE__ */ new Map();
           for (const group of groups.values())
             if (group.keys[0] !== null) {
               tick();
@@ -4918,17 +5432,17 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
               observed.push(metricDateTime(group.keys[0]));
               const tuple = group.keys.slice(1);
               const key = JSON.stringify(tuple);
-              if (!series.has(key)) {
+              if (!series2.has(key)) {
                 const bytes = 128 + 16 * tuple.length + 2 * key.length;
                 reserve(bytes);
                 groupBytes += bytes;
-                series.set(key, tuple);
+                series2.set(key, tuple);
               }
             }
-          if (c.groupBy.length === 1 && !series.size) {
+          if (c.groupBy.length === 1 && !series2.size) {
             reserve(132);
             groupBytes += 132;
-            series.set("[]", []);
+            series2.set("[]", []);
           }
           const range = metricDateRange(
             config,
@@ -4940,7 +5454,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           if (range)
             for (let time = range[0]; time <= range[1]; ) {
               tick();
-              for (const tuple of series.values()) {
+              for (const tuple of series2.values()) {
                 tick();
                 const keys = [
                   new Date(time).toISOString(),
@@ -5100,22 +5614,7 @@ function evaluateMetrics(rows, q, schema, options2 = {}) {
           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) => {
-          if (!!(a.error || a.yError) !== !!(b.error || b.yError))
-            return a.error || a.yError ? 1 : -1;
-          for (const s of ordering) {
-            const av = target(a, s), bv = target(b, s);
-            const cmp = av === null || bv === null ? av === bv ? 0 : (av === null ? 1 : -1) * (s.nulls === "first" ? -1 : 1) : compareMetricValues(av, bv) * (s.dir === "asc" ? 1 : -1);
-            if (cmp) return cmp;
-          }
-          for (let i = 0; i < a.keys.length; i++) {
-            const cmp = compareMetricValues(a.keys[i], b.keys[i]);
-            if (cmp) return cmp;
-          }
-          return 0;
-        });
+        sortMetricBuckets(buckets, c);
         tick();
         const groupCount = buckets.length;
         let other;
@@ -5223,7 +5722,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.where !== void 0 || a.minCount !== 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 || hasMetricSeries(a)
   );
   if (advanced.length) {
     if ((q.aggregations?.length ?? 0) > 20 || normalizeQueryState(q).aggregations?.length !== q.aggregations?.length)
@@ -6149,7 +6648,7 @@ function toQueryRequestV3(query, baseSchema, capabilities, execution, options2 =
       if (predicate.field.startsWith("@computed/") && !capabilities.computedSourceFilters) diagnostics.push("This server does not support computed source predicates.");
   }
   const metricQuery = toMetricQuery(withoutGrouping(q), resultSchema, execution);
-  diagnostics.push(...metricQuery.diagnostics.filter((issue) => issue.code === "residual_metric_filter").map((issue) => issue.message));
+  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;
@@ -6223,12 +6722,21 @@ function inspectBucketQuery(query, bucket, clause, schema) {
       } catch {
         return null;
       }
-      const { interval, timeZone } = clause.dateGrouping;
+      const { interval, timeZone, partialIntervals } = 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() }
-      );
+      let from = start;
+      const periods = clause.window?.periods;
+      if (periods === "all") from = void 0;
+      else if (periods !== void 0) {
+        if (!Number.isInteger(periods) || periods < 2 || periods > MAX_METRIC_WINDOW_PERIODS) return null;
+        for (let i = 1; i < periods; i++) from = metricDateFloor(from - 1, interval, timeZone);
+      }
+      if (partialIntervals === "exclude") {
+        const whole = wholeIntervalSpan(clause, query, fields, Date.now()).start;
+        if (whole !== void 0) from = Math.max(from ?? whole, whole);
+      }
+      if (from !== void 0) terms.push({ field: field.name, op: ">=", value: new Date(from).toISOString() });
+      terms.push({ field: field.name, op: "<", value: new Date(next).toISOString() });
       continue;
     }
     const term = keyClause(field, key);
@@ -6273,6 +6781,7 @@ export {
   ITEM_DETAILS_COLUMN,
   MAX_AGGREGATIONS,
   MAX_GROUP_BY_FIELDS,
+  MAX_METRIC_WINDOW_PERIODS,
   MAX_ORDER_BY_TERMS,
   MAX_PROPERTIES,
   MAX_QUERY_LIMIT,
@@ -6320,6 +6829,7 @@ export {
   groupLinkQuery,
   groupPreview,
   groupSourceQuery,
+  hasMetricSeries,
   hasRegex,
   histogramCounts,
   histogramEdges,
@@ -6354,6 +6864,7 @@ export {
   memoryStorageAdapter,
   metricAggregatePlans,
   metricComputationKey,
+  metricCustomEndTime,
   metricDateFloor,
   metricDateNext,
   metricDateRange,
@@ -6372,6 +6883,7 @@ export {
   opsForField,
   parseRelativeDuration,
   percentile,
+  planMetricSeries,
   predicatesOf,
   prepareGrouping,
   queriesEqual,
@@ -6387,6 +6899,7 @@ export {
   selectedFields,
   setFilterModes,
   setFilterTarget,
+  sortMetricBuckets,
   sourceDependencies,
   sourceExecutionSchema,
   stripSetFilter,
@@ -6399,8 +6912,10 @@ export {
   validateDateGrouping,
   validateItemPageTemplate,
   validateMetric,
+  validateMetricSeries,
   validateQueryResultV3,
   validateQuerySnapshot,
+  wholeIntervalSpan,
   withGroupingKeys,
   withoutGrouping,
   withoutLinkSummaries