طلب عدد نقاط الاهتمام حسب نوع المكان

تعرض الدالة PLACES_COUNT_PER_TYPE_V2 جدول BigQuery يحتوي على أعداد الأماكن وعيّنات من أرقام تعريف الأماكن، مقسّمة حسب نوع المكان، لمناطق جغرافية متعدّدة. تم تصميم هذه الدالة لتوفير معالجة فعّالة على دفعات من خلال قبول مَعلمة جدول إدخال للمناطق الجغرافية. يمكنك تقديم المواقع الجغرافية من خلال جدول إدخال وتحديد أنواع الأماكن كمصفوفة.

البنية

SELECT * FROM `PROJECT_NAME.LINKED_DATASET_NAME.PLACES_COUNT_PER_TYPE_V2`(
  TABLE input_geographies,
  target_types,
  filters
)

المعلمات

• ‫PROJECT_NAME: اسم مشروعك على Google Cloud
• ‫LINKED_DATASET_NAME: اسم مجموعة بيانات BigQuery التي تحتوي على دوال إحصاءات الأماكن (مثلاً، places_insights___us).
• ‫input_geographies: جدول BigQuery يحتوي على المناطق الجغرافية المطلوب تحليلها. يجب أن يتضمّن هذا الجدول الأعمدة التالية:
  • ‫geo_id (STRING): معرّف فريد لكل منطقة جغرافية
  • ‫geo (GEOGRAPHY): عنصر GEOGRAPHY في BigQuery الذي يمثّل المنطقة. ويمكن أن يكون نقطة أو مضلّعًا أو نوعًا جغرافيًا آخر.
• ‫target_types (ARRAY<STRING>): مصفوفة من سلاسل أنواع الأماكن التي تريد الحصول على أعدادها. سيتم احتساب الأماكن إذا كانت تتطابق مع أي من الأنواع المدرَجة في مصفوفة types، وليس فقط primary_type.
• ‫filters (JSON): عنصر JSON يحتوي على أزواج مفتاح/قيمة لفلترة الأماكن بشكل إضافي. يُرجى الاطّلاع على مَعلمات الفلتر.

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

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

اسم العَمود	نوع البيانات	الوصف
geo_id	STRING	المعرّف الفريد للمنطقة الجغرافية المُدخلة، من جدول input_geographies
input_geography	GEOGRAPHY	كائن GEOGRAPHY الأصلي من جدول input_geographies
place_type	STRING	نوع المكان من مصفوفة target_types التي يمثّلها هذا الصف
place_count	INTEGER	عدد الأماكن التي تتطابق مع place_type والفلاتر الأخرى داخل المنطقة الجغرافية أو بالقرب منها
sample_place_ids	ARRAY<STRING>	مصفوفة تضم ما يصل إلى 250 رقم تعريف مكان يتطابق مع معايير هذا النوع والموقع الجغرافي.

ستحتوي النتيجة على صف لكل مجموعة من geo_id وplace_type المحدّدة في مصفوفة target_types، حتى إذا كان العدد صفرًا.

آلية العمل

تعالج الدالة كل منطقة جغرافية مقدَّمة في جدول input_geographies. بالنسبة إلى كل منطقة جغرافية، يتم احتساب الأماكن التي تتطابق مع أي من الأنواع المدرَجة في مصفوفة target_types وتستوفي أيضًا جميع الشروط في عنصر JSON‏ filters. يتم تجميع النتائج وتقسيمها حسب كل geo_id وكل نوع في target_types.

مثال: حساب أنواع مختلفة من المطاعم في مقاطعات مدينة نيويورك

ينشئ هذا المثال جدولاً للأعداد لأنواع "مطعم" و"مقهى" و "بار" في ثلاث مقاطعات في مدينة نيويورك.

