questions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Steedos Analytics Questions — File Format Guide

Steedos Analytics 问题文件格式指南

Overview | 概述

概述

Questions are analytics report/chart definitions stored as

.question.yml

seed data files under

<package>/main/default/questions/

. Each file defines one question (internally a "card") — a data query paired with a visualization.

问题是以

.question.yml

种子数据文件形式存储的分析报表/图表定义，位于

<package>/main/default/questions/

目录下。

问题是以

.question.yml

种子数据文件形式存储的分析报表/图表定义，位于

<package>/main/default/questions/

目录下。每个文件定义一个问题（内部称为“卡片”）——一个配对了可视化效果的数据查询。

问题是以

.question.yml

种子数据文件形式存储的分析报表/图表定义，位于

<package>/main/default/questions/

目录下。

File Location & Naming | 文件路径与命名

文件路径与命名

<package>/main/default/questions/<问题名称>.question.yml

Examples:

```
questions/单位总数.question.yml
```

questions/媒体类型统计.question.yml

```
questions/从业人员数.question.yml
```

<package>/main/default/questions/<问题名称>.question.yml

示例：

```
questions/单位总数.question.yml
```

questions/媒体类型统计.question.yml

```
questions/从业人员数.question.yml
```

File Structure | 文件结构

文件结构

yaml

name: <问题名称>
created_at: <ISO8601 datetime>
creator_id: <MongoDB ObjectId>
database_id: 1
dataset_query:
  database: 1
  type: query          # "query" for MBQL, "native" for SQL
  query:
    source-table: <object_name>
    # optional: filter, aggregation, breakout, limit, order-by
display: <display_type>
enable_embedding: false
entity_id: <MongoDB ObjectId>   # same as id
id: <MongoDB ObjectId>
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - ...               # column metadata list
table_id: <object_name>
updated_at: <ISO8601 datetime>
visualization_settings: '{}'

yaml

name: <问题名称>
created_at: <ISO8601 datetime>
creator_id: <MongoDB ObjectId>
database_id: 1
dataset_query:
  database: 1
  type: query          # "query" 对应MBQL，"native" 对应SQL
  query:
    source-table: <object_name>
    # 可选：filter、aggregation、breakout、limit、order-by
display: <display_type>
enable_embedding: false
entity_id: <MongoDB ObjectId>   # 与id相同
id: <MongoDB ObjectId>
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - ...               # 列元数据列表
table_id: <object_name>
updated_at: <ISO8601 datetime>
visualization_settings: '{}'

ID Generation | ID 生成

ID生成

All

id

and

entity_id

values are 24-character MongoDB-style hex ObjectIds. Generate unique IDs — never reuse the same ID across different questions.

Example:

68a5805bb74676d1c8cb3614

entity_id

and

id

are always the same value within one question file.

所有

id

和

entity_id

值都是24位MongoDB风格的十六进制ObjectId。生成唯一ID——切勿在不同问题中重复使用同一ID。

示例：

68a5805bb74676d1c8cb3614

单个问题文件中的

entity_id

和

id

始终为相同值。

dataset_query — MBQL Query | MBQL 查询结构

dataset_query — MBQL查询结构

Count (scalar) | 计数

计数（单值）

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_org_info
    aggregation:
      - - count

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_org_info
    aggregation:
      - - count

Count with filter | 带过滤的计数

带过滤的计数

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_journalist
    filter:
      - '='
      - - field
        - media_journalist.open
        - null
      - true
    aggregation:
      - - count

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_journalist
    filter:
      - '='
      - - field
        - media_journalist.open
        - null
      - true
    aggregation:
      - - count

Group by field (breakout) | 按字段分组

按字段分组（breakout）

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_infor
    aggregation:
      - - count
    breakout:
      - - field
        - media_infor.type
        - null

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_infor
    aggregation:
      - - count
    breakout:
      - - field
        - media_infor.type
        - null

Table list with limit | 列表查询

带限制的列表查询

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_org_info
    limit: 10000

yaml

dataset_query:
  database: 1
  type: query
  query:
    source-table: media_org_info
    limit: 10000

Native SQL query | 原生 SQL 查询

原生SQL查询

yaml

dataset_query:
  database: 1
  type: native
  native:
    query: "SELECT status, COUNT(*) as cnt FROM contracts GROUP BY status"

yaml

dataset_query:
  database: 1
  type: native
  native:
    query: "SELECT status, COUNT(*) as cnt FROM contracts GROUP BY status"

Display Types | 显示类型

显示类型

`display` value	Description
`scalar`	Single number (计数/合计等单值)
`table`	Data table (数据列表)
`bar`	Bar chart (柱状图)
`line`	Line chart (折线图)
`pie`	Pie chart (饼图)
`area`	Area chart (面积图)
`row`	Horizontal bar (横向柱状图)
`smartscalar`	Number with trend (带趋势的数值)
`funnel`	Funnel chart (漏斗图)
`pivot`	Pivot table (透视表)

`display` 值	描述
`scalar`	单个数值（计数/合计等单值）
`table`	数据表（数据列表）
`bar`	柱状图
`line`	折线图
`pie`	饼图
`area`	面积图
`row`	横向柱状图
`smartscalar`	带趋势的数值
`funnel`	漏斗图
`pivot`	透视表

visualization_settings | 可视化设置

visualization_settings 可视化设置

For simple questions, use

'{}'

(empty JSON string).

Common examples:

yaml

undefined

对于简单问题，使用

'{}'

（空JSON字符串）。

常见示例：

yaml

undefined

Scalar — show specific column

单值——显示指定列

visualization_settings: '{"table.cell_column":"count"}'

Bar chart — specify axes

柱状图——指定坐标轴

visualization_settings: >- {"graph.dimensions":["type"],"graph.metrics":["count"],"graph.show_values":true,"graph.x_axis.labels_enabled":false,"graph.y_axis.labels_enabled":false}

Table — specify pivot and cell columns

表格——指定透视列和单元格列

visualization_settings: >- {"table.pivot_column":"status","table.cell_column":"count"}

undefined

visualization_settings: >- {"table.pivot_column":"status","table.cell_column":"count"}

undefined

result_metadata | 结果列元数据

result_metadata 结果列元数据

result_metadata

describes the output columns. Required format varies by query type.

result_metadata

描述输出列。所需格式因查询类型而异。

For aggregation (count) | 聚合查询结果

聚合查询（计数）结果

yaml

result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation

yaml

result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation

For breakout + count | 分组+计数结果

分组+计数结果

yaml

result_metadata:
  - id: type                       # field name (short form when no table prefix)
    name: type
    display_name: 媒体类型
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    source: breakout
    visibility_type: normal
    table_id: media_infor
    field_ref:
      - field
      - media_infor.type
      - null
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation

yaml

result_metadata:
  - id: type                       # 字段名（无表前缀时使用短格式）
    name: type
    display_name: 媒体类型
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    source: breakout
    visibility_type: normal
    table_id: media_infor
    field_ref:
      - field
      - media_infor.type
      - null
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation

For table list query | 列表查询结果

列表查询结果

Each output column needs an entry.

id

uses

<table>.<field>

format:

yaml

result_metadata:
  - id: media_org_info.name
    name: name
    display_name: 单位名称
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    field_ref:
      - field
      - media_org_info.name
      - null
    source: fields
    visibility_type: normal
    table_id: media_org_info
  - id: media_org_info.created
    name: created
    display_name: 创建时间
    base_type: type/DateTime
    effective_type: type/DateTime
    semantic_type: null
    field_ref:
      - field
      - media_org_info.created
      - null
    source: fields
    visibility_type: normal
    table_id: media_org_info

每个输出列都需要一个条目。

id

使用

<table>.<field>

格式：

yaml

result_metadata:
  - id: media_org_info.name
    name: name
    display_name: 单位名称
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    field_ref:
      - field
      - media_org_info.name
      - null
    source: fields
    visibility_type: normal
    table_id: media_org_info
  - id: media_org_info.created
    name: created
    display_name: 创建时间
    base_type: type/DateTime
    effective_type: type/DateTime
    semantic_type: null
    field_ref:
      - field
      - media_org_info.created
      - null
    source: fields
    visibility_type: normal
    table_id: media_org_info

base_type mapping | 字段类型映射

字段类型映射

Steedos field type	base_type
text / select / lookup	`type/Text`
number / currency	`type/Float`
integer	`type/Integer`
date	`type/Date`
datetime	`type/DateTime`
boolean	`type/Boolean`
count result	`type/BigInteger`

Steedos字段类型	base_type
text / select / lookup	`type/Text`
number / currency	`type/Float`
integer	`type/Integer`
date	`type/Date`
datetime	`type/DateTime`
boolean	`type/Boolean`
count结果	`type/BigInteger`

Complete Examples | 完整示例

完整示例

Scalar — count of records

单值——记录计数

yaml

name: 单位总数
created_at: 2025-08-20T07:59:23.569Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  query:
    source-table: media_org_info
    aggregation:
      - - count
  type: query
  database: 1
display: scalar
entity_id: 68a5805bb74676d1c8cb3614
id: 68a5805bb74676d1c8cb3614
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_org_info
updated_at: 2025-08-20T07:59:23.569Z
visualization_settings: '{}'

yaml

name: 单位总数
created_at: 2025-08-20T07:59:23.569Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  query:
    source-table: media_org_info
    aggregation:
      - - count
  type: query
  database: 1
display: scalar
entity_id: 68a5805bb74676d1c8cb3614
id: 68a5805bb74676d1c8cb3614
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_org_info
updated_at: 2025-08-20T07:59:23.569Z
visualization_settings: '{}'

Bar chart — grouped count

柱状图——分组计数

yaml

name: 媒体类型统计
created_at: 2025-08-20T08:06:22.163Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  database: 1
  type: query
  query:
    source-table: media_infor
    aggregation:
      - - count
    breakout:
      - - field
        - media_infor.type
        - null
display: bar
enable_embedding: false
entity_id: 68a581feb74676d1c8cb361e
id: 68a581feb74676d1c8cb361e
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - id: type
    name: type
    display_name: 媒体类型
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    source: breakout
    visibility_type: normal
    table_id: media_infor
    field_ref:
      - field
      - media_infor.type
      - null
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_infor
updated_at: 2025-08-20T08:06:22.163Z
visualization_settings: >-
  {"graph.x_axis.labels_enabled":false,"graph.y_axis.labels_enabled":false,"graph.dimensions":["type"],"graph.metrics":["count"],"graph.show_values":true}

yaml

name: 媒体类型统计
created_at: 2025-08-20T08:06:22.163Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  database: 1
  type: query
  query:
    source-table: media_infor
    aggregation:
      - - count
    breakout:
      - - field
        - media_infor.type
        - null
display: bar
enable_embedding: false
entity_id: 68a581feb74676d1c8cb361e
id: 68a581feb74676d1c8cb361e
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - id: type
    name: type
    display_name: 媒体类型
    base_type: type/Text
    effective_type: type/Text
    semantic_type: null
    source: breakout
    visibility_type: normal
    table_id: media_infor
    field_ref:
      - field
      - media_infor.type
      - null
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_infor
updated_at: 2025-08-20T08:06:22.163Z
visualization_settings: >-
  {"graph.x_axis.labels_enabled":false,"graph.y_axis.labels_enabled":false,"graph.dimensions":["type"],"graph.metrics":["count"],"graph.show_values":true}

Scalar — count with filter

单值——带过滤的计数

yaml

name: 从业人员数
created_at: 2025-08-20T08:01:35.156Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  database: 1
  type: query
  query:
    source-table: media_journalist
    filter:
      - '='
      - - field
        - media_journalist.open
        - null
      - true
    aggregation:
      - - count
display: scalar
enable_embedding: false
entity_id: 68a580dfb74676d1c8cb3617
id: 68a580dfb74676d1c8cb3617
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_journalist
updated_at: 2025-08-20T08:01:35.156Z
visualization_settings: '{"table.cell_column":"count"}'

yaml

name: 从业人员数
created_at: 2025-08-20T08:01:35.156Z
creator_id: 689c34199c7714afa7502547
database_id: 1
dataset_query:
  database: 1
  type: query
  query:
    source-table: media_journalist
    filter:
      - '='
      - - field
        - media_journalist.open
        - null
      - true
    aggregation:
      - - count
display: scalar
enable_embedding: false
entity_id: 68a580dfb74676d1c8cb3617
id: 68a580dfb74676d1c8cb3617
parameter_mappings: []
parameters: []
query_type: query
result_metadata:
  - base_type: type/BigInteger
    display_name: 计数
    effective_type: type/BigInteger
    field_ref:
      - aggregation
      - 0
    name: count
    semantic_type: type/Quantity
    source: aggregation
table_id: media_journalist
updated_at: 2025-08-20T08:01:35.156Z
visualization_settings: '{"table.cell_column":"count"}'

Key Rules | 关键规则

关键规则

File name = question name:
```
单位总数.question.yml
```
id
==
entity_id
: always the same 24-char hex value
table_id
: the Steedos object name (e.g.
```
media_org_info
```
)
database_id
and dataset_query.database
: always
```
1
```
query_type
: always
```
"query"
```
(even for native SQL, use
```
"query"
```
)
parameter_mappings
and parameters
: use
```
[]
```
unless this question participates in dashboard filtering
visualization_settings
: must be a JSON string (quoted), not an object
Generate fresh unique ObjectIds — never copy IDs from other questions

文件名 = 问题名称：
```
单位总数.question.yml
```
id
==
entity_id
：始终为相同的24位十六进制值
table_id
：Steedos对象名称（例如
```
media_org_info
```
）
database_id
和 dataset_query.database
：始终为
```
1
```
query_type
：始终为
```
"query"
```
（即使是原生SQL也使用
```
"query"
```
）
parameter_mappings
和 parameters
：除非该问题参与仪表盘过滤，否则使用
```
[]
```
visualization_settings
：必须是JSON字符串（带引号），而非对象
生成全新的唯一ObjectId——切勿复制其他问题的ID