数据工作——CLI

Dataworks体育数据平台的官方命令行界面. 通过数据工作认证,运行公共数据引擎API,摄入度量衡,并从终端或自动化工作流程中消耗实时事件.

概览

这个 dw 二进制翻转公开的 GraphQL 合同 @dataworks-technology/data 输入可发现、可键入的命令。 它提供人可读输出供交互使用,并稳定JSON或NDJSON输出给脚本和代理.

表面指挥

先决条件

• 节点.js 22 或更新运行已公布的 CLI
• 数据工作账户
• 阿宝 数据库开发
• 仅将寄存器开发:带有CodeArtifact的AWS证书改为访问. bun install 运行 a preinstall 用来为私人取一个符号的钩子 @dataworks/sdk 依赖性,提供度量目录. 使用 AWS_PROFILE=your-profile-name bun install 非默认配置文件,以及 bun run sdk 要刷新过期的符号。 安装已公布的 CLI 需求 没有这些.

快速启动

1. 安装 CLI :

   npm install --global @dataworks-technology/cli
   dw --help
   

2. 认证 :

   dw auth login --environment uat
   dw auth status
   

   CLI 在您的浏览器中打开管理登录的 Dataworks , 并且从未收到您的密码 。 会话存储在操作系统认证存储中,从未存储在数据工作配置文件中. 如果浏览器无法自动打开, 请通过 --no-browser 并访问同一计算机上显示的 URL。 无头工作可以提供受保护的工作 DW_SESSION_JSON 换成秘密.

   --environment 接受 live, (中文(简体) ), uat,或任何命名的环境,例如 james-dev. 通过Live Cognito游泳池进行现场直播 环境标志通过UAT的。 公共 UAT 和 Live Cognitto 客户端的ID 被构建在。 用它代替它们 --client-id, (中文(简体) ), DW_UAT_CLIENT_ID, (中文(简体) ), DW_LIVE_CLIENT_ID,或 DW_CLIENT_ID 当测试不同的应用程序客户端时.

3. 列出并选择租户. 选择被保存到您的本地配置文件 用于后续命令.

   dw tenant list
   dw tenant select
   dw tenant select tenant-123
   

   dw tenant list 显示友好名称、ID和当前选择。 探员 并使用脚本 dw tenant list --json。 。 。 .

4. 发现并运行命令 :

   dw commands
   dw data athlete list
   dw data athlete create --name "Ada" --date-of-birth 1992-01-01
   

生成的命令文档可见于 docs/commands。 。 。 .

5. 在 Codex 或 Claude 代码中启用数据工作 :

   dw agents install
   

   此检测支持客户端并安装完整的数据工作插件 : 平滑的技巧加上只读的 query_metrics MCP服务器. 开始 a 安装后新建 Codex 线程 。 在克洛德代码,运行 /reload-plugins 或者说 启动新会话 。 只配置一个客户端, 使用 dw agents install codex 或者说 dw agents install claude-code。 。 。 .

   在设置完成之前, 交互式 CLI 最多使用此提醒打印 每24小时一次 从来没有出现过 --json永远藏起来 dw agents reminder disable,用 dw agents reminder enable,或 设定 DW_NO_AGENT_REMINDER=1 用于单一过程或自动化环境.

巴什自动完成

生成补全缓存并打印一次性的 Bash 设置指令 :

dw autocomplete bash

Global npm 安装并升级自动运行此命令. 它准备 最新的补全缓存并打印设置指令,但不编辑您的 shell 启动文件 。 如果 npm 无法访问 shell 缓存, 仍然安装 成功,您可以重试 dw autocomplete bash。 。 。 .

遵循显示的指示并重新装入 Bash 后, 按 Tab 到 完整 dw 命令名称和旗帜。 运行 dw autocomplete --refresh-cache 在安装添加命令的发布后.

AI 代理计量查询

该软件包包括一个有重点的,只读的MCP服务器,它有三个工具: query_metrics, (中文(简体) ), list_athletes,以及 list_events。它使用同样的OS支持的登录会话,并选定租户为 dw,通过准确的ID或独有的名称解决运动员,解决公制名称 对照Cononical Dataworks目录, 民调同步数据探索器 查询,并返回正规结构行。 GPS 值包括解码 纬度和经度;心率值在有效时使用数字 BPM.

量子措辞与案例、空间、连字符和下划线不一致, 因此,“心率”决定 heartrate,与别名,例如: gps, (中文(简体) ), hr, (中文(简体) ), 财务报告和审定财务报表 watts。未识别名称返回最接近的犬科候选人 而不是赤裸裸的拒绝.

Codex和Claude代码最简单的设置是:

dw agents install

该命令在升级后可以安全地重新运行. 它安装或更新完整 每个被检测到的客户端的数据工作插件,并报告重装或重新启动步骤. 如果旧的市场注册指向不同的CLI安装,则重新运行 与 --force。 。 。 .

保持插件当前

代理客户端将插件复制到一个版本绑定的目录而不是读取 已安装 npm 软件包,因此升级 CLI 本身并不更新 技术 代理加载。 MCP服务器确实与CLI一起移动,因为它是 以 dw-mcp 从 PATH ——留下由老技能驱动的新服务器 直到插件刷新为止.

