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

פונקציות ספירת מקומות הן שאילתות 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 יכול לחלק את עומס העבודה ולעבד חיתוכים מרחביים במקביל, וכך לאפשר עיבוד יעיל מאוד של קבוצות נתונים לניתוח בקנה מידה גדול.
• ‫ PLACES_COUNT_PER_TYPE_V2: מחזירה טבלה של ספירות מקומות ומזהי מקומות לדוגמה, לפי סוג המקום. בדומה ל-PLACES_COUNT_V2, העברת האזורים הגיאוגרפיים של הקלט כפרמטר של טבלה מאפשרת ל-BigQuery לבצע במקביל חיתוכים מרחביים במערכי נתונים גדולים.
• PLACES_COUNT_CHANGE: מחזירה טבלה של ספירת מקומות, וגם מזהי מקומות שנוספו והוסרו בין שני חודשים נתונים. בדומה ל-PLACES_COUNT_V2, העברת האזורים הגיאוגרפיים של הקלט כפרמטר של טבלה מאפשרת ל-BigQuery לבצע באופן מקורי פעולות חיתוך מרחביות במקביל במערכי נתונים גדולים.

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

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

• Places API (חדש)
• Geocoding API
• Places UI Kit

הערה: אתם יכולים לגשת לפונקציות של Places Count באותן ערים ומדינות שיש לכם גישה אליהן.

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

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

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

לדוגמה:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

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

הערה: כשמשתמשים בפונקציה Places Count, צריך לציין את הפונקציה בסעיף FROM ולהשמיט את WITH_AGGREGATION_THRESHOLD.

סינון תוצאות של שאילתות באמצעות פרמטרים תלויי אותיות רישיות (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.

קודם כל, משתמשים בטבלת הקלט של האזורים הגיאוגרפיים או מכינים טבלה עם האזורים הגיאוגרפיים שנבחרו:

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

-- 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
      )
);

הערה: צריך לכלול את המסנן business_status כדי לוודא שמתקבלת ספירה של עסקים מסוג OPERATIONAL. אחרת, הספירה תכלול עסקים סגורים.

דוגמה: שאילתה על מספר המסעדות ומיקומי המותגים באמצעות 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. איך ממחישים את תוצאות השאילתות

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

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

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