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:

• science PLACES_COUNT_V2: retorna uma tabela com contagens de lugares e exemplos de IDs de lugar. Essa função aceita um parâmetro de tabela para entrada de várias regiões geográficas, permitindo o processamento em lote eficiente. Ele é altamente otimizado para junções geoespaciais em comparação com as funções PLACES_COUNT e PLACES_COUNT_PER_GEO.
• science PLACES_COUNT_PER_TYPE_V2: retorna uma tabela de contagens de lugares e exemplos de IDs de lugares, categorizados por tipo de lugar. Assim como PLACES_COUNT_V2, essa função aceita um parâmetro de tabela para processar várias regiões de entrada simultaneamente. Essa arquitetura oferece suporte ao processamento em lote eficiente e fornece junção geoespacial otimizada em comparação com PLACES_COUNT_PER_TYPE.
• PLACES_COUNT_PER_H3: retorna uma tabela do BigQuery com contagens de lugares por célula H3.
• 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.

Além das contagens de lugares, todas as funções, exceto PLACES_COUNT, também retornam até 250 IDs de lugar por elemento da resposta.

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 próximo exemplo, 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, usando a função PLACES_COUNT_V2.

Primeiro, use sua tabela de geografia de entrada ou prepare uma com as regiões escolhidas:

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

Em seguida, chame PLACES_COUNT_V2 com a tabela e o objeto JSON que contém os filtros. O raio de pesquisa é incluído nos filtros JSON e aplicado em torno de cada ponto na tabela my_search_areas.

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

Exemplo da função "Contagem de lugares"

O exemplo a seguir usa a função PLACES_COUNT_V2 com a tabela geográfica de entrada personalizada my_search_area para retornar o número de restaurantes operacionais em um raio de 1.000 metros do Empire State Building e da Times Square em Nova York:

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"]
      )
);

A resposta é uma tabela do BigQuery que contém o geo_id, a geografia, a contagem e uma amostra de IDs de lugar.

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²).
• Limite de tamanho da entrada de parâmetro:o objeto JSON transmitido como parâmetro para as funções é limitado a 1 MB. O impacto desse limite depende da versão da função:
• Para funções da V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2), esse limite se aplica apenas ao objeto JSON de filtros. Como as regiões geográficas são fornecidas separadamente usando um parâmetro de tabela, essas funções podem ser escalonadas para um número muito maior de regiões geográficas de entrada sem atingir o limite de tamanho do JSON.
  • Para PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE e PLACES_COUNT_PER_GEO, esse limite se aplica a todo o objeto JSON, incluindo todas as definições de geografia. Isso pode limitar o número de regiões geográficas que podem ser processadas em uma única chamada.
• 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