全局安装并升级自动刷新:后置钩子运行 dw agents install --refresh,仅更新已有客户端 数据工作和配置没有新内容 。 事后重新装入客户端 /reload-plugins 在克洛德代码中,或者一个新的代码线.

当不能运行时——安装 --ignore-scripts,或重新设置CLI 在不同的节点版本下—— dw 每天最多打印一次提醒 告诉你插件在后面 并命名修复它所需的两个步骤. 刷新为 dw agents install,添加 --force 如果市场仍然 在上次安装时点,然后重新装入客户端.

重新装入任何一种方式的事务: 已经运行的客户端保留插件复制 在启动时加载, 因此仅刷新不会改变当前会话中的任何内容 .

成功的设置会自动禁用定期的 CLI 提醒 。 选择退出 不安装代理集成, 运行 dw agents reminder disable。 。 。 .

其他 MCP 客户端可以启动安装 dw-mcp 二进制直接 :

{
  "mcpServers": {
    "dataworks": {
      "command": "dw-mcp",
      "args": []
    }
  }
}

Npm 包装一个相容的 Codex 和 Claude 代码插件 plugins/dataworks它的突出重点的技巧使诸如“给我最后的..... James Haigh的30个GPS值“改为 query_metrics 电话 该工具接受 完全一个 athlete_id 或者说 athlete_name附加时 metric; 可选输入为 limit, (中文(简体) ), order, (中文(简体) ), from, (中文(简体) ), to, (中文(简体) ), event_id, (中文(简体) ), dataset_datasource_id, (中文(简体) ), tenant_id, (中文(简体) ), metric_category,以及 timeout_ms。 。 。 .

查询范围必须是 athlete_id, (中文(简体) ), athlete_name, (中文(简体) ), event_id,或 dataset_datasource_id。只提供事件或数据源回答问题 关于整个种族——"T100旧金山的最新心率值",以及 返回无效 athlete 每一行仍然随身携带 athlete_id。 。 。 .

list_athletes 财务报告和审定财务报表 list_events 存在,所以代理可以解析一个ID而不是 猜猜看,除了"错误拼写"以外,还能分辨出"不是在这个租户". 何时 list_events 报告 unavailable: true aPI没有为此归还任何东西 ,这是一个权限问题,而不是空置的租户.

服务器从不执行突变. 如果名称解析模糊,它 返回候选人,并需要明确的运动员ID而不是猜测. 每个错误都带有 recovery 字段命名修正它的命令.

产出和安全

• 命令默认会让人读取表格.
• 过 --json 对脚本和代理。 有限结果使用稳定 {data,meta} 信封; 订阅和其他流会释放出新行限制的JSON(NDJSON).
• 生成突变支持 --dry-run --json 在不发送请求的情况下提出请求.
• 破坏性突变和所有活性突变需要确认;非互动性呼叫者必须通过 --yes。 。 。 .
• 密码,令牌,授权信头,秘密,以及API密钥均由结构输出进行编辑.
• 缺少参数错误列出所需的 GraphQL 类型和代表性值,然后提供一个安全的复制复制示例和一个精确 --help 命令; --json 包含与结构化细节相同的指导.

# Preview a mutation without sending it
dw data athlete update --public-id athlete-123 --name "Ada L." --dry-run --json

# Explicitly confirm a destructive mutation
dw data athlete delete --public-id athlete-123 --yes

# Use raw GraphQL when no friendly command fits
dw graphql query --document @query.graphql --variables @variables.json --json

粗略的衡量标准

dw ingest 验证并发送运动员参数到一个事件和 数据集数据源. 每个衡量标准都要求 athletePublicId, (中文(简体) ), metric, (中文(简体) ), value, (中文(简体) ), 和一个正整数 timestamp通过一个内置的 JSON 阵列, a { "metrics": [...] } 对象, @filename,或 - 从标准读取 JSON 输入.

# Inline JSON
dw ingest --event event-123 --dataset-datasource ds-456 --metrics '[{"athletePublicId":"ath-1","metric":"heartrate_calculated","value":172,"timestamp":1700000000}]'

# File input; strict validation rejects the whole batch if any metric is invalid
dw ingest --event event-123 --dataset-datasource ds-456 --metrics @metrics.json

# Send valid metrics, report dropped invalid metrics, and return stable JSON
dw ingest --event event-123 --dataset-datasource ds-456 --metrics @metrics.json --best-effort --json

订阅实时事件

实时计量频道使用情况 dataworks/<dataset-datasource-id>/<event-id>/<metric-or-*>启用 * 观看 数据集数据源/事件对的每个度量,或缩小的度量名 溪流。 溪流。 领先 / 是可选的。 人类产出为表格;添加 --json 页:1 邓杰森.

新闻 Ctrl+C 一次关闭 WebSocket 订阅并返回 壳.

