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 Places se for importante saber quando uma consulta não retorna resultados ou se você precisar saber contagens baixas de Places 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 fazer 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 Insights de Lugares é compatível com as seguintes funções:

• PLACES_COUNT: retorna uma única linha que contém 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 contagens 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 Places

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 Insights de Lugares, use seu nome personalizado em vez dos nomes de tabela padrão listados em Funções de contagem de lugares de referência no BigQuery. Se quiser, inclua 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.

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;

Exemplo da função "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.

Exemplo de contagem de lugares por tipo, região geográfica 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 de 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.

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 Insights de Lugares.

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 Insights de Lugares, consulte Visualizar resultados de consultas.

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 Insights de Lugares 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.

Funções de contagem de lugares de referência no BigQuery

Todas as cidades no conjunto de dados de amostra e o conjunto de dados completo de países são compatíveis com as funções de contagem de lugares.

Você tem acesso às funções de contagem de lugares correspondentes aos conjuntos de dados de cidades e países a que se inscreveu. Consulte Configurar o Places Insights para acesso ao conjunto de dados.

Essas tabelas listam as cidades e os países disponíveis, além dos nomes das tabelas correspondentes.

Dados de amostra

Dados completos