数据类型和语义类型

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

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

社区连接器架构和数据洞察字段

您在为社区连接器定义架构时，会发现系统为每个字段提供了各种不同的属性，这些属性将决定字段在数据洞察中的表示和使用方式。例如：

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

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

设置语义信息

设置语义信息的方式有两种。您可以手动设置字段语义，也可以依靠数据洞察自动检测。

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

手动设置语义类型（推荐）

如果您知道自己的语义类型，则可以手动为每个架构字段定义 semantics。如需了解可用属性的完整详细信息，请访问字段参考页面。如果您选择定义手动语义类型，建议您为每个字段定义 semanticType 和 semanticGroup。手动提供这些属性时，系统不会运行自动语义类型检测流程。如果您手动为部分字段（而非全部字段）设置语义类型，则您未指定的字段的语义类型默认为 Text、Number 或 Boolean，具体取决于为字段指定的 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. 在数据洞察中制作表格，仅在其中纳入您尝试检查的字段。
  3. 密切留意 Geo 和 Date 字段，因为它们的格式最为严格。

自动语义类型检测

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

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

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

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

数据洞察出于语义检测的目的执行社区连接器的 getData 函数时，传入请求中会包含一个 sampleExtraction 属性，该属性应设为 true。连接器返回的数据仅由数据洞察用于确定字段的语义类型。由于该值不用于任何其他用途，因此不需要来自外部来源的实际数据。

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

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

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

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

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

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

日期与时间
  • 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
  • 时间：秒、微秒、毫秒和纳秒（新纪元时间）。
地理位置