# Watch all metrics for dataset-datasource 1 and event 1
dw events subscribe --channel dataworks/1/1/*

# Watch only heart-rate metrics as NDJSON
dw events subscribe --channel dataworks/1/1/heartrate --json

查询数据探索器

dw data data-explorer execute 带有明确列的查询参数存储 清单和计量类别。 可选字段支持数据浏览器过滤规则, 组合、分组、订购、限制和投票是同步的 queryExecutionId。该类别必须是 METRICS_TYPE_A, (中文(简体) ), METRICS_TYPE_B,或 METRICS_TYPE_C· ; --columns 是JSON阵列.

# Keep a filtered GPS query in a reusable JSON file
dw data data-explorer execute --input @gps-query.json --json

# Return the latest 30 GPS positions for one athlete
dw data data-explorer execute --columns '["timestamp","athletepublicid","current"]' --metric-category METRICS_TYPE_A --filter-rules '{"combinator":"and","rules":[{"field":"metric","operator":"in","value":"latlong"},{"field":"athletepublicid","operator":"in","value":"athlete-123"}]}' --limit 30 --order-by timestamp --order-direction DESC --json

相应 gps-query.json 包含没有 CLI 旗的相同字段 转换 :

{
  "columns": ["timestamp", "athletepublicid", "metric", "current"],
  "metricCategory": "METRICS_TYPE_A",
  "filterRules": "{\"combinator\":\"and\",\"rules\":[{\"field\":\"metric\",\"operator\":\"in\",\"value\":\"latlong\"},{\"field\":\"athletepublicid\",\"operator\":\"in\",\"value\":\"athlete-123\"}]}",
  "limit": 30,
  "orderBy": "timestamp",
  "orderDirection": "DESC"
}

filterRules 是一个包含顶级的 AWSJSON 字符串 combinator (单位:千美元) rules 阵列。 每一个规则 field, (中文(简体) ), operator字符串 value; 已支持 运算符包括 =, (中文(简体) ), !=, (中文(简体) ), >, (中文(简体) ), <, (中文(简体) ), >=, (中文(简体) ), <=, (中文(简体) ), contains,以及 in。 。 。 . 用于 in 以逗号分隔。 GPS是标准 latlong 内 METRICS_TYPE_A; 数据 current 值是一个 latitude:longitude 绳子。 运行 dw data data-explorer execute --help 用于完整旗帜列表和示例. 单位 --json 输出, rows 是AWSJSON,可能需要JSON解码直到它成为 数组; 默认表格输出为人类进行解码.

常见命令

SDK 和命令生成

数据引擎SDK发布过滤后的公共GraphQL schema和包含其SDK版本,操作计数和schema hash的版本合同. 这个寄存器将SDK版本所标注,验证合同,并为每次公共操作生成一个oclif命令和Markdown页面.

下方的文件 src/generated/, (中文(简体) ), src/commands/data/,以及 docs/commands/ 生成。 变动 schema/operation-overrides.json, (中文(简体) ), scripts/generate-commands.ts,或上游公共计划而不是编辑生成的文件.

冠名是用同样的方式生成的. scripts/generate-metrics.ts 读取 metricConfig 从私人 @dataworks/sdk 依赖和排放 src/generated/metrics.ts 和目录块 query-dataworks-metrics 技术。 要添加一个度量, 请更改 SDK , 而不是生成的文件, 而不是在 src/lib/metric-names.ts。 。 。 .

每天对新软件进行SDK维护工作流程检查 @dataworks-technology/data 财务报告和审定财务报表 @dataworks/sdk 各个版本。 决定式生成首先运行;如果需要兼容性工作,则受限的LiteLLM维护代理修复. 寄存器工作流程用完整的CI验证准确的更新,自动合并成功的更新,并开始CLI发布. 修复失败仍然是供人审查的公关草案.

见 结构, (中文(简体) ), 捐款, (中文(简体) ), 自动 SDK 维护, (中文(简体) ), 警卫,以及 释放 详细情况.

排雷中心/发改委

成功的SDK维护与放行取悦PR被验证并自动合并. SDK修复失败仍为人审查PR草案. npm 成功出版后通知Slack通过 SLACK_WEBHOOK_URL。 。 。 .

代码样式

• 阿宝 依赖管理和寄存脚本
• 节点.js 22+ 已公布的 CLI 兼容性
• 高级 用于格式化
• 维特 用于单位测试
• 常规承诺 由承诺方强制执行feat:, (中文(简体) ), fix:, (中文(简体) ), chore:, (中文(简体) ), refactor:, (中文(简体) ), test:, (中文(简体) ), docs:(中文(简体) )
• 对每个生成的图QL突变进行明确的风险分类

交叉依赖关系

• 取决于 数据工作-数据 用于公共图QL计划 @dataworks-technology/data 软件包
• 使用生成 Data SDK Docusaurus 引用的相同的公共合同
• 运行时对 UAT 或 Live Cognitto 和数据引擎端点进行认证
• 新的SDK版本通过经核实的自动拉动请求而不是手动复制

贡献者

• 詹姆斯・海格
• 费利克斯·阿隆索·罗德里格斯
• 保罗·加德纳
• 克里斯·摩尔
• 玛蒂娜·布里兰特

许可证

麻省理工学院