Queries and collections

Separate collection from presentation

A named Query defines data retrieval. A view determines how to display the result. Client quotes can feed a table, count and Client relation panel without creating three independent business searches.

Element	Options / expected values	Description
Identity	Stable Query key	Reference from views and rules
Sources	Authorized Surface definitions	Object types to retrieve
Parameters	Declared keys and types	Values from context or controls
Predicates	Contract-admitted comparisons	Restrict results
Sort	Authorized Fields and direction	Define stable ordering
Pagination	Bounded size and continuation	Navigate the complete collection
Aggregate	Declared count or calculation	Compute across the full scope

Data Sources, Data Views and layouts

A Data Source provides access to data: Surface, an external database or an API. A Data View is a saved, reusable Query definition. A Layout presents its results as a Table, Kanban or other admitted presentation. A Data View belongs to its primary Space. It can query that Space alone, with optional linked sources from other authorized Spaces. It does not copy source records or grant access to them.

The development runtime exposes saved definitions through data_view_read, data_view_save, data_view_query and data_view_delete in MCP. Begin with the primary source, then request each related source page using its parent record. Relations must already be declared; equal identifiers do not create a join. Removing the definition preserves source records and Links. Applications remain independently installed and published.

In development, choose Data Views from a Data, Knowledge or Content Space’s collection actions. The shared Builder presents illustrated Definition, Fields, Query, Linked sources and Preview screens. The current Space is the fixed primary source: select Fields, configure filters and sorting, then save. No linked source is required. Choose a linked source adds an optional branch through an existing Link; Link from selects its parent when several sources are included. Definitions remain independent of the application Model. Preview reads pages from the saved definition; select a row to explore its related sources. Unsaved changes are confirmed before dismissal, and deletion moves only the definition to trash, preserving source records and Links.

Save becomes available when the definition is changed and valid. An incomplete draft displays the missing requirement and opens its editor when selected. The discard confirmation protects unsaved edits even when they are not yet valid. Opening a picker alone does not change the draft.

Surface block/layout binding is not connected to saved definitions yet. Flat SQL joins, cross-source aggregates and external database adapters are not supplied by this initial service. A snapshot import is not a live external Data Source.

Bind from a record

Presentation binds named Query parameters to context values. In North Studio’s record, client identity supplies Client quotes with its parameter. Quotes remain the data source; the client does not own copies of proposals.

Bindings use variants admitted by the Query binding contract. They do not contain arbitrary SQL or JavaScript.

Controls and filters

Visible search, filters and sorting must correspond to authorized parameters and operations. A table filter cannot expand the reader’s permissions. The engine owns pagination and aggregates; a client’s quote total cannot be inferred from the four items shown in a preview panel.

Expected result example

Query: Client quotes
Context: North Studio
Filter: status is not Rejected
Sort: last updated descending
View: number, status, amount, last updated

Define this scope first, then configure table columns. The reference gives exact properties for each Query contract version.

Applied examples : Quotes for the current client

The Query declares clientId; the binding supplies the identity of the open record.

Configuration

Fragment placed in queries[]. Properties and accepted values.

{
  "contract": "WorkspaceQuery@1",
  "key": "client-quotes",
  "label": "Client quotes",
  "spaceKeys": [
    "quotes"
  ],
  "definitionPaths": [
    "workspace/quotes/surface/quote"
  ],
  "parameters": [
    {
      "key": "clientId",
      "type": "node-id",
      "required": true
    }
  ],
  "predicates": [],
  "relations": [
    {
      "linkTypePath": "application/client",
      "direction": "outgoing",
      "parameterKey": "clientId",
      "distinct": true
    }
  ],
  "orderBy": [
    {
      "fieldKey": "updatedAt",
      "direction": "descending"
    }
  ],
  "aggregate": "none",
  "pageSize": 25,
  "maximumDepth": 1
}

Variation and connection

Fragment placed in presentation.recordProfiles[].queryBindings[]. Properties and accepted values.

{
  "key": "client-quotes",
  "queryKey": "client-quotes",
  "parameters": {
    "clientId": {
      "kind": "entity-id",
      "definitionPath": "workspace/clients/surface/client"
    }
  }
}

UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Number
2. Status
3. Amount
4. Last updated

SurfaceClients / North StudioExample

Queries and collectionsQuotes for the current client

Clients

Client : North StudioStatus: All ⌄Search…

Number	Status	Amount	Open
S-1042	Draft	12 500	↗
S-1041	Approved	8 200	↗
S-1040	Sent	4 750	↗

Client Query resultsNext page →