# 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. ```typescript 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. ```typescript 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. ```typescript { key: 'price', type: 'int' } { key: 'tags', type: 'Array' } ``` ### Reference A relationship between models. References link items in one model to items in another, enabling queries across related data. | Type | Cardinality | Example | | -------------- | ----------- | --------------------------- | | `singleValued` | 1:1 or n:1 | Order has one Customer | | `multiValued` | 1:n or n:m | Product has many Categories | 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](/sdk/api/models#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. ```typescript const list = dcupl.lists.create({ modelKey: 'Product' }); ``` ### Catalog The query interface attached to each list. Provides methods for filtering, sorting, pagination, facets, and aggregations. ```typescript 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. ```typescript { attribute: 'price', operator: 'gte', value: 100 } ``` ### Operator A comparison function used in queries. dcupl has ten built-in operators (see [Query Operators](/sdk/api/query-operators)): | Operator | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | `eq` | Equals | | `in` | Equals any value in a list | | `gt` | Greater than | | `gte` | Greater than or equal | | `lt` | Less than | | `lte` | Less than or equal | | `find` | Pattern match: wrap the term in slashes (`'/term/'`) for substring search; a bare string must match the whole value | | `typeof` | Value has the given JavaScript type | | `isTruthy` | Value is truthy (or falsy with `value: false`) | | `size` | Array or string length equals the value | 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. ```typescript 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](/sdk/api/functions). ### Facets Counts of items grouped by property values. Used to build filter interfaces showing how many items match each option. ```typescript 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. ```typescript 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. ```typescript { 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. ```typescript 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. ```json { "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. ```json { "key": "storefront", "resourceTags": ["products", "categories"] } ``` ### Variable A placeholder in LoaderConfiguration URLs that gets replaced at runtime. Used for environment-specific values. ```json { "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](#transform). > **Note:** **Application, `dcupl app` and instance are three different things.** An _application_ is a named set of resources in the LoaderConfiguration. `dcupl app` is the CLI command group that runs local data apps (the SDK in memory on your machine). An _instance_ is an API template deployed as a REST API (RAPI) on a runner. ## 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](/console/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](/console/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](/console/rapi). - **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](/console/rapi/mcp). ### 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](/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. ```typescript { 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](/sdk/api/models#reference)'s result, or when more than half of the models **and** more than half of their items changed (thresholds configurable, see [Performance](/sdk/advanced/performance#when-dcupl-falls-back-to-a-full-update)); 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](/sdk/advanced/quality-validation). ### Value mapping A transformation that converts raw values to different values during loading. Useful for translating codes or normalizing data. ```typescript 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. ```typescript { 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. ```typescript { 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](/sdk/guides/scripts). ## Common abbreviations | Abbreviation | Meaning | | ------------ | -------------------------------------------------------------- | | SDK | Software Development Kit | | API | Application Programming Interface | | RAPI | REST API (an API template deployed as an instance on a runner) | | MCP | Model Context Protocol | | SSR | Server-Side Rendering | | CDN | Content Delivery Network | | ETL | Extract, Transform, Load | | CSV | Comma-Separated Values | | JSON | JavaScript Object Notation | ## Next steps - [Introduction](/introduction) — What dcupl is and when to use it - [Architecture](/learn/concepts/architecture) — System components - [Data flow](/learn/concepts/data-flow) — How data moves through dcupl - [Core concepts](/sdk/core-concepts) — SDK fundamentals