Tipos de dados e tipos semânticos

Quando você cria um conector da comunidade, cada campo definido no esquema requer um tipo de dados. O tipo dos dados define o tipo primitivo do campo, por exemplo, BOOLEAN, STRING, NUMBER etc.

Além dos tipos de dados, o Data Studio também utiliza os tipos semânticos. Os tipos semânticos ajudam a descrever o tipo de informação que os dados representam. Por exemplo, um campo com um tipo de dados NUMBER pode representar semanticamente uma quantidade ou porcentagem de moeda. Além disso, um campo com tipo de dados STRING pode representar semanticamente uma cidade. Para ver os tipos semânticos disponíveis, consulte a documentação sobre tipos semânticos.

Esquema do conector da comunidade e campos do Data Studio

Quando você define o esquema para seu conector da comunidade, há várias propriedades que determinarão a forma como cada campo será representado e usado no Data Studio. Exemplo:

  • O conceptType é definido no esquema do conector por meio da propriedade conceptType. Essa propriedade determina se o campo será tratado como uma dimensão ou métrica. Veja uma explicação sobre a diferença entre métricas e dimensões no artigo relacionado.
  • O tipo semântico pode ser definido no esquema do conector ou detectado automaticamente pelo Data Studio com base na propriedade de tipo de dados definida no conector e nos valores de dados retornados pelo seu conector. Consulte a seção Detecção automática do tipo semântico para ver detalhes sobre isso.
  • O tipo de agregação determina se é possível agregar novamente os valores de métrica (as dimensões são ignoradas). Definir a propriedade semantics.isReaggregatable como true estabelecerá a agregação SUM como padrão. Caso contrário, ela será definida Auto. Você também pode configurar manualmente o tipo de agregação padrão para os campos reagregáveis usando a propriedade defaultAggregationType.

Quando você configura um conector no Data Studio e o utiliza para se conectar, o editor de campos exibe o esquema completo para o conector com base na maneira como você definiu as propriedades acima. Se você incluiu os tipos semânticos, eles serão exibidos da maneira como você os definiu. Se estiver usando a detecção automática do tipo semântico, os campos serão exibidos conforme foram detectados. Fields Screen

Definir informações semânticas

Há duas maneiras de definir informações semânticas. Você pode definir a semântica de campo manualmente ou deixar que o Data Studio a detecte de maneira automática.

Por exemplo, se houver um número que represente semanticamente dólares americanos, o Data Studio não detectará esse tipo semântico de maneira automática. Além disso, a detecção automática da semântica requer que o Data Studio faça chamadas de busca de dados para cada campo do seu esquema. Se você especificar o esquema manualmente, nenhuma chamada de busca de dados será feita. Se você souber o tipo semântico (por exemplo, moeda, porcentagem, data etc.) dos seus dados, recomendamos que o configure no esquema para melhorar a precisão e o desempenho.

Definir tipos semânticos manualmente (recomendado)

Se souber seus tipos semânticos, você poderá definir manualmente semantics para cada campo do esquema. Veja todos os detalhes sobre as propriedades disponíveis para você na página de referência do campo. Se optar por definir manualmente os tipos semânticos, é recomendável que você defina semanticType e semanticGroup para cada campo. Ao fazer isso, o processo de detecção automática do tipo semântico não será executado. Se você definir manualmente alguns dos seus campos, mas não todos, aqueles que você não especificar serão definidos por padrão como Text, Number ou Boolean, dependendo do dataType especificado para o campo.

Veja a seguir o exemplo de um esquema simples que define os tipos semânticos manualmente. Income é definido como a moeda, e Filing Year como a data.

data-studio/semantics.gs
Ver no GitHub (em inglês) 
 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'
        }
      }
    ];

Solucionar problemas dos tipos semânticos manuais

Se você definir seus tipos semânticos para os dados subjacentes de maneira incorreta, eles não funcionarão adequadamente. Isso é difícil de testar, mas há algumas coisas que você pode fazer para ajudar a encontrar problemas.

  1. Retorne duas ou três linhas dos seus dados em vez de tudo, e o inspecione manualmente.
  2. Faça uma tabela no Data Studio que use apenas o campo que está tentando verificar.
  3. Preste muita atenção aos campos Geo e Date, porque eles têm o formato mais rigoroso.

Detecção automática do tipo semântico

Se você não definiu nenhum tipo semântico no seu esquema, o Data Studio tentará detectá-lo automaticamente com base na propriedade do tipo de dados e no formato dos valores de informações retornados pelo seu conector.

Estas são as etapas do processo de detecção automática:

  1. Solicite o esquema executando a função getSchema do seu conector da comunidade.
  2. Itere por meio de lotes de campos definidos no esquema do conector e envie solicitações getData para os campos. As solicitações getData são executadas com o parâmetro sampleExtraction definido como true para indicar que as solicitações de dados são para fins de detecção semântica.
  3. Com base no tipo de dados de campo e no formato do valor retornado da solicitação getData, identifique o tipo semântico do campo.

Opções de tratamento da detecção automática de tipo semântico

Quando o Data Studio executa a função getData de um conector da comunidade para realizar a detecção semântica, a solicitação de entrada conterá uma propriedade sampleExtraction que será definida como true. Os dados retornados pelo seu conector são usados apenas pelo Data Studio para identificar o tipo semântico do campo. Como o valor não será usado para nenhum outro propósito, não são necessários dados reais da sua fonte externa.

Há várias maneiras de melhorar a detecção do tipo semântico no seu código:

  • Recomendado: transfira valores predefinidos
    Retornar um valor predefinido para cada campo que melhor representa o tipo semântico para o campo e é conhecido por ser devidamente detectado pelo Data Studio. Por exemplo: se o tipo semântico de um campo for País, um valor como IT será retornado para "Itália". Outra vantagem desta abordagem é que ela é muito mais rápida. Com ela, não é necessário fazer solicitações HTTP para o serviço de terceiros para receber dados.

  • Somente retorne n registros
    Se o serviço de terceiros do qual você recebe dados for compatível com os limites de linha ao solicitar dados, retorne um pequeno subconjunto de linhas para o Data Studio em vez do conjunto de dados completo. Isso limitará a quantidade de dados que você precisa transmitir para o Data Studio para cada solicitação de detecção semântica.

  • Solicite todas as colunas e armazene a resposta em cache
    Se for possível solicitar todas as colunas para o serviço de terceiros do qual você recebe dados, na primeira solicitação de detecção semântica recebida do Data Studio procure todas as colunas e armazene os resultados em cache. Para as solicitações de detecção semântica subsequentes, busque valores de coluna do cache em vez de fazer solicitações HTTP adicionais para o serviço de terceiros.

  • Não faça nada diferente
    Você pode optar por não implementar nenhuma acomodação específica para solicitações em que sampleExtraction é definido como true. Isso fará com que o processo de detecção semântica seja mais lento, porque o Data Studio terá que buscar todos os dados para o processo. Além disso, a taxa de solicitação será afetada para sua fonte de dados externa, já que muitas solicitações de detecção semântica serão executadas em paralelo.

Formatos reconhecidos para detecção automática do tipo semântico

Data e hora
  • 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
  • Hora: época por segundos, microssegundos, milissegundos e nanossegundos.
Geográfico