Glossary

This glossary defines terms used throughout the dcupl documentation. Terms are grouped by category for easier reference.

Core SDK terms

Dcupl

The main class and entry point for the SDK. You create a Dcupl instance, add models and data, then call init() to start querying.

import { Dcupl } from '@dcupl/core';
const dcupl = new Dcupl();

Model

A data structure definition that describes the shape of your data. Models include properties, references, and optional validation rules. Similar to database schemas or TypeScript interfaces.

const model: ModelDefinition = {
  key: 'Product',
  properties: [
    { key: 'name', type: 'string' },
    { key: 'price', type: 'int' },
  ],
};

Property

An attribute of a model that defines a data field. Properties have a key (name) and type. Supported types include string, int, float, boolean, date, json, and arrays.

{ key: 'price', type: 'int' }
{ key: 'tags', type: 'Array<string>' }

Reference

A relationship between models. References link items in one model to items in another, enabling queries across related data.

Besides these basic references, a reference can be computed. The key that defines it names the kind: resolve (the reverse of another model's reference, e.g. a category's products), derive (a reference read through a local reference), groupBy (the other items of the same model that share a reference value) and query (the result of a query run for each item). See Reference.

List

A queryable view of a model's data. A list keeps its own query state: the conditions you add stay until you change or clear them. Multiple lists can exist for the same model with different filters.

const list = dcupl.lists.create({ modelKey: 'Product' });

Catalog

The query interface attached to each list. Provides methods for filtering, sorting, pagination, facets, and aggregations.

list.catalog.query.addCondition({ ... });
list.catalog.query.items();
list.catalog.fn.facets({ ... });

Query

A set of conditions that filter data. Queries use operators to match items based on property values.

{
  attribute: 'price',
  operator: 'gte',
  value: 100
}

Operator

A comparison function used in queries. dcupl has ten built-in operators (see Query Operators):

Every operator can be negated with options: { invert: true }. find is case-sensitive; with a slash pattern, add options: { regexFlags: 'i' } to ignore case (flags are ignored for a bare string).

Query group

A set of conditions combined with groupType: 'and' or 'or', identified by its groupKey. addCondition() puts each condition into a group keyed by its attribute, so conditions on the same attribute are combined with OR and conditions on different attributes with AND. addGroup() adds a group of your own, for example an 'and' group for a price range.

list.catalog.query.addGroup({
  groupKey: 'price',
  groupType: 'and',
  queries: [
    { attribute: 'price', operator: 'gte', value: 50 },
    { attribute: 'price', operator: 'lte', value: 200 },
  ],
});

Functions (fn)

The analysis namespace: facets, aggregate, groupBy, pivot, suggest and metadata. list.catalog.fn runs them on a list's current results, dcupl.fn on a model with a query you pass. See Functions.

Facets

Counts of items grouped by property values. Used to build filter interfaces showing how many items match each option.

const facets = list.catalog.fn.facets({ attribute: 'category' });
// [{ value: 'Electronics', size: 5, ... }, { value: 'Clothing', size: 3, ... }, { value: 'Books', size: 8, ... }]

Aggregations

Statistical calculations across items: sum, average, min, max, count.

const stats = list.catalog.fn.aggregate({ attribute: 'price', types: ['min', 'max', 'avg', 'sum', 'count'] });
// { attribute: 'price', types: [...], min: 29, max: 999, avg: 450, sum: 4500, count: 10 }

Index

An index that speeds up queries. References and properties marked index: true are indexed while init() processes the data; dcupl builds other indices on demand (for example when you request facets for a property). eq and in conditions use an existing index; other operators scan the items.

View

A saved report shape on a model: a section view for groupBy or a pivot view for pivot, stored with dcupl.views.set() or loaded from a view file (a model resource whose definition names a model), and unregistered with dcupl.views.remove(). The SDK only stores views; you pass a view's settings to fn.groupBy / fn.pivot yourself. Not to be confused with a list, which is a queryable view of a model's items.

Deep query

A query that traverses references to filter by related model properties. For example, filtering orders by customer email.

{
  attribute: 'customer.email',
  operator: 'eq',
  value: 'user@example.com'
}

Data loading terms

DcuplAppLoader

A class from @dcupl/loader that loads configuration and data from URLs. Used when connecting to Console or loading from hosted files.

import { DcuplAppLoader } from '@dcupl/loader';
const loader = new DcuplAppLoader();

LoaderConfiguration

A JSON file (dcupl.lc.json) that defines resources to load, applications, and environment variables. The central configuration for Console-managed projects. Also called loader config.

Resource

A file referenced in LoaderConfiguration: a model definition (or a view definition), a data file, or a script, custom operator or transformer (type: model, data, script, operator, transformer). Resources have URLs, types, and tags.

{
  "url": "${baseUrl}/data/products.json",
  "type": "data",
  "model": "Product",
  "tags": ["product-data"]
}

Resource tag

A label applied to resources for grouping. Applications specify which tags to load, enabling different configurations for different use cases.

Application

A named configuration in LoaderConfiguration that specifies which resource tags to load. Allows one project to serve multiple applications.

{
  "key": "storefront",
  "resourceTags": ["products", "categories"]
}

Variable

A placeholder in LoaderConfiguration URLs that gets replaced at runtime. Used for environment-specific values.

{
  "url": "${baseUrl}/data/products.json"
}

Transformer

A JavaScript resource the loader runs on a file it loads: a raw-file transformer before parsing, a parsed-file transformer on the parsed items. Not the same as a query Transform.

Console platform terms

Console

The dcupl web platform at console.dcupl.com. Provides visual editors for models and workflows, data management, and API deployment.

Project