SELECT geo_id, input_geography, place_type, place_count
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_TYPE_V2`(
  (
    SELECT county_name AS geo_id,
           ST_SIMPLIFY(county_geom, 100) AS geo
    FROM
      `bigquery-public-data.geo_us_boundaries.counties`
    WHERE
      state_fips_code = "36"  -- New York State
      AND county_name IN ("Queens", "Kings", "New York")
  ),
  ['restaurant', 'cafe', 'bar'],  -- target_types
  JSON_OBJECT(
      'business_status', ['OPERATIONAL']
  )
);

ستكون النتيجة جدولاً يتضمّن 9 صفوف (3 مقاطعات * 3 أنواع). سيعرض كل صف عدد مؤسسات "المطاعم" أو "المقاهي" أو "الحانات" في كل مقاطعة. يمكنك أيضًا تضمين نماذج لأرقام تعريف الأماكن إذا أضفتها إلى عبارة SELECT.

مزايا استخدام PLACES_COUNT_PER_TYPE_V2

تقدّم دالة PLACES_COUNT_PER_TYPE_V2 العديد من المزايا الرئيسية، خاصةً عند مقارنتها بدالة PLACES_COUNT_PER_TYPE الأقدم:

• معالجة المواقع الجغرافية على دفعات: على عكس PLACES_COUNT_PER_TYPE التي تعالج موقعًا جغرافيًا واحدًا في كل مرة، تقبل PLACES_COUNT_PER_TYPE_V2 TABLE من المواقع الجغرافية المُدخلة. يتيح لك ذلك تحليل الأعداد الخاصة بالنوع والحصول عليها عبر العديد من المناطق الجغرافية (النقاط والمضلعات) في طلب واحد، بدلاً من إجراء استدعاءات متعددة للدالة.
• تحسين الأداء وقابلية التوسّع: من خلال إدخال جدول، يمكن لـ PLACES_COUNT_PER_TYPE_V2 الاستفادة من عمليات الربط الجغرافية المكانية المحسّنة في BigQuery وإمكانات المعالجة المتوازية في جميع المناطق الجغرافية المقدَّمة في الوقت نفسه. ويؤدي ذلك إلى تحسينات كبيرة في الأداء وقابلية أفضل للتوسّع عند التعامل مع عدد كبير من المناطق الجغرافية.
• تضمين الأعداد الصفرية: تعرض هذه المَعلمة الصفوف التي تحتوي على أعداد صفرية للأنواع غير الموجودة في منطقة معيّنة ضمن الدفعة، ما يضمن الحصول على مجموعة نتائج كاملة لجميع مجموعات الأنواع والمواقع الجغرافية.
• اللقطات السابقة: يمكنك الاستعلام عن بيانات عدد الأماكن من شهر معيّن باستخدام فلتر snapshot_date الاختياري.

مثال: الاستعلام عن أعداد نقاط الاهتمام السابقة حسب النوع باستخدام فلاتر معيّنة

يوضّح هذا المثال كيفية العثور على أعداد أنواع معيّنة من الأماكن، مثل محطات شحن المركبات الكهربائية، باستخدام المَعلمة snapshot_date لاسترداد الأعداد لشهر سابق. يتم تطبيق فلاتر إضافية لـ "regular_opening_hours" للبحث فقط عن الأماكن المفتوحة طوال اليوم في عطلات نهاية الأسبوع، ومدى توفّر شواحن المركبات الكهربائية (توفّر 10 وصلات على الأقل) المحدّدة من خلال "min_ev_charge_connector_count".

SELECT *
FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_TYPE_V2`(
  (
    SELECT county_name AS geo_id,
           ST_SIMPLIFY(county_geom, 100) AS geo
    FROM
      `bigquery-public-data.geo_us_boundaries.counties`
    WHERE
      state_fips_code = "36"  -- New York State
      AND county_name IN ("Queens", "Kings", "New York")
  ),
  ['electric_vehicle_charging_station'], -- target_types array
  JSON_OBJECT(
    'geography_radius', 10000,
    'snapshot_date', '2026-01', -- Target snapshot month (YYYY-MM)
    'min_ev_charge_connector_count', 10, -- Look for a min amount of chargers
    'regular_opening_hours', JSON_OBJECT(
      'saturday', [JSON_OBJECT('start_time', '00:00', 'end_time', '23:59')], 'sunday', [JSON_OBJECT('start_time', '00:00', 'end_time', '23:59')]
    )
  )
);