Back to Details

sql-to-business-logic

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

SQL to Business Logic Translator

SQL转业务逻辑翻译器

When to use

使用场景

  • A stakeholder asks "what exactly does this query calculate?"
  • Documenting a query library or a dbt model for non-technical readers
  • Reviewing a query for correctness by comparing its logic to the business requirement
  • Onboarding new analysts to existing SQL patterns
  • Translating legacy undocumented queries before refactoring
  • 利益相关方询问“这个查询到底计算什么？”
  • 为非技术读者编写查询库或dbt模型的文档
  • 通过对比逻辑与业务需求来审查查询的正确性
  • 帮助新分析师熟悉现有SQL模式
  • 在重构前翻译未归档的遗留查询

Process

流程

  1. Receive the query and context — obtain the SQL and the business question it answers. Also collect any schema notes (what the key tables and columns represent in business terms).
  2. Translate the FROM/JOIN structure — describe in plain language which data sources are combined and what type of join is used (inner keeps only matches; left keeps all rows from the left side). Note if the join type seems inconsistent with the stated purpose.
  3. Translate WHERE filters — list each filter condition as a business rule in plain language (e.g., 
    status = 'completed'
    → "only includes orders that have been paid and fulfilled").
  4. Explain GROUP BY and aggregations — describe what each aggregation computes and at what grain. Use 
    scripts/sql_explainer.py
    to automate a first-pass structural parse.
  5. Summarise output columns — for each output column, state its business meaning and any edge cases (nulls, rounding, currency units).
  6. Flag issues and write validation questions — identify potential problems (implicit null propagation, unexpected fan-out, hardcoded dates). Generate 3–5 questions the query author should confirm. Use 
    assets/query_documentation_template.md
    to record the full translation.
  1. 接收查询及上下文 — 获取SQL语句及其要解答的业务问题。同时收集所有架构说明（关键表和列在业务层面的含义）。
  2. 翻译FROM/JOIN结构 — 用通俗易懂的语言描述哪些数据源被组合，以及使用的连接类型（inner连接仅保留匹配项；left连接保留左侧表的所有行）。注意连接类型是否与声明的用途不一致。
  3. 翻译WHERE筛选条件 — 将每个筛选条件列为通俗易懂的业务规则（例如：
    status = 'completed'
    → “仅包含已支付并完成的订单”）。
  4. 解释GROUP BY与聚合操作 — 描述每个聚合计算的内容以及粒度。使用
    scripts/sql_explainer.py
    自动完成初步的结构解析。
  5. 总结输出列 — 针对每个输出列，说明其业务含义及任何边缘情况（空值、取整、货币单位）。
  6. 标记问题并编写验证问题 — 识别潜在问题（隐式空值传播、意外数据膨胀、硬编码日期）。生成3-5个需要查询作者确认的问题。使用
    assets/query_documentation_template.md
    记录完整的翻译内容。

Inputs the skill needs

该技能所需输入

  • The complete SQL query (SELECT through ORDER BY)
  • The business question the query is intended to answer
  • Table and column descriptions (or a data catalog entry)
  • Any business rules for key status values, date handling, or currency
  • The intended output: who reads the result and for what decision
  • 完整的SQL查询（从SELECT到ORDER BY）
  • 查询旨在解答的业务问题
  • 表和列的描述（或数据目录条目）
  • 关键状态值、日期处理或货币相关的任何业务规则
  • 预期输出：结果的受众及决策用途

Output

输出

  • scripts/sql_explainer.py
    — parses a SQL query and generates a structured plain-language explanation
  • assets/query_documentation_template.md
    — completed translation covering purpose, step-by-step logic, output columns, business rules, and validation questions
  • Optionally: a flowchart representation of the query logic
  • scripts/sql_explainer.py
    — 解析SQL查询并生成结构化的通俗易懂的解释
  • assets/query_documentation_template.md
    — 完成的翻译内容，涵盖用途、分步逻辑、输出列、业务规则和验证问题
  • 可选：查询逻辑的流程图表示