Looker Studio连接器指标字段名称与描述缓存问题排查

问题描述 #

我们正在开发基于BigQuery的Looker Studio连接器，通过getSchema方法添加自定义字段。维度字段修改名称或描述后可正常更新，示例代码如下：

fieldConfig = fields
          .newDimension()
          .setId("country")
          .setName("Country")
          .setType(types.TEXT);

但带公式聚合的指标字段修改名称后无变化，示例代码如下：

fieldConfig = fields
          .newMetric()
          .setId(`sessions_sum`)
          .setName(Sessions)
          .setType(types.NUMBER)
          .setFormula(`sum(sessions)`)
          .setAggregation(aggregations.AUTO);

刷新字段、重新配置连接器均无效。即使修改公式（如改为sum(sessions + 0)）触发字段变更通知，界面及资源仍未更新。现咨询该缓存的工作机制及稳定清除方法。

缓存机制解析 #

Looker Studio对连接器字段的缓存分为两层：

• 连接器元数据缓存：getSchema返回的字段定义会被缓存，维度字段结构简单（无依赖公式/聚合逻辑），修改名称/描述时，系统能快速识别字段ID对应的元数据变更；而带公式的指标字段，系统会将字段ID、公式、聚合规则作为缓存键的核心组成部分，仅修改名称时，缓存键未发生变化，因此不会触发缓存更新。
• 报表资源缓存：已添加到报表的字段，其显示名称会被单独缓存到报表资源中，即使连接器端的字段名称更新，报表端仍会沿用本地缓存的旧名称，除非触发报表级的缓存刷新。

稳定清除方法 #

• 强制修改缓存键触发更新：
  除了修改公式，还可以临时调整字段的setAggregation值（比如从aggregations.AUTO改为aggregations.SUM，更新后再改回），这样会改变缓存键的组成，触发getSchema的重新拉取。
• 报表端手动刷新：
  在报表编辑器中，进入「资源 > 管理添加的数据源」，选中目标连接器数据源，点击「刷新字段」后，再重新编辑使用该指标的组件，选择最新的字段名称。
• 重置数据源连接：
  若上述方法无效，可删除报表中的数据源，重新添加并配置连接器，这会彻底清除报表端的本地缓存。
• 利用版本号控制：
  在连接器代码中添加setVersion方法，每次修改字段定义时升级版本号（比如fields.setVersion("2.0")），Looker Studio会检测到版本变更，强制重新拉取完整的字段 schema。

内容的提问来源于stack exchange，提问作者Dominic Woodman