---
id: SCR-PFM-QRY-003
title: New query designer
route: '/console/{tenantId}/queries/new'
surface: console
product_area: platform
module: queries
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference:
  - IOP-PFM-QRY-001
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
purpose: >-
  Compose and execute a dataset question by hand, from a registered recipe or with assisted
  drafting.
supports:
  - JNY-PFM-QRY-002
  - CAP-PFM-QRY-001
  - CAP-PFM-QRY-002
  - CAP-PFM-QRY-003
  - CAP-PFM-QRY-008
  - CAP-PFM-QRY-014
permission: platform.queries.read and the dataset’s own query key; drafting needs platform.queries.generate
entry_from:
  - Query library
  - header prompt (?prompt=)
  - record lists (?type=)
exits_to:
  - '/console/{tenantId}/queries/{id} after saving'
displays:
  - field: Application-grouped dataset choices with caller usability.
    source: listQueryDatasets
  - field: 'Selected dataset fields, supported operators, relationships and authoring defaults.'
    source: describeQueryDataset
  - field: The paged result with available record links and totals.
    source: runDatasetQuery
  - field: Validation problems located in the question.
    source: validateDatasetQuery
  - field: Workspace-calendar interpretation of date expressions.
    source: resolveDateExpressions
  - field: 'The settled drafting query, clarification request or unsupported explanation.'
    source: 'generateDatasetQuery, getQueryGeneration'
actions:
  - label: Run
    operation_id: runDatasetQuery
    permission: platform.queries.read
    confirm: false
  - label: Ask (written request)
    operation_id: generateDatasetQuery
    permission: platform.queries.generate
    confirm: false
  - label: Start from a recipe
    operation_id: createQueryRecipeDraft
    permission: platform.queries.read
    confirm: false
  - label: Save
    operation_id: createSavedQuery
    permission: platform.saved-queries.use
    confirm: false
  - label: Export
    operation_id: startQueryExport
    permission: platform.queries.read
    confirm: false
states:
  - metadata loading
  - choose an authoring start
  - query execution pending
  - drafting outcome polling
  - request error
  - dataset access refused
  - unsaved draft
validation:
  - BR-CAP-PFM-QRY-002-03
  - BR-CAP-PFM-QRY-002-09
  - BR-CAP-PFM-QRY-002-11
  - BR-CAP-PFM-QRY-002-15
  - BR-CAP-PFM-QRY-003-03
  - BR-CAP-PFM-QRY-003-06
  - BR-CAP-PFM-QRY-008-03
  - BR-CAP-PFM-QRY-006-12
patterns:
  - Full layout
  - 'query builder (columns, criteria groups, sort, grouping)'
  - dataset and field pickers
  - AI prompt bar with conversation history
  - results table
  - save dialog
  - export dialog
  - unsaved-changes guard
component: 'components/queries/query-workspace.tsx (PlatformNewQuery), new-query-start.tsx, ai-prompt-bar.tsx'
evidence:
  - >-
    react-console at baf6dae: app/(console)/console/[tenantId]/queries/new/page.tsx;
    components/queries/query-workspace.tsx, new-query-start.tsx, ai-prompt-bar.tsx,
    criteria-editor.tsx, results-table.tsx; lib/queries/platform/*.ts
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-SEC-001, TC-SEC-002, TC-SEC-003, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# New query designer

## What the Screen Is For

Compose and execute a dataset question by hand, from a registered recipe or with assisted drafting.

## What It Shows and Lets People Do

The designer lets the person choose fields, filters, joins, grouping and order, then run the structured request. Recipes and assisted drafting populate editable proposals. Saving creates a reusable definition; file export uses a separate background request.

## States and Errors

Metadata and execution can fail independently. The prompt area waits for generation settlement and explains refusals or clarification without treating a draft as an automatically executed answer.

## Patterns It Must Respect

The full workspace contains the established query builder, dataset and field selectors, result table and conversation history. Save and export dialogs retain the unsaved-change guard.