Skip to main content
Availability: Config files are a Beta feature. See Config Files for how they work.

Syntax

Every config file is one record: a constructor name followed by fields in braces.
  • Config files are not JSON. Field names are bare (never quoted), and values use =, never :.
  • Comments start with -- and run to the end of the line. // and # are errors.
  • Fields and list items are separated by commas. A trailing comma after the last item is an error.
  • Strings are double-quoted, with backslash escapes. Booleans are lowercase true and false.
  • Lists use [ ] and nested records use { }.
  • A field you leave out takes its default. Unknown fields and values outside a field’s allowed list are errors.

References

Config files refer to other things in a few fixed forms. Paths work like this, unless a field says otherwise:
  • A bare name is a file beside the config file.
  • A path without a leading slash is relative to the config file’s folder.
  • A path with a leading slash starts at the root of the Ontology.
Members are always written by email address, not by id.

Prompt files

A playbook or agent sets its instructions with exactly one of prompt or prompt_file. Use prompt only for a prompt that fits on one line; anything longer goes in a markdown file that prompt_file points to. A long inline prompt is flagged by a check and moved into a file by automatic fixes. Add or change the prompt file in the same change as the config file.

Attached files

Playbooks, agents, and dashboards can attach Ontology files to every run with files, a list of { path, alias } records. alias is optional.

Playbook

File: <name>.playbook. Constructor: Playbook.
playbooks/weekly-revenue/weekly-revenue.playbook
access controls the run Threads, not the file:
level is viewer, editor, or owner. Only a member can be an owner, not a role, and each member or role may appear once.

Connector items

connector_items narrows what each run uses inside a Tableau or Power BI connector. Write one entry per connector, with connector spelled like its connectors entry, and exactly one of a powerbi or a tableau block:
  • Naming something with nothing below it gives all of it. A listed connector with no entry, or with an empty block, gets everything it syncs, including items synced later. A Power BI workspace with no datasets is the whole workspace.
  • Once a tableau block lists anything, each list holds exactly what it lists. A workbook gives all its views and its calculated fields; views are never named. Datasources with no workbooks give no views.
  • Use ids only, never names: Power BI workspace and dataset ids, Tableau datasource and workbook LUIDs.
  • Each workspace, dataset, datasource, and workbook appears once in an entry.
  • Runs ignore an entry for a connector that connectors doesn’t list.
  • A playbook or agent whose file has never held connector_items keeps the connector items set on its page.

Agent

File: <name>.agent. Constructor: Agent.
agents/revenue-watcher/revenue-watcher.agent
email_recipients, slack_dm_recipients, teams_dm_recipients, feed_channels, subagents, and subagent_invokers keep only the entries that match. An empty or omitted list clears the saved list. If a non-empty list has no matches, the agent’s saved list is left as it was. slack_trigger.channels is different: an empty list means every channel.

Dashboard

File: <name>.dashboard. Constructor: Dashboard. The dashboard’s code lives beside it.
dashboards/sales-overview/sales-overview.dashboard
Each data source has a type and a name, plus the fields its type needs: parameters declares live query parameters, each { name, type, default }; only name is required.

Data App

File: app.dataapp, in a folder of its own under apps/. Constructor: DataApp. The folder is the app: its code, queries, and assets live beside the file, and other config files inside it are not read as objects.
apps/quarterly-revenue/app.dataapp
path values in sources and functions are relative to the app’s content root: root_path when set, otherwise the folder holding app.dataapp. Sources. Each has a unique name and a type: connector is a typed reference such as id:42. For library_tql, the file at path contains the Ontology path of a saved .tql query, such as queries/revenue.tql. ontology_sql is retired; use library_tql instead. A file source’s uri names one CSV, TSV, Excel, or Parquet file in Artifacts, such as artifact://finance/targets.csv. It cannot be combined with dataset_id or file_name, and cannot name a folder. Each refresh reads the latest version unless the URI pins a version with @vN. params_json is a JSON-encoded parameter map used only by library_tql. parameters declares live query parameters on sql_query, library_tql, and powerbi_dax; each entry has { name, type, default }, with only name required. Names must be unique within a source and contain only letters, digits, and underscores, starting with a letter or underscore. For powerbi_dax, the parameter name dax is reserved. File and Python sources cannot declare live parameters. Functions. Each has a name and exactly one body:
  • path: a file in the app’s folder. The extension picks the kind: .py for Python, .sql for SQL against the app’s private database, .tql for TQL. A .tql body also takes a connector, where id:-1 means the app’s private database.
  • tql_path: a saved .tql file elsewhere in the Ontology.
  • server_handled = true: handled by a function of the same name in the app’s server module.
Optional: description, returns, and parameters (each { name, type, description }). Compute. Jobs. Each job calls one of the app’s functions: A job with neither cron nor after_refresh runs only when started by hand.

Capabilities

Dashboards and data apps list the platform actions their code may call in capabilities. Each entry has a type, and a name the code calls it by (not needed for state and assets). Capabilities other than ask and decide can declare parameters, each { name, type, description }; ask and decide take none. Each capability type must be available to your organization; a check flags one that isn’t. recipients for deliver takes any of subscribers (true for the app’s subscribers), member_emails, roles, runtime_emails (true when the code names recipients as it sends), slack_channel_ids (requires slack_channel in channels), and teams_channel_ids (requires teams_channel).

Data App immediate server stop

Use Build → Settings → Server → Immediate stop to block server starts and requests without changing the app’s configured on/off switch or Library files. The stop stays until an app editor clears it. Saving, pulling or restoring files cannot clear it. Clearing the stop allows the configured server to start on demand. The stop also requests release of all app compute workers, including running Python work; release can take time. Settings shows the process status reported by the server. Open server connections close within three seconds when stop reads succeed. A continuous read outage closes them after three failed checks, within seven seconds. A stop of the live app does not stop its previews. Only app writers see the stop control and its value. A copy starts without a stop; restoring the same app row preserves its stop.