askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
rollup_definitions.json · 5.7 KB · 114 lines
| 1 | { |
| 2 | "name": "rollup_definitions", |
| 3 | "title": "Rollup Definitions", |
| 4 | "version": 1, |
| 5 | "description": "Declared aggregations (plan/vocabulary/14-rollup-spec.md): one record per definition -- a source collection, an optional flat-equality filter, a group_by, an optional time_bucket, and a list of metrics. The daemon's rollup pass (object_daemon.process_rollups, object_rollups.compute_rollup) materializes the answer into target_collection, an ordinary schema-shaped collection generated from this definition. filter/group_by/metrics are stored as JSON text -- this schema does not parse or validate their structure; object_rollups.parse_definition does that at compute time, same convention app-finance's fin_recurring.template_lines uses for its own JSON-shaped field. Admin-owned, full stop (see permissions/rules.json): a definition's filter/group-by shape reveals source schema structure.", |
| 6 | "fields": [ |
| 7 | { |
| 8 | "name": "id" |
| 9 | }, |
| 10 | { |
| 11 | "name": "name", |
| 12 | "type": "text", |
| 13 | "required": true, |
| 14 | "label": "Name", |
| 15 | "help": "Human label, e.g. \"Orders per day\".", |
| 16 | "validation": {"min_length": 1, "max_length": 200} |
| 17 | }, |
| 18 | { |
| 19 | "name": "source_collection", |
| 20 | "type": "text", |
| 21 | "required": true, |
| 22 | "label": "Source Collection", |
| 23 | "help": "Exactly one collection -- no joins. The rollup pass reads it outside row-level permissions (daemon posture), so it must already exist." |
| 24 | }, |
| 25 | { |
| 26 | "name": "filter", |
| 27 | "type": "textarea", |
| 28 | "label": "Filter (JSON)", |
| 29 | "help": "Optional flat {field: value} object, ANDed on equality -- e.g. {\"status\": \"paid\"}. No OR, no sub-query, no cross-collection join, no computed expression; a report that needs one of those is a custom object, not a rollup definition. Blank means every row." |
| 30 | }, |
| 31 | { |
| 32 | "name": "group_by", |
| 33 | "type": "textarea", |
| 34 | "label": "Group By (JSON list)", |
| 35 | "help": "JSON list of source field names, e.g. [\"channel\"]. Empty or blank means one row total per bucket." |
| 36 | }, |
| 37 | { |
| 38 | "name": "time_bucket", |
| 39 | "type": "textarea", |
| 40 | "label": "Time Bucket (JSON)", |
| 41 | "help": "Optional {\"field\": <source date/datetime field>, \"granularity\": none|day|week|month} object, e.g. {\"field\": \"created_at\", \"granularity\": \"day\"}. granularity defaults to \"none\" (bucket_start present, unbucketed) when omitted. Blank means no time dimension at all -- bucket_start is absent from the target. No timezone conversion: truncation happens in the field's own stored value, matching docs/schema-forms.md's date/datetime types." |
| 42 | }, |
| 43 | { |
| 44 | "name": "metrics", |
| 45 | "type": "textarea", |
| 46 | "required": true, |
| 47 | "label": "Metrics (JSON list)", |
| 48 | "help": "JSON list of {\"op\": count|sum|min|max|avg, \"field\": <source field, required except for count>, \"as\": <target field name, optional>}. avg is always sum/count computed fresh from that group's exact values, never a running average." |
| 49 | }, |
| 50 | { |
| 51 | "name": "target_collection", |
| 52 | "type": "text", |
| 53 | "required": true, |
| 54 | "label": "Target Collection", |
| 55 | "help": "Where the computed answer lands -- an ordinary collection whose schema is generated from this definition and regenerated on every recompute. Dedicated 1:1 to this definition; do not point two definitions at the same target." |
| 56 | }, |
| 57 | { |
| 58 | "name": "min_group_size", |
| 59 | "type": "integer", |
| 60 | "label": "Minimum Group Size", |
| 61 | "help": "Groups (within a bucket) with fewer underlying rows than this are suppressed -- dropped from the target entirely, never merged into an \"other\" bucket. Blank means no suppression. See permissions/rules.json's reason field for the disclosure threat this exists to blunt: it is declared, not enforced against whatever permission rule the target collection is later granted." |
| 62 | }, |
| 63 | { |
| 64 | "name": "refresh_mode", |
| 65 | "type": "enum", |
| 66 | "default": "scheduled", |
| 67 | "label": "Refresh Mode", |
| 68 | "enum": ["scheduled", "incremental"], |
| 69 | "help": "scheduled (recommended default) recomputes the whole definition every refresh_interval_seconds. incremental is accepted but v1's daemon pass has no create-fast-path yet -- an incremental definition simply behaves as scheduled-only until that lands (plan/vocabulary/14-rollup-spec.md's Events section)." |
| 70 | }, |
| 71 | { |
| 72 | "name": "refresh_interval_seconds", |
| 73 | "type": "integer", |
| 74 | "required": true, |
| 75 | "label": "Refresh Interval (seconds)", |
| 76 | "help": "Required in both refresh modes -- the scheduled recompute interval, or (once incremental's fast path exists) the reconciling recompute interval that runs alongside it." |
| 77 | }, |
| 78 | { |
| 79 | "name": "last_computed_at", |
| 80 | "type": "datetime", |
| 81 | "read_only": true, |
| 82 | "label": "Last Computed", |
| 83 | "help": "Server-set by the rollup pass after a successful recompute. This is both the freshness signal and the scheduled-mode due gate: a definition is due once refresh_interval_seconds have elapsed since this value (or immediately, if it has never run)." |
| 84 | }, |
| 85 | { |
| 86 | "name": "enabled", |
| 87 | "type": "boolean", |
| 88 | "default": "true", |
| 89 | "label": "Enabled", |
| 90 | "help": "Per-definition kill switch, independent of the instance-wide rollup_enabled flag -- pause one noisy or broken definition without disabling every rollup." |
| 91 | } |
| 92 | ], |
| 93 | "forms": { |
| 94 | "default": { |
| 95 | "fields": [ |
| 96 | "name", |
| 97 | "source_collection", |
| 98 | "filter", |
| 99 | "group_by", |
| 100 | "time_bucket", |
| 101 | "metrics", |
| 102 | "target_collection", |
| 103 | "min_group_size", |
| 104 | "refresh_mode", |
| 105 | "refresh_interval_seconds", |
| 106 | "enabled" |
| 107 | ] |
| 108 | } |
| 109 | }, |
| 110 | "views": { |
| 111 | "list_mode": "table", |
| 112 | "list_fields": ["name", "source_collection", "target_collection", "refresh_mode", "enabled", "last_computed_at"] |
| 113 | } |
| 114 | } |