@mixd-id/web-scaffold 0.1.240411125 → 0.1.240411126

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mixd-id/web-scaffold",
   "private": false,
-  "version": "0.1.240411125",
+  "version": "0.1.240411126",
   "scripts": {
     "dev": "vite serve",
     "build": "vite build",
@@ -33,6 +33,7 @@
     "./listpage1": "./src/utils/listpage1.js",
     "./dashboard": "./src/utils/dashboard.js",
     "./ai-dashboard": "./src/utils/ai-dashboard.js",
+    "./ai-dashboard-query": "./src/utils/ai-dashboard-query.js",
     "./ai-dashboard-chat": "./src/utils/ai-dashboard-chat.mjs",
     "./ai-dashboard-views": {
       "import": "./src/utils/ai-dashboard-views.mjs"

package/src/components/AIDashboardChart.vue

@@ -165,9 +165,13 @@ export default {
 
       const nested = (kind === 'pie' || kind === 'doughnut') && this.data.nested && typeof this.data.nested === 'object' ? this.data.nested : null
       let rows = this.rows.map(r => ({ label: `${r.label}`, value: Number(r.value) || 0, other: !!r.other }))
+      // Past eight slices the rest is folded into Other, or left out with `groupOther: false`.
+      if(round && query.groupOther === false) rows = rows.filter(r => !r.other)
       if(round && rows.length > 8){
-        const top = [ ...rows ].sort((a, b) => b.value - a.value).slice(0, 7)
-        rows = [ ...top, { label: 'Other', value: rows.reduce((sum, r) => sum + r.value, 0) - top.reduce((sum, r) => sum + r.value, 0), other: true } ]
+        const sorted = [ ...rows ].sort((a, b) => b.value - a.value)
+        const top = sorted.slice(0, query.groupOther === false ? 8 : 7)
+        rows = query.groupOther === false ? top
+          : [ ...top, { label: 'Other', value: rows.reduce((sum, r) => sum + r.value, 0) - top.reduce((sum, r) => sum + r.value, 0), other: true } ]
       }
       const stacks = round ? [] : this.stacks
       const stacked = stacks.length > 0

package/src/components/AIDashboardChartSetting.vue

@@ -24,7 +24,7 @@
     <div class="flex flex-row gap-2">
       <div class="flex-1 min-w-0">
         <label class="text-xs text-text-400">Chart</label>
-        <Dropdown :model-value="node.chart || 'bar'" @update:model-value="node.chart = $event; $emit('change')">
+        <Dropdown :model-value="node.chart || 'bar'" @update:model-value="setChart($event)">
           <option value="bar">Bar</option>
           <option value="line">Line</option>
           <option value="pie">Pie</option>
@@ -135,24 +135,24 @@
         </Checkbox>
       </div>
 
-      <div v-if="!measurable">
-        <label class="text-xs text-text-400">Aggregation</label>
-        <Dropdown v-model="query.aggregation" @change="$emit('change')">
-          <option v-for="a in aggregations" :key="a" :value="a">{{ aggLabel(a) }}</option>
-        </Dropdown>
-      </div>
-
-      <template v-if="!measurable && query.aggregation && query.aggregation !== 'count'">
-        <div>
-          <label class="text-xs text-text-400">Field</label>
-          <Dropdown v-model="query.field" @change="$emit('change')">
-            <option value="">— select —</option>
-            <option v-for="f in aggFields" :key="f.key" :value="f.key">{{ f.label }}</option>
+      <template v-if="node.chart === 'map'">
+        <div v-if="!measurable">
+          <label class="text-xs text-text-400">Aggregation</label>
+          <Dropdown v-model="query.aggregation" @change="$emit('change')">
+            <option v-for="a in aggregations" :key="a" :value="a">{{ aggLabel(a) }}</option>
           </Dropdown>
         </div>
-      </template>
 
-      <template v-if="node.chart === 'map'">
+        <template v-if="!measurable && query.aggregation && query.aggregation !== 'count'">
+          <div>
+            <label class="text-xs text-text-400">Field</label>
+            <Dropdown v-model="query.field" @change="$emit('change')">
+              <option value="">— select —</option>
+              <option v-for="f in aggFields" :key="f.key" :value="f.key">{{ f.label }}</option>
+            </Dropdown>
+          </div>
+        </template>
+
         <div>
           <label class="text-xs text-text-400">Location from</label>
           <Dropdown :model-value="'latField' in query ? 'coords' : 'name'" @update:model-value="setLocation">
@@ -197,6 +197,12 @@
           <div class="flex-1 min-w-0">
             <div class="flex flex-row items-center h-5">
               <label class="flex-1 min-w-0 truncate text-xs text-text-400">{{ axisLabels?.group ?? 'Group by' }}</label>
+              <label v-if="[ 'pie', 'doughnut', 'polarArea' ].includes(node.chart)" class="flex flex-row items-center gap-1 text-xs text-text-300 cursor-pointer"
+                     title="Past eight groups, fold the rest into one Other slice">
+                <input type="checkbox" class="w-3 h-3 accent-primary cursor-pointer" :checked="query.groupOther !== false"
+                       @change="$event.target.checked ? delete query.groupOther : query.groupOther = false; $emit('change')" />
+                Other
+              </label>
             </div>
             <Dropdown v-model="query.groupBy" @change="groupType !== 'date' && (query.dateModifier = '', delete query.weekOfMonth); groupType !== 'number' && delete query.bucketSize; $emit('change')">
               <option value="">— select —</option>
@@ -230,7 +236,7 @@
             </Dropdown>
           </div>
 
-          <div v-if="groupType === 'number'" class="flex-1 min-w-0">
+          <div v-if="groupType === 'number' && ![ 'pie', 'doughnut', 'polarArea' ].includes(node.chart)" class="w-[90px]">
             <div class="flex flex-row items-center h-5">
               <label class="flex-1 min-w-0 truncate text-xs text-text-400">Range size</label>
               <label v-if="query.bucketSize" class="flex flex-row items-center gap-1 text-xs text-text-300 cursor-pointer" title="Show empty buckets">
@@ -239,10 +245,27 @@
                 Empty
               </label>
             </div>
-            <Textbox v-model.number="query.bucketSize" type="tel" item-class="text-right" placeholder="Exact values" @change="$emit('change')" />
+            <Textbox v-model.number="query.bucketSize" type="tel" item-class="text-right" placeholder="" @change="$emit('change')" />
           </div>
         </div>
 
+        <div v-if="!measurable">
+          <label class="text-xs text-text-400">Aggregation</label>
+          <Dropdown v-model="query.aggregation" @change="$emit('change')">
+            <option v-for="a in aggregations" :key="a" :value="a">{{ aggLabel(a) }}</option>
+          </Dropdown>
+        </div>
+
+        <template v-if="!measurable && query.aggregation && query.aggregation !== 'count'">
+          <div>
+            <label class="text-xs text-text-400">Field</label>
+            <Dropdown v-model="query.field" @change="$emit('change')">
+              <option value="">— select —</option>
+              <option v-for="f in aggFields" :key="f.key" :value="f.key">{{ f.label }}</option>
+            </Dropdown>
+          </div>
+        </template>
+
         <div v-if="!(query.extraFields ?? []).length" class="flex flex-row gap-2">
           <div class="flex-1 min-w-0">
             <div class="flex flex-row items-center h-5">
@@ -470,6 +493,15 @@ export default {
       if (!allowed.includes(row.aggregation)) row.aggregation = allowed.includes('sum') ? 'sum' : allowed[0]
       this.writeFields(rows)
     },
+    // Round charts slice by exact value, so a number range size does not apply to them.
+    setChart(chart) {
+      this.node.chart = chart
+      if ([ 'pie', 'doughnut', 'polarArea' ].includes(chart) && this.query.bucketSize != null) {
+        delete this.query.bucketSize
+        if (!this.query.dateModifier) delete this.query.fillEmpty
+      }
+      this.$emit('change')
+    },
     // Two or more fields draw one line each, which a split cannot share.
     writeFields(rows) {
       const [ main, ...extras ] = rows

package/src/components/AIDashboardFilterSetting.vue

@@ -12,7 +12,7 @@
             <option value="" disabled>field</option>
             <option v-for="fl in fields" :key="fl.key" :value="fl.key">{{ fl.label }}</option>
           </Dropdown>
-          <Dropdown v-model="f.op" class="w-[64px]" @change="onOp(f)">
+          <Dropdown v-model="f.op" :class="opLabel(f.op).length > 3 ? 'w-[110px]' : 'w-[64px]'" @change="onOp(f)">
             <option v-for="o in opsFor(f.field, f.op)" :key="o" :value="o">{{ opLabel(o) }}</option>
           </Dropdown>
           <Dropdown v-if="f.op === 'period'" class="flex-1"
@@ -26,6 +26,7 @@
             <option value="lastMonth">Last month</option>
             <option value="custom">Custom date</option>
           </Dropdown>
+          <div v-else-if="[ 'between', 'exceptBetween', 'weekday', 'monthOfYear' ].includes(f.op)" class="flex-1"></div>
           <Dropdown v-else-if="typeOf(f.field) === 'date'" class="flex-1"
                     :model-value="isToken(f.value) ? f.value : 'custom'"
                     @update:model-value="setDate(f, $event)">
@@ -38,19 +39,27 @@
             <option value="" disabled>value</option>
             <option v-for="o in enumOptions(f.field)" :key="o.value" :value="`${o.value}`">{{ o.label }}</option>
           </Dropdown>
-          <Textbox v-else v-model="f.value" class="flex-1" placeholder="value" @change="$emit('change')" />
+          <Textbox v-else v-model="f.value" class="flex-1" :placeholder="[ 'in', 'notIn' ].includes(f.op) ? 'a, b, c' : 'value'" @change="$emit('change')" />
           <button type="button" class="px-1 text-text-300 hover:text-red-600" title="Remove filter" @click="filters.splice(fi, 1); $emit('change')">
             <svg width="11" height="11" class="fill-current" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><path d="M342.6 150.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L192 210.7 86.6 105.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L146.7 256 41.4 361.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0L192 301.3 297.4 406.6c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L237.3 256 342.6 150.6z"/></svg>
           </button>
         </div>
-        <div v-if="f.op === 'period' && /\.\./.test(f.value)" class="flex flex-row items-center gap-1 ml-[16px] mr-[19px]">
+        <div v-if="(f.op === 'period' && /\.\./.test(f.value)) || [ 'between', 'exceptBetween' ].includes(f.op)" class="flex flex-row items-center gap-1 ml-[16px] mr-[19px]">
           <Datepicker mode="popup" class="flex-1" :model-value="f.value.split('..')[0]"
                       @update:model-value="f.value = `${$event}..${f.value.split('..')[1]}`; $emit('change')" />
           <span class=" text-text-400 mx-1">to</span>
           <Datepicker mode="popup" class="flex-1" :model-value="f.value.split('..')[1]"
                       @update:model-value="f.value = `${f.value.split('..')[0]}..${$event}`; $emit('change')" />
         </div>
-        <Datepicker v-if="f.op !== 'period' && typeOf(f.field) === 'date' && !isToken(f.value)" mode="popup"
+        <div v-if="[ 'weekday', 'monthOfYear' ].includes(f.op)" class="flex flex-row flex-wrap gap-x-3 gap-y-1 ml-[16px] mr-[19px]">
+          <label v-for="[ value, label ] in f.op === 'weekday' ? WEEKDAYS : MONTHS" :key="value"
+                 class="flex flex-row items-center gap-1 text-xs text-text-400 cursor-pointer">
+            <input type="checkbox" class="w-3 h-3 accent-primary cursor-pointer" :checked="listOf(f.value).includes(value)"
+                   @change="toggleList(f, value, $event.target.checked)" />
+            {{ label }}
+          </label>
+        </div>
+        <Datepicker v-if="!SPECIAL_DATE_OPS.includes(f.op) && typeOf(f.field) === 'date' && !isToken(f.value)" mode="popup"
                     :model-value="f.value" @update:model-value="f.value = $event; $emit('change')" />
       </div>
       </template>
@@ -82,6 +91,15 @@ export default {
 
   emits: [ 'change' ],
 
+  data() {
+    return {
+      SPECIAL_DATE_OPS: [ 'period', 'between', 'exceptBetween', 'weekday', 'monthOfYear' ],
+      // Stored as MySQL WEEKDAY() / MONTH() numbers: Monday = 0, January = 1.
+      WEEKDAYS: [ 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun' ].map((label, i) => [ `${i}`, label ]),
+      MONTHS: [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' ].map((label, i) => [ `${i + 1}`, label ]),
+    }
+  },
+
   computed: {
     filters() {
       return Array.isArray(this.query.filters) ? this.query.filters : []
@@ -125,12 +143,27 @@ export default {
     },
     opsFor(key, current) {
       const type = this.typeOf(key)
-      if (type === 'date') return [ 'period', ...([ '=', '!=' ].includes(current) ? [ current ] : []), '>', '>=', '<', '<=' ]
-      if (type === 'number') return [ '=', '!=', '>', '>=', '<', '<=' ]
-      return [ '=', '!=', 'contains', 'in' ]
+      if (type === 'date') return [ 'period', ...([ '=', '!=' ].includes(current) ? [ current ] : []), '>', '>=', '<', '<=', 'between', 'except', 'exceptBetween', 'weekday', 'monthOfYear' ]
+      if (type === 'number') return [ '=', '!=', '>', '>=', '<', '<=', 'in', 'notIn' ]
+      return [ '=', '!=', 'contains', 'startsWith', 'endsWith', 'in', 'notIn' ]
     },
     opLabel(op) {
-      return { '=': '=', '!=': '≠', '>': '>', '>=': '≥', '<': '<', '<=': '≤', contains: 'has', in: 'in', period: 'is' }[op] ?? op
+      return {
+        '=': '=', '!=': '≠', '>': '>', '>=': '≥', '<': '<', '<=': '≤', contains: 'has', in: 'in', notIn: 'not in',
+        startsWith: 'starts with', endsWith: 'ends with', period: 'is', between: 'between', except: 'except',
+        exceptBetween: 'except between', weekday: 'weekday', monthOfYear: 'month',
+      }[op] ?? op
+    },
+    listOf(value) {
+      return `${value ?? ''}`.split(',').map(v => v.trim()).filter(Boolean)
+    },
+    toggleList(filter, value, checked) {
+      const order = (filter.op === 'weekday' ? this.WEEKDAYS : this.MONTHS).map(([ v ]) => v)
+      const next = new Set(this.listOf(filter.value))
+      if (checked) next.add(value)
+      else next.delete(value)
+      filter.value = order.filter(v => next.has(v)).join(',')
+      this.$emit('change')
     },
     addFilter() {
       if (!Array.isArray(this.query.filters)) this.query.filters = []
@@ -142,11 +175,30 @@ export default {
       if (!allowed.includes(filter.op)) filter.op = allowed[0]
       this.onOp(filter)
     },
+    // Keeps the value when it still fits the new op, otherwise starts it at a sensible default.
     onOp(filter) {
-      const isPeriod = /^(today|yesterday|thisWeek|lastWeek|thisMonth|lastMonth|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2})$/.test(`${filter.value}`)
-      if (filter.op === 'period' && !isPeriod) filter.value = 'today'
-      if (filter.op !== 'period' && isPeriod) filter.value = ''
-      if (filter.op !== 'period' && this.typeOf(filter.field) === 'date' && !this.isToken(filter.value) && !/^\d{4}-\d{2}-\d{2}/.test(`${filter.value}`)) filter.value = '@today'
+      const value = `${filter.value ?? ''}`
+      const day = (d) => `${d.getFullYear()}-${`${d.getMonth() + 1}`.padStart(2, '0')}-${`${d.getDate()}`.padStart(2, '0')}`
+      const today = new Date()
+      const range = /^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$/
+      const dateLike = this.isToken(value) || /^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}(:\d{2})?)?$/.test(value)
+      const isPeriod = /^(today|yesterday|thisWeek|lastWeek|thisMonth|lastMonth)$/.test(value) || range.test(value)
+      if (filter.op === 'period') {
+        if (!isPeriod) filter.value = 'today'
+      }
+      else if ([ 'between', 'exceptBetween' ].includes(filter.op)) {
+        if (!range.test(value)) filter.value = `${day(new Date(today.getFullYear(), today.getMonth(), 1))}..${day(today)}`
+      }
+      else if (filter.op === 'weekday') {
+        if (!/^[0-6](,[0-6])*$/.test(value)) filter.value = '0,1,2,3,4'
+      }
+      else if (filter.op === 'monthOfYear') {
+        if (!/^([1-9]|1[0-2])(,([1-9]|1[0-2]))*$/.test(value)) filter.value = `${today.getMonth() + 1}`
+      }
+      else if (this.typeOf(filter.field) === 'date') {
+        if (!dateLike) filter.value = '@today'
+      }
+      else if (isPeriod || this.isToken(value)) filter.value = ''
       this.$emit('change')
     },
     setPeriod(filter, value) {

package/src/components/AIDashboardMetricSetting.vue

@@ -83,12 +83,31 @@
         </Card>
       </div>
 
-      <div>
-        <label class="text-xs text-text-400 mb-1">Breakdown by (first field)</label>
-        <Dropdown v-model="query.breakdownBy" @change="$emit('change')">
-          <option value="">— none —</option>
-          <option v-for="f in fields.filter(f => f.type !== 'date')" :key="f.key" :value="f.key">{{ f.label }}</option>
-        </Dropdown>
+      <div class="flex flex-row gap-2">
+        <div class="flex-1 min-w-0">
+          <div class="flex flex-row items-center h-5">
+            <label class="flex-1 min-w-0 truncate text-xs text-text-400">Breakdown by (first field)</label>
+          </div>
+          <Dropdown v-model="query.breakdownBy" @change="setBreakdownBy">
+            <option value="">— none —</option>
+            <option v-for="f in fields.filter(f => f.type !== 'date')" :key="f.key" :value="f.key">{{ f.label }}</option>
+          </Dropdown>
+        </div>
+
+        <div v-if="query.breakdownBy" class="w-[100px] min-w-0">
+          <div class="flex flex-row items-center h-5">
+            <label class="flex-1 min-w-0 truncate text-xs text-text-400" title="Top values shown in the bar, plus Other">Limit</label>
+            <label class="flex flex-row items-center gap-1 text-xs text-text-300 cursor-pointer" title="Show Other">
+              <input type="checkbox" class="w-3 h-3 accent-primary cursor-pointer" :checked="query.breakdownOther !== false"
+                     @change="$event.target.checked ? delete query.breakdownOther : query.breakdownOther = false; $emit('change')" />
+              Other
+            </label>
+          </div>
+          <Dropdown :model-value="query.breakdownLimit || 4"
+                    @update:model-value="Number($event) === 4 ? delete query.breakdownLimit : query.breakdownLimit = Number($event); $emit('change')">
+            <option v-for="n in 20" :key="n" :value="n">{{ n }}</option>
+          </Dropdown>
+        </div>
       </div>
       <AIDashboardDetailSetting :owner="query" :fields="fields" :datasources="datasources" pick-field collapsible @change="$emit('change')" />
     </template>
@@ -206,6 +225,13 @@ export default {
       else delete this.query.extraFields
       this.$emit('change')
     },
+    setBreakdownBy() {
+      if (!this.query.breakdownBy) {
+        delete this.query.breakdownLimit
+        delete this.query.breakdownOther
+      }
+      this.$emit('change')
+    },
     extraLabel(extra) {
       const field = this.fields.find(f => f.key === extra.field)?.label
       if (extra.aggregation === 'count' || !field) return this.aggLabel(extra.aggregation)

package/src/utils/ai-dashboard-chat.mjs

@@ -30,7 +30,7 @@ export function buildInstruction(catalog) {
     '- Any widget or nested group inside a grid group may take `"colSpan": 2-8` (how many of the group\'s columns it spans, at most `cols`) and `"rowSpan": 2-4` (how many rows tall it is). Use them for a wide widget (a map, a long time series or a pivot table across a whole row: `colSpan` = the group\'s `cols`) or a tall one beside smaller ones (a chart with `rowSpan` 2 next to two stacked charts). Leave them out for one cell.',
     '- `{ "name", "type": "metric", "query", "fieldFormats" }` — a single KPI number.',
     '  - `fieldFormats` (optional) sets how each of the metric\'s numbers is shown, one entry per field in order — the main field first, then each `extraFields` entry; `null` keeps a field as it is. An entry is `{ "size": "xs"|"sm"|"lg"|"xl", "type": "number"|"percent"|"date"|"datetime", ... }`, every key optional: `size` is the text size (left out: medium); `number` takes `decimals` (0-6), `prefix`, `suffix` and `"compact": true` for the short form (1.2M); `percent` takes `decimals`, `prefix`, `suffix` and `"fraction": true` when the value is a fraction to multiply by 100 (0.25 → 25%); `date` / `datetime` (for a `min` / `max` of a date field) take `format`, a pattern built from YYYY YY MMMM MMM MM M DD D dddd ddd HH H hh h mm ss A, with [brackets] around literal words ("D MMM YYYY HH:mm"). Left out (no `type`), the number is shown plainly with thousands separators. `prefix` and `suffix` are any text written before or after the number, units and words alike — "add the suffix claim" / "tambahkan suffix claim" is `{ "type": "number", "suffix": " claim" }` (start a word suffix with a space, end a word prefix with one); always give `type` with them. Use it for "show it in rupiah" (`prefix` "Rp "), "as a percentage", "no decimals", "short numbers", "bigger number" (`size` "lg" or "xl"), "latest order date" shown as a date. Set it only when the user asks about how a number looks, and never say a prefix, suffix, decimals, percent, short form, size or date format is impossible — answer with `update` and the metric\'s `fieldFormats`; when returning an existing metric, keep its `fieldFormats` unchanged, and when you reorder or remove its fields move or drop their entries with them.',
-    '- `{ "name", "type": "chart", "chart": "bar"|"line"|"pie"|"doughnut"|"polarArea"|"radar"|"scatter"|"bubble", "query" }` — a chart, `bar` when left out. `line` for a trend over time; `pie` or `doughnut` for the shares of a whole and `polarArea` to compare a few groups by size (count or sum over a few groups — past eight groups the rest is folded into Other); a `pie` or `doughnut` with `splitBy` draws two rings, the inner one by `groupBy` and the outer one splitting each inner slice by `splitBy` (its top `splitLimit` plus Other) — use it for shares by two fields, "chat sessions by business and sub-business" (`groupBy` business, `splitBy` subBusiness), count or sum only and never on a date `groupBy`; never split a `polarArea`; `radar` to compare a few groups (or splitBy parts) around one circle; `scatter` and `bubble` to show one dot per group, bubble sized by its value. A bar chart takes `"horizontal": true` to lay its bars sideways — use it for many groups or long labels (campaign names, customers), or when asked. Only when the user asks for one of these kinds, or the data clearly suits it.',
+    '- `{ "name", "type": "chart", "chart": "bar"|"line"|"pie"|"doughnut"|"polarArea"|"radar"|"scatter"|"bubble", "query" }` — a chart, `bar` when left out. `line` for a trend over time; `pie` or `doughnut` for the shares of a whole and `polarArea` to compare a few groups by size (count or sum over a few groups — past eight groups the rest is folded into Other; `"groupOther": false` on the query shows only the top eight with no Other slice, only when asked); a `pie` or `doughnut` with `splitBy` draws two rings, the inner one by `groupBy` and the outer one splitting each inner slice by `splitBy` (its top `splitLimit` plus Other) — use it for shares by two fields, "chat sessions by business and sub-business" (`groupBy` business, `splitBy` subBusiness), count or sum only and never on a date `groupBy`; never split a `polarArea`; `radar` to compare a few groups (or splitBy parts) around one circle; `scatter` and `bubble` to show one dot per group, bubble sized by its value. A bar chart takes `"horizontal": true` to lay its bars sideways — use it for many groups or long labels (campaign names, customers), or when asked. Only when the user asks for one of these kinds, or the data clearly suits it.',
     '- Chart look, any chart kind including a map: `"color": { "mode": "single", "color": "#RRGGBB" }` paints the whole series one color (not for pie, doughnut, polarArea or a split chart); `{ "mode": "mixed", "colors": ["#RRGGBB", ...] }` gives every bar, slice, dot or split part its own color (`colors` optional, the palette when left out). Leave `color` out for the default look. `"axisMarks": "day"|"week"|"month"|"none"` (bar or line grouped by `hour`, `day` or `week`, a horizontal bar too) marks where each day, week or month starts on the date axis — separator lines, alternating bands and the period\'s name ("Oct week 3" — the week of the month its Monday falls in — or "Oct 2026") under the dates — while every bar stays one bucket; left out, it is automatic (days for hourly data over several days, weeks past three weeks of days, months past three months of days or eight weeks). Set it only when asked ("show the weeks on the axis"); for one bar per week use `dateModifier` `week` instead. `"legend": true|false` shows or hides the legend; left out, it shows for split and round charts, and for mixed or heatmap maps. Set `color` and `legend` only when the user asks about colors or the legend.',
     '- `{ "name", "type": "chart", "chart": "map", "country": "ID", "color": { "mode": "single"|"mixed"|"heatmap" }, "query" }` — a map of one country (only Indonesia, `ID`, so far) with one point per place, sized by its value. Use it for "by city", "per region", "per province", "where are our customers", "map".',
     '  - Places come either from a place name field — `groupBy`, a string field holding Indonesian city, regency or province names; names match without case or punctuation, with or without "Kota" / "Kabupaten" / "Kab." / "Provinsi", in Indonesian or English ("Jakarta Selatan", "Kota Bandung", "Jawa Timur", "West Java", "Solo", "Jogja"), and a province is placed at its capital — or from `latField` + `lngField`, number fields holding latitude and longitude, with an optional `groupBy` naming each point. Pick a name field only when its values look like place names; names that cannot be placed are counted as "not on the map".',
@@ -40,14 +40,15 @@ export function buildInstruction(catalog) {
     '- `{ "name", "type": "table", "query" }` — a data table: a list of rows, or a pivot table when `query.pivot` is set.',
     '',
     '# Query shapes (preferred — the server computes live data from them)',
-    '- metric: `{ "datasource", "aggregation": "count"|"countDistinct"|"sum"|"avg"|"min"|"max", "field", "extraFields": [{ "aggregation", "field", "label" }], "breakdownBy": <field key>, "filters" }` — `field` is required unless aggregation is `count`; `countDistinct` counts the different values of any field ("unique customers" is countDistinct of the customer field). `extraFields` (up to 4) are more fields over the same rows and filters, shown smaller after the main number as a ratio — "76 / 12,000" for a *Total Chats / Total Views* metric (main: sum of chats, extra: sum of views); name the widget after all its fields, `label` names each extra one. `breakdownBy` breaks down the main field only.',
-    '- chart: `{ "datasource", "aggregation": "count"|"countDistinct"|"sum"|"avg"|"min"|"max", "field", "groupBy": <field key>, "dateModifier": ""|"hour"|"day"|"week"|"month"|"quarter"|"year"|"hourOfDay"|"dayOfWeek"|"dayOfMonth"|"monthOfYear", "bucketSize": <number>, "limit", "sort": "labelAsc"|"labelDesc"|"valueDesc"|"valueAsc", "fillEmpty": true, "splitBy": <field key>, "splitLimit": 1-20, "splitOther": false, "breakdownBy": <field key>, "filters" }` — `aggregation` / `field` measure every bar, slice or point: left out, each one counts its rows; `sum` / `avg` need a number field, `min` / `max` a number or date field, `countDistinct` any field. Use them for "revenue per month" (sum of the amount field), "average order value by city" (avg). Set a dateModifier when grouping by a date field: `hour` for "per hour" / "hourly", `day` for "per day" / "daily", and so on. `week` with `"weekOfMonth": true` keeps one bar per week but names each by the week of the month its Monday falls in ("Oct week 2") — use it for "week of month" or "weeks named by month". The recurring ones fold every date onto one cycle: `hourOfDay` (0-23) for "busiest hour" / "by hour of day" over several days, `dayOfWeek` (Monday to Sunday) for "by weekday", `dayOfMonth`, `monthOfYear` for seasonality. `bucketSize` groups a number field into ranges that wide (order totals in steps of 100000). `sort` orders the bars (left out: dates and ranges by label, other groups largest first). `fillEmpty` shows a zero bar for every empty bucket — set it for time series and recurring buckets so gaps are visible. `splitBy` stacks every bar by another field, one colour per value (its top `splitLimit`, 1 to 20, default 7, plus "Other" — `"splitOther": false` leaves Other out, only when asked) — use it for "per day, grouped by business", "by status per month". A split bar chart stacks its parts; `"stacked": false` on the node puts them side by side instead — set it when asked to compare the parts bar by bar ("side by side", "grouped", "not stacked"). Leave it out for a single-colour chart.',
+    '- metric: `{ "datasource", "aggregation": "count"|"countDistinct"|"sum"|"avg"|"min"|"max", "field", "extraFields": [{ "aggregation", "field", "label" }], "breakdownBy": <field key>, "breakdownLimit": 1-20, "breakdownOther": false, "filters" }` — `field` is required unless aggregation is `count`; `countDistinct` counts the different values of any field ("unique customers" is countDistinct of the customer field). `extraFields` (up to 4) are more fields over the same rows and filters, shown smaller after the main number as a ratio — "76 / 12,000" for a *Total Chats / Total Views* metric (main: sum of chats, extra: sum of views); name the widget after all its fields, `label` names each extra one. `breakdownBy` breaks down the main field only; `breakdownLimit` (default 4) sets how many top values its bar shows, `"breakdownOther": false` leaves the Other part out — only when asked.',
+    '- chart: `{ "datasource", "aggregation": "count"|"countDistinct"|"sum"|"avg"|"min"|"max", "field", "groupBy": <field key>, "dateModifier": ""|"hour"|"day"|"week"|"month"|"quarter"|"year"|"hourOfDay"|"dayOfWeek"|"dayOfMonth"|"monthOfYear", "bucketSize": <number>, "limit", "sort": "labelAsc"|"labelDesc"|"valueDesc"|"valueAsc", "fillEmpty": true, "splitBy": <field key>, "splitLimit": 1-20, "splitOther": false, "groupOther": false, "breakdownBy": <field key>, "filters" }` — `aggregation` / `field` measure every bar, slice or point: left out, each one counts its rows; `sum` / `avg` need a number field, `min` / `max` a number or date field, `countDistinct` any field. Use them for "revenue per month" (sum of the amount field), "average order value by city" (avg). Set a dateModifier when grouping by a date field: `hour` for "per hour" / "hourly", `day` for "per day" / "daily", and so on. `week` with `"weekOfMonth": true` keeps one bar per week but names each by the week of the month its Monday falls in ("Oct week 2") — use it for "week of month" or "weeks named by month". The recurring ones fold every date onto one cycle: `hourOfDay` (0-23) for "busiest hour" / "by hour of day" over several days, `dayOfWeek` (Monday to Sunday) for "by weekday", `dayOfMonth`, `monthOfYear` for seasonality. `bucketSize` groups a number field into ranges that wide (order totals in steps of 100000) — not on a pie, doughnut or polarArea. `sort` orders the bars (left out: dates and ranges by label, other groups largest first). `fillEmpty` shows a zero bar for every empty bucket — set it for time series and recurring buckets so gaps are visible. `splitBy` stacks every bar by another field, one colour per value (its top `splitLimit`, 1 to 20, default 7, plus "Other" — `"splitOther": false` leaves Other out, only when asked) — use it for "per day, grouped by business", "by status per month". A split bar chart stacks its parts; `"stacked": false` on the node puts them side by side instead — set it when asked to compare the parts bar by bar ("side by side", "grouped", "not stacked"). Leave it out for a single-colour chart.',
     '- chart `extraFields` (line and bar only, up to 4): `[{ "aggregation", "field", "label" }]` — more measures over the same rows, groups and filters, each drawn as its own line (or bar) in its own colour with a legend; `aggregation` / `field` stay the first one. Use it when one chart should compare several numbers over the same axis — "spend, impressions, chats and sales per hour" is a `line` chart grouped by the date field with `dateModifier: "hour"`, `aggregation: "sum"`, `field` the spend field and `extraFields` sum of impressions, chats and sales. Give the first one a label too as `fieldLabel`. Each line is scaled on its own, so numbers of very different sizes all read; set `"sharedAxis": true` on the node only when they share a unit and should be compared directly. It cannot be combined with `splitBy`; `breakdownBy` and a click break down the first field.',
     '- `detail` — cards with more about one value, e.g. a creative\'s image, title, body and link: `{ "fields": [{ "key", "type": "text"|"longText"|"number"|"date"|"datetime"|"image"|"link", "label", "format" }], "groupBy": <field key> }` reads the widget\'s own rows, one card per `groupBy` value (left out: one card, the latest row). When the details live in another datasource, give `"datasource": <its key>, "match": { "field": <this datasource\'s id field>, "to": <that datasource\'s matching field> }` instead of `groupBy`; `fields` are then that datasource\'s keys, and one card is shown per matching row (e.g. results by creative → `{ "datasource": "marketing_campaign_creative", "match": { "field": "creativeId", "to": "id" } }`). It goes on a pivot row field, or on a metric, chart or pivot table query with `"field": <the field whose values open it>` — an ⓘ then sits beside each of its values in the breakdown, and a chart grouped by that field shows Detail on the rows behind a bar. A date or date & time detail field may take `format`, a date pattern as in `fieldFormats`. Set it when asked to see or open details of a value.',
     '- `breakdownBy` (metric, chart and pivot table) — a field that is not a date; tapping the number or a bar opens a table of that value per `breakdownBy` value, every value listed. Set it when the user asks to see a widget broken down, or "per business" detail behind a number. A chart without one breaks down by its `splitBy`.',
     '- table: `{ "datasource", "columns": [{ "key", "label", "format" }], "order": [[<field key>, "asc"|"desc"], ...], "pageSize": 1-50, "filters" }` — `order` sorts by its first entry, then the next for ties (up to 5 levels); a column\'s optional `format` sets how its values are shown, the same shape as a metric\'s `fieldFormats` entry without `size` (`{ "type": "number", "prefix": "Rp " }`, `{ "type": "date", "format": "D MMM YYYY" }`); set it only when asked how a column looks, and keep it when returning the table. A column may also take `"colorScale"` (and `"colorScaleReverse": true`), the same as a pivot value\'s: its cells are tinted by rank among the table\'s rows — set it when asked to color, highlight or heat-map a column.',
     '- pivot table (a table with `pivot` instead of columns/order/pageSize): `{ "datasource", "pivot": { "rows": [{ "field", "label", "dateModifier", "bucketSize" }], "columns": [same], "values": [{ "aggregation", "field", "label", "showAs": "percentOfTotal"|"percentOfRow"|"percentOfColumn"|"percentOfParent" }], "sort": "labelDesc"|"valueDesc"|"valueAsc", "sortValue": <value index>, "grandTotals": "both"|"row"|"column"|"none", "subtotals": false }, "breakdownBy": <field key>, "filters" }` — like an Excel PivotTable: `rows` are nested down the side (each one a level with its own subtotal, collapsible), `columns` go across the top (usually one field, often a date with a dateModifier such as `month`), and every cell shows each of `values` for that row and column, with grand totals. `label` on a value reads like "Sum of Spend". `showAs` turns a value into a share (leave it out for the plain value). A row field may take a `"detail"` (see below): an ⓘ beside each of its rows opens its cards for that row — set it when asked to see the details behind a row. `sort` orders the rows within each level (left out: label A → Z; `valueDesc` / `valueAsc` = largest / smallest first by the value at index `sortValue` in `values`, 0 when left out). A value may also be calculated from two other values of the same pivot: `{ "aggregation": "calc", "label", "calc": { "a": { "aggregation", "field" }, "op": "/"|"*"|"+"|"-", "b": { "aggregation", "field" } }, "format": "percent" }` — `a` and `b` name values already in `values` (same aggregation and field); it is computed in each cell, so "impressions per spend %" is `a` sum of impressions, `op` "/", `b` sum of spend, `format` "percent". Calculated values cannot take `showAs`. Any value may take `"colorScale"`: a theme color (`primary`, `secondary`, `accent`) or a Tailwind color (`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `slate`, `gray`) — its cells are tinted by rank among the rows of the same level in that column, strongest at the highest value, or at the lowest with `"colorScaleReverse": true` (use it for \"lower is better\", like cost per chat) — set it when asked to color, highlight or heat-map a value. When a calculated value needs a value the pivot does not have yet, add that value to `values` too. Sorting "by Meta Chats" or "by impressions per spend" is `sort` `valueDesc` (or `valueAsc` for "lowest first") with `sortValue` the index of that value. Use a pivot table for "X by Y and Z", "per campaign per month", cross-tabs or summaries with subtotals. Tapping a cell opens its breakdown by `breakdownBy`, or the rows behind it when there is none.',
-    '- filters: `[{ "field": <field key>, "op": "="|"!="|">"|">="|"<"|"<="|"contains"|"in", "value" }]`',
+    '- filters: `[{ "field": <field key>, "op": "="|"!="|">"|">="|"<"|"<="|"contains"|"startsWith"|"endsWith"|"in"|"notIn", "value" }]` — `in` / `notIn` take a comma-separated list ("1,8") on text and number fields; `contains`, `startsWith`, `endsWith` are for text fields.',
+    '- more date ops: `between` / `exceptBetween` with `"YYYY-MM-DD..YYYY-MM-DD"` (both days included) keep or leave out a date range; `except` with one day (a date or a token like `@today`) leaves that whole day out; `weekday` keeps only those days of the week, `"value": "0,1,2,3,4"` (Monday = 0 … Sunday = 6, so "5,6" is weekends); `monthOfYear` keeps only those months of any year, `"value": "6,7,8"` (January = 1). Use `weekday` for "weekdays only" / "weekends", `monthOfYear` for "every December", `exceptBetween` for "excluding the holidays from … to …".',
     '- A field listed with `values` stores codes that each mean something ("8 = Closed"): filter on the stored code (`{ "field": "status", "op": "=", "value": 8 }` for closed sessions, `in` with "1,8" for several), never on the meaning. The dashboard shows the meanings wherever the codes appear, so use the meanings in widget names and replies.',
     '- periods — today, yesterday, this week, last week, this month, last month or a date range on a date field is ONE filter with the op `period`: `{ "field": "createdAt", "op": "period", "value": "today" | "yesterday" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth" | "2026-10-01..2026-10-15" }` (a range includes both days: from 00:00:00 of the first day to the end of the last). It is recomputed every time the dashboard opens, so "today" stays today. One specific day ("on 15 October", "2026-10-15") is a range of that day to itself, `"2026-10-15..2026-10-15"`. Never filter a date field with `=` or `!=` — on a date-time that matches only one exact moment, and the filter editor no longer offers them for dates (it shows `period` as **is**, with Today, Yesterday, This week, Last week, This month, Last month or Custom date — a from and a to date).',
     '- other relative dates ("last 7 days", "last 30 days", "this year") — a `>=` filter whose value is a token, never a literal date: `@today`, `@startOfWeek`, `@startOfMonth`, `@startOfYear`, optionally shifted (`@today-7d`, `@today-30d`, `@startOfMonth-1m`; units d, w, m, y). Each is that day at 00:00.',
@@ -57,7 +58,7 @@ export function buildInstruction(catalog) {
     '',
     '# What the user can do on the dashboard (answer questions about it with the action `none`)',
     '- Tapping a metric, a bar, a pie slice, a map point or a pivot cell opens its breakdown by `breakdownBy` (a chart without one uses `splitBy`), and tapping a breakdown row lists the records behind it. Without a breakdown field the tap lists the records straight away.',
-    '- A metric with `breakdownBy` also shows a thin bar under its number, split into its top four values plus Other.',
+    '- A metric with `breakdownBy` also shows a thin bar under its number, split into its top `breakdownLimit` values (default four) plus Other.',
     '- A metric\'s settings (Views, with the metric selected) list its fields one per row — the first is the big number, the rest are shown after it as a ratio; drag a row to the top to make it the main field. Clicking a field (or **+ Add field**) opens a card with its Field, Aggregation, **Font size** (Extra small to Extra large) and **Data type** — Auto, Number (decimal places, prefix, suffix, short form 1.2M), Percent (decimal places, prefix, suffix, value is a fraction) or Date / Date & time (a date format, or Custom… with its own pattern) — with a preview. These are the metric\'s `fieldFormats`.',
     '- The breakdown table and the table of records behind a widget each have a **Customize** button (sliders icon) that picks, orders, renames and hides their columns, sets a column\'s type (text, number, date, date & time) and date format; column widths dragged there are saved too. These are saved with the widget and kept when you change it, but you cannot set them — tell the user where they are.',
     '- A pivot table\'s row levels collapse and expand one by one or all at once; its columns can be resized by dragging their edges, and the widths are saved with the dashboard (your edits keep them).',
@@ -234,8 +235,11 @@ const querySchema = {
     splitBy: { type: 'string' },
     splitLimit: { type: 'number' },
     splitOther: { type: 'boolean' },
+    groupOther: { type: 'boolean' },
     weekOfMonth: { type: 'boolean' },
     breakdownBy: { type: 'string' },
+    breakdownLimit: { type: 'number' },
+    breakdownOther: { type: 'boolean' },
     detail: detailSchema,
     fieldLabel: { type: 'string' },
     extraFields: {
@@ -383,8 +387,12 @@ export const RESPONSE_SCHEMA = {
 
 const NODE_TYPES = [ 'group', 'metric', 'chart', 'table' ]
 const COLOR_SCALES = [ 'primary', 'secondary', 'accent', 'red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose', 'slate', 'gray' ]
-const FILTER_OPS = [ '=', '!=', '>', '>=', '<', '<=', 'contains', 'in', 'period' ]
+const FILTER_OPS = [ '=', '!=', '>', '>=', '<', '<=', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'period', 'between', 'except', 'exceptBetween', 'weekday', 'monthOfYear' ]
 const PERIOD = /^(today|yesterday|thisWeek|lastWeek|thisMonth|lastMonth|\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2})$/
+const DATE_RANGE = /^\d{4}-\d{2}-\d{2}\.\.\d{4}-\d{2}-\d{2}$/
+// Which values each op takes: date-only ops, their value shapes, and ops a date field cannot take.
+const DATE_ONLY_OPS = { period: PERIOD, between: DATE_RANGE, exceptBetween: DATE_RANGE, except: /^(@[a-zA-Z]+([+-]\d+[dwmy])?|\d{4}-\d{2}-\d{2})$/, weekday: /^[0-6](,[0-6])*$/, monthOfYear: /^([1-9]|1[0-2])(,([1-9]|1[0-2]))*$/ }
+const TEXT_ONLY_OPS = [ 'contains', 'startsWith', 'endsWith' ]
 const DATE_MODIFIERS = [ '', 'hour', 'day', 'week', 'month', 'quarter', 'year', 'hourOfDay', 'dayOfWeek', 'dayOfMonth', 'monthOfYear' ]
 const SORTS = [ 'labelAsc', 'labelDesc', 'valueDesc', 'valueAsc' ]
 const DETAIL_TYPES = [ 'text', 'longText', 'number', 'date', 'datetime', 'image', 'link' ]
@@ -422,7 +430,13 @@ function sanitizeFilters(filters, ds) {
   if (!Array.isArray(filters)) return []
   return filters
     .filter(f => f && ds.fields.has(f.field) && FILTER_OPS.includes(f.op) && f.value !== '' && f.value != null)
-    .filter(f => f.op !== 'period' || (ds.fields.get(f.field).type === 'date' && PERIOD.test(`${f.value}`)))
+    .filter(f => {
+      const type = ds.fields.get(f.field).type
+      if (DATE_ONLY_OPS[f.op]) return type === 'date' && DATE_ONLY_OPS[f.op].test(`${f.value}`)
+      if (TEXT_ONLY_OPS.includes(f.op)) return type !== 'date' && type !== 'number'
+      if (f.op === 'notIn') return type !== 'date'
+      return true
+    })
     .slice(0, 10)
     .map(f => ds.fields.get(f.field).type === 'date' && f.op === '=' && /^\d{4}-\d{2}-\d{2}$/.test(`${f.value}`)
       ? { field: f.field, op: 'period', value: `${f.value}..${f.value}` }
@@ -491,6 +505,10 @@ function sanitizeQuery(node, dsMap, notes) {
         if (extras.length) clean.extraFields = extras
       }
       sanitizeBreakdown(query, clean, ds, node, notes, dsMap)
+      if (clean.breakdownBy) {
+        if (query.breakdownLimit != null) clean.breakdownLimit = clampInt(query.breakdownLimit, 1, 20, 4)
+        if (query.breakdownOther === false) clean.breakdownOther = false
+      }
       return clean
     }
 
@@ -530,7 +548,7 @@ function sanitizeQuery(node, dsMap, notes) {
       const groupType = ds.fields.get(query.groupBy).type
       clean.dateModifier = groupType === 'date' && DATE_MODIFIERS.includes(query.dateModifier) ? query.dateModifier : ''
       if (clean.dateModifier === 'week' && query.weekOfMonth === true) clean.weekOfMonth = true
-      if (groupType === 'number' && Number(query.bucketSize) > 0 && Number.isFinite(Number(query.bucketSize))) clean.bucketSize = Number(query.bucketSize)
+      if (groupType === 'number' && ![ 'pie', 'doughnut', 'polarArea' ].includes(node.chart) && Number(query.bucketSize) > 0 && Number.isFinite(Number(query.bucketSize))) clean.bucketSize = Number(query.bucketSize)
       if (query.limit != null) clean.limit = clampInt(query.limit, 1, 100, 30)
       if (SORTS.includes(query.sort)) clean.sort = query.sort
       if (query.fillEmpty === true && (clean.dateModifier || clean.bucketSize)) clean.fillEmpty = true
@@ -553,6 +571,7 @@ function sanitizeQuery(node, dsMap, notes) {
         }
         else notes.push(`invalid splitBy "${query.splitBy}" on "${node.name}" — drawn without a split`)
       }
+      if (query.groupOther === false && [ 'pie', 'doughnut', 'polarArea' ].includes(node.chart)) clean.groupOther = false
       if (clean.splitBy && [ 'pie', 'doughnut', 'polarArea' ].includes(node.chart)
         && (node.chart === 'polarArea' || groupType === 'date' || ![ 'count', 'sum' ].includes(clean.aggregation))) {
         notes.push(`splitBy dropped on "${node.name}" — only a count or sum pie or doughnut not grouped by a date has an outer ring`)

package/src/utils/ai-dashboard-query.js

@@ -0,0 +1,465 @@
+// ── AI dashboard query engine ────────────────────────────────────────────────
+// Runs a dashboard node query (metric, chart, table, pivot) against a catalogue
+// of datasources, each mapping a Sequelize model to the fields it exposes.
+//
+//   const { createQueryEngine } = require('@mixd-id/web-scaffold/ai-dashboard-query')
+//   const { runQuery } = createQueryEngine({ models, datasources, canRead, fail })
+//   await runQuery({ datasource: 'order', type: 'chart', groupBy: 'createdAt', dateModifier: 'day' }, user)
+//
+// Options:
+//   models      → { [name]: SequelizeModel }, looked up by datasource.model and field.subquery.model
+//   datasources → [ { key, model, aggregations, fields: [ { key, label, type, relation?, attribute?, count?, subquery?, enum? } ] } ]
+//   canRead     → (datasource, user) => boolean, defaults to allowing all
+//   fail        → (key, message) => never, throws the host's validation error;
+//                 defaults to an Error carrying `errors: { [key]: [ message ] }`
+//   Sequelize   → the host's Sequelize class; defaults to the one the models are bound to.
+//                 It must be the host's copy, fn / col / literal are checked with instanceof
+
+const dayjs = require('dayjs')
+
+const TYPES = [ 'metric', 'chart', 'table', 'pivot' ]
+const OPS = [ '=', '!=', '>', '>=', '<', '<=', 'contains', 'startsWith', 'endsWith', 'in', 'notIn', 'notBetween', 'empty' ]
+const DATE_FORMATS = { hour: '%Y-%m-%d %H:00', day: '%Y-%m-%d', week: '%Y-%u', month: '%Y-%m', year: '%Y' }
+const RECURRING = { hourOfDay: 'HOUR', dayOfWeek: 'WEEKDAY', dayOfMonth: 'DAYOFMONTH', monthOfYear: 'MONTH' }
+const DATE_MODIFIERS = [ '', ...Object.keys(DATE_FORMATS), 'quarter', ...Object.keys(RECURRING) ]
+const MAX_CHART_LIMIT = 2000
+const MAX_PAGE_SIZE = 100
+const MAX_PIVOT_GROUPS = 5000
+const MAX_PIVOT_DIMENSIONS = 4
+const MAX_PIVOT_VALUES = 12
+
+const defaultFail = (key, message) => {
+  const error = new Error(message)
+  error.errors = { [key]: [ message ] }
+  throw error
+}
+
+function createQueryEngine({ models, datasources, canRead = () => true, fail = defaultFail, Sequelize } = {}) {
+  if(!models) throw new Error('createQueryEngine needs models')
+  if(!Array.isArray(datasources)) throw new Error('createQueryEngine needs a datasources array')
+
+  Sequelize = Sequelize ?? Object.values(models).find(_ => _?.sequelize)?.sequelize.constructor
+  if(!Sequelize) throw new Error('createQueryEngine needs Sequelize, or models bound to a connection')
+  const { Op, fn, col, literal, where: whereOf } = Sequelize
+
+  const datasourceFor = (key, user) => {
+    const datasource = datasources.find(_ => _.key === key)
+    if(!datasource) fail('datasource', `Unknown datasource: ${key}`)
+    if(!canRead(datasource, user)) fail('datasource', `No access to datasource: ${key}`)
+    return datasource
+  }
+
+  const fieldOf = (datasource, key, name = 'field') => {
+    const field = datasource.fields.find(_ => _.key === key)
+    if(!field) fail(name, `Unknown field "${key}" in ${datasource.key}`)
+    return field
+  }
+
+  const columnOf = (Model, key) => Model.rawAttributes[key]?.field ?? key
+
+  // Where a field is read from: the association path to join (empty for this table), the column,
+  // and for this table the attribute key. `relation` may be nested ('marketingCampaign.addon').
+  // The last relation's own key (addonId → addon.id) is the foreign key on the table before it, so it skips that join.
+  const sourceOf = (Model, field) => {
+    if(field.count || field.subquery) return { path: [] }
+    if(!field.relation) return { path: [], column: columnOf(Model, field.key), key: field.key }
+
+    const segments = field.relation.split('.')
+    let Source = Model
+    for(const [ i, segment ] of segments.entries()){
+      const association = Source.associations[segment]
+      if(!association) throw new Error(`Unknown relation ${field.relation} on ${Model.name}`)
+
+      if(i === segments.length - 1){
+        const path = segments.slice(0, i)
+        if(association.associationType === 'BelongsTo' && field.attribute === association.targetKey)
+          return { path, column: columnOf(Source, association.foreignKey), key: path.length ? undefined : association.foreignKey }
+        return { path: segments, column: columnOf(association.target, field.attribute) }
+      }
+      Source = association.target
+    }
+  }
+
+  // The SQL column of a field, qualified so it stays unambiguous next to joined tables
+  const refOf = (Model, field) => {
+    if(field.count) return countOf(Model, field)
+    if(field.subquery) return subqueryOf(Model, field)
+    const { path, column } = sourceOf(Model, field)
+    return col(`${path.length ? path.join('->') : Model.name}.${column}`)
+  }
+
+  // A `count` field: the number of rows of that has-many relation per record, as a correlated subquery,
+  // so it never multiplies this table's rows the way a join would
+  const countOf = (Model, field) => {
+    const association = Model.associations[field.count]
+    if(association?.associationType !== 'HasMany') throw new Error(`${field.count} is not a has-many relation of ${Model.name}`)
+
+    const queryInterface = Model.sequelize.getQueryInterface()
+    const table = queryInterface.quoteIdentifier(association.target.getTableName())
+    const foreignKey = queryInterface.quoteIdentifier(columnOf(association.target, association.foreignKey))
+    const sourceKey = queryInterface.quoteIdentifiers(`${Model.name}.${columnOf(Model, association.sourceKey)}`)
+    return literal(`(SELECT COUNT(*) FROM ${table} WHERE ${table}.${foreignKey} = ${sourceKey})`)
+  }
+
+  // A `subquery` field: count or sum of another model's rows that match this record, as a correlated subquery
+  // like a `count` field, for links no association can express.
+  // { model, aggregate: 'count' | 'sum', attribute, match: { theirKey: ourKey | { key: ourKey, collate } }, range: [ theirDate, ourFrom, ourTo ], where: { theirKey: value | [ values ] } }
+  // `collate` converts our column to the collation of theirs, so their index is used when the two differ.
+  // `index` forces their index, for a match column whose statistics make the optimizer scan instead
+  const subqueryOf = (Model, field) => {
+    const { model, aggregate = 'count', attribute, match = {}, range, where = {}, index } = field.subquery
+    const Target = models[model]
+    const queryInterface = Model.sequelize.getQueryInterface()
+    const theirs = (key) => `sub.${queryInterface.quoteIdentifier(columnOf(Target, key))}`
+    const ours = (key) => queryInterface.quoteIdentifiers(`${Model.name}.${columnOf(Model, key)}`)
+    const escape = (value) => Model.sequelize.escape(value)
+    const matchOf = (our) => {
+      const { key, collate } = typeof our === 'string' ? { key: our } : our
+      if(!collate) return ours(key)
+      if(!/^[a-z0-9_]+$/.test(collate)) throw new Error(`Invalid collation ${collate}`)
+      return `CONVERT(${ours(key)} USING ${collate.split('_')[0]}) COLLATE ${collate}`
+    }
+
+    const conditions = [
+      ...Object.entries(match).map(([ their, our ]) => `${theirs(their)} = ${matchOf(our)}`),
+      ...(range ? [ `${theirs(range[0])} >= ${ours(range[1])}`, `${theirs(range[0])} <= ${ours(range[2])}` ] : []),
+      ...Object.entries(where).map(([ key, value ]) => Array.isArray(value) ?
+        `${theirs(key)} IN (${value.map(escape).join(', ')})` : `${theirs(key)} = ${escape(value)}`)
+    ]
+    const expr = aggregate === 'sum' ? `COALESCE(SUM(${theirs(attribute)}), 0)` : 'COUNT(*)'
+    const table = queryInterface.quoteIdentifier(Target.getTableName())
+    const hint = index ? ` FORCE INDEX (${queryInterface.quoteIdentifier(index)})` : ''
+    return literal(`(SELECT ${expr} FROM ${table} sub${hint}${conditions.length ? ` WHERE ${conditions.join(' AND ')}` : ''})`)
+  }
+
+  // The where key of a field: its own attribute, or $relation.column$ for a joined one
+  const whereKeyOf = (Model, field) => {
+    const { path, column, key } = sourceOf(Model, field)
+    return path.length ? `$${path.join('.')}.${column}$` : key
+  }
+
+  // Nested LEFT JOINs for the relations the given field keys use.
+  // Queries pass subQuery: false, or a has-many join with a LIMIT moves this table into a subquery the joined columns can't reach
+  const joinsFor = (datasource, keys) => {
+    const Model = models[datasource.model]
+    const include = []
+
+    for(const key of new Set(keys)){
+      const field = datasource.fields.find(_ => _.key === key)
+      if(!field) continue
+
+      let level = include
+      for(const association of sourceOf(Model, field).path){
+        let node = level.find(_ => _.association === association)
+        if(!node) level.push(node = { association, attributes: [], required: false, include: [] })
+        level = node.include
+      }
+    }
+
+    return include
+  }
+
+  const queryKeys = ({ field, secondary, groupBy, filters, columns, order } = {}) => [
+    field, secondary?.field, groupBy,
+    ...(Array.isArray(filters) ? filters.map(_ => _?.field) : []),
+    ...(Array.isArray(columns) ? columns.map(_ => typeof _ === 'string' ? _ : _?.key) : []),
+    ...(Array.isArray(order) ? order.map(_ => Array.isArray(_) ? _[0] : undefined) : [])
+  ]
+
+  const RELATIVE_UNITS = { d: 'day', day: 'day', w: 'week', week: 'week', m: 'month', month: 'month', y: 'year', year: 'year' }
+
+  const toDate = (field, value) => {
+    if(value === null) return value
+    if(value === undefined || `${value}`.trim() === '') return undefined
+
+    const text = `${value}`.trim().toLowerCase()
+    let date
+
+    if(text === 'now') date = dayjs()
+    else if(text === 'today') date = dayjs().startOf('day')
+    else if(text === 'yesterday') date = dayjs().subtract(1, 'day').startOf('day')
+    else{
+      const relative = text.match(/^(now|today)?\s*([+-])\s*(\d+)\s*([a-z]+?)s?$/)
+      if(relative && RELATIVE_UNITS[relative[4]]){
+        const [ , base, sign, amount ] = relative
+        date = (base === 'today' ? dayjs().startOf('day') : dayjs()).add((sign === '-' ? -1 : 1) * amount, RELATIVE_UNITS[relative[4]])
+      }
+      else if(typeof value === 'number' || /^\d{4}-\d{2}(-\d{2})?([ t]\d{2}:\d{2}(:\d{2})?)?/.test(text))
+        date = dayjs(value)
+    }
+
+    if(!date?.isValid())
+      fail('filters', `Invalid date for ${field}: "${value}". Use YYYY-MM-DD [HH:mm:ss], today, yesterday, now or a relative value like -7d / now-1 month`)
+
+    return date.format('YYYY-MM-DD HH:mm:ss')
+  }
+
+  const isBlank = (value) => value === undefined || value === null || `${value}`.trim() === ''
+
+  const listOf = (value) => (Array.isArray(value) ? value : `${value ?? ''}`.split(',')).map(_ => `${_}`.trim()).filter(_ => _ !== '')
+
+  const COMPARE = { '=': Op.eq, '!=': Op.ne, '>': Op.gt, '>=': Op.gte, '<': Op.lt, '<=': Op.lte, 'in': Op.in, 'notIn': Op.notIn }
+  const LISTS = [ 'in', 'notIn' ]
+
+  const filtersToWhere = (datasource, filters = []) => {
+    if(!Array.isArray(filters)) fail('filters', 'filters must be an array')
+    const Model = models[datasource.model]
+
+    const and = filters.map(({ field, op = '=', value, dateModifier } = {}) => {
+      const definition = fieldOf(datasource, field, 'filters')
+      const { type } = definition
+      const key = whereKeyOf(Model, definition)
+      // A count / subquery field is an expression, not a column key
+      const where = (operator, value) => definition.count || definition.subquery ?
+        whereOf(refOf(Model, definition), { [operator]: value }) : { [key]: { [operator]: value } }
+      if(!OPS.includes(op)) fail('filters', `Unknown operator: ${op}`)
+
+      if(op === 'empty'){
+        const empty = type === 'string' ? { [Op.or]: [ where(Op.is, null), where(Op.eq, '') ] } : where(Op.is, null)
+        return value === false || value === 'false' ? { [Op.not]: empty } : empty
+      }
+
+      if(isBlank(value) || (LISTS.includes(op) && !listOf(value).length)) return null
+      if(op === 'notBetween' && !(Array.isArray(value) && value.length === 2)) fail('filters', `notBetween needs [ from, to ] for ${field}`)
+
+      if(dateModifier){
+        if(!RECURRING[dateModifier]) fail('filters', `Unknown filter dateModifier: ${dateModifier}`)
+        if(type !== 'date') fail('filters', `dateModifier needs a date field, ${field} is ${type}`)
+        if(!COMPARE[op]) fail('filters', `${op} cannot be used with dateModifier`)
+        return whereOf(fn(RECURRING[dateModifier], refOf(Model, definition)), { [COMPARE[op]]: LISTS.includes(op) ? listOf(value) : value })
+      }
+
+      if(type === 'date' && ![ 'contains', 'startsWith', 'endsWith' ].includes(op)){
+        value = LISTS.includes(op) ? listOf(value).map(_ => toDate(field, _))
+          : op === 'notBetween' ? value.map(_ => toDate(field, _))
+          : toDate(field, value)
+      }
+
+      switch(op){
+        case 'contains': return where(Op.substring, `${value}`)
+        case 'startsWith': return where(Op.startsWith, `${value}`)
+        case 'endsWith': return where(Op.endsWith, `${value}`)
+        case 'in': return where(Op.in, listOf(value))
+        case 'notIn': return where(Op.notIn, listOf(value))
+        case 'notBetween': return where(Op.notBetween, value)
+        default: return where(COMPARE[op], value)
+      }
+    })
+
+    const conditions = and.filter(Boolean)
+    return conditions.length ? { [Op.and]: conditions } : {}
+  }
+
+  const aggregateExpr = (datasource, Model, aggregation = 'count', field) => {
+    if(!datasource.aggregations.includes(aggregation)) fail('aggregation', `Unknown aggregation: ${aggregation}`)
+
+    if(aggregation === 'count')
+      return field ? fn('COUNT', refOf(Model, fieldOf(datasource, field))) : fn('COUNT', literal('*'))
+
+    if(!field) fail('field', `${aggregation} needs a field`)
+    const definition = fieldOf(datasource, field)
+    if(aggregation === 'countDistinct') return fn('COUNT', fn('DISTINCT', refOf(Model, definition)))
+    const { key, type } = definition
+    if((aggregation === 'sum' || aggregation === 'avg') && type !== 'number')
+      fail('field', `${aggregation} needs a number field, ${key} is ${type}`)
+    if(type === 'string') fail('field', `${aggregation} needs a number or date field, ${key} is a string`)
+
+    return fn(aggregation.toUpperCase(), refOf(Model, definition))
+  }
+
+  const toNumber = (value) => value === null || value === undefined || value instanceof Date || isNaN(Number(value)) ? value : Number(value)
+
+  const metric = async (datasource, Model, query) => {
+    const { aggregation, field, filters, secondary } = query
+    const where = filtersToWhere(datasource, filters)
+
+    const attributes = [ [ aggregateExpr(datasource, Model, aggregation, field), 'value' ] ]
+    if(secondary)
+      attributes.push([ aggregateExpr(datasource, Model, secondary.aggregation, secondary.field), 'secondary' ])
+
+    const row = await Model.findOne({ attributes, where, include: joinsFor(datasource, queryKeys(query)), subQuery: false, raw: true })
+
+    return {
+      value: toNumber(row?.value ?? 0),
+      ...(secondary ? { secondary: { value: toNumber(row?.secondary ?? 0) } } : {})
+    }
+  }
+
+  const groupLabel = (Model, group, dateModifier, bucketSize) => {
+    const column = refOf(Model, group)
+
+    if(dateModifier){
+      if(!DATE_MODIFIERS.includes(dateModifier)) fail('dateModifier', `Unknown dateModifier: ${dateModifier}`)
+      if(group.type !== 'date') fail('dateModifier', `dateModifier needs a date groupBy, ${group.key} is ${group.type}`)
+      if(RECURRING[dateModifier]) return fn(RECURRING[dateModifier], column)
+      if(dateModifier === 'quarter') return fn('CONCAT', fn('YEAR', column), '-Q', fn('QUARTER', column))
+      return fn('DATE_FORMAT', column, DATE_FORMATS[dateModifier])
+    }
+
+    if(!isBlank(bucketSize)){
+      const size = Number(bucketSize)
+      if(!(size > 0)) fail('bucketSize', `bucketSize must be a positive number`)
+      if(group.type !== 'number') fail('bucketSize', `bucketSize needs a number groupBy, ${group.key} is ${group.type}`)
+      const sql = column.val ?? Model.sequelize.getQueryInterface().quoteIdentifiers(column.col)
+      return literal(`FLOOR(${sql} / ${size}) * ${size}`)
+    }
+
+    return group.type === 'date' ? fn('DATE_FORMAT', column, '%Y-%m-%d %H:%i:%s') : column
+  }
+
+  const chart = async (datasource, Model, query) => {
+    const { aggregation, field, groupBy, dateModifier = '', bucketSize, limit, filters } = query
+    if(!groupBy) fail('groupBy', 'chart needs groupBy')
+
+    const group = fieldOf(datasource, groupBy, 'groupBy')
+    const label = groupLabel(Model, group, dateModifier, bucketSize)
+    const ascending = !!dateModifier || !isBlank(bucketSize)
+
+    const rows = await Model.findAll({
+      attributes: [ [ label, 'label' ], [ aggregateExpr(datasource, Model, aggregation, field), 'value' ] ],
+      where: filtersToWhere(datasource, filters),
+      include: joinsFor(datasource, queryKeys(query)),
+      group: [ literal('label') ],
+      order: ascending ? [ [ literal('label'), 'ASC' ] ] : [ [ literal('value'), 'DESC' ] ],
+      limit: Math.min(Math.max(parseInt(limit) || MAX_CHART_LIMIT, 1), MAX_CHART_LIMIT),
+      subQuery: false,
+      raw: true
+    })
+
+    return { series: rows.map(row => ({ label: row.label, value: toNumber(row.value) })) }
+  }
+
+  const table = async (datasource, Model, query) => {
+    const { columns, order = [], page = 0, pageSize = 20, filters } = query
+    if(columns !== undefined && columns !== null && !Array.isArray(columns)) fail('columns', 'columns must be an array')
+
+    const cols = (columns?.length ? columns : datasource.fields).map(column => {
+      const key = typeof column === 'string' ? column : column?.key
+      const field = fieldOf(datasource, key, 'columns')
+      return { key: field.key, label: (typeof column === 'object' && column.label) || field.label, field }
+    })
+
+    if(!Array.isArray(order)) fail('order', 'order must be an array')
+    const sort = order.map(([ key, dir = 'asc' ] = []) => {
+      const field = fieldOf(datasource, key, 'order')
+      if(![ 'asc', 'desc' ].includes(`${dir}`.toLowerCase())) fail('order', `Unknown direction: ${dir}`)
+      return [ refOf(Model, field), `${dir}`.toUpperCase() ]
+    })
+
+    const size = Math.min(Math.max(parseInt(pageSize) || 20, 1), MAX_PAGE_SIZE)
+    const offset = Math.max(parseInt(page) || 0, 0) * size
+
+    const rows = await Model.findAll({
+      attributes: cols.map(_ => [ refOf(Model, _.field), _.key ]),
+      where: filtersToWhere(datasource, filters),
+      include: joinsFor(datasource, [ ...queryKeys({ filters, order }), ...cols.map(_ => _.key) ]),
+      order: sort.length ? sort : [ [ refOf(Model, fieldOf(datasource, 'id')), 'DESC' ] ],
+      limit: size + 1,
+      offset,
+      subQuery: false,
+      raw: true
+    })
+
+    return {
+      columns: cols.map(({ key, label }) => ({ key, label })),
+      rows: rows.slice(0, size),
+      hasNext: rows.length > size
+    }
+  }
+
+  // A pivot dimension (row or column), read like a chart's groupBy
+  const pivotDimension = (datasource, Model, name) => (dimension) => {
+    const field = fieldOf(datasource, dimension?.field, `pivot.${name}`)
+    if(sourceOf(Model, field).path.some((_, i, path) => !oneRowPer(Model, path.slice(0, i + 1))))
+      fail(`pivot.${name}`, `${field.key} cannot be used in a pivot, its relation can match several rows`)
+    return { field, expr: groupLabel(Model, field, dimension.dateModifier ?? '', dimension.bucketSize) }
+  }
+
+  // Whether joining this association path keeps one row per record: belongs-to a primary or unique key, or has-one
+  const oneRowPer = (Model, path) => {
+    let Source = Model
+    for(const segment of path){
+      const association = Source.associations[segment]
+      const { targetKey, target } = association
+      const toUniqueKey = association.associationType === 'BelongsTo' &&
+        (targetKey === target.primaryKeyAttribute || !!target.rawAttributes[targetKey]?.unique)
+      if(!toUniqueKey && association.associationType !== 'HasOne') return false
+      Source = association.target
+    }
+    return true
+  }
+
+  const pivotKey = (value) => value === null || value === undefined ? '' : `${value}`
+
+  // One grouped query per subtotal level, so every subtotal and grand total (avg / min / max included)
+  // comes from the database. Level { r, c } groups by the first r row fields and by all column fields (c > 0) or none.
+  const pivot = async (datasource, Model, query) => {
+    const { pivot: spec, filters } = query
+    if(!spec || typeof spec !== 'object' || Array.isArray(spec)) fail('pivot', 'pivot needs { rows, columns, values }')
+
+    const listIn = (name, max) => {
+      const list = spec[name] ?? []
+      if(!Array.isArray(list)) fail(`pivot.${name}`, `pivot.${name} must be an array`)
+      if(list.length > max) fail(`pivot.${name}`, `pivot.${name} allows at most ${max}`)
+      return list
+    }
+
+    const rows = listIn('rows', MAX_PIVOT_DIMENSIONS).map(pivotDimension(datasource, Model, 'rows'))
+    const columns = listIn('columns', MAX_PIVOT_DIMENSIONS).map(pivotDimension(datasource, Model, 'columns'))
+    const values = listIn('values', MAX_PIVOT_VALUES)
+    const measures = (values.length ? values : [ { aggregation: 'count' } ])
+      .map(value => ({ field: value?.field, expr: aggregateExpr(datasource, Model, value?.aggregation ?? 'count', value?.field) }))
+
+    const where = filtersToWhere(datasource, filters)
+    const filterKeys = queryKeys({ filters })
+
+    const levels = []
+    for(let r = 0; r <= rows.length; r++)
+      for(const c of columns.length ? [ 0, columns.length ] : [ 0 ])
+        levels.push({ r, c, dimensions: [ ...rows.slice(0, r), ...columns.slice(0, c) ] })
+
+    const results = await Promise.all(levels.map(({ dimensions }) => Model.findAll({
+      attributes: [
+        ...dimensions.map((_, i) => [ _.expr, `k${i}` ]),
+        ...measures.map((_, i) => [ _.expr, `v${i}` ])
+      ],
+      where,
+      include: joinsFor(datasource, [ ...dimensions.map(_ => _.field.key), ...measures.map(_ => _.field), ...filterKeys ]),
+      ...(dimensions.length ? { group: dimensions.map((_, i) => literal(`k${i}`)) } : {}),
+      limit: MAX_PIVOT_GROUPS + 1,
+      subQuery: false,
+      raw: true
+    })))
+
+    return {
+      pivot: {
+        levels: levels.map(({ r, c, dimensions }, i) => ({
+          r, c,
+          rows: results[i].slice(0, MAX_PIVOT_GROUPS).map(row => [
+            ...dimensions.map((_, k) => pivotKey(row[`k${k}`])),
+            ...measures.map((_, v) => toNumber(row[`v${v}`] ?? null))
+          ])
+        })),
+        truncated: results.some(_ => _.length > MAX_PIVOT_GROUPS)
+      }
+    }
+  }
+
+  const runQuery = async ({ datasource: key, type, ...query } = {}, user) => {
+    if(!TYPES.includes(type)) fail('type', `type must be one of ${TYPES.join(', ')}`)
+
+    const datasource = datasourceFor(key, user)
+    const Model = models[datasource.model]
+
+    switch(type){
+      case 'metric': return metric(datasource, Model, query)
+      case 'chart': return chart(datasource, Model, query)
+      case 'table': return table(datasource, Model, query)
+      case 'pivot': return pivot(datasource, Model, query)
+    }
+  }
+
+  return { runQuery, filtersToWhere }
+}
+
+module.exports = { createQueryEngine, TYPES, OPS, DATE_MODIFIERS }

package/src/utils/ai-dashboard.js

@@ -52,10 +52,33 @@ function resolveDateToken(value, now = new Date()) {
   return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} 00:00:00`
 }
 
+// The filter editor's date ops, lowered to the plain ops every query engine runs:
+//   between / exceptBetween  "YYYY-MM-DD..YYYY-MM-DD", both days included
+//   except                   one day (a date or a token), the whole day left out
+//   weekday / monthOfYear    "0,4" — WEEKDAY() numbers (Monday = 0) / MONTH() numbers (January = 1)
 function resolveFilters(filters, now = new Date()) {
   if (!Array.isArray(filters)) return filters
+  const day = (value) => `${resolveDateToken(value, now) ?? ''}`.slice(0, 10)
+  const nextDay = (date) => resolveDateToken('@today+1d', new Date(`${date}T00:00:00`))
   return filters.flatMap(filter => {
-    if (filter?.op !== 'period') return [ { ...filter, value: resolveDateToken(filter?.value, now) } ]
+    const { field, op, value } = filter ?? {}
+    if (op === 'weekday' || op === 'monthOfYear') {
+      const list = `${value ?? ''}`.split(',').map(v => v.trim()).filter(Boolean)
+      return list.length ? [ { field, op: 'in', value: list.join(','), dateModifier: op === 'weekday' ? 'dayOfWeek' : 'monthOfYear' } ] : []
+    }
+    if (op === 'except') {
+      const date = day(value)
+      return /^\d{4}-\d{2}-\d{2}$/.test(date) ? [ { field, op: 'notBetween', value: [ `${date} 00:00:00`, `${date} 23:59:59` ] } ] : []
+    }
+    if (op === 'between' || op === 'exceptBetween') {
+      const range = `${value ?? ''}`.split('..').map(day)
+      if (range.length !== 2 || !range.every(date => /^\d{4}-\d{2}-\d{2}$/.test(date))) return []
+      const [ from, to ] = range[0] <= range[1] ? range : [ range[1], range[0] ]
+      return op === 'between'
+        ? [ { field, op: '>=', value: `${from} 00:00:00` }, { field, op: '<', value: nextDay(to) } ]
+        : [ { field, op: 'notBetween', value: [ `${from} 00:00:00`, `${to} 23:59:59` ] } ]
+    }
+    if (op !== 'period') return [ { ...filter, value: resolveDateToken(value, now) } ]
     const named = { today: [ '@today', '@tomorrow' ], yesterday: [ '@yesterday', '@today' ], thisWeek: [ '@startOfWeek', '@startOfWeek+1w' ], lastWeek: [ '@startOfWeek-1w', '@startOfWeek' ], thisMonth: [ '@startOfMonth', '@startOfMonth+1m' ], lastMonth: [ '@startOfMonth-1m', '@startOfMonth' ] }[filter.value]
     const custom = `${filter.value ?? ''}`.match(/^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/)
     if (!named && !custom) return []
@@ -66,6 +89,9 @@ function resolveFilters(filters, now = new Date()) {
   })
 }
 
+// Pie, doughnut and polar area slice by exact value: a saved `bucketSize` is ignored on them.
+const ROUND_CHARTS = [ 'pie', 'doughnut', 'polarArea' ]
+
 function bucketFilters(query, bucket) {
   if (bucket == null || bucket === '' || !query?.groupBy) return []
   const label = `${bucket}`
@@ -127,7 +153,7 @@ const AIDashboardMixin = {
         try{
           const filters = resolveFilters(copy.query.filters, now)
           const { extraFields, fieldLabel, weekOfMonth, detail, ...base } = copy.query
-          const query = { ...base, filters }
+          const query = { ...base, filters, ...(ROUND_CHARTS.includes(copy.chart) ? { bucketSize: undefined } : {}) }
           let data = copy.type === 'chart' && query.latField && query.lngField
             ? await this.analyzeMapNode(query)
             : await this.analyzeNode({ node: { ...copy, query } })
@@ -148,11 +174,14 @@ const AIDashboardMixin = {
                 .map(row => ({ label: row.label == null || `${row.label}` === 'null' ? '' : `${row.label}`, value: Number(row.value) || 0 }))
                 .sort((a, b) => b.value - a.value)
               const additive = [ 'count', 'sum', undefined, '' ].includes(query.aggregation)
-              const top = rows.length > 5 ? rows.slice(0, 4) : rows
+              const limit = Math.min(20, Math.max(1, parseInt(query.breakdownLimit) || 4))
+              const showOther = additive && query.breakdownOther !== false
+              // With Other on, one leftover value is shown itself rather than as an "Other" of one.
+              const top = showOther && rows.length === limit + 1 ? rows : rows.slice(0, limit)
               data.breakdown = {
                 field: query.breakdownBy,
                 rows: top,
-                other: additive && rows.length > top.length ? rows.slice(top.length).reduce((sum, row) => sum + row.value, 0) : null,
+                other: showOther && rows.length > top.length ? rows.slice(top.length).reduce((sum, row) => sum + row.value, 0) : null,
                 total: additive ? rows.reduce((sum, row) => sum + row.value, 0) : null,
               }
             }
@@ -173,11 +202,11 @@ const AIDashboardMixin = {
   },
 
   async loadBreakdown({ node, bucket, cell, value, page = 0 } = {}) {
-    const { splitBy, splitLimit, splitOther, weekOfMonth, breakdownBy, extraFields, fieldLabel, pivot, detail, ...query } = node?.query ?? {}
+    const { splitBy, splitLimit, splitOther, groupOther, weekOfMonth, breakdownBy, breakdownLimit, breakdownOther, extraFields, fieldLabel, pivot, detail, ...query } = node?.query ?? {}
     const field = breakdownBy || splitBy || null
     const filters = [
       ...(resolveFilters(query.filters, new Date()) ?? []),
-      ...(node.type === 'chart' ? bucketFilters(query, bucket) : []),
+      ...(node.type === 'chart' ? bucketFilters(ROUND_CHARTS.includes(node.chart) ? { ...query, bucketSize: undefined } : query, bucket) : []),
       ...(Array.isArray(cell) ? cell : []).flatMap(dim => `${dim?.value ?? ''}` === ''
         ? [ { field: dim.field, op: 'empty', value: true } ]
         : bucketFilters({ groupBy: dim.field, dateModifier: dim.dateModifier, bucketSize: dim.bucketSize }, dim.value)),
@@ -308,8 +337,9 @@ const AIDashboardMixin = {
   },
 
   // ── Filters → Sequelize `where` ─────────────────────────────────────────────
-  // A filter row is { field, op, value, dateModifier? }; op ∈ = != > >= < <= contains in empty.
-  // Rows with no field or no value are dropped, `in` is comma-split.
+  // A filter row is { field, op, value, dateModifier? }; op ∈ = != > >= < <= contains startsWith
+  // endsWith in notIn notBetween empty. Rows with no field or no value are dropped, `in` / `notIn`
+  // are comma-split, `notBetween` takes [ from, to ] (resolveFilters writes it for the date ops).
 
   filtersToWhere(scope, filters) {
     const { Op } = this.Sequelize
@@ -326,7 +356,13 @@ const AIDashboardMixin = {
         ? { [Op.or]: [ { [Op.is]: null }, { [Op.eq]: '' } ] }
         : { [Op.is]: null }
       else if (filter.op === 'contains') condition = { [Op.like]: `%${filter.value}%` }
-      else if (filter.op === 'in') condition = { [Op.in]: `${filter.value}`.split(',').map(v => v.trim()).filter(Boolean) }
+      else if (filter.op === 'startsWith') condition = { [Op.startsWith]: `${filter.value}` }
+      else if (filter.op === 'endsWith') condition = { [Op.endsWith]: `${filter.value}` }
+      else if (filter.op === 'in' || filter.op === 'notIn') {
+        const list = `${filter.value}`.split(',').map(v => v.trim()).filter(Boolean)
+        if (list.length) condition = { [filter.op === 'in' ? Op.in : Op.notIn]: list }
+      }
+      else if (filter.op === 'notBetween' && Array.isArray(filter.value) && filter.value.length === 2) condition = { [Op.notBetween]: filter.value }
       else if (ops[filter.op]) condition = { [ops[filter.op]]: filter.value }
       const target = (filter.dateModifier && bucketExpr(this.conn.fn, field.expr, filter.dateModifier)) || (field.sql ? field.expr : null)
       if (condition) and.push(target ? this.Sequelize.where(target, condition) : { [field.where]: condition })
@@ -446,7 +482,7 @@ const AIDashboardMixin = {
   },
 
   async nestChart(node, run) {
-    const { splitBy, splitLimit, splitOther, ...query } = node.query ?? {}
+    const { splitBy, splitLimit, splitOther, groupOther, ...query } = node.query ?? {}
     const plain = { ...node, query: { ...query, dateModifier: '', bucketSize: undefined } }
     if (![ 'count', 'sum', undefined, '' ].includes(query.aggregation)) return run(plain)
     const limit = Math.min(20, Math.max(1, parseInt(splitLimit) || 7))
@@ -455,9 +491,9 @@ const AIDashboardMixin = {
     const rows = ((await run(plain))?.series ?? [])
       .map(row => ({ label: named(row.label) ? `${row.label}` : '', value: Number(row.value) || 0 }))
       .sort((a, b) => b.value - a.value)
-    const top = rows.length > 8 ? rows.slice(0, 7) : rows
+    const top = rows.length > 8 ? rows.slice(0, groupOther === false ? 8 : 7) : rows
     const rest = rows.slice(top.length)
-    const series = [ ...top, ...(rest.length ? [ { label: 'Other', value: rest.reduce((sum, row) => sum + row.value, 0), other: true } ] : []) ]
+    const series = [ ...top, ...(rest.length && groupOther !== false ? [ { label: 'Other', value: rest.reduce((sum, row) => sum + row.value, 0), other: true } ] : []) ]
 
     const nested = {}
     await Promise.all(top.map(async row => {