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

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

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

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

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

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

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

تنفيذ طلبات البحث باستخدام دوال Places Count

استخدِم التنسيق التالي لاستدعاء الدوال: [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 لعرض عدد المطاعم المفتوحة ضمن مسافة 1,000 متر من مبنى Empire State وTimes Square في مدينة نيويورك في تموز (يوليو) 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 للفلترة حسب معرّفات علامات تجارية معيّنة. في هذا المثال، نفلتر مواقع "ستاربكس" باستخدام معرّف العلامة التجارية "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.
  • يجب أن تكون مساحة البحث 40.0 مترًا على الأقل في 40.0 مترًا (1600 متر2) (40.0 مترًا في 40.0 مترًا / 1,600 متر مربع).
  • الحد الأقصى لحجم إدخال المَعلمات: يقتصر حجم كائن JSON الذي يتم تمريره كمَعلمة إلى الدوال على 1 ميغابايت. يعتمد تأثير هذا الحدّ على إصدار الدالة:
    • بالنسبة إلى دوال الإصدار 2 (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) حسّاسة لحالة الأحرف ويجب أن تتطابق مع أسماء المَعلمات تمامًا، وإلا سيفشل طلب البحث.