json-rest-api 2.4.0 → 3.0.0

package/plugins/core/lib/anyapi/canonical-relationship-reader.js

@@ -1,7 +1,7 @@
 import { whereInIdentifiers } from '../querying/identifier-query.js'
 import { loadIncludedParentMap, parseIncludeTree } from '../querying/include-query-helpers.js'
 import { getResourceFieldset, parseFieldset } from '../querying-writing/field-utils.js'
-import { COMPUTED_DEPENDENCIES_KEY, RELATIONSHIP_READ_BATCH_SIZE } from '../querying-writing/knex-constants.js'
+import { COMPUTED_DEPENDENCIES_KEY } from '../querying-writing/knex-constants.js'
 import { buildResourceUrl, buildRelationshipUrl } from '../querying/url-helpers.js'
 import { normalizeId } from './utils/descriptor-helpers.js'
 import { applyFieldSelectionToQuery, buildFieldSelection } from '../querying-writing/knex-field-helpers.js'
@@ -177,36 +177,34 @@ export function createCanonicalRelationshipReader ({ api, knex, getDescriptor, g
         const targetDescriptor = getDescriptor(belongsToInfo.target)
 
         const nestedResources = []
-        for (let offset = 0; offset < ids.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
-          let query = db(targetDescriptor.canonical.tableName)
-            .where(targetDescriptor.canonical.tenantColumn, targetDescriptor.tenant)
-            .where(targetDescriptor.canonical.resourceColumn, targetDescriptor.resource)
-            .whereIn(getCanonicalResourceIdColumn(targetDescriptor), ids.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE))
-          const selectionState = await applyIncludeFieldSelection({
-            query,
-            resourceName: targetDescriptor.resource,
-            tableName: targetDescriptor.canonical.tableName,
-            context
-          })
-          query = selectionState.query
-          const scopedQueryState = await applyTargetScopeFilters({
-            query,
-            resourceName: targetDescriptor.resource,
-            tableName: targetDescriptor.canonical.tableName,
-            context
-          })
-          query = scopedQueryState.query
-          const rows = await applyDatabaseReadOptions(query)
+        let query = db(targetDescriptor.canonical.tableName)
+          .where(targetDescriptor.canonical.tenantColumn, targetDescriptor.tenant)
+          .where(targetDescriptor.canonical.resourceColumn, targetDescriptor.resource)
+          .modify(whereInIdentifiers, getCanonicalResourceIdColumn(targetDescriptor), ids)
+        const selectionState = await applyIncludeFieldSelection({
+          query,
+          resourceName: targetDescriptor.resource,
+          tableName: targetDescriptor.canonical.tableName,
+          context
+        })
+        query = selectionState.query
+        const scopedQueryState = await applyTargetScopeFilters({
+          query,
+          resourceName: targetDescriptor.resource,
+          tableName: targetDescriptor.canonical.tableName,
+          context
+        })
+        query = scopedQueryState.query
+        const rows = await applyDatabaseReadOptions(query)
 
-          for (const row of rows) {
-            const includeResource = includeRow({
-              row,
-              descriptor: targetDescriptor,
-              context,
-              fieldSelectionInfo: selectionState.fieldSelectionInfo
-            }, includes)
-            nestedResources.push(includeResource)
-          }
+        for (const row of rows) {
+          const includeResource = includeRow({
+            row,
+            descriptor: targetDescriptor,
+            context,
+            fieldSelectionInfo: selectionState.fieldSelectionInfo
+          }, includes)
+          nestedResources.push(includeResource)
         }
 
         if (childKeys.length > 0 && nestedResources.length > 0) {
@@ -244,36 +242,34 @@ export function createCanonicalRelationshipReader ({ api, knex, getDescriptor, g
           const targetDescriptor = getDescriptor(targetType)
 
           const ids = [...idSet]
-          for (let offset = 0; offset < ids.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
-            let query = db(targetDescriptor.canonical.tableName)
-              .where(targetDescriptor.canonical.tenantColumn, targetDescriptor.tenant)
-              .where(targetDescriptor.canonical.resourceColumn, targetDescriptor.resource)
-              .whereIn(getCanonicalResourceIdColumn(targetDescriptor), ids.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE))
-            const selectionState = await applyIncludeFieldSelection({
-              query,
-              resourceName: targetDescriptor.resource,
-              tableName: targetDescriptor.canonical.tableName,
-              context
-            })
-            query = selectionState.query
-            const scopedQueryState = await applyTargetScopeFilters({
-              query,
-              resourceName: targetDescriptor.resource,
-              tableName: targetDescriptor.canonical.tableName,
-              context
-            })
-            query = scopedQueryState.query
-            const rows = await applyDatabaseReadOptions(query)
-
-            for (const row of rows) {
-              const includeResource = includeRow({
-                row,
-                descriptor: targetDescriptor,
-                context,
-                fieldSelectionInfo: selectionState.fieldSelectionInfo
-              }, includes)
-              nestedResources.push(includeResource)
-            }
+          let query = db(targetDescriptor.canonical.tableName)
+            .where(targetDescriptor.canonical.tenantColumn, targetDescriptor.tenant)
+            .where(targetDescriptor.canonical.resourceColumn, targetDescriptor.resource)
+            .modify(whereInIdentifiers, getCanonicalResourceIdColumn(targetDescriptor), ids)
+          const selectionState = await applyIncludeFieldSelection({
+            query,
+            resourceName: targetDescriptor.resource,
+            tableName: targetDescriptor.canonical.tableName,
+            context
+          })
+          query = selectionState.query
+          const scopedQueryState = await applyTargetScopeFilters({
+            query,
+            resourceName: targetDescriptor.resource,
+            tableName: targetDescriptor.canonical.tableName,
+            context
+          })
+          query = scopedQueryState.query
+          const rows = await applyDatabaseReadOptions(query)
+
+          for (const row of rows) {
+            const includeResource = includeRow({
+              row,
+              descriptor: targetDescriptor,
+              context,
+              fieldSelectionInfo: selectionState.fieldSelectionInfo
+            }, includes)
+            nestedResources.push(includeResource)
           }
         }
 

package/plugins/core/lib/dbIntrospection.js

@@ -117,8 +117,17 @@ function parseEnumLikeValues (columnType = '', typeName = 'enum', backslashEscap
   return values
 }
 
-function normalizeMysqlDefault (row) {
+// MariaDB (10.2.7+) writes COLUMN_DEFAULT as SQL: a literal is quoted, NULL is
+// the word NULL and an expression is bare, where MySQL gives the bare literal.
+function normalizeMariadbDefault (value) {
+  if (typeof value !== 'string') return value
+  if (value === 'NULL') return null
+  return /^'(?:''|\\.|[^'\\])*'$/s.test(value) ? parseEnumLikeValues(`enum(${value})`, 'enum', true)[0] : value
+}
+
+function normalizeMysqlDefault (row, mariadb) {
   const value = Object.hasOwn(row, 'columnDefault') ? row.columnDefault : row.column_default
+  if (mariadb) return normalizeMariadbDefault(value)
   if (row.dataType !== 'json' || typeof value !== 'string') return value
   let expression = value.trim()
   if (expression.startsWith('(') && expression.endsWith(')')) expression = expression.slice(1, -1).trim()
@@ -917,8 +926,9 @@ function normalizeDbSchemaName (rows = []) {
 }
 
 async function introspectMysqlTableSnapshot (knex, { tableName, idColumn }) {
-  const schemaRows = normalizeRows(await knex.raw('SELECT DATABASE() AS schemaName'))
+  const schemaRows = normalizeRows(await knex.raw('SELECT DATABASE() AS schemaName, VERSION() AS version'))
   const schemaName = normalizeDbSchemaName(schemaRows)
+  const mariadb = /mariadb/i.test(normalizeText(schemaRows[0]?.version))
 
   const tableRows = normalizeRows(
     await knex.raw(
@@ -1052,12 +1062,17 @@ async function introspectMysqlTableSnapshot (knex, { tableName, idColumn }) {
     )
   )
 
+  // MariaDB stores JSON as LONGTEXT with a column check json_valid(`column`):
+  // that pair is a JSON column, and its check is part of the type.
+  const jsonCheck = (/** @type {any} */ row) => mariadb && /^json_valid\(`((?:``|[^`])+)`\)$/i.exec(normalizeText(row.checkClause))?.[1].replace(/``/g, '`')
+  const jsonColumns = new Set(checkConstraintRows.map(jsonCheck).filter(Boolean))
   const columns = columnRows.map((row) => buildColumnSnapshot({
     name: row.columnName,
-    dataType: row.dataType,
-    columnType: row.columnType,
+    ...(jsonColumns.has(row.columnName) && normalizeText(row.dataType).toLowerCase() === 'longtext'
+      ? { dataType: 'json', columnType: 'json' }
+      : { dataType: row.dataType, columnType: row.columnType }),
     nullable: normalizeText(row.isNullable).toUpperCase() === 'YES',
-    defaultValue: normalizeMysqlDefault(row),
+    defaultValue: normalizeMysqlDefault(row, mariadb),
     defaultIsLiteral: true,
     extra: row.extra,
     autoIncrement: normalizeText(row.extra).toLowerCase().includes('auto_increment'),
@@ -1088,7 +1103,7 @@ async function introspectMysqlTableSnapshot (knex, { tableName, idColumn }) {
     indexes: normalizeIndexes(indexRows),
     foreignKeys: normalizeForeignKeys(foreignKeyRows, [], tableName),
     checkConstraints: normalizeCheckConstraints(
-      checkConstraintRows.map((row) => ({
+      checkConstraintRows.filter(row => !jsonColumns.has(jsonCheck(row))).map((row) => ({
         name: row.constraintName,
         clause: row.checkClause
       })),
@@ -1265,6 +1280,91 @@ export async function listKnexTableIndexes (knex, tableName) {
   return new Map(rows.map(row => [row.name, { valid: row.valid !== false, building: row.building === true }]))
 }
 
+/**
+ * The schema a MySQL or MariaDB connection is using, from `database()`, a
+ * statement that reads no table.
+ * @param {any} knex
+ * @returns {Promise<string>}
+ */
+export async function currentKnexMysqlSchema (knex) {
+  return normalizeRows(await knex.raw('select database() as name'))[0]?.name
+}
+
+/**
+ * The indexes of a MySQL or MariaDB table that the optimizer may use, unique
+ * or not, the primary key included: each with its columns in key order and
+ * the length of a column prefix (`prefix`, null for the whole column). A
+ * column list ends before its first functional key part, which names no
+ * column. Invisible (MySQL) and ignored (MariaDB) indexes are left out.
+ * @param {any} knex
+ * @param {string} schema
+ * @param {string} tableName
+ * @returns {Promise<Array<{ name: string, columns: Array<{ name: string, prefix: number | null }> }>>}
+ */
+export async function listKnexMysqlIndexes (knex, schema, tableName) {
+  const rows = normalizeRows(await knex.raw(`
+    select * from information_schema.statistics
+    where table_schema = ? and table_name = ?
+    order by index_name, seq_in_index`, [schema, tableName]))
+  const byIndex = new Map()
+  for (const raw of rows) {
+    const row = Object.fromEntries(Object.entries(raw).map(([key, value]) => [key.toLowerCase(), value]))
+    if (row.is_visible === 'NO' || row.ignored === 'YES') continue
+    if (!byIndex.has(row.index_name)) byIndex.set(row.index_name, [])
+    byIndex.get(row.index_name).push(row.column_name == null ? null : { name: row.column_name, prefix: row.sub_part == null ? null : Number(row.sub_part) })
+  }
+  return [...byIndex].map(([name, columns]) => ({ name, columns: columns.includes(null) ? columns.slice(0, columns.indexOf(null)) : columns }))
+}
+
+/**
+ * The column lists of a table's unique indexes and constraints, primary key
+ * included, that guarantee uniqueness for every row: partial, expression and
+ * invalid indexes are left out.
+ * @param {any} knex
+ * @param {string} tableName
+ * @returns {Promise<string[][]>}
+ */
+export async function listKnexUniqueKeyColumns (knex, tableName) {
+  const dialect = detectDialect(knex)
+  if (dialect === 'sqlite') {
+    const keys = []
+    for (const index of normalizeRows(await knex.raw('PRAGMA index_list(??)', [tableName]))) {
+      if (Number(index.unique) !== 1 || Number(index.partial) === 1) continue
+      const columns = normalizeRows(await knex.raw('PRAGMA index_info(??)', [index.name]))
+      if (columns.length && columns.every(column => column.name)) keys.push(columns.sort((a, b) => a.seqno - b.seqno).map(column => column.name))
+    }
+    // An INTEGER PRIMARY KEY is the rowid and has no index entry.
+    const primary = normalizeRows(await knex.raw('PRAGMA table_info(??)', [tableName])).filter(column => Number(column.pk) > 0)
+    if (primary.length) keys.push(primary.sort((a, b) => a.pk - b.pk).map(column => column.name))
+    return keys
+  }
+  const rows = dialect === 'mysql2'
+    ? normalizeRows(await knex.raw(`
+      select index_name as indexName, column_name as columnName, seq_in_index as position
+      from information_schema.statistics
+      where table_schema = database() and table_name = ? and non_unique = 0
+      order by index_name, seq_in_index`, [tableName]))
+    : normalizeRows(await knex.raw(`
+      select c.relname as "indexName", a.attname as "columnName", k.position
+      from pg_index i
+      join pg_class t on t.oid = i.indrelid
+      join pg_namespace n on n.oid = t.relnamespace
+      join pg_class c on c.oid = i.indexrelid
+      cross join lateral unnest(i.indkey) with ordinality as k(num, position)
+      left join pg_attribute a on a.attrelid = t.oid and a.attnum = k.num
+      where t.relname = ? and n.nspname = current_schema() and i.indisunique and i.indisvalid
+        and i.indpred is null and i.indexprs is null and k.position <= i.indnkeyatts
+      order by c.relname, k.position`, [tableName]))
+  const byIndex = new Map()
+  for (const row of rows) {
+    const name = row.indexName ?? row.INDEX_NAME
+    if (!byIndex.has(name)) byIndex.set(name, [])
+    byIndex.get(name).push(row.columnName ?? row.COLUMN_NAME ?? null)
+  }
+  // A functional index (MySQL) has no column name.
+  return [...byIndex.values()].filter(columns => columns.every(Boolean))
+}
+
 // Column-only ALTER must not impose the resource snapshot's ID or index restrictions.
 export async function introspectKnexColumnConstraints (knex, tableName) {
   requireKnexRaw(knex)

package/plugins/core/lib/querying/aggregate-query.js

@@ -1,5 +1,6 @@
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 import { applyDatabaseReadOptions, normalizeStoredFieldValue } from '../querying-writing/database-value-normalizers.js'
+import { databaseFamily } from '../storage/many-row-data-helpers.js'
 
 const NUMERIC_TYPES = new Set(['number', 'integer', 'epochMilliseconds', 'epochSeconds'])
 const ORDERED_TYPES = new Set([...NUMERIC_TYPES, 'string', 'email', 'uuid', 'date', 'dateTime', 'time'])
@@ -17,6 +18,13 @@ const PARAMS = new Set(['groupBy', 'measures', 'queryParams', 'transaction'])
 const QUERY_PARAMS = new Set(['filters', 'sort', 'page'])
 const OUTPUT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const AGGREGATE_ALIAS = '__jra_aggregate'
+const TEMPORAL_TYPES = new Set(['date', 'dateTime'])
+const BUCKETS = new Set(['day', 'week', 'month', 'year'])
+const UTC_NAMES = new Set(['UTC', 'Etc/UTC', '+00:00', '-00:00'])
+const OFFSET = /^([+-])(\d{2}):(\d{2})$/
+const ZONE_NAME = /^[A-Za-z][A-Za-z0-9_+\-/]*$/
+// Comparison operators of a measure's where, by SQL operator.
+const WHERE_OPERATORS = { eq: '=', ne: '<>', gt: '>', gte: '>=', lt: '<', lte: '<=' }
 
 const invalid = (field, message) => {
   throw new RestApiValidationError(message, { fields: [field], violations: [{ field, rule: 'aggregate', message }] })
@@ -36,9 +44,13 @@ const positiveInteger = (value, field) => {
  * Validate an aggregate request against a resource's compiled schema.
  * Only stored scalar fields whose stored values are their public values qualify:
  * getters and storage serializers would make SQL group or sum other values than clients see.
- * @param {{ params: Record<string, any>, schemaInfo: Record<string, any>, scopeName: string, defaultLimit: number, maxLimit: number }} request
+ * A system context may also group by, and count distinct, a hidden ownership
+ * field, so a job can find which owners have rows. A scoped caller would see
+ * only its own owner, and one whose optional owner filter did not resolve
+ * would see every owner's hidden value, so neither may.
+ * @param {{ params: Record<string, any>, schemaInfo: Record<string, any>, scopeName: string, defaultLimit: number, maxLimit: number, system?: boolean }} request
  */
-export function compileAggregateRequest ({ params, schemaInfo, scopeName, defaultLimit, maxLimit }) {
+export function compileAggregateRequest ({ params, schemaInfo, scopeName, defaultLimit, maxLimit, system = false }) {
   if (!isPlainObject(params)) invalid('params', 'aggregate requires a parameter object')
   for (const key of Object.keys(params)) {
     if (!PARAMS.has(key)) invalid(key, `Unknown aggregate parameter '${key}'`)
@@ -50,44 +62,54 @@ export function compileAggregateRequest ({ params, schemaInfo, scopeName, defaul
   }
 
   const fields = schemaInfo.schemaStructure || {}
-  const fieldDefinition = (name, parameter) => {
+  // A storage serializer changes what SQL sees; date and dateTime fields may still be
+  // bucketed and take min/max, as SQL orders and truncates their stored temporal values.
+  const owners = new Set(system ? schemaInfo.ownershipFields || [] : [])
+  const fieldDefinition = (name, parameter, { serializedTemporal = false, owner = false } = {}) => {
     const definition = typeof name === 'string' && Object.hasOwn(fields, name) ? fields[name] : null
-    if (!definition || name === 'id' || name === schemaInfo.idProperty || definition.virtual === true || definition.hidden === true) {
+    const hidden = definition?.hidden === true && !(owner && owners.has(name))
+    if (!definition || name === 'id' || name === schemaInfo.idProperty || definition.virtual === true || hidden) {
       invalid(parameter, `'${name}' is not an attribute of '${scopeName}' that can be aggregated`)
     }
-    if (typeof definition.getter === 'function' || definition.storage?.serialize) {
+    const serialized = Boolean(definition.storage?.serialize) && !(serializedTemporal && TEMPORAL_TYPES.has(definition.type))
+    if (typeof definition.getter === 'function' || serialized) {
       invalid(parameter, `Field '${name}' transforms its stored values, so it cannot be aggregated`)
     }
     return definition
   }
 
-  if (!Array.isArray(groupBy)) invalid('groupBy', 'groupBy must be an array of field names')
-  const groups = groupBy.map((field, index) => {
-    const definition = fieldDefinition(field, `groupBy.${index}`)
-    if (!SCALAR_TYPES.has(definition.type)) invalid(`groupBy.${index}`, `Field '${field}' has type '${definition.type}' and cannot be grouped`)
-    return { name: field, field, definition, alias: `g${index}` }
+  if (!Array.isArray(groupBy)) invalid('groupBy', 'groupBy must be an array of field names or buckets')
+  const names = new Set()
+  const groups = groupBy.map((entry, index) => {
+    const parameter = `groupBy.${index}`
+    if (isPlainObject(entry)) return compileBucket(entry, { parameter, alias: `g${index}`, fieldDefinition, names })
+    const definition = fieldDefinition(entry, parameter, { owner: true })
+    if (!SCALAR_TYPES.has(definition.type)) invalid(parameter, `Field '${entry}' has type '${definition.type}' and cannot be grouped`)
+    if (names.has(entry)) invalid('groupBy', 'groupBy lists a field twice')
+    names.add(entry)
+    return { name: entry, field: entry, definition, alias: `g${index}` }
   })
-  if (new Set(groupBy).size !== groupBy.length) invalid('groupBy', 'groupBy lists a field twice')
 
   if (!isPlainObject(measures) || !Object.keys(measures).length) invalid('measures', 'measures must name at least one measure')
-  const names = new Set(groupBy)
   const measureList = Object.entries(measures).map(([name, spec], index) => {
     const parameter = `measures.${name}`
     if (!OUTPUT_NAME.test(name)) invalid(parameter, `Measure name '${name}' must be a letter or underscore followed by letters, digits or underscores`)
     if (names.has(name)) invalid(parameter, `Measure '${name}' has the name of a grouped field`)
     names.add(name)
-    const entries = isPlainObject(spec) ? Object.entries(spec) : []
+    const { where, ...functions } = isPlainObject(spec) ? spec : {}
+    const entries = Object.entries(functions)
     if (entries.length !== 1 || !Object.hasOwn(MEASURES, entries[0][0])) {
-      invalid(parameter, `Measure '${name}' must be one of { ${Object.keys(MEASURES).join(' | ')}: field }`)
+      invalid(parameter, `Measure '${name}' must be one of { ${Object.keys(MEASURES).join(' | ')}: field, where? }`)
     }
     const [fn, field] = entries[0]
+    const condition = where === undefined ? null : compileWhere(where, { parameter: `${parameter}.where`, fieldDefinition })
     if (field === '*') {
       if (fn !== 'count') invalid(parameter, "Only count accepts '*'")
-      return { name, fn, field, definition: null, alias: `m${index}` }
+      return { name, fn, field, definition: null, alias: `m${index}`, where: condition }
     }
-    const definition = fieldDefinition(field, parameter)
+    const definition = fieldDefinition(field, parameter, { serializedTemporal: fn === 'min' || fn === 'max', owner: fn === 'countDistinct' })
     if (!MEASURES[fn].has(definition.type)) invalid(parameter, `${fn} cannot be applied to field '${field}' of type '${definition.type}'`)
-    return { name, fn, field, definition, alias: `m${index}` }
+    return { name, fn, field, definition, alias: `m${index}`, where: condition }
   })
 
   const outputs = new Map([...groups, ...measureList].map(output => [output.name, output.alias]))
@@ -121,6 +143,155 @@ export function compileAggregateRequest ({ params, schemaInfo, scopeName, defaul
   return { groups, measures: measureList, sort, page, scopeName }
 }
 
+/**
+ * A time bucket: { field, bucket: day | week | month | year, timezone?, as? }.
+ * Buckets come out as the 'YYYY-MM-DD' of their first day (weeks start on Monday).
+ */
+function compileBucket (entry, { parameter, alias, fieldDefinition, names }) {
+  const { field, bucket, timezone, as, ...unknown } = entry
+  if (Object.keys(unknown).length) invalid(parameter, `Unknown bucket options: ${Object.keys(unknown).join(', ')}`)
+  if (!BUCKETS.has(bucket)) invalid(`${parameter}.bucket`, `bucket must be one of ${[...BUCKETS].join(', ')}`)
+  const definition = fieldDefinition(field, `${parameter}.field`, { serializedTemporal: true })
+  if (!TEMPORAL_TYPES.has(definition.type)) invalid(`${parameter}.field`, `Field '${field}' has type '${definition.type}'; buckets need a date or dateTime field`)
+  const zone = compileTimezone(timezone, `${parameter}.timezone`)
+  if (definition.type === 'date' && zone.kind !== 'utc') invalid(`${parameter}.timezone`, 'A date field has no time of day, so it takes no timezone')
+  const name = as ?? field
+  if (typeof name !== 'string' || !OUTPUT_NAME.test(name)) invalid(`${parameter}.as`, 'as must be a letter or underscore followed by letters, digits or underscores')
+  if (names.has(name)) invalid(parameter, `groupBy names '${name}' twice; give the bucket another name with as`)
+  names.add(name)
+  return { name, field, definition, alias, bucket, timezone: zone }
+}
+
+// 'UTC' (default), a fixed offset '±HH:MM', or an IANA zone name.
+function compileTimezone (timezone, parameter) {
+  if (timezone === undefined || UTC_NAMES.has(timezone)) return { kind: 'utc' }
+  if (typeof timezone !== 'string') invalid(parameter, 'timezone must be a string')
+  const offset = OFFSET.exec(timezone)
+  if (offset) {
+    const [, sign, hours, minutes] = offset
+    if (Number(hours) > 14 || Number(minutes) > 59) invalid(parameter, `'${timezone}' is not a UTC offset`)
+    return { kind: 'offset', minutes: (sign === '-' ? -1 : 1) * (Number(hours) * 60 + Number(minutes)) }
+  }
+  let known = ZONE_NAME.test(timezone)
+  try {
+    // eslint-disable-next-line no-new
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone })
+  } catch {
+    known = false
+  }
+  if (!known) invalid(parameter, `'${timezone}' is not a time zone: use 'UTC', an offset such as '+10:00', or an IANA name`)
+  return { kind: 'named', name: timezone }
+}
+
+/**
+ * A measure's where: { field: value | [values] | null | { eq, ne, gt, gte, lt, lte, in, notIn } },
+ * every entry required. Compiled to the condition of a CASE, so one query computes
+ * conditional and unconditional measures together.
+ */
+function compileWhere (where, { parameter, fieldDefinition }) {
+  if (!isPlainObject(where) || !Object.keys(where).length) invalid(parameter, 'where must map fields to conditions')
+  const conditions = []
+  for (const [field, condition] of Object.entries(where)) {
+    const definition = fieldDefinition(field, `${parameter}.${field}`)
+    if (!SCALAR_TYPES.has(definition.type)) invalid(`${parameter}.${field}`, `Field '${field}' has type '${definition.type}' and cannot be compared`)
+    const add = (operator, value) => {
+      if (operator === 'in' || operator === 'notIn') {
+        if (!Array.isArray(value) || !value.length || value.some(item => item === null || typeof item === 'object')) {
+          invalid(`${parameter}.${field}.${operator}`, `${operator} takes a non-empty array of scalar values`)
+        }
+      } else if (value !== null && typeof value === 'object' && !(value instanceof Date)) {
+        invalid(`${parameter}.${field}`, 'Conditions compare scalar values')
+      } else if (value === null && operator !== 'eq' && operator !== 'ne') {
+        invalid(`${parameter}.${field}.${operator}`, `${operator} cannot compare with null`)
+      }
+      conditions.push({ field, definition, operator, value })
+    }
+    if (Array.isArray(condition)) add('in', condition)
+    else if (isPlainObject(condition)) {
+      const entries = Object.entries(condition)
+      if (!entries.length) invalid(`${parameter}.${field}`, 'A condition needs an operator')
+      for (const [operator, value] of entries) {
+        if (!Object.hasOwn(WHERE_OPERATORS, operator) && operator !== 'in' && operator !== 'notIn') {
+          invalid(`${parameter}.${field}.${operator}`, `Unknown operator '${operator}': use ${[...Object.keys(WHERE_OPERATORS), 'in', 'notIn'].join(', ')}`)
+        }
+        add(operator, value)
+      }
+    } else add('eq', condition)
+  }
+  return conditions
+}
+
+/** SQL and bindings for a compiled where, against qualified columns. */
+function whereSql (conditions, { column, storageAdapter }) {
+  const parts = []
+  const bindings = []
+  for (const { field, operator, value } of conditions) {
+    const target = column(field)
+    if (value === null) {
+      parts.push(operator === 'eq' ? '?? is null' : '?? is not null')
+      bindings.push(target)
+    } else if (operator === 'in' || operator === 'notIn') {
+      const values = storageAdapter.translateFilterValue(field, value)
+      parts.push(`?? ${operator === 'in' ? 'in' : 'not in'} (${values.map(() => '?').join(', ')})`)
+      bindings.push(target, ...values)
+    } else {
+      parts.push(`?? ${WHERE_OPERATORS[operator]} ?`)
+      bindings.push(target, storageAdapter.translateFilterValue(field, value))
+    }
+  }
+  return { sql: parts.join(' and '), bindings }
+}
+
+/**
+ * The bucket of a stored date or dateTime, as 'YYYY-MM-DD' text. Values are
+ * stored in UTC: SQLite holds epoch milliseconds (or ISO text), MySQL DATETIME
+ * and PostgreSQL timestamptz or date. Offsets and zone names are validated and
+ * written into the SQL, so GROUP BY repeats the selected expression exactly
+ * (PostgreSQL cannot match two expressions that differ in bound parameters).
+ * The only bindings are the column identifier.
+ */
+function bucketSql ({ family, column, bucket, timezone, type }) {
+  const minutes = timezone.kind === 'offset' ? timezone.minutes : 0
+  if (family === 'pg') {
+    let local = type === 'date' ? 'cast(?? as timestamp)' : "(?? at time zone 'UTC')"
+    if (timezone.kind === 'offset') local = `(${local} + interval '${minutes} minutes')`
+    if (timezone.kind === 'named') local = `(?? at time zone '${timezone.name}')`
+    return { sql: `to_char(date_trunc('${bucket}', ${local}), 'YYYY-MM-DD')`, bindings: [column] }
+  }
+  if (family === 'mysql') {
+    let local = '??'
+    if (timezone.kind === 'offset') local = `(?? + interval ${minutes} minute)`
+    if (timezone.kind === 'named') local = `convert_tz(??, '+00:00', '${timezone.name}')`
+    if (bucket === 'week') return { sql: `date_format(${local} - interval weekday(${local}) day, '%Y-%m-%d')`, bindings: [column, column] }
+    const format = { day: '%Y-%m-%d', month: '%Y-%m-01', year: '%Y-01-01' }[bucket]
+    return { sql: `date_format(${local}, '${format}')`, bindings: [column] }
+  }
+  // SQLite: epoch milliseconds (the drivers bind dates as numbers) or ISO text.
+  let local = "(case when typeof(??) in ('integer', 'real') then datetime(?? / 1000.0, 'unixepoch') else datetime(??) end)"
+  if (timezone.kind === 'offset') local = `datetime(${local}, '${minutes >= 0 ? '+' : ''}${minutes} minutes')`
+  const bindings = [column, column, column]
+  if (bucket === 'week') return { sql: `date(${local}, '-6 days', 'weekday 1')`, bindings }
+  const format = { day: '%Y-%m-%d', month: '%Y-%m-01', year: '%Y-01-01' }[bucket]
+  return { sql: `strftime('${format}', ${local})`, bindings }
+}
+
+// Zone names need the server's zone data: PostgreSQL has it; MySQL only with
+// loaded time zone tables (checked once per name); SQLite has none.
+async function checkNamedZones ({ db, family, plan }) {
+  const names = [...new Set(plan.groups.filter(group => group.timezone?.kind === 'named').map(group => group.timezone.name))]
+  for (const name of names) {
+    if (family === 'sqlite') {
+      invalid('groupBy', `SQLite has no time zone data: use 'UTC' or a fixed offset instead of '${name}'`)
+    }
+    if (family === 'mysql') {
+      const [rows] = await db.raw("select convert_tz('2000-01-01 00:00:00', '+00:00', ?) as converted", [name])
+      if (rows?.[0]?.converted == null) {
+        invalid('groupBy', `The MySQL server has no time zone data for '${name}': load its time zone tables or use a fixed offset`)
+      }
+    }
+  }
+}
+
 const measureValue = (value, measure, resourceType) => {
   if (measure.fn === 'count' || measure.fn === 'countDistinct') return Number(value ?? 0)
   if (value == null) return null
@@ -133,9 +304,14 @@ const measureValue = (value, measure, resourceType) => {
  * Run a compiled aggregate over the rows a filtered query selects.
  * The filtered query only supplies identifiers, so joins added by filters or
  * policies cannot repeat a row inside a group.
- * @param {{ source: import('knex').Knex.QueryBuilder, sourceTable: string, storageAdapter: Record<string, any>, db: import('knex').Knex | import('knex').Knex.Transaction, plan: ReturnType<typeof compileAggregateRequest> }} request
+ * @param {{ source: import('knex').Knex.QueryBuilder, sourceTable: string, storageAdapter: Record<string, any>, db: import('knex').Knex | import('knex').Knex.Transaction, plan: import('../storage/storage-types.js').AggregatePlan }} request
  */
 export async function runAggregateQuery ({ source, sourceTable, storageAdapter, db, plan }) {
+  const family = databaseFamily(db)
+  if (plan.groups.some(group => group.bucket) && storageAdapter.isCanonical()) {
+    invalid('groupBy', 'Date buckets need table storage; AnyAPI resources group by stored values only')
+  }
+  await checkNamedZones({ db, family, plan })
   const idColumn = storageAdapter.getIdColumn()
   const ids = source.clearSelect().clearOrder().select(`${sourceTable}.${idColumn}`)
   const query = storageAdapter.buildBaseQuery({ transaction: db, tableAlias: AGGREGATE_ALIAS })
@@ -143,13 +319,26 @@ export async function runAggregateQuery ({ source, sourceTable, storageAdapter,
   const column = field => `${AGGREGATE_ALIAS}.${storageAdapter.translateColumn(field)}`
 
   for (const group of plan.groups) {
-    query.select({ [group.alias]: column(group.field) }).groupBy(column(group.field))
+    if (group.bucket) {
+      const { sql, bindings } = bucketSql({ family, column: column(group.field), bucket: group.bucket, timezone: group.timezone, type: group.definition.type })
+      query.select(db.raw(`${sql} as ??`, [...bindings, group.alias])).groupByRaw(sql, bindings)
+    } else {
+      query.select({ [group.alias]: column(group.field) }).groupBy(column(group.field))
+    }
   }
   for (const measure of plan.measures) {
-    query[measure.fn]({ [measure.alias]: measure.field === '*' ? '*' : column(measure.field) })
+    if (!measure.where) {
+      query[measure.fn]({ [measure.alias]: measure.field === '*' ? '*' : column(measure.field) })
+      continue
+    }
+    // Conditional measures aggregate a CASE that is NULL outside the condition.
+    const condition = whereSql(measure.where, { column, storageAdapter })
+    const value = measure.field === '*' ? { sql: '1', bindings: [] } : { sql: '??', bindings: [column(measure.field)] }
+    const fn = { countDistinct: 'count(distinct ', count: 'count(', sum: 'sum(', avg: 'avg(', min: 'min(', max: 'max(' }[measure.fn]
+    query.select(db.raw(`${fn}case when ${condition.sql} then ${value.sql} end) as ??`, [...condition.bindings, ...value.bindings, measure.alias]))
   }
   // NULL sorts as the lowest value, as MySQL and SQLite order it by default.
-  const pg = ['pg', 'postgresql'].includes(db.client.config.client)
+  const pg = family === 'pg'
   for (const { alias, direction } of plan.sort) {
     if (pg) query.orderBy(alias, direction, direction === 'asc' ? 'first' : 'last')
     else query.orderBy(alias, direction)
@@ -162,7 +351,11 @@ export async function runAggregateQuery ({ source, sourceTable, storageAdapter,
 
   const data = rows.map(row => {
     const result = {}
-    for (const group of plan.groups) result[group.name] = normalizeStoredFieldValue(row[group.alias], group.definition, { fieldName: group.field, resourceType: plan.scopeName })
+    for (const group of plan.groups) {
+      result[group.name] = group.bucket
+        ? (row[group.alias] == null ? null : String(row[group.alias]))
+        : normalizeStoredFieldValue(row[group.alias], group.definition, { fieldName: group.field, resourceType: plan.scopeName })
+    }
     for (const measure of plan.measures) result[measure.name] = measureValue(row[measure.alias], measure, plan.scopeName)
     return result
   })