---
title: .query 查询 DSL 元数据
description: .query 查询 DSL 文件阅读入口，指向查询结构、字段、过滤、分组、排序和运行选项的 DTS 说明
navTitle: .query
---
# .query 查询 DSL 元数据

查询 DSL 是数据模型之上的结构化取数描述，把报表、仪表板、低代码页面、程序流和接口中的取数请求表达为字段、数据源、过滤、分组、聚合、排序和运行选项，而不是让每个使用方各自拼接 SQL。

query 适合承载可复用或需要稳定协作的查询口径。它可以描述明细查询、统计查询、TopN、去重、窗口排序、多来源指标和跨源查询，也可以在运行时叠加用户权限、数据范围、分页、钻取和临时过滤，让同一份查询既能被页面组件消费，也能被接口、程序流或二次开发代码复用。

当目标是定义业务对象、字段语义、物理表和加工流程时，应优先考虑数据模型（tbl）；当目标是在已有模型之上组织一次可执行、可复用、可带运行参数的数据查询时，应使用 query。

query 文件遵守 SuccApp Super JSON 的数据类文件约定，字段、过滤阶段、维度指标和权限行为由 DTS 的 `succ.meta.dw.Query` 及相关分支类型承接。

## 查询能力{#query-capabilities}

- 自动作用用户对报表或模型资源的行列权限，见 `QueryDSLOptions.disableDataRange`。
- 一次查询来自多个数据源的指标，见 `Query.sources`。
- 支持分组查询和明细查询，见 `Query.groupFields`。
- 支持查询扩展字段，见 `QueryDSLExtField`。
- 支持缓慢变化模型的查询，见 `QueryDSLOptions.disableAutoSlowChange`。
- 支持 TopN 过滤，见 `QueryDSLHavingTopNFilter`。
- 支持窗口函数、跨库跨介质查询和按指定维度去重，见 `Query.distinct` 和 `Query.distinctFields`。

## 维度和指标{#dimension-measure}

维度是当前查询的数据粒度，用于描述和分类数据的属性或特征，通常是时间、空间或类别。指标是业务被拆解量化后的数量特征，可以是统计汇总计算，也可以是普通明细查询结果。

当查询涉及多个数据源的多个指标时，系统会自动分析维度字段在这些数据源中的一致性维度，并处理数据的关联合并。具体字段、过滤、排序、运行参数和结果结构以 DTS 为准。

## 示例文件{#examples}

- [KPI查询.query](https://demo.succbi.com/v5/DEMO/data/tables/QUERY/多模型查询/KPI查询.query) - 多模型指标查询示例
- [KPI查询\_单指标.query](https://demo.succbi.com/v5/DEMO/data/tables/QUERY/多模型查询/KPI查询_单指标.query) - 单指标查询示例

## DTS 入口{#types}

- 根结构：[`types/meta/file-types/query.d.ts`](../../../../../dev-types/types/meta/file-types/query.d.ts)
- 模型和字段结构：[`types/meta/file-types/tbl.d.ts`](../../../../../dev-types/types/meta/file-types/tbl.d.ts)、[`types/meta/data-model/field.d.ts`](../../../../../dev-types/types/meta/data-model/field.d.ts)
- 原始 DW 类型：[`types/api/succ.dw.d.ts`](../../../../../dev-types/types/api/succ.dw.d.ts)