תחילת העבודה עם תובנות לגבי מקומות

פונקציות ספירת מקומות הן שאילתות SQL מוגדרות מראש שפועלות ב-BigQuery. זו הדרך המומלצת לשלוח שאילתות למערך הנתונים של Places Insights כדי לאחזר ספירות מדויקות ומזהי מקומות. אפשר גם לשלוח שאילתה ישירות למערך הנתונים, אבל שתי שיטות השאילתות מטפלות בספי הפרטיות ובאזורי החיפוש:

  • פונקציות של ספירת מקומות יכולות להחזיר כל ספירה, כולל 0, אבל אוכפות אזור חיפוש מינימלי של 40.0 מטרים על 40.0 מטרים (1,600 מ"ר). הפונקציות גם מחזירות מזהי מקומות, שאפשר להשתמש בהם כדי לחפש מידע על מקומות ספציפיים, ותומכות בניתוח היסטורי של נקודות עניין בתמונות מצב חודשיות קודמות באמצעות מסנני תאריכים אופציונליים.

  • שאילתות על מערך הנתונים של המקומות יכולות להחזיר רק ספירות של 5 ומעלה (השמטת ספירות נמוכות של 0-4 כדי לשמור על פרטיות דיפרנציאלית), אבל לא אוכפות מגבלות על גודל אזור החיפוש.

אם אתם לא צריכים לבצע ניתוח מרחבי מורכב, מומלץ להתחיל עם פונקציות של ספירת מקומות כמו PLACES_COUNT_PER_H3. הוא מספק תובנות מיידיות לגבי צפיפות מרחבית בתאי רשת סטנדרטיים, מחזיר מזהי מקומות לבדיקת אמת קרקע (ground truth), והוא תוכנן במיוחד להנדסת פיצ'רים (feature engineering) גיאוגרפיים-מרחביים ולמודלים של למידת מכונה (ML).

בחירת הפונקציה האופטימלית לספירת מקומות

‫Places Insights תומך בכמה פונקציות מרחביות. כדי לבצע שאילתות בצורה אופטימלית, לעבד במקביל ולהרחיב את היקף הנתונים באצווה, מומלץ להשתמש בפונקציות הבאות:

  • ‫PLACES_COUNT_PER_H3: מחזירה טבלה ב-BigQuery עם מספר המקומות בכל תא H3. הפונקציה הזו מומלצת לניתוח צפיפות אזורי ולמיפוי חום של מפות כורופלת.
  • ‫ PLACES_COUNT_V2: מחזירה טבלה שמכילה את מספר המקומות ומזהי מקומות לדוגמה. הפונקציה הזו מקבלת פרמטר של טבלה שמכיל את האזורים הגיאוגרפיים שהזנתם. כשמעבירים טבלה שלמה ישירות, מנוע הביצוע של BigQuery יכול לחלק את עומס העבודה ולעבד חיתוכים מרחביים במקביל, וכך לאפשר עיבוד ברצף (batch processing) יעיל מאוד לניתוח בקנה מידה גדול.
  • ‫ PLACES_COUNT_PER_TYPE_V2: מחזירה טבלה של ספירות מקומות ומזהי מקומות לדוגמה, שמסווגים לפי סוג המקום. בדומה ל-PLACES_COUNT_V2, העברת האזורים הגיאוגרפיים של הקלט כפרמטר של טבלה מאפשרת ל-BigQuery לבצע במקביל חיתוכים מרחביים במערכי נתונים גדולים.
  • PLACES_COUNT_CHANGE: מחזירה טבלה של ספירות מקומות, וגם מזהי מקומות שנוספו והוסרו בין שני חודשים נתונים. PLACES_COUNT_V2, העברת האזורים הגיאוגרפיים של הקלט כפרמטר של טבלה מאפשרת ל-BigQuery לבצע במקביל חיתוכים מרחביים במערכי נתונים גדולים.

בנוסף לספירת המקומות, הפונקציות האלה מחזירות גם עד 250 מזהי מקומות לכל רכיב בתגובה.

אפשר להשתמש במזהי מקומות עם:

הרצת שאילתות באמצעות פונקציות של ספירת מקומות

כדי להפעיל את הפונקציות, משתמשים בפורמט הבא: [project name (optional)].[table name].[function name].

אם שיניתם את השם של מערך הנתונים המקושר כשהגדרתם את Places Insights, השתמשו בשם המותאם אישית במקום בשמות ברירת המחדל של הטבלאות. אפשר גם להוסיף את שם הפרויקט. אם לא מציינים מזהה פרויקט, השאילתה תתבצע כברירת מחדל בפרויקט הפעיל.

לדוגמה:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

משתמשים ב-JSON_OBJECT כדי להעביר ארגומנטים לפונקציה.

סינון תוצאות של שאילתות באמצעות פרמטרים תלויי אותיות רישיות (case-sensitive)

הפונקציות של ספירת מקומות תומכות בהרבה מסננים כדי לצמצם את החיפוש. הפרמטרים האלה (לדוגמה, price_level או types) הם תלויי אותיות רישיות, וחייבים להתאים בדיוק לשמות הפרמטרים. רשימה מלאה של האפשרויות מופיעה בחומר העזר בנושא פרמטרים של סינון.

הרצת שאילתות על תמונות מצב היסטוריות באמצעות snapshot_date

כברירת מחדל, פונקציות של ספירת מקומות מריצות שאילתות על תמונת המצב העדכנית ביותר של הנתונים. כדי לנתח נתוני מקומות כפי שהיו בחודש ספציפי בעבר, מוסיפים את הפרמטר האופציונלי 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 מטרים מבניין האמפייר סטייט ומכיכר טיימס בניו יורק ביולי 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_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 Insights.

לדוגמה של הצגת התוצאות של פונקציה, ראו הצגת תוצאות בתוך ה-PLACES_COUNT_PER_H3 reference. למידע נוסף על הצגת תוצאות Places Insights, ראו הצגת תוצאות שאילתות.

מגבלות ודרישות של הפונקציה

לפונקציות ספירת מקומות יש את המגבלות והדרישות הבאות:

  • הפונקציות תומכות רק בתובנות של COUNT.
  • אזור החיפוש המינימלי הנדרש הוא 40.0 מטרים על 40.0 מטרים (1,600 מ"ר).
  • מגבלת גודל הקלט של הפרמטר: אובייקט ה-JSON שמועבר כפרמטר לפונקציות מוגבל ל-1MB. ההשפעה של המגבלה הזו תלויה בגרסת הפונקציה:
    • בפונקציות מגרסה 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, כולל כל ההגדרות הגיאוגרפיות. יכול להיות שהמגבלה הזו תצמצם את מספר האזורים הגיאוגרפיים שאפשר לעבד בקריאה אחת.
  • אין תמיכה בסינון לפי מזהה מקום או רכיב כתובת.
  • אתם יכולים לגשת לפונקציות של ספירת מקומות רק בערים ובמדינות שנרשמתם אליהן. כדי לקבל גישה למערך הנתונים, עיינו במאמר הגדרת Places Insights.
  • הפרמטרים של המסנן (לדוגמה, geography או types) הם תלויי אותיות רישיות (case-sensitive) וחייבים להתאים בדיוק לשמות הפרמטרים, אחרת השאילתה תיכשל.