使用地点数函数查询数据集

地点统计函数是在 BigQuery 中运行的预定义 SQL 查询，可作为直接查询数据集的补充。直接查询数据与使用函数之间的主要区别在于，函数不会强制执行最低计数阈值，而是强制执行最低搜索区域：

• 地点数据集查询只能返回 5 个及以上的计数，但对搜索区域的大小没有任何限制。
• 地点数量函数可以返回任何数量（包括 0），但会强制执行 40.0 米 x 40.0 米（1600 平方米）的最小搜索区域。函数还可以返回地点 ID，该 ID 可用于查找有关各个地点的信息。

如果您需要了解查询何时未返回任何结果，或者需要了解低于 5 的低地点数，则可能需要使用地点数函数。如果您需要获取各个地点的信息以抽查结果，此方法也很有用。

地点数量函数仅提供数量，因此如果您需要执行更复杂的查询（例如数据联接），或者获取其他数据洞见（例如一组地点的平均评分），请直接查询数据集。

支持的地点数函数和国家/地区

Places Insights 支持以下功能：

• PLACES_COUNT：返回包含地点数量的单行。
• PLACES_COUNT_PER_TYPE：返回一个 BigQuery 表，其中包含每种地点类型的地点数量。
• PLACES_COUNT_PER_GEO：返回每个地理位置的地点数量的 BigQuery 表。
• PLACES_COUNT_PER_H3：返回每个 H3 单元格的地点数量的 BigQuery 表。

除了地点数量之外，PLACES_COUNT_PER_TYPE、PLACES_COUNT_PER_GEO 和 PLACES_COUNT_PER_H3 函数还会针对响应的每个元素返回最多 250 个地点 ID。查看所有过滤参数。

地点 ID 可用于：

• Places API（新版）
• Geocoding API
• Places UI Kit

注意： 您可以访问自己有权访问的城市和国家/地区的“地点数量”函数。

使用函数编写查询

请使用以下格式调用函数：[project name (optional)].[table name].[function name]。

如果您在设置地点洞察时更改了关联数据集名称，请使用您的自定义名称，而不是在 BigQuery 中引用地点计数函数中列出的默认表名称。您还可以选择性地添加项目名称。如果未包含任何项目，则查询将默认为有效项目。

例如：

PROJECT_NAME.places_insights___us.PLACES_COUNT

使用 JSON_OBJECT 将实参传递给函数。

注意： 使用地点数量函数时，该函数在 FROM 子句中指定，并省略 WITH_AGGREGATION_THRESHOLD。

过滤结果

Places Count 函数支持多种过滤条件，可用于优化搜索。这些参数（例如 price_level 或 types）区分大小写，并且必须与参数名称完全一致。如需查看完整的选项列表，请参阅过滤条件参数参考。

在下一个示例中，您将应用过滤条件，按最低用户评分、价格水平、营业状态以及餐厅是否允许携带狗来限制搜索范围：

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;

注意： 请添加 business_status 过滤条件，以确保您获得 OPERATIONAL 个商家的数量。否则，该数量会包含已关闭的商家。

Places Count 函数示例

以下示例使用 PLACES_COUNT 函数返回纽约市帝国大厦 1,000 米范围内的营业餐厅数量：

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;

响应包含一个计数：

此示例使用 BigQuery ST_GEOGPOINT 函数从点返回 GEOGRAPHY 值，然后将该值传递给 geography 参数。它还会传递该点周围的搜索半径和要搜索的地点类型 "restaurant"。

注意： 每个 Places Count 函数的必需参数和可选参数各不相同，如过滤条件中所述。

按类型、地理位置或 H3 划分的地点数量示例

除了地点数量之外，PLACES_COUNT_PER_TYPE、PLACES_COUNT_PER_GEO 和 PLACES_COUNT_PER_H3 函数还会返回响应中包含的最多 250 个地点的地点 ID。

例如，PLACES_COUNT_PER_TYPE 函数会返回一个表格，其中包含每种地点类型的地点数量。响应中包含一个地点 ID 数组，其中列出了与每种类型匹配的地点。您可以使用返回的地点 ID 查找有关每个地点的信息。

