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

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

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

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

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

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

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

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

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

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

• Places API (New)
• Geocoding API
• کیت میانای کاربر «جاها»

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

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

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

برای مثال:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

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

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

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

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

به‌طور پیش‌فرض، توابع Places Count جدیدترین عکس آنی داده‌های دردسترس را پُرسمان می‌کنند. برای تجزیه‌وتحلیل داده‌های مکان‌ها به‌صورتی که در یک ماه خاص در گذشته وجود داشته است، پارامتر اختیاری 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) به حروف بزرگ و کوچک حساس هستند و باید دقیقاً با نام پارامترها مطابقت داشته باشند، درغیراین‌صورت پُرسمان ناموفق خواهد بود.