الاستعلام عن التغييرات في نقاط الاهتمام بين الأشهر (PLACES_COUNT_CHANGE)

تحسب الدالة PLACES_COUNT_CHANGE التغييرات في أعداد "الأماكن المثيرة للاهتمام" وتستردّ نموذجًا لمعرّفات الأماكن التي تمّت إضافتها وإزالتها بين شهرَين محدّدَين في مناطق جغرافية متعدّدة.

على غرار الدالة PLACES_COUNT_V2، تم تصميم هذه الدالة لمعالجة الدُفعات بكفاءة من خلال قبول مَعلمة جدول الإدخال للمناطق الجغرافية، ما يسمح لك بتقييم مؤشرات النمو والتغييرات التجارية في العديد من المواقع الجغرافية في آنٍ واحد.

البنية

SELECT *
FROM
  `PROJECT_NAME.LINKED_DATASET_NAME.PLACES_COUNT_CHANGE`(
    TABLE input_geographies,
    filters
  );

المعلمات

  • PROJECT_NAME: اسم مشروع Google Cloud.
  • LINKED_DATASET_NAME: اسم مجموعة بيانات BigQuery التي تحتوي على دوال "إحصاءات الأماكن" (مثل places_insights___us).
  • input_geographies: جدول BigQuery يحتوي على المناطق الجغرافية المطلوب تحليلها. يجب أن يتضمّن هذا الجدول الأعمدة التالية:
    • geo_id (STRING): معرّف فريد لكل منطقة جغرافية.
    • geo (GEOGRAPHY): كائن BigQuery GEOGRAPHY الذي يمثّل المنطقة. يمكن أن يكون نقطة أو مضلّعًا أو نوعًا آخر من المناطق الجغرافية.
  • filters (JSON): كائن JSON يحتوي على أزواج مفتاح/قيمة لتصفية الأماكن. راجِع مَعلمات الفلتر. يجب أن يتضمّن الفلاتر التالية:
    • month1 (STRING): الشهر الأول الذي يتم البحث فيه عن الأماكن.
    • month2 (STRING): الشهر الثاني الذي يتم البحث فيه عن الأماكن.

مخطط الجدول الناتج

تعرض الدالة PLACES_COUNT_CHANGE جدولاً يتضمّن الأعمدة التالية:

اسم العمود نوع البيانات الوصف
geo_id STRING المعرّف من المنطقة الجغرافية المُدخَلة.
start_count INT64 عدد الأماكن من الشهر الأول.
end_count INT64 عدد الأماكن من الشهر الثاني.
net_change INT64 الفرق بين end_count وstart_count (end_count - start_count).
percentage_change FLOAT64 النسبة المئوية للتغيير من month1 إلى month2.
compound_monthly_growth_rate FLOAT64 معدّل النمو الشهري المركّب من month1 إلى month2.
added_count INT64 عدد معرّفات الأماكن النموذجية في sample_added_place_ids.
removed_count INT64 عدد معرّفات الأماكن النموذجية في sample_removed_place_ids.
sample_added_place_ids ‫ARRAY<سلسلة> قائمة بمعرّفات الأماكن النموذجية المتوفّرة في month2 ولكن غير المتوفّرة في month1.
sample_removed_place_ids ‫ARRAY<سلسلة> قائمة بمعرّفات الأماكن النموذجية المتوفّرة في month1 ولكن غير المتوفّرة في month2.

يتم ترتيب النتائج حسب percentage_change وstart_count بترتيب تنازلي.

آلية العمل

تعالج الدالة كل صف في جدول input_geographies. لكل geo كائن، تحسب الدالة عدد الأماكن التي تقع ضمن المنطقة الجغرافية (أو ضمن الـ geography_radius إذا كان الـ geo نقطة وتم تحديد نصف القطر في الـ filters) في الشهرَين المحدّدَين في month1 و month2 في الـ filters. باستخدام هذه الأماكن، تحسب الدالة إحصاءات مفيدة أخرى، مثل النسبة المئوية للتغيير ومعدّل النمو الشهري المركّب من الشهر الأول إلى الثاني.

لا يشمل العدد سوى الأماكن التي تستوفي جميع الشروط المحدّدة في كائن JSON filters.

مثال: حساب التغييرات في أعداد نقاط الاهتمام بين شهرَين

يوضّح هذا المثال كيفية طلب التغييرات في أعداد نقاط الاهتمام بين شهرَين محدّدَين باستخدام المَعلمتَين month1 وmonth2، مع نطاق جغرافي يبلغ 5000 من نقطة رصد الموقع الجغرافي معيّنة.

WITH my_locations AS (
  SELECT
    'loc_1' AS geo_id,
    ST_GEOGFROMTEXT('POINT(-122.4194 37.7749)') AS geo
  -- Add more target locations as needed...
)

SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_CHANGE`(
  TABLE my_locations,
  JSON_OBJECT(
    'geography_radius', 5000,
    'month1', '2026-01', -- Baseline snapshot month (YYYY-MM)
    'month2', '2026-02'  -- Comparison snapshot month (YYYY-MM)
  )
);

تحليل الناتج

يعرض الطلب جدولاً يتضمّن صفًا لكل منطقة جغرافية مُدخَلة.

  • مؤشرات النمو: يعرض الناتج العدد الأساسي (start_count: 89,560) وعدد المقارنة (end_count: 90,923)، ما يؤدي إلى net_change يبلغ +1,363 مكانًا (+1.52% percentage_change).
  • فحص البيانات الأساسية: تسردّ مصفوفة sample_added_place_ids معرّفات أماكن محدّدة أصبحت نشطة في month2 (فبراير 2026)، بينما تسردّ sample_removed_place_ids معرّفات الأماكن التي لم تعُد متوفّرة.
  • الربط بواجهة برمجة التطبيقات Places API: يمكنك تمرير معرّفات الأماكن النموذجية هذه مباشرةً إلى Place Details API (الجديدة) للبحث عن أسماء المتاجر وعناوينها وسماتها للأنشطة التجارية التي تم فتحها أو إغلاقها حديثًا.

نتائج الدالة Places Count Change