---
title: "workspaceQueryControls"
url: https://developers.dagio.ai/reference/workspace-query-controls/
---

# workspaceQueryControls

   
                               
                                                                                 
                                          
                  
           
          
   

This reference describes the full structure of `workspaceQueryControls`. Paths include nested objects, list items and conditional branches. A branch selected by `kind`, `contract` or `mode` only admits its own properties.

## Structure and values

| Field | Options / expected values | Description |
| --- | --- | --- |
| `contract` | `"WorkspaceQueryControls@1"` | **Required.** Exact discriminant of this contract variant. Match the literal value shown. |
| `filters` | `Array<closed object OR closed object>; max length 20` | **Required.** Defines filters for this object. Observe the type, variants and bounds in the Options column. |
| `filters[].[variant 1].parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `filters[].[variant 1].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `filters[].[variant 1].input` | `"choice"` | **Required.** Control or input selected by the variant; must remain compatible with its binding. |
| `filters[].[variant 1].options` | `Array<closed object>; min length 1; max length 100` | **Required.** Suggested and admitted values for a declared choice. |
| `filters[].[variant 1].options[].value` | `string; max length 4000 OR number OR true \| false` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `filters[].[variant 1].options[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `filters[].[variant 2].parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `filters[].[variant 2].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `filters[].[variant 2].input` | `"text" \| "number" \| "decimal" \| "integer" \| "real"` | **Required.** Control or input selected by the variant; must remain compatible with its binding. |
| `sort` | `closed object; null` | **Required.** Defines sort for this object. Observe the type, variants and bounds in the Options column. |
| `sort.parameterKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Stable key reference to the corresponding named declaration; the compiler checks existence and compatibility. |
| `sort.label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `sort.options` | `Array<closed object>; min length 1; max length 30` | **Required.** Suggested and admitted values for a declared choice. |
| `sort.options[].value` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9-]*$/u` | **Required.** Effective value interpreted according to the enclosing type and discriminant. |
| `sort.options[].label` | `string; min length 1; max length 4000` | **Required.** Human-readable label displayed in the interface. |
| `sort.options[].orderBy` | `Array<closed object>; min length 1; max length 5` | **Required.** Declared sort order using keys within the authorized scope. |
| `sort.options[].orderBy[].fieldKey` | `string; min length 1; max length 120; /^[a-zA-Z][a-zA-Z0-9]*$/u` | **Required.** Key of a Field declared on the referenced Surface definition. |
| `sort.options[].orderBy[].direction` | `"ascending" \| "descending"` | **Required.** Traversal or presentation direction using this contract’s closed values. |

## Reading the contract

A path ending in `[]` describes each list item; `{key}` describes each dictionary value. The `↻` marker refers to the same recursive expression. Closed objects reject additional properties. Semantic validation denotes an additional check: matching a type does not make a reference, permission or transition valid. References must resolve in the Model and the current user context.

An older variant cannot accept properties belonging to a newer variant. The compiler checks the version and consistency of the complete Model.

## Structural example

This fragment passes the schema for this section. Its business references must be defined in the enclosing Model.

```json
{
  "contract": "WorkspaceQueryControls@1",
  "filters": [],
  "sort": {
    "parameterKey": "sort",
    "label": "Trier par",
    "options": [
      {
        "value": "name-asc",
        "label": "Nom",
        "orderBy": [
          {
            "fieldKey": "title",
            "direction": "ascending"
          }
        ]
      },
      {
        "value": "recent",
        "label": "Modification récente",
        "orderBy": [
          {
            "fieldKey": "updatedAt",
            "direction": "descending"
          }
        ]
      },
      {
        "value": "oldest",
        "label": "Modification ancienne",
        "orderBy": [
          {
            "fieldKey": "updatedAt",
            "direction": "ascending"
          }
        ]
      }
    ]
  }
}
```

## Related references

[Complete Model index](https://developers.dagio.ai/reference/) · [Build a Model](https://developers.dagio.ai/models/)

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

## Applied examples : Quotes for the current client

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

### Configuration

Contract object `workspaceQueryControls`. [Properties and accepted values](https://developers.dagio.ai/reference/workspace-query-controls/).

```json
{
  "contract": "WorkspaceQueryControls@1",
  "filters": [
    {
      "parameterKey": "status",
      "label": "Status",
      "input": "choice",
      "options": [
        {
          "value": "draft",
          "label": "Draft"
        },
        {
          "value": "approved",
          "label": "Approved"
        }
      ]
    }
  ],
  "sort": null
}
```

### 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 -->