数据类型和语义类型

构建社区连接器时,您在架构中定义的每个字段都要对应一种数据类型。数据类型定义了字段的基本类型,例如 BOOLEANSTRINGNUMBER 等。

除了数据类型之外,Looker 数据洞察还使用语义类型。语义类型可帮助描述数据表示的信息类型。例如,数据类型为 NUMBER 的字段在语义上可以表示货币金额或百分比,而数据类型为 STRING 的字段在语义上可以表示城市。要查看可以使用哪些语义类型,请查阅语义类型文档

社区连接器架构和 Looker Studio 字段

为社区连接器定义架构时,每个字段有各种不同的属性,这些属性将决定字段在 Looker Studio 中的表示方式和使用方式。例如:

  • conceptType是使用 conceptType 属性在连接器架构中定义的。此属性可确定相应字段是维度字段还是指标字段。有关指标和维度之间的差异的说明,请参阅维度和指标
  • 语义类型可以在连接器架构中定义,也可以由 Looker Studio 根据连接器中定义的数据类型属性和连接器返回的数据值自动检测。如需详细了解相关工作原理,请参阅自动语义类型检测
  • 汇总类型决定了指标值是否可以重新汇总(忽略维度)。如果将 semantics.isReaggregatable 属性设置为 true,则该聚合将默认为 SUM 聚合,否则将设置为 Auto。此外,您还可以使用 defaultAggregationType 属性为可重新聚合的字段手动设置默认聚合类型。

使用 Looker Studio 中的连接器配置和连接时,字段编辑器会根据您定义上述属性的方式显示连接器的完整架构。如果您已纳入语义类型,则字段将按照您定义的方式显示。如果您使用了自动语义类型检测,则字段会按照检测的方式显示。 字段屏幕

设置语义信息

设置语义信息的方式有两种。您可以手动设置字段语义,也可以依靠 Looker Studio 自动检测。

例如,如果某个数字在语义上表示美元,Looker Studio 将无法自动检测此语义类型。此外,自动语义检测要求 Looker Studio 针对架构的每个字段进行数据提取调用。反之,如果您手动指定架构,则不会发起任何数据提取调用。如果您知道数据的语义类型(例如,货币、百分比、日期等),出于准确度和效果考虑,我们建议您在架构中进行明确设置。

手动设置语义类型(推荐)

如果您知道自己的语义类型,则可以手动为每个架构字段定义 semantics。如需了解可用属性的完整详细信息,请访问字段参考页面。如果您选择定义手动语义类型,建议您为每个字段定义 semanticTypesemanticGroup。手动提供这些属性时,系统不会运行自动语义类型检测流程。如果您手动为部分字段(而非全部字段)设置语义类型,则您未指定的字段的语义类型默认为 TextNumberBoolean,具体取决于为字段指定的 dataType

下面是一个手动设置语义类型的简单架构示例。Income 设为货币,Filing Year 设为日期。

data-studio/semantics.gs
var schema = [
  {
    'name': 'Income',
    'label': 'Income (in USD)',
    'dataType': 'NUMBER',
    'semantics': {
      'conceptType': 'METRIC',
      'semanticGroup': 'CURRENCY',
      'semanticType': 'CURRENCY_USD'
    }
  }, {
    'name': 'Filing Year',
    'label': 'Year in which you filed the taxes.',
    'dataType': 'STRING',
    'semantics': {
      'conceptType': 'METRIC',
      'semanticGroup': 'DATE_OR_TIME',
      'semanticType': 'YEAR'
    }
  }
];

对手动语义类型进行问题排查

如果您未正确设置基础数据的语义类型,这些数据将无法正常工作。要测试此类问题并非易事,但您可以执行以下操作来帮助发现问题。

  1. 返回 2 行或 3 行数据(而非全部数据),然后手动检查数据。
  2. 在 Looker Studio 中创建一个仅使用您尝试检查的字段的表。
  3. 密切留意 GeoDate 字段,因为它们的格式最为严格。

自动语义类型检测

如果您尚未在架构中定义任何语义类型,则 Looker Studio 将尝试根据数据类型属性和连接器返回的数据值的格式自动检测语义类型。

自动检测流程的步骤如下:

  1. 执行社区连接器的 getSchema 函数,以请求架构。
  2. 反复迭代连接器架构中定义的批量字段并向字段发起 getData 请求。执行 getData 请求时将 sampleExtraction 参数设置为 true,以指明数据请求用于进行语义检测。
  3. 根据字段数据类型和 getData 请求返回的值的格式来确定字段的语义类型。

处理自动语义类型检测的选项

当 Looker Studio 出于语义检测的目的执行社区连接器的 getData 函数时,传入的请求将包含 sampleExtraction 属性,该属性将设置为 true。连接器返回的数据仅供 Looker Studio 用于标识字段的语义类型。由于该值不用于任何其他用途,因此不需要来自外部来源的实际数据。

您可以通过以下几种方法改进代码的语义类型检测:

  • 建议:传递预定义值
    返回每个字段的预定义值,该值最能代表字段的语义类型,并且已知可被 Looker Studio 正确检测。例如,如果某个字段的语义类型是“国家/地区”,则返回 IT(对应意大利)等值。这种方法的另一好处是处理速度要快得多,因为它不需要您向第三方服务发起 HTTP 请求以获取数据。

  • 仅返回 n 个记录
    如果您从中提取数据的第三方服务在请求数据时存在行数限制,请向 Looker Studio 返回一小部分行,而不是整个数据集。n这将限制您需要针对每个语义检测请求向 Looker Studio 传递的数据量。

  • 请求所有列并缓存响应
    如果可以针对您从中提取数据的第三方服务请求所有列,那么在 Looker Studio 收到第一个语义检测请求时,请提取所有列并缓存结果。对于后续语义检测请求,请从缓存中提取列值,而不是向第三方服务发起额外的 HTTP 请求。

  • 执行相同的操作
    对于 sampleExtraction 已设为 true 的请求,您可以选择不做任何具体调整。这将使语义检测流程变慢,因为 Looker Studio 必须提取所有数据才能执行语义检测流程。此外,由于许多语义检测请求都是并行执行的,因此这种方法还会影响对外部数据源的请求速率。

适用于自动语义类型检测的认可的格式

日期与时间
  • YYYY/MM/DD-HH:MM:SS
  • YYYY-MM-DD [HH:MM:SS[.uuuuuu]]
  • YYYY/MM/DD [HH:MM:SS[.uuuuuu]]
  • YYYYMMDD [HH:MM:SS[.uuuuuu]]
  • Sat, 24 May 2008 20:09:47 GMT
  • 2008-05-24T20:09:47Z
  • 时间:秒、微秒、毫秒和纳秒(新纪元时间)。
地理位置