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

# Queries et collections

   
                               
                                                                                
               
              
          
   

## Séparer la collection de son affichage

Une Query nommée définit une recherche de données. Une vue choisit comment afficher son résultat. La Query **Soumissions du client** peut alimenter un tableau, un compteur et le panneau de relations de la fiche Client sans créer trois recherches métier indépendantes.

| Élément | Options / valeurs attendues | Description |
| --- | --- | --- |
| Identité | Clé stable de Query | Référence depuis les vues et règles |
| Sources | Définitions autorisées de Surfaces | Types d’objets recherchés |
| Paramètres | Clés et types déclarés | Valeurs reçues du contexte ou des contrôles |
| Prédicats | Comparaisons admises par le contrat | Restreindre les résultats |
| Tri | Fields autorisés et direction | Définir un ordre stable |
| Pagination | Taille et continuation bornées | Parcourir une collection complète |
| Agrégat | Compte ou calcul déclaré | Produire un résultat sur le périmètre complet |

## Data Sources, Data Views et layouts

Une **Data Source** fournit l'accès aux données : Surface, base externe ou API. Une **Data View**
est une définition de Query enregistrée et réutilisable. Un **Layout** présente ses résultats en
Table, Kanban ou autre présentation admise. Une Data View appartient à son Space source principal.
Elle peut interroger ce seul Space et inclure en option d'autres Spaces autorisés par des Links.
Elle ne copie pas les records sources et n'accorde aucun droit sur eux.

Le runtime de développement expose les définitions enregistrées par `data_view_read`,
`data_view_save`, `data_view_query` et `data_view_delete` dans MCP. Lire d'abord la source
principale, puis chaque page liée avec l'identité de son record parent. Les relations doivent être
déclarées; une égalité d'identifiants ne crée aucune jointure. Retirer la définition conserve les
records sources et les Links. Les applications restent installées et publiées indépendamment.

En développement, choisir **Data Views** dans les actions de collection d'un Space Data, Knowledge
ou Content. Le Builder partagé présente les écrans illustrés Definition, Fields, Query, Linked sources
et Preview. Le Space courant est la source principale fixe : sélectionner les Fields, configurer
les filtres et le tri, puis enregistrer. Aucune source liée n'est requise. **Choose a linked source**
ajoute une branche optionnelle par un Link existant; **Link from** sélectionne le parent lorsque
plusieurs sources sont incluses. Les définitions restent indépendantes du Model. L'aperçu lit les pages de la définition enregistrée; sélectionner
une ligne permet d'explorer ses sources liées. Les modifications non enregistrées demandent une
confirmation avant fermeture, et la suppression place uniquement la définition dans la corbeille,
en conservant les records sources et les Links.

**Save** est disponible lorsque la définition est modifiée et valide. Un brouillon incomplet
indique le prérequis manquant et ouvre son éditeur au clic. La confirmation d'abandon protège les
modifications même si elles ne sont pas encore valides. Ouvrir un sélecteur seul ne modifie pas le
brouillon.

Le binding des blocs/layouts Surface aux définitions enregistrées reste à raccorder. Les jointures SQL
aplaties, agrégats multi-sources et adaptateurs de BD externes ne sont pas fournis par ce premier
service. Un import instantané n'est pas une Data Source externe en direct.

## Paramétrer depuis une fiche

La présentation lie les paramètres nommés de la Query à des valeurs du contexte. Dans la fiche Atelier Nord, l’identité du client alimente le paramètre de **Soumissions du client**. La source des données reste Soumissions; le client ne possède pas une copie de chaque proposition.

Les bindings utilisent les variantes admises par le [contrat de Query](https://developers.dagio.ai/fr/reference/workspace-query-binding/). Ils ne contiennent pas du SQL ou du JavaScript libre.

## Contrôles et filtres

La recherche, les filtres et le tri visibles doivent correspondre à des paramètres et opérations autorisés. Un filtre du tableau ne peut pas élargir les droits du lecteur. La pagination et les agrégats sont évalués par le moteur; le total de soumissions d’un client ne se déduit pas des quatre éléments visibles dans son panneau.

## Exemple de résultat attendu

```text
Query : Soumissions du client
Contexte : Atelier Nord
Filtre : état différent de Refusée
Tri : mise à jour décroissante
Vue : numéro, état, montant et mise à jour
```

Définissez d’abord ce périmètre, puis configurez les [colonnes du tableau](https://developers.dagio.ai/fr/tables/). La référence détaille les propriétés exactes de chaque version de Query.

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

## Exemples appliqués : Les soumissions du client courant

La Query déclare clientId; le binding fournit l’identité de la fiche ouverte.

### Configuration

Fragment à placer dans `queries[]`. [Propriétés et valeurs admises](https://developers.dagio.ai/fr/reference/workspace-model-foundation/).

```json
{
  "contract": "WorkspaceQuery@1",
  "key": "client-quotes",
  "label": "Soumissions du client",
  "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
}
```

### Variante et raccordement

Fragment à placer dans `presentation.recordProfiles[].queryBindings[]`. [Propriétés et valeurs admises](https://developers.dagio.ai/fr/reference/workspace-record-query-binding/).

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

### Exemple de disposition UI

La disposition illustrative ci-dessous situe cette configuration dans l’app Clients/Soumissions. Chaque fragment s’insère à l’emplacement indiqué; ses références aux Fields, Queries et Actions correspondent aux déclarations du Model.

1. Numéro
2. État
3. Montant
4. Dernière mise à jour

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