شروع به کار با «اطلاعات آماری مکان‌ها»

توابع «شمارش جاها» پُرسمان‌های SQL ازپیش تعریف‌شده‌ای هستند که در BigQuery اجرا می‌شوند و روش توصیه‌شده برای پُرسمان کردن مجموعه داده‌های «اطلاعات آماری جاها» برای بازیابی تعداد دقیق و شناسه‌های جا هستند. درحالی‌که می‌توانید مستقیماً از مجموعه داده‌ها پُرسمان کنید، دو روش پُرسمان آستانه‌های حریم خصوصی و مناطق جستجو را مدیریت می‌کنند:

  • عملکردهای «شمارش مکان‌ها» می‌توانند هر تعداد شمارشی را برگردانند، ازجمله ۰، اما حداقل منطقه جستجوی ۴۰٫۰ متر در ۴۰٫۰ متر (۱۶۰۰ متر۲) (۴۰٫۰ متر در ۴۰٫۰ متر / ۱۶۰۰ متر مربع) را اعمال می‌کنند. عملکردها همچنین شناسه‌های مکان را برمی‌گردانند که می‌توانند برای جستجوی اطلاعات درباره مکان‌های فردی استفاده شوند و از تحلیل تاریخی نقاط جالب در عکس‌های آنی ماهانه گذشته بااستفاده از فیلترهای تاریخ اختیاری پشتیبانی می‌کنند.

  • پُرسمان‌های مجموعه داده مکان فقط می‌توانند تعداد ۵ و بالاتر را برگردانند (تعدادهای کم ۰ تا ۴ برای حفظ حریم خصوصی تفاضلی حذف می‌شوند)، اما هیچ محدودیتی برای اندازه منطقه جستجو اعمال نمی‌کنند.

توصیه می‌کنیم با توابع Places Count مثل PLACES_COUNT_PER_H3 شروع کنید، مگراینکه لازم باشد تجزیه‌وتحلیل فضایی پیچیده‌ای انجام دهید. این ابزار اطلاعات آماری فوری درباره تراکم فضایی در سلول‌های شبکه‌ای استاندارد ارائه می‌دهد، «شناسه‌های مکان» را برای بازرسی واقعیت عینی برمی‌گرداند، و به‌طور خاص برای مهندسی ویژگی‌های جغرافیایی-فضایی و مدل‌های یادگیری ماشین ساخته شده است.

انتخاب تابع بهینه «تعداد مکان‌ها»

«اطلاعات آماری جاها» از چندین تابع فضایی پشتیبانی می‌کند. برای اجرای بهینه پُرسمان، پردازش موازی، و مقیاس‌پذیری دسته‌ای، توصیه می‌کنیم از توابع زیر استفاده کنید:

  • PLACES_COUNT_PER_H3: جدول BigQuery از تعداد مکان‌ها در هر سلول H3 را برمی‌گرداند. این تابع برای تحلیل تراکم منطقه‌ای و نقشه‌برداری حرارتی کروپلت توصیه می‌شود.
  • PLACES_COUNT_V2: جدولی حاوی تعداد مکان‌ها و نمونه «شناسه‌های مکان» برمی‌گرداند. این تابع یک پارامتر جدول حاوی جغرافیای ورودی شما را می‌پذیرد. با ارسال مستقیم کل جدول، موتور اجرای BigQuery می‌تواند حجم کاری را توزیع کند و تقاطع‌های فضایی را به‌طور موازی پردازش کند، که این امر پردازش دسته‌ای بسیار کارآمدی را برای تحلیل‌های مقیاس بزرگ ممکن می‌سازد.
  • PLACES_COUNT_PER_TYPE_V2: جدولی از تعداد مکان‌ها و نمونه شناسه‌های مکان را که براساس نوع مکان دسته‌بندی شده‌اند برمی‌گرداند. مشابه PLACES_COUNT_V2، ارسال جغرافیای ورودی شما به‌عنوان پارامتر جدول به BigQuery اجازه می‌دهد تا به‌طور بومی تقاطع‌های فضایی را در مجموعه‌های داده بزرگ موازی کند.
  • PLACES_COUNT_CHANGE: جدولی از تعداد مکان‌ها به‌علاوه «شناسه‌های مکان» اضافه‌شده و برداشته‌شده بین دو ماه مشخص را برمی‌گرداند. مشابه PLACES_COUNT_V2، ارسال جغرافیای ورودی شما به‌عنوان پارامتر جدول به BigQuery اجازه می‌دهد تا به‌طور بومی تقاطع‌های فضایی را در مجموعه‌های داده بزرگ موازی کند.

