MCP Toolbox 的 looker-health-vacuum 工具：基于系统活动数据分析并清理未使用的 LookML 对象

MCP Toolbox 的 looker-health-vacuum 工具基于系统活动数据分析并清理未使用的 LookML 对象【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox本指南系统讲解 MCP Toolbox 中looker-health-vacuum工具的功能定位、参数语义、配置方法及其底层实现原理。该工具面向 Looker 实例的健康治理场景通过查询 Looker 系统活动数据system__activity识别长期未被查询使用的模型models、探索explores、连接joins与字段fields为语义层瘦身、LookML 重构和权限清理提供数据依据。读完本文你将能够独立完成该工具的参数调优、YAML 配置接入并理解其判定未使用的完整算法。工具概览从体检到清理建议在 MCP Toolbox 的 Looker 集成体系中looker-health-vacuum与looker-health-analyze构成一对互补工具looker-health-analyze 负责统计项目、模型、探索的使用情况相当于体检报告而looker-health-vacuum则进一步输出可直接移除的低活跃度对象候选清单相当于清理建议帮助团队在语义层规模膨胀前主动治理。根据工具说明looker-health-vacuum.md该工具通过action参数选择执行的清理分析类型models识别一个模型model内部未被使用的 exploresexplores识别一个探索explore内部未被使用的 joins 和 fields。从源码结构看两种 action 的输出对象不同models模式的返回值聚焦模型 → 未使用探索列表的映射而explores模式则细化到探索 → 未使用连接 / 未使用字段两个维度详见 lookerhealthvacuum.go。参数详解六个参数控制整个判定逻辑工具的运行时参数定义于 lookerhealthvacuum.go 的 Initialize 方法与文档参数表完全对应fieldtyperequireddescriptionactionstringtrueThe vacuum to perform:models, orexplores.projectstringfalseThe name of the Looker project to vacuum.modelstringfalseThe name of the Looker model to vacuum.explorestringfalseThe name of the Looker explore to vacuum.timeframeintfalseThe timeframe in days to analyze for usage. Defaults to 90.min_queriesintfalseThe minimum number of queries for an object to be considered used. Defaults to 1.各参数要点说明action必填合法值仅为models与explores。源码中switch action对未知值返回unknown action: %s的 Agent 错误Invoke 方法因此调用时务必使用文档规定的两种取值。project / model / explore可选逐级收窄用于将分析范围限定到指定对象。从源码实现看过滤条件为空字符串时视为不过滤models模式同时支持project与model两个过滤维度models 方法explores模式则用model过滤模型、用explore过滤探索explores 方法。不指定任何范围参数时将扫描实例内全部 LookML 模型。timeframe默认 90回溯分析的使用时间窗口天。该值会拼入系统活动查询的时间过滤条件例如history.created_date: 90 days。min_queries默认 1判定被使用的查询次数下限。默认值 1 意味着至少被查询过 1 次即视为已使用将值调大如 5、10可以更严格地筛选出真正的低频对象。注意源码中默认值的生效逻辑为参数为 0 时回退到默认值Invoke 方法即显式传入timeframe: 0或min_queries: 0与不传效果相同会分别被重置为 90 与 1。配置接入完整的 YAML 工具定义在 MCP Toolbox 中工具通过 YAML 声明式配置注册。文档给出了一个识别thelook模型中order_items探索内低活跃字段与连接的示例这里min_queries判定阈值下20 天内查询次数少于 1 的字段被标记为未使用kind: tool name: health_vacuum type: looker-health-vacuum source: looker-source description: | This tool identifies and suggests LookML models or explores that can be safely removed due to inactivity or low usage. Parameters: - action (required): The type of resource to analyze for removal candidates. Can be models or explores. - project (optional): The specific project ID to consider. - model (optional): The specific model name to consider. Requires project if used without explore. - explore (optional): The specific explore name to consider. Requires model if used. - timeframe (optional): The lookback period in days to assess usage. Defaults to 90 days. - min_queries (optional): The minimum number of queries for a resource to be considered active. Defaults to 1. Output: A JSON array of objects, each representing a model or explore that is a candidate for deletion due to low usage.配置块中的三个顶层字段含义如下fieldtyperequireddescriptiontypestringtrueMust be looker-health-vacuumsourcestringtrueLooker source namedescriptionstringtrueDescription of the tool that is passed to the LLM.其中description会被直接传递给 LLM 作为工具说明Manifest 定义是模型理解工具用途与参数语义的关键文本务必写清 action 取值、可选参数依赖关系与输出格式。该工具的预置配置已随项目提供在 looker-dev.yaml 中可以看到名为health_vacuum的完整工具条目且它被列入该预置配置的工具清单looker-dev.yaml 工具列表。因此直接加载looker-dev预置配置即可快速获得该工具无需手工编写。配置解析的严格性工具的配置解析由 newConfig 与Config结构体type、source均为validate:required承载。对应的单元测试 lookerhealthvacuum_test.go 验证了两类行为合法配置可正常解析最小化配置仅kind、name、type、source、description能正确反序列化为Config对象未知字段会直接报错若在配置中混入未定义的字段如invalid_field: true解析将失败并返回unknown field invalid_field错误防止拼写错误悄悄生效。此外工具初始化时若description为空会直接返回错误Initialize 方法这是配置被拒绝的最常见原因。前置条件Looker 源与认证looker-health-vacuum属于 Looker 集成必须挂载在合法的 Looker source 上运行。源码通过compatibleSource接口约束来源类型接口定义要求来源具备GetLookerSDK能力若 source 不兼容ValidateSource会返回类型错误。在认证方面Looker source 仅使用 API 认证需要先在 Looker 中创建 API 用户以登录并确保运行 MCP Toolbox 的服务身份具备相应的 GCP IAM 权限如roles/looker.instanceUser等详见 Looker Source 说明。调用工具时 SDK 的获取基于访问令牌源码对 401 未授权错误有专门处理Invoke 方法认证失效时会返回 401 状态以便上层重试或刷新凭据。实现原理如何判定未使用这是本文的核心部分。工具的判定逻辑全部建立在Looker 系统活动数据system__activity中的history视图之上——即查询历史记录。整体分为三层查询1. 模型使用度getUsedModelsgetUsedModels 通过内联查询inline query汇总最近timeframe天内每个模型被查询的次数其过滤条件相当精细按history.created_date限定时间窗口如90 days排除系统模型自身-system__activity, -i__looker仅统计达到活跃阈值的记录history.query_run_count min_queries-1排除开发分支上的查询user.dev_branch_name: NULL即只统计生产环境的真实使用。查询结果以{模型名: 查询次数}的映射形式返回供后续匹配。2. 未使用探索getUnusedExploresgetUnusedExplores 针对单个模型内的每个探索构造以query.model与query.view即探索名为过滤条件的计数查询若结果集为空该探索在时间窗口内一条生产查询都没有则将其标记为未使用。注意该函数对查询失败的处理是记录错误并继续单个探索查询失败不会中断整体分析。3. 未使用字段与连接getUsedExploreFieldsgetUsedExploreFields 是整个工具最核心的细节所在它决定了一个字段是否被使用查询query.formatted_fields与query.filters两个字段即被选中展示的字段与被用作筛选条件的字段并限制在production工作区history.workspace_id: production用正则(\w\.\w)从这两类文本中提取视图名.字段名形式的字段标识将每次命中的history.query_run_count累加到对应字段上得到每个字段的总查询次数。随后 explores 方法 组装判定结果未使用字段从LookmlModelExplore拉取该探索全部未隐藏的 dimension 与 measure凡是不在已使用字段映射中的即判定为未使用未使用连接按字段名首段.前的 join 名聚合各 join 的查询次数再与该探索的 join 列表比对计数为 0 的 join 即为未使用。输出格式工具最终返回一个 JSON 数组。models模式的每个元素形如{Model: ..., Unused Explores: [...], Model Query Count: N}explores模式的每个元素形如{Model: ..., Explore: ..., Unused Joins: [...], Unused Fields: [...]}。Agent 可据此直接生成建议移除对象清单交人工复核后执行删除。使用建议与注意事项先 analyze 后 vacuum建议先运行looker-health-analyze获取使用统计概览再运行looker-health-vacuum获取可移除对象清单两步数据相互印证避免误删。生产数据为基准判定仅统计生产环境排除开发分支的查询符合线上真实使用的清理语义如果团队存在大量未上线的预研模型它们会自然进入候选清单这是预期行为而非缺陷。合理设置时间窗口默认 90 天适合大多数季度节奏对快速迭代的团队可缩短如 30 天对数据仓库类低频业务可拉长如 180 天以平衡清理收益与误伤风险。字段级清理需人工复核字段与连接的判定依赖系统活动数据的字段名文本解析若 Looker 中存在自定义字段命名或异常查询日志建议将min_queries保持默认值并结合人工抽查确认后再删除对象。小结looker-health-vacuum是 MCP Toolbox Looker 集成中面向语义层治理的实用工具它以 Looker 系统活动数据为唯一事实来源通过models与explores两种模式分别输出未使用的探索、连接与字段候选清单并以时间窗口 最小查询次数两个可调阈值控制清理灵敏度。配合本文所述的源码级判定逻辑lookerhealthvacuum.go、配置规范looker-dev.yaml与测试保障lookerhealthvacuum_test.go开发者可以安全地将该工具接入日常的 Looker 健康巡检流程持续控制语义层规模与维护成本。【免费下载链接】mcp-toolboxMCP Toolbox for Databases is an open source MCP server for databases.项目地址: https://gitcode.com/GitHub_Trending/ge/mcp-toolbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考