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

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

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

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

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

• Тип понятия задается в схеме коннектора с помощью свойства conceptType, которое определяет, является ли значение поля параметром или показателем. Описание различий между параметрами и показателями можно найти в этой статье.
• Семантический тип может быть задан в схеме коннектора или определен Студией данных автоматически – по заданному в коннекторе свойству тип данных и значениям, которые возвращает коннектор. Подробную информацию об этом можно найти в разделе Автоматическое определение семантических типов.
• Тип агрегирования определяет, могут ли значения показателей быть агрегированы повторно (к значениям параметров это свойство неприменимо). Если свойству semantics.isReaggregatable присвоить значение true, то по умолчанию будет использоваться метод агрегации SUM. В противном случае используется тип Auto. Кроме того, для полей с возможностью агрегирования данных вы можете задать тип агрегирования по умолчанию с помощью свойства defaultAggregationType.

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

Примечание. Свойства схемы, определенные в вашем коннекторе с открытым кодом, применяются в качестве настроек по умолчанию для создаваемых пользователями источников данных. Пользователи могут переопределять любые свойства, кроме типа агрегирования, если для него задано значение Auto.

Настройка семантической информации

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

Например, если есть числовое поле, которое семантически представляет значение в долларах США, Студия данных не сможет автоматически определить этот семантический тип. Кроме того, для автоматического определения семантического типа Студия данных должна выполнить запросы на извлечение данных для каждого поля схемы. Если схема определена вручную, запросы на извлечение данных не выполняются. Если вы знаете семантический тип данных (валюта, процентное значение, дата и т. п.), рекомендуется явным образом задавать его в схеме для повышения точности и эффективности.

Настройка семантических типов вручную (рекомендуется)

Если семантические типы известны, можно определить объект semantics вручную для каждого поля схемы. Подробную информацию о доступных свойствах можно найти на странице справки по полям. При определении семантических типов вручную рекомендуется определять semanticType и semanticGroup для каждого поля. Если эти свойства заданы вручную, процесс автоматического определения семантических типов не запускается. Если вручную определены не все поля, то оставшиеся по умолчанию будут определены как Text, Number или Boolean в зависимости от типа dataType, определенного для поля.

Далее представлен пример простой схемы, в которой вручную задаются семантические типы. В этом примере для поля Income задан семантический тип "валюта", а для поля Filing Year – "дата".

data-studio/semantics.gs

Посмотреть на GitHub

 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, так как они имеют наиболее строгий формат.

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

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

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

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

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

География

• Название или код континента
• Название или код субконтинента
• Название или код региона
• Название и код страны. См. также ISO_3166-1.
• Название города
• Географическая широта и долгота, разделенные запятой
• Название и код медиарынка (DMA)