Типы данных и семантические типы

При создании коннектора независимых разработчиков для каждого поля, которое вы определяете в схеме, необходимо указывать тип данных. Тип данных определяет примитивный тип поля, такой как BOOLEAN, STRING, NUMBER и т. п.

Кроме типов данных, Студия данных использует семантические типы для описания типа информации, которую предоставляют данные. Например, поле с типом данных NUMBER семантически представляет денежную сумму или процент, а поле с типом данных STRING может семантически представлять город. Чтобы узнать о доступных семантических типах, см. документацию по семантическим типам.

Схема коннектора независимых разработчиков и поля Студии данных

При определении схемы коннектора независимых разработчиков существуют разные параметры для каждого поля, которые определяют способ представления и использования этого поля в Центре данных. Пример:

  • Тип параметра или показателя определяется в схеме коннектора с помощью свойства conceptType, которое определяет, является ли значение поля параметром или показателем. Описание различий между параметрами и показателями можно найти в этой статье.
  • Семантический тип может быть задан в схеме коннектора или определен Студией данных автоматически – по заданному в коннекторе свойству DataType и значениям, которые он возвращает. Подробную информацию об этом можно найти в разделе Автоматическое определение семантического типа.
  • Тип агрегирования определяет, могут ли значения показателей быть агрегированы повторно (к значениям параметров это свойство неприменимо). Если свойству 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 (они имеют наиболее строгий формат).

Автоматическое определение семантического типа

Если вы не задали семантические типы в своей схеме, Студия данных попробует автоматически определить их с помощью свойства DataType, а также по формату возвращаемых коннектором значений.

Автоматическое определение происходит следующим образом:

  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
  • Время в секундах, микро-, милли- и наносекундах с начала отсчета.
Геоданные