Consultar o conjunto de dados usando funções de contagem de lugares

As funções de contagem de lugares são consultas SQL predefinidas que são executadas no BigQuery e complementam a consulta direta do conjunto de dados. A principal diferença entre consultar os dados diretamente e usar uma função é que as funções não exigem um limite mínimo de contagem, mas sim uma área mínima de pesquisa:

• As consultas de conjuntos de dados de lugares só podem retornar contagens de 5 ou mais, mas não impõem limitações ao tamanho da área de pesquisa.
• As funções de contagem de lugares podem retornar qualquer contagem, incluindo 0, mas exigem uma área de pesquisa mínima de 40,0 metros por 40,0 metros (1.600 m²). As funções também podem retornar IDs de lugar, que podem ser usados para pesquisar informações sobre lugares individuais.

Use as funções de contagem de lugares se for importante saber quando uma consulta não retorna resultados ou se você precisar saber contagens baixas de lugares abaixo de 5. Também é útil se você precisar de informações individuais sobre lugares para verificar seus resultados.

As funções de contagem de lugares só fornecem contagens. Portanto, se você precisar realizar consultas mais complexas, como junções de dados, ou receber insights adicionais, como a classificação média de um grupo de lugares, consulte o conjunto de dados diretamente.

Funções e países compatíveis com a contagem de lugares

O Places Insights é compatível com as seguintes funções:

• PLACES_COUNT: retorna uma única linha contendo uma contagem de lugares.
• PLACES_COUNT_PER_TYPE: retorna uma tabela do BigQuery com a contagem de lugares por tipo.
• PLACES_COUNT_PER_GEO: retorna uma tabela do BigQuery com contagens de lugares por região geográfica.
• PLACES_COUNT_PER_H3: retorna uma tabela do BigQuery com a contagem de lugares por célula H3.

Além das contagens de lugares, as funções PLACES_COUNT_PER_TYPE, PLACES_COUNT_PER_GEO e PLACES_COUNT_PER_H3 também retornam até 250 IDs de lugar por elemento da resposta. Confira todos os parâmetros de filtro.

Os IDs de lugar podem ser usados com:

• API Places (nova)
• API Geocoding
• Kit de interface do Google Places

Observação: é possível acessar as funções de contagem de lugares para as mesmas cidades e países em que você tem

Escrever consultas com funções

Use o seguinte formato para chamar as funções: [project name (optional)].[table name].[function name].

Se você mudou o nome do conjunto de dados vinculado ao configurar o Places Insights, use seu nome personalizado em vez dos nomes de tabela padrão listados aqui. Você também pode incluir o nome do projeto. Se um não for incluído, a consulta será padronizada para o projeto ativo.

Exemplo:

PROJECT_NAME.places_insights___us.PLACES_COUNT

Use um JSON_OBJECT para transmitir argumentos à função.

Observação: quando você usa uma função de contagem de lugares, ela é especificada na cláusula FROM e WITH_AGGREGATION_THRESHOLD é omitido.

Filtrar os resultados

As funções de contagem de lugares oferecem suporte a muitos filtros para refinar sua pesquisa. Esses parâmetros (por exemplo, price_level ou types) diferenciam maiúsculas de minúsculas e precisam corresponder exatamente aos nomes dos parâmetros. Consulte a referência de parâmetros de filtro para ver uma lista completa de opções.

No exemplo a seguir, você aplica filtros para limitar a pesquisa por classificação mínima do usuário, nível de preço, status da empresa e se o restaurante aceita cachorros:

SELECT `PROJECT_NAME.places_insights___us.PLACES_COUNT`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
) as count;

Observação: inclua o filtro business_status para garantir que você receba a contagem de empresas OPERATIONAL. Caso contrário, a contagem inclui empresas fechadas.

Exemplo de função de contagem de lugares

O exemplo a seguir usa a função PLACES_COUNT para retornar o número de restaurantes em funcionamento em um raio de 1.000 metros do Empire State Building em Nova York:

SELECT `PROJECT_NAME.places_insights___us.PLACES_COUNT`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"]
      )
) as count;

A resposta contém uma única contagem:

Este exemplo usa a função ST_GEOGPOINT do BigQuery para retornar um valor GEOGRAPHY de um ponto e transmitir esse valor ao parâmetro geography. Ele também transmite o raio de pesquisa ao redor do ponto e o tipo de lugar, "restaurant", a ser pesquisado.

Observação: os parâmetros obrigatórios e opcionais variam de acordo com cada função de contagem de lugares, conforme descrito em filtros.

Exemplo de contagem de lugares por tipo, região ou H3

Além das contagens de lugares, as funções PLACES_COUNT_PER_TYPE, PLACES_COUNT_PER_GEO e PLACES_COUNT_PER_H3 também retornam até 250 IDs dos lugares incluídos na resposta.

Por exemplo, a função PLACES_COUNT_PER_TYPE retorna uma tabela de contagens de lugares por tipo de lugar. A resposta inclui uma matriz de IDs de lugar para os lugares que correspondem a cada tipo. Você pode usar os IDs de lugar retornados para pesquisar informações sobre cada lugar.

A chamada de função a seguir retorna uma contagem de lugares com os tipos: restaurant, cafe e bar:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_TYPE`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'types', ["restaurant", "cafe", "bar"],
      'business_status', ['OPERATIONAL']
      )
);

Essa função retorna uma tabela com três colunas: type, count e sample_place_ids. As colunas count mostram a contagem de lugares para cada type, e a coluna sample_place_ids mostra até 250 IDs de lugar para cada type.

Observação: para receber informações sobre um lugar, use o ID para chamar a API Places ou o kit de interface do usuário Places. Validar dados do Places Insights usando exemplos de IDs de lugar mostra um exemplo.

Visualizar resultados

As ferramentas de análise e Business Intelligence são cruciais para ajudar você a descobrir insights dos seus dados do BigQuery. O BigQuery é compatível com várias ferramentas de visualização de dados do Google e de terceiros que podem ser usadas para analisar os resultados das suas funções nos dados do Places Insights.

Para um exemplo de como visualizar os resultados de uma função, consulte Visualizar resultados. Para mais informações e um exemplo de como visualizar os resultados do Places Insights, consulte Visualizar resultados da consulta.

Limitações e requisitos

As funções de contagem de lugares têm as seguintes limitações e requisitos:

• Há suporte apenas para insights COUNT.
• É necessário ter uma área de pesquisa mínima de 40,0 metros por 40,0 metros (1.600 m²).
• O tamanho da entrada do parâmetro de contagem da função de lugar é limitado a 1 MB.
• Não é possível filtrar por ID do lugar, marcas, opções de recarga de VE ou componente de endereço.
• Só é possível acessar as funções de contagem de lugares das cidades e países a que você se inscreveu. Consulte Configurar o Places Insights para acesso ao conjunto de dados.
• Os parâmetros de filtro (por exemplo, geography ou types) diferenciam maiúsculas de minúsculas e precisam corresponder exatamente aos nomes dos parâmetros. Caso contrário, a consulta vai falhar.