The Console's unit of work: its models, data files and loader configuration (versioned), workflows, REST APIs, members and API keys.

API key

A project credential for everything outside the Console: the SDK's loader, the CLI and workflows. The key's type decides what it may read or write. See API keys.

Workflow

An automated data transformation pipeline defined in Console. Workflows fetch data from sources, apply transformations and store results; a dcupl instance node can also validate the data against your models.

A workflow is a graph: a trigger (HTTP or scheduled) starts it, nodes do the work (requests, scripts, files, data mapping, dcupl instances) and edges connect the nodes. See Workflows.

REST APIs

The REST API feature (RAPI for short): a REST API that executes SDK queries on the server. You deploy an API template from Console as an instance on a runner for scenarios requiring server-side processing. See REST APIs.

• API template - describes the API: the data it loads, its API key, its scripted endpoints
• Instance - a deployed template, running on a runner with its data in memory

MCP

Model Context Protocol. A REST API instance can serve an MCP endpoint, so AI agents can query its data. You switch it on per API template. MCP is part of a paid plan that dcupl turns on for your project; ask your dcupl contact. See MCP endpoint.

Workflow runner

A runner of type workflow-runner: it executes workflows. dcupl runs runners in the cloud; a runner can also be self-hosted (ask your dcupl contact).

Runner

The server you deploy to from the Console (its deploy forms call it Runner). A runner of type workflow-runner executes workflows (see Workflow Runner above); a runner of type app-runner hosts REST API instances. Each instance keeps a dcupl instance with its loaded data in memory and answers HTTP requests (query, facets, aggregate, pivot, suggest, metadata).

Architecture terms

SDK

Software Development Kit. The free TypeScript packages on npm (@dcupl/core, @dcupl/loader, etc.) that run in browser or Node.js.

CLI

The free @dcupl/cli package: scaffolds projects, validates models, syncs files with the Console and runs local data apps. See CLI.

In-memory

Data stored in application memory (RAM) rather than a database. dcupl loads data into memory for fast querying.

Client-side

Code executing in the user's browser. dcupl can run client-side for instant interactions without server requests.

Server-side

Code executing on a server. dcupl runs server-side for SSR (initial page renders) or on REST API instances.

SSR (server-side rendering)

Rendering HTML on the server before sending to the browser. dcupl supports SSR for SEO and initial page load performance.

Hydration

The process where client-side JavaScript takes over a server-rendered page. The dcupl SDK initializes with the same data used for SSR.

CDN (content delivery network)

A distributed network for serving files. dcupl uses CDN for fast delivery of configuration and data files globally.

Data terms

Item

A single record in a model. Items have a unique key and properties matching the model definition.

{ key: 'p1', name: 'Laptop', price: 999 }

Key

The unique identifier for an item within a model. By default, items use a key property, but this is configurable.

Staging

Data calls (dcupl.data.set, upsert, update, remove, reset) only stage changes. await dcupl.init() applies them the first time, await dcupl.update() afterwards.

Update types

Each data call stages its items for one model with an update type: set replaces the model's items, upsert adds or updates, update changes existing items (unknown keys are ignored), remove deletes. data.reset() stages an empty set.

Partial update

A dcupl.update() that reprocesses only the changed items and the attributes that depend on them, instead of rebuilding the models. dcupl runs a full rebuild instead when a set or reset is staged, when a model definition changed after init() (models.set, models.update, models.remove, or a loader process() that loads model files), when the staged change can alter a query reference's result, or when more than half of the models and more than half of their items changed (thresholds configurable, see Performance); an update() with nothing staged and no definition change also runs a full rebuild, but emits no dcupl_partial_update event (after a definition change alone the event fires with isPartialUpdate: false). In every other case that succeeds, the dcupl_partial_update event reports which path ran (isPartialUpdate); a failed update() resolves false and emits no event.

Quality error

A data or model problem that dcupl records instead of throwing, for example a value of the wrong type or a reference to a missing key. dcupl.quality.errors.summary() lists them grouped by model, attribute and error type. See Quality Validation.

Value mapping

A transformation that converts raw values to different values during loading. Useful for translating codes or normalizing data.

valueMappings: [
  {
    attributes: ['active'],
    values: [
      { from: ['1', 'Y'], to: true },
      { from: ['0', 'N'], to: false },
    ],
  },
];

Derived property

A property whose value is copied from a referenced item: derive names the local reference and the property to read on the remote model.

{
  key: 'categoryName',
  type: 'string',
  derive: { localReference: 'category', remoteProperty: 'name' }
}

Expression property

A property whose value is a template filled with other attribute values. Expressions only interpolate ${...} placeholders: they cannot calculate (${price * 2} yields ''), and the result is always a string.

{
  key: 'fullName',
  type: 'string',
  expression: '${firstName} ${lastName}'
}

Query terms

Condition

A single filter rule in a query. Conditions specify an attribute, operator, and value.

Attribute

The property name to filter on. Can include dot notation for deep queries (customer.email).

Sort

The ordering applied to query results. Specify attributes and directions in uppercase: sort: { attributes: ['price'], order: ['DESC'] } ('ASC' or 'DESC').

Pagination

Limiting results to a subset for display. Specify an offset (start) and a page size (count), e.g. list.catalog.query.applyOptions({ start: 0, count: 20 }).

Transform

A modification applied to values before comparison. The three transforms are lowercase, trim and removeWhitespace, applied in the order you list them in options.transform.

Script and custom operator

A script is JavaScript you register under a key with dcupl.scripts.set() (or load as a script resource) and run with dcupl.scripts.execute(). A custom operator is a script used as a query operator: a condition whose operator is not a built-in one runs the script registered under that key, once per item. See Scripts.

Common abbreviations