以下函数调用会返回类型为 restaurant、cafe 和 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']
      )
);

此函数会返回一个包含三列的表：type、count 和 sample_place_ids。count 列显示每个 type 的地点数量，sample_place_ids 列显示每个 type 最多 250 个地点 ID。

注意： 如需获取有关某个地点的信息，请使用地点 ID 调用 Places API 或 Places UI 工具包。使用示例 Place ID 验证 Places Insights 数据中提供了一个示例。

直观呈现结果

分析和商业智能工具对于帮助您发现 BigQuery 数据中的数据洞见至关重要。BigQuery 支持多种 Google 和第三方数据可视化工具，您可以使用这些工具来分析 Places Insights 数据上函数的结果。

如需查看可视化函数结果的示例，请参阅可视化结果。 如需详细了解如何直观呈现 Places Insights 结果并查看相关示例，请参阅直观呈现查询结果。

限制和要求

Places Count 函数具有以下限制和要求：

• 仅支持 COUNT 类数据洞见。
• 搜索区域的最小面积为 40.0 米 x 40.0 米（1600 平方米）。
• 地点函数计数参数输入大小的上限为 1 MB。
• 不支持按地点 ID、品牌、电动汽车充电选项或地址组成部分进行过滤。
• 您只能访问已订阅的城市和国家/地区的“地点数量”函数。如需了解如何设置 Places Insights 以获取数据集访问权限，请参阅设置 Places Insights。
• 过滤参数（例如 geography 或 types）区分大小写，必须与参数名称完全一致，否则查询将失败。

参考 BigQuery 中的地点数函数

示例数据集中的所有城市以及完整数据集中的所有国家/地区都支持“地点数”函数。

您可以访问与您订阅的城市和国家/地区数据集对应的地点数量函数。如需了解数据集访问权限，请参阅设置 Places Insights。

注意： 如果您在设置地点概览时更改了关联数据集的名称，请使用您的自定义名称，而不是此处列出的默认表名称。您还可以选择性地添加项目名称。如果未包含任何项目，查询将默认为有效项目。

下表列出了可用的城市、国家/地区及其对应的表名称。

示例数据

国家/地区，城市	表名称
澳大利亚悉尼	places_insights___au___sample.FUNCTION_NAME
巴西圣保罗	places_insights___br___sample.FUNCTION_NAME
加拿大多伦多	places_insights___ca___sample.FUNCTION_NAME
法国巴黎	places_insights___fr___sample.FUNCTION_NAME
德国柏林	places_insights___de___sample.FUNCTION_NAME
印度孟买	places_insights___in___sample.FUNCTION_NAME
印度尼西亚雅加达	places_insights___id___sample.FUNCTION_NAME
意大利罗马	places_insights___it___sample.FUNCTION_NAME
日本东京	places_insights___jp___sample.FUNCTION_NAME
墨西哥的墨西哥城	places_insights___mx___sample.FUNCTION_NAME
西班牙马德里	places_insights___es___sample.FUNCTION_NAME
瑞士苏黎世	places_insights___ch___sample.FUNCTION_NAME
英国伦敦	places_insights___gb___sample.FUNCTION_NAME
美国纽约市	places_insights___us___sample.FUNCTION_NAME

完整数据

国家/地区	表名称
澳大利亚	places_insights___au.FUNCTION_NAME
巴西	places_insights___br.FUNCTION_NAME
加拿大	places_insights___ca.FUNCTION_NAME
法国	places_insights___fr.FUNCTION_NAME
德国	places_insights___de.FUNCTION_NAME
印度	places_insights___in.FUNCTION_NAME
印度尼西亚	places_insights___id.FUNCTION_NAME
意大利	places_insights___it.FUNCTION_NAME
日本	places_insights___jp.FUNCTION_NAME
墨西哥	places_insights___mx.FUNCTION_NAME
西班牙	places_insights___es.FUNCTION_NAME
瑞士	places_insights___ch.FUNCTION_NAME
英国	places_insights___gb.FUNCTION_NAME
美国	places_insights___us.FUNCTION_NAME