---
title: "Queries and collections"
url: https://developers.dagio.ai/queries/
---

# 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](https://developers.dagio.ai/reference/workspace-query-binding/). 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

```text
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](https://developers.dagio.ai/tables/). The reference gives exact properties for each Query contract version.

<!-- surface-examples:start -->

## 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](https://developers.dagio.ai/reference/workspace-model-foundation/).

```json
{
  "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](https://developers.dagio.ai/reference/workspace-record-query-binding/).

```json
{
  "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

<!-- surface-examples:end -->