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 do Places 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 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 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 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 Google Places

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

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 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.

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 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.

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 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.

Observação: para receber informações sobre um lugar, use o ID do lugar 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 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 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.

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.

Observação: 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 não houver, a consulta vai usar o projeto ativo por padrão.

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

Dados de amostra

Cidade, país	Nomes de tabela
Sydney, Austrália	places_insights___au___sample.FUNCTION_NAME
São Paulo, Brasil	places_insights___br___sample.FUNCTION_NAME
Toronto, Canadá	places_insights___ca___sample.FUNCTION_NAME
Paris, França	places_insights___fr___sample.FUNCTION_NAME
Berlim, Alemanha	places_insights___de___sample.FUNCTION_NAME
Mumbai, Índia	places_insights___in___sample.FUNCTION_NAME
Jacarta, Indonésia	places_insights___id___sample.FUNCTION_NAME
Roma, Itália	places_insights___it___sample.FUNCTION_NAME
Tóquio, Japão	places_insights___jp___sample.FUNCTION_NAME
Cidade do México, México	places_insights___mx___sample.FUNCTION_NAME
Madri, Espanha	places_insights___es___sample.FUNCTION_NAME
Zurique, Suíça	places_insights___ch___sample.FUNCTION_NAME
Londres, Reino Unido	places_insights___gb___sample.FUNCTION_NAME
Nova York, Estados Unidos	places_insights___us___sample.FUNCTION_NAME

Dados completos

País	Nomes de tabela
Austrália	places_insights___au.FUNCTION_NAME
Brasil	places_insights___br.FUNCTION_NAME
Canadá	places_insights___ca.FUNCTION_NAME
França	places_insights___fr.FUNCTION_NAME
Alemanha	places_insights___de.FUNCTION_NAME
Índia	places_insights___in.FUNCTION_NAME
Indonésia	places_insights___id.FUNCTION_NAME
Itália	places_insights___it.FUNCTION_NAME
Japão	places_insights___jp.FUNCTION_NAME
México	places_insights___mx.FUNCTION_NAME
Espanha	places_insights___es.FUNCTION_NAME
Suíça	places_insights___ch.FUNCTION_NAME
Reino Unido	places_insights___gb.FUNCTION_NAME
Estados Unidos	places_insights___us.FUNCTION_NAME