DataOps-platform/docs/api/metric-check-api.md

指标公式检查API文档

API概述

该API用于检查指标计算公式中的变量，并在Neo4j数据库中查找匹配的元数据。

接口信息

• URL: /api/data/metric/check
• 方法: POST
• Content-Type: application/json

请求参数

参数名	类型	必填	说明
formula	string	是	指标计算公式文本

公式格式说明

公式格式为：指标名称 = 计算表达式

• 等号左侧：指标名称
• 等号右侧：包含中文变量和数学运算符的计算表达式
• 支持的运算符：+、-、*、/、()、（）、[]、{}
• 变量：中文字符串或数字
• 只有中文字符串会被识别为需要查找的变量

请求示例

{
  "formula": "销售额 = 单价 * 数量 + 运费"
}

更复杂的示例：

{
  "formula": "利润率 = (销售收入 - 成本) / 销售收入 * 100"
}

响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "variable": "单价",
      "name_zh": "单价",
      "name_en": "unit_price",
      "id": 12345,
      "create_time": "2024-01-15 10:30:00",
      "findit": 1
    },
    {
      "variable": "数量",
      "name_zh": "数量",
      "name_en": "quantity",
      "id": 12346,
      "create_time": "2024-01-15 10:31:00",
      "findit": 1
    },
    {
      "variable": "运费",
      "name_zh": "",
      "name_en": "",
      "id": null,
      "create_time": "",
      "findit": 0
    }
  ]
}

响应字段说明

字段名	类型	说明
variable	string	从公式中提取的变量名
name_zh	string	匹配到的元数据中文名称（未找到时为空字符串）
name_en	string	匹配到的元数据英文名称（未找到时为空字符串）
id	integer/null	匹配到的元数据节点ID（未找到时为null）
create_time	string	匹配到的元数据创建时间（未找到时为空字符串）
findit	integer	是否找到匹配：1表示找到，0表示未找到

错误响应

参数错误

{
  "code": 400,
  "message": "failed",
  "data": {},
  "error": {
    "error": "公式文本不能为空"
  }
}

公式格式错误

{
  "code": 400,
  "message": "failed",
  "data": {},
  "error": {
    "error": "公式格式错误：缺少等号"
  }
}

服务器错误

{
  "code": 500,
  "message": "failed",
  "data": {},
  "error": {
    "error": "具体错误信息"
  }
}

功能说明

变量提取规则

1. 公式以等号（=）分割，只处理等号右侧的计算表达式
2. 按照数学运算符分割表达式，提取所有token
3. 只保留包含中文字符的token作为变量
4. 数字会被自动过滤掉
5. 相同的变量会去重，每个变量只查询一次

元数据匹配规则

1. 使用模糊匹配（CONTAINS）在Neo4j的DataMeta节点中查找
2. 匹配字段为节点的name属性
3. 每个变量只返回第一个匹配的结果
4. 如果没有找到匹配，findit字段设置为0

使用场景

1. 指标定义验证：在创建或编辑指标时，验证公式中的变量是否存在于元数据库中
2. 数据血缘分析：了解指标依赖哪些元数据
3. 数据质量检查：发现公式中引用但未在元数据库中定义的变量

示例代码

Python (requests)

import requests
import json

url = "http://your-server/api/data/metric/check"
headers = {"Content-Type": "application/json"}
data = {
    "formula": "销售额 = 单价 * 数量 + 运费"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

print(json.dumps(result, indent=2, ensure_ascii=False))

JavaScript (fetch)

const url = 'http://your-server/api/data/metric/check';
const data = {
  formula: '销售额 = 单价 * 数量 + 运费'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.error('Error:', error));

cURL

curl -X POST http://your-server/api/data/metric/check \
  -H "Content-Type: application/json" \
  -d '{"formula": "销售额 = 单价 * 数量 + 运费"}'

注意事项

1. 公式必须包含等号（=），否则会返回错误
2. 变量名必须包含中文字符才会被识别
3. 元数据匹配使用模糊匹配，可能会匹配到相似的名称
4. 数据库连接失败时会返回空数组
5. 相同的变量名只会查询一次并返回一个结果

更新历史

• 2025-10-30: 初始版本创建