.md

Applications

A project is a set of files. An application is the thing you run: a named selection of those files loaded into a live dcupl instance in your browser. Nothing on the Applications page says how one becomes the other, so here is the chain, once.

flowchart LR
  F["Project files<br/>models · data · scripts"] --> LC["dcupl.lc.json<br/>declares resources"]
  LC --> A["Application<br/>picks resources by tag"]
  A --> R["Run<br/>live instance in your browser"]
  R --> V["Dashboard · Data Explorer · Models<br/>Loader Insights · Quality Analyzer"]

1. A project is a set of files

Models describe the shape of your data, data resources hold the rows, and dcupl.lc.json is the loader config that ties them together. You edit them in the file editor on the right-hand rail.

2. The loader config declares what gets loaded

A file is only loaded if the loader config lists it as a resource — a model, a data file, a transformer, a script or an operator. Files that are not declared are simply ignored. See Loader configuration.

3. An application picks resources by tag

Resources can carry tags, and an application names the tags it wants. One project can host several applications over the same files: a "catalog" app and a "sales" app can share one dcupl.lc.json. An application with no tags loads everything.

4. A run is a live instance

Running an application loads it into your browser. It is a real dcupl core, not a preview of the files.

The five views on a run

Dashboard, Data Explorer, Models, Loader Insights and Quality Analyzer are five views on that one running instance, not five separate loads.

  • Dashboard — a grid of insight widgets over the app's data. Widgets are added, hidden and rearranged per application, and the layout is stored in your browser, not shared with teammates.
  • Data Explorer — the query surface. Pick a model, filter it, group or pivot it, aggregate a column. Your query and column set are remembered per model until you leave the application. The URL carries only the selected model and view (modelKey, viewKey), not your filters.
  • Models — the model definitions that actually loaded, plus the reference graph between them.
  • Loader Insights — what each resource cost: stalled time, server response, download, parse and transform.
  • Quality Analyzer — the errors the load recorded. A single bad resource never aborts a run, so this is where a half-loaded app explains itself.

Quick run vs a saved application

Quick run runs files as a temporary application — nothing is saved. Upload or paste CSV or JSON, fetch it from a URL that allows cross-origin requests, or pick project files from data/; for each file the console infers a model or uses an existing one you pick, and opens the Data Explorer directly. A quick run shows only the Data Explorer, Models and the Quality Analyzer. Save as application saves it to the project: for each file you choose what to write (data file, model file, tags), and a switch, off by default, also creates an application from the new loader entries.

A saved application is an entry in dcupl.lc.json. It has a key, a name and its own resourceTags, and every SDK or runner pointed at the project can load it by that key: loader.process({ applicationKey: 'catalog' }). Projects created in the console start from a starter whose loader configuration defines an application default. A configuration you write yourself may have none, and a key that is not in the file throws The applicationKey <key> does not exist.

Run settings

Three controls open an application's run settings: the gear on its card (Configure & run), Configure & Run in its menu, and the environment button on a running application. They hold the environment, custom variables (kept only for this browser tab) and the SDK the run uses. Runs use SDK 2.0 by default; pick v1 (SDK 1.11) to compare an application against the previous major. Scripts and newer SDK features need 2.0. The SDK choice is stored per application in your browser, not in the project, and the running application shows it as an SDK v1 or SDK v2 badge. A quick run has no run settings and always uses 2.0.

Environments

An environment is a named bundle of variables, HTTP headers and query parameters, also declared in the loader config. Environments are opt-in: pick one in the run settings. The choice sticks for the project in this browser tab, so later runs from the Applications page, its Run button included, use it until you pick No Environment again. Use them to point the same application at a different backend or to send a different auth header.

Environment headers only reach resources that carry at least one tag: an untagged resource is fetched without them, even when the header itself has no tags. Query parameters also reach untagged resources: a parameter without tags goes to every resource, a tagged one to the resources that share a tag. If an auth header must reach every request, tag every resource.