بدء استخدام "إحصاءات الأماكن"

دوال "عدد الأماكن" هي طلبات SQL محدّدة مسبقًا يتم تنفيذها في BigQuery، وهي الطريقة المقترَحة لإجراء طلبات بحث في مجموعة بيانات "إحصاءات الأماكن" من أجل استرداد الأعداد الدقيقة وأرقام تعريف الأماكن. يمكنك أيضًا الاستعلام عن مجموعة البيانات مباشرةً، ولكنّ طريقتَي الاستعلام تتعاملان مع حدود الخصوصية ومناطق البحث:

  • يمكن أن تعرض دوال عدد الأماكن أي أعداد، بما في ذلك 0، ولكنّها تفرض حدًا أدنى لمساحة البحث يبلغ 40.0 مترًا في 40.0 مترًا (1600 متر2) (40.0 مترًا في 40.0 مترًا / 1,600 متر مربع). تعرض الدوال أيضًا أرقام تعريف الأماكن، والتي يمكن استخدامها للبحث عن معلومات حول الأماكن الفردية، وتتيح تحليل نقاط الاهتمام السابقة في جميع اللقطات الشهرية السابقة باستخدام فلاتر التاريخ الاختيارية.

  • يمكن أن تعرض طلبات البحث في مجموعة بيانات الأماكن الأعداد 5 وما فوق فقط (مع حذف الأعداد المنخفضة من 0 إلى 4 للحفاظ على الخصوصية التفاضلية)، ولكن لا تفرض أي قيود على حجم منطقة البحث.

ننصحك بالبدء بدوال عدد الأماكن، مثل PLACES_COUNT_PER_H3، إلا إذا كنت بحاجة إلى إجراء تحليل مكاني معقّد. وتوفّر هذه الواجهة إحصاءات فورية حول الكثافة المكانية في خلايا الشبكة الموحّدة، وتعرض أرقام تعريف الأماكن لفحص المعلومات الفعلية، وهي مصمّمة خصيصًا لهندسة الخصائص الجغرافية المكانية ونماذج تعلُّم الآلة.

اختيار دالة Places Count المثلى

تتيح خدمة "إحصاءات الأماكن" استخدام عدة دوال مكانية. لتحسين تنفيذ طلبات البحث والمعالجة المتوازية وقابلية توسّع الدفعات، ننصحك باستخدام الدوال التالية:

  • 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 إجراء عمليات تقاطع مكانية متوازية بشكلٍ أصلي على مستوى مجموعات البيانات الكبيرة.

بالإضافة إلى أعداد الأماكن، تعرض هذه الدوال أيضًا ما يصل إلى 250 رقم تعريف مكان لكل عنصر من عناصر الاستجابة.

يمكن استخدام أرقام تعريف الأماكن مع:

تنفيذ طلبات البحث باستخدام دوال عدد الأماكن

استخدِم التنسيق التالي لاستدعاء الدوال: [project name (optional)].[table name].[function name].

إذا غيّرت اسم مجموعة البيانات المرتبطة عند إعداد إحصاءات الأماكن، استخدِم اسمك المخصّص بدلاً من أسماء الجداول التلقائية. يمكنك أيضًا تضمين اسم مشروعك اختياريًا. وإذا لم يتم تضمين مشروع، يتم ضبط الطلب تلقائيًا على المشروع النشط.

على سبيل المثال:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

استخدِم JSON_OBJECT لتمرير الوسيطات إلى الدالة.

فلترة نتائج طلب البحث باستخدام مَعلمات حسّاسة لحالة الأحرف

تتيح دوال عدد الأماكن استخدام العديد من الفلاتر لتحسين عملية البحث. هذه المَعلمات (على سبيل المثال، price_level أو types) حسّاسة لحالة الأحرف ويجب أن تتطابق مع أسماء المَعلمات تمامًا. للاطّلاع على قائمة كاملة بالخيارات، يُرجى مراجعة مرجع مَعلمات الفلتر.

الاستعلام عن اللقطات السابقة باستخدام snapshot_date

تستعلم دوال Places Count تلقائيًا عن أحدث لقطة بيانات متاحة. لتحليل بيانات الأماكن كما كانت خلال شهر سابق معيّن، أضِف المَعلمة الاختيارية snapshot_date إلى JSON_OBJECT.

  • التنسيق: YYYY-MM (على سبيل المثال، '2026-07').
  • القيمة التلقائية: في حال حذف هذه المَعلمة، ستطلب الدالة تلقائيًا أحدث لقطة.

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

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 لعرض عدد المطاعم العاملة ضمن مسافة 1000 متر من مبنى "إمباير ستيت" و"تايمز سكوير" في مدينة نيويورك في يوليو 2026:

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 في مدينة نيويورك

يستخدم المثال التالي الدالة PLACES_COUNT_V2 للفلترة حسب معرّفات علامات تجارية معيّنة. في هذا المثال، نفلتر المواقع الجغرافية لفروع Starbucks باستخدام رقم تعريف العلامة التجارية "1413758728321880760".

للعثور على معرّفات العلامات التجارية التي تريد الفلترة حسبها، يمكنك الاستعلام عن الجدول brands لمجموعة بياناتك (على سبيل المثال، places_insights___us.brands). لمزيد من المعلومات حول مجموعة بيانات العلامات التجارية، يمكنك الاطّلاع على كتابة طلب بحث باستخدام بيانات العلامات التجارية.

على سبيل المثال، للعثور على رقم تعريف العلامة التجارية "Starbucks":

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.
  • يجب ألا تقل مساحة البحث عن 40.0 متر في 40.0 متر (1,600 مترمربع).
  • الحدّ الأقصى لحجم إدخال المَعلمة: يبلغ الحدّ الأقصى لحجم كائن JSON الذي يتم تمريره كمَعلمة إلى الدوال 1 ميغابايت. يعتمد تأثير هذا الحدّ على إصدار الدالة:
    • بالنسبة إلى دوال الإصدار الثاني (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) حسّاسة لحالة الأحرف ويجب أن تتطابق مع أسماء المَعلمات تمامًا، وإلا سيتعذّر تنفيذ طلب البحث.