این توابع علاوه‌بر تعداد مکان‌ها، حداکثر ۲۵۰ شناسه مکان را نیز برای هر عنصر پاسخ برمی‌گردانند.

از «شناسه مکان» می‌توان در موارد زیر استفاده کرد:

اجرای پُرسمان‌ها با توابع «تعداد مکان‌ها»

از قالب زیر برای فراخوانی توابع استفاده کنید: [project name (optional)].[table name].[function name].

اگر نام مجموعه داده پیوندشده را هنگام راه‌اندازی «اطلاعات آماری جاها» تغییر داده‌اید، به‌جای نام‌های پیش‌فرض جدول، از نام سفارشی‌تان استفاده کنید. همچنین می‌توانید به‌صورت اختیاری نام پروژه‌تان را اضافه کنید. اگر پروژه‌ای اضافه نشده باشد، پُرسمان به‌طور پیش‌فرض به پروژه فعال اعمال می‌شود.

برای مثال:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

از JSON_OBJECT برای ارسال متغیرهای مستقل به تابع استفاده کنید.

فیلتر کردن نتایج پُرسمان بااستفاده از پارامترهای حساس به حروف بزرگ و کوچک

تابع‌های «تعداد مکان‌ها» از فیلترهای زیادی برای پالایش جستجو پشتیبانی می‌کنند. این پارامترها (برای مثال، price_level یا types) حروف‌حساس هستند و باید دقیقاً با نام پارامترها مطابقت داشته باشند. برای مشاهده فهرست کامل گزینه‌ها، مرجع پارامترهای فیلتر را ببینید.

پُرسمان کردن عکس‌های آنی تاریخی با snapshot_date

به‌طور پیش‌فرض، تابع‌های «شمارش مکان‌ها» جدیدترین عکس آنی داده‌های دردسترس را پُرسمان می‌کنند. برای تجزیه‌وتحلیل داده‌های مکان‌ها به‌صورتی که در ماه خاصی در گذشته وجود داشته است، پارامتر اختیاری snapshot_date را به JSON_OBJECT خود اضافه کنید.

  • قالب: YYYY-MM (برای مثال، '2026-07').
  • پیش‌فرض: اگر حذف شود، تابع به‌طور خودکار جدیدترین عکس آنی را جستجو می‌کند.

نمونه زیر تعداد رستوران‌های اطراف مناطق جستجوی شما را همان‌طور که در عکس آنی ژوئیه ۲۰۲۶ ثبت شده است پُرسمان می‌کند:

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"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

در مثال بعدی، بااستفاده از تابع PLACES_COUNT_V2، فیلترهایی را برای محدود کردن جستجو براساس حداقل رده‌بندی کاربر، سطح قیمت، وضعیت کسب‌وکار، و اینکه آیا رستوران ورود سگ را مجاز می‌داند یا نه اعمال می‌کنید.

ابتدا، از جدول جغرافیای ورودی‌تان استفاده کنید یا جدولی با جغرافیای انتخاب‌شده آماده کنید:

-- 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
);

سپس، PLACES_COUNT_V2 را با جدول و شیء JSON حاوی فیلترها فراخوانی کنید. شعاع جستجو در فیلترهای JSON گنجانده شده است و در اطراف هر نقطه در جدول 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
      )
);

مثال: تعداد رستوران‌ها و مکان‌های نمانام را با PLACES_COUNT_V2 پُرسمان کنید

مثال زیر از تابع PLACES_COUNT_V2 با جدول جغرافیایی ورودی سفارشی 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
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'snapshot_date', '2026-07'
      )
);

پاسخ یک جدول BigQuery است که حاوی geo_id، جغرافیا، تعداد، و نمونه‌ای از «شناسه‌های مکان» است.

نتایج تابع «تعداد مکان‌ها» در شهر نیویورک.

مثال زیر از تابع PLACES_COUNT_V2 برای فیلتر کردن براساس شناسه‌های نمانام خاص استفاده می‌کند. در این مثال، مکان‌های Starbucks را بااستفاده از شناسه نمانام "1413758728321880760" فیلتر می‌کنیم.

برای پیدا کردن شناسه نمانام برای نمانام‌هایی که می‌خواهید براساس آن‌ها فیلتر کنید، جدول brands را برای مجموعه‌داده‌تان پُرسمان کنید (برای مثال، places_insights___us.brands). برای اطلاعات بیشتر درباره مجموعه‌داده نمانام‌ها، به نوشتن پُرسمان بااستفاده از داده‌های نمانام‌ها مراجعه کنید.

برای مثال، برای پیدا کردن شناسه نمانام «استارباکس»:

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

پس‌از دریافت شناسه‌های نمانام، می‌توانید از آن‌ها در فیلتر brand_ids استفاده کنید، همان‌طور که در پُرسمان زیر نشان داده شده است:

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'],
      'brand_ids', ["1413758728321880760"]
      )
);

تجسم خروجی پُرسمان با ابزارهای Google Cloud

ابزارهای تجزیه‌وتحلیل و هوش تجاری به شما کمک می‌کنند تا اطلاعات آماری را از داده‌های BigQuery خود کشف کنید. BigQuery از چندین ابزار تجسم داده Google و طرف ثالث پشتیبانی می‌کند که می‌توانید از آن‌ها برای تجزیه‌وتحلیل نتایج توابع خود در داده‌های «اطلاعات آماری جاها» استفاده کنید.

برای دیدن نمونه‌ای از تجسم نتایج یک تابع، به تجسم نتایج در مرجع PLACES_COUNT_PER_H3 مراجعه کنید. برای اطلاعات بیشتر درباره تجسم نتایج «اطلاعات آماری جاها»، به تجسم نتایج پُرسمان مراجعه کنید.

محدودیت‌ها و الزامات عملکرد

توابع «تعداد مکان‌ها» محدودیت‌ها و الزامات زیر را دارند:

  • این عملکردها فقط از اطلاعات آماری COUNT پشتیبانی می‌کنند.
  • حداقل منطقه جستجوی ۴۰٫۰ متر در ۴۰٫۰ متر (۱۶۰۰ متر۲) (۴۰٫۰ متر در ۴۰٫۰ متر / ۱۶۰۰ متر مربع) لازم است.
  • حد مجاز اندازه ورودی پارامتر: شیء JSON که به‌عنوان پارامتر به توابع ارسال می‌شود به ۱ مگابایت محدود است. تأثیر این محدودیت به نسخه تابع بستگی دارد:
    • برای توابع V2 (PLACES_COUNT_V2،‏ PLACES_COUNT_PER_TYPE_V2،‏ PLACES_COUNT_CHANGE)، این محدودیت فقط برای شیء JSON فیلترها اعمال می‌شود. ازآنجایی‌که مناطق جغرافیایی به‌طور جداگانه بااستفاده از پارامتر جدول ارائه می‌شوند، این توابع می‌توانند به تعداد بسیار بیشتری از مناطق جغرافیایی ورودی مقیاس‌بندی شوند بدون اینکه به حد مجاز اندازه JSON برسند.
    • برای PLACES_COUNT_PER_H3، PLACES_COUNT، PLACES_COUNT_PER_TYPE، و PLACES_COUNT_PER_GEO، این محدودیت برای کل شیء JSON، ازجمله همه تعاریف جغرافیایی، اعمال می‌شود. این امر ممکن است تعداد جغرافیاهایی را که می‌توانند در یک تماس پردازش شوند محدود کند.
  • فیلتر کردن براساس شناسه مکان یا مؤلفه نشانی پشتیبانی نمی‌شود.
  • فقط می‌توانید به عملکردهای «تعداد مکان‌ها» برای شهرها و کشورهایی که در آن‌ها مشترک شده‌اید دسترسی داشته باشید. برای دسترسی به مجموعه داده، راه‌اندازی اطلاعات آماری جاها را ببینید.
  • پارامترهای فیلتر (برای مثال، geography یا types) به حروف بزرگ و کوچک حساس هستند و باید دقیقاً با نام پارامترها مطابقت داشته باشند، درغیراین‌صورت پُرسمان ناموفق خواهد بود.