steedos-questions（斯蒂多斯问题）

Steedos Analytics Questions — File Format Guide

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/ 目录下。

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

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

Examples:

• questions/单位总数.question.yml
• questions/媒体类型统计.question.yml
• questions/从业人员数.question.yml

File Structure | 文件结构

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: '{}'

ID Generation | 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.

dataset_query — MBQL Query | MBQL 查询结构

Count (scalar) | 计数

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

Count with filter | 带过滤的计数

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

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

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

Table list with limit | 列表查询

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

Native SQL query | 原生 SQL 查询

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

Display Types | 显示类型

visualization_settings | 可视化设置

For simple questions, use '{}' (empty JSON string).

Common examples:

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

result_metadata | 结果列元数据

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

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

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 | 分组+计数结果

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

For table list query | 列表查询结果

Each output column needs an entry. id uses <table>.<field> format:

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 | 字段类型映射

Complete Examples | 完整示例

Scalar — count of records

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

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

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 | 关键规则

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