המבנה והסעיפים של השאילתות

שאילתה מורכבת ממספר תנאים: SELECT,‏ FROM,‏ WHERE,‏ ORDER BY,‏ LIMIT ו-PARAMETERS.

התנאים כוללים שמות שדות, שמות משאבים, אופרטורים, תנאים וסדרי מיון שמתחברים לבקשת שאילתה אחת.

באופן כללי, כדי ליצור שאילתה:

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

SELECT פסקה

התנאי SELECT:

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

בדוגמה הבאה מוסבר איך לבחור מאפיינים של המשאב campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

כמה סוגי שדות

אפשר לבקש סוגים שונים של שדות באותה בקשה.

בשאילתה לדוגמה שבהמשך מוצגת שאילתה אחת עם שילוב של:

  • שדות המשאבים: campaign.id,‏ campaign.name,‏ bidding_strategy.id ו-bidding_strategy.name.
  • שדות של פלחים: segments.device ו-segments.date.
  • שדות מדדים: metrics.impressions ו-metrics.clicks.
SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

במאמר פילוח מוסבר בהרחבה איך לפלח את דוחות החיפוש.

שדה המשאב הראשי

בדרך כלל, כדאי לכלול את שדה המשאב הראשי בפסקה SELECT, אבל זה אופציונלי (לא נדרש).

בשאילתה לדוגמה הזו נעשה שימוש בשדה משאב ראשי (ad_group.status) כדי לסנן רק את התוצאות.

SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

משתנים מותאמים אישית ב-Floodlight

אפשר לכלול משתנים מותאמים אישית ב-Floodlight בתנאי ה-SELECT באמצעות המזהים שלהם.

בדוגמה הזו, השאילתה כוללת משתנה מותאם אישית עם המזהה 123454321 של משאב הקמפיין.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

עמודות מותאמות אישית

אפשר לכלול עמודות בהתאמה אישית בתנאי ה-SELECT באמצעות המזהים שלהן.

בדוגמה הזו, השאילתה כוללת עמודה בהתאמה אישית עם המזהה 12345678 של משאב הקמפיין.

SELECT
  custom_columns.id[12345678]
FROM campaign

איך מקבלים מזהי עמודות בהתאמה אישית

שדות של מדדים

אפשר לבחור שדות מדדים של משאב נתון בלי לכלול שדות אחרים מהמשאב בפסקה SELECT.

בשאילתה לדוגמה הזו נבחרים המדדים impressions ו-clicks למשאב campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

בmetrics מופיעה רשימה של שדות מדדים שאפשר להשתמש בהם בשאילתות.

שדות של פלחים

אפשר לבחור שדות של פלחים בלי לציין שדות משאבים או מדדים נלווים בפסקה SELECT.

בשאילתה לדוגמה הזו, התוצאות מחולקות לפי מכשיר.

SELECT segments.device
FROM campaign

בקטע segments מופיעה רשימה של שדות פלחים שבהם אפשר להשתמש בשאילתות.

שדות אסורים

אי אפשר להשתמש בשדות הבאים בפסקה SELECT:

  • שדות שלא ניתן לבחור, כלומר שדות עם מאפיין המטא-נתונים Selectable שמסומן כ-false.
  • שדות חוזרים, כלומר שדות עם מאפיין המטא-נתונים Repeated שמסומן כ-true.
  • שדות שלא זמינים למשאב הנתון בפסקה FROM. אי אפשר לבחור יחד מאפיינים של משאבים מסוימים. בחלק מהמשאבים זמינה רק קבוצת משנה של כל המדדים והפלחים.
  • מדדים או פלחים לא תואמים. מידע נוסף זמין במאמר פילוח.

במסמכי העזרה מוסבר איפה אפשר למצוא את המידע הזה לכל משאב.

תנאי FROM

התנאי FROM:

  • תנאי חובה לשאילתות ל-SearchAds360Service (גם בשיטות Search וגם בשיטות SearchStream).
  • לא צריך לכלול אותו בשאילתות ל-SearchAds360FieldService.
  • מציין את המשאב הראשי שהשאילתה מחזירה.
  • אפשר לציין רק משאב אחד.
  • מגדיר את השדות שבהם אפשר להשתמש בכל שאר התנאים בשאילתה.

משאבים שמשויכים

אם יש משאבים משויכים זמינים, הם מצורפים באופן משתמע למשאב שציינתם בפסקה FROM. כדי להחזיר את הערכים שלהם, צריך רק להוסיף את המאפיינים שלהם לפסקה SELECT.

השאילתה לדוגמה הזו מחזירה גם את מזהה קבוצת המודעות וגם את מזהה הקמפיין, כי campaign הוא משאב שמשוייך למשאב ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

השדה resource_name

השדה resource_name של המשאב הראשי בפסקה FROM תמיד מוחזר.

בשאילתה לדוגמה הזו, השדה ad_group.resource_name ייכלל בתשובה גם אם לא בחרתם בו במפורש בשאילתה:

SELECT ad_group.id
FROM ad_group

השדה resource_name של משאב שמשוייך מוחזר כשבוחרים לפחות שדה אחד.

בשאילתה לדוגמה הזו, הערך campaign.resource_name ייכלל בתגובה כי הערך campaign.id נבחר:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

תנאי WHERE

התנאי WHERE:

  • הוא אופציונלי בשאילתה.
  • התנאים לסינון ולפילוח הנתונים של הבקשה. התנאים צריכים להיות בפורמט הזה: FIELD_NAME OPERATOR VALUE (מופרדים באמצעות רווחים).
  • אפשר לכלול כמה תנאים מופרדים באמצעות המפריד AND.

בדוגמה הבאה מוצג איך להשתמש בפסקה WHERE כדי להציג מדדי impressions לתקופה נתונה:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

במאמר פילוח מוסבר בהרחבה איך לפלח את דוחות החיפוש.

במאמר טווחי תאריכים מוסבר איך מציינים טווחי תאריכים בשאילתות.

סינון לפי השדה resource_name

אפשר להשתמש בשדה resource_name כדי לסנן או למיין נתונים.

בשאילתה לדוגמה הזו נעשה שימוש בשדה campaign.resource_name כדי לסנן את התוצאות לפי קמפיין נתון:

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

מספר תנאים

אפשר לשלב כמה תנאים כדי לסנן את הנתונים.

בשאילתה לדוגמה הזו מופיע דרישה למספר המדדים clicks לכל הקמפיינים עם מדדי impressions בנייד ב-30 הימים האחרונים.

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = MOBILE
  AND segments.date DURING LAST_30_DAYS

מידע נוסף על פילוח הדוחות זמין במאמר פילוח.

תלות באותיות רישיות (Case sensitivity)

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

בטבלה הבאה מוצגת רגישות ברירת המחדל של כל אופרטור.

תלות בריישיות כברירת מחדל
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

אפשר להשתמש במשתנה המשנה (?i) כדי לשנות את רגישות ברירת המחדל של REGEXP_MATCH ו-NOT REGEXP_MATCH כך שלא תהיה תלות אותיות רישיות, לדוגמה:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

במאמר בנושא 'חומר עזר בנושא תחביר של שאילתות' מפורטת רשימה מלאה של האופרטורים שאפשר להשתמש בהם כדי לסנן את הנתונים.

פלחי תאריכים מרכזיים

שדות הפלחים הבאים נקראים פלחי תאריכים מרכזיים: segments.date, segments.week, segments.month, segments.quarter ו-segments.year.

אפשר להשתמש בפלחי תאריכים מרכזיים בפסקה WHERE כדי לציין תאריך או תקופת זמן.

בשאילתה לדוגמה הזו מצוין DURING LAST_30_DAYS בשדה segments.date בפסקה WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

מידע מפורט על השימוש בפלחי תאריכים מרכזיים זמין בקטע פילוח > פלחי תאריכים מרכזיים.

סינון אסור

אסור לסנן:

  • בשדות של פלחים שלא נבחרו, מלבד פלחי תאריכים מרכזיים.
  • בשדות של כל סוג הודעה, מלבד פרימיטיבים (לדוגמה, Int64Value,‏ StringValue וכו').
  • במאפיינים של שדות חוזרים בכל סוג הודעה, מלבד פרימיטיבים (לדוגמה, Int64Value,‏ StringValue וכו').

תנאי ORDER BY

התנאי ORDER BY:

  • הוא אופציונלי בשאילתה.
  • מציין את הסדר שבו התוצאות יחזרו. הסדר הוא לפי התבנית הבאה: FIELD_NAME ORDERING_OPTION (מופרדים באמצעות רווח).
  • יש שתי אפשרויות: ASC (עולה) או DESC (יורד). ברירת המחדל היא עלייה.

בשאילתה לדוגמה הזו, הקמפיינים ממוינים לפי מספר הקליקים בסדר יורד (מהגבוה לנמוך):

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

מספר סדרות

אפשר לציין כמה שדות בפסקה ORDER BY באמצעות רשימה מופרדת בפסיקים. התוצאות ימוינו באותה רצף שציינתם בשאילתה.

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

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

שילוב של סדר והגבלה

אפשר להשתמש בפסקה ORDER BY בשילוב עם פסקה LIMIT כדי לשפר את התוצאות.

השאילתה לדוגמה הזו מחזירה את חמשת הקמפיינים עם מספר החשיפות הגבוה ביותר ב-30 הימים האחרונים:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

הזמנות אסורות

אסור להזמין:

  • לפי מאפיינים של משאבים שלא נבחרו.
  • לפי מדדים שלא נבחרו.
  • לפי פלחים שלא נבחרו.
  • בסוגי השדות הבאים:
    • MESSAGE
    • שדות חוזרים
    • מאפיינים של שדות חוזרים.

תנאי LIMIT

התנאי LIMIT:

  • הוא אופציונלי בשאילתה.
  • מאפשרת להגביל את מספר התוצאות שהוחזרו על ידי השאילתה.

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

השאילתה לדוגמה הזו מגבילה את המספר הכולל של התוצאות ל-50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

התנאי PARAMETERS

באמצעות התנאי PARAMETERS אפשר לציין מטא-פרמטרים לבקשה.

יש לכלול טיוטות

הפרמטר include_drafts קובע אם ישויות בטיוטה ייכללו בתוצאות. ערך ברירת המחדל הוא false. מגדירים אותו כ-true כדי לכלול ישויות טיוטה.

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

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

השמטת resource_name שלא נבחרו

הפרמטר omit_unselected_resource_names מאפשר להחריג מהשדה resource_name את כל המשאבים שלא מופיעים בבקשה במפורש בפסקה SELECT. ערך ברירת המחדל הוא false. אם מגדירים את הפרמטר הזה ל-true, מומלץ לבקש באופן מפורש את שם המשאב של המשאב הראשי ואת כל המשאבים המשויכים בפסקה SELECT.

בשאילתה לדוגמה הזו לא מוחזר השדה campaign.resource_name וגם לא השדה customer.resource_name, כי הם לא כלולים בפסקה SELECT:

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

השאילתה לדוגמה הזו מחזירה את השדה campaign.resource_name, כי היא מבקשת אותו במפורש בפסקה SELECT:

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

שינוי המטבע שמוצג במדדים

הפרמטר metrics_currency מאפשר לציין את המטבע שבו יתבצע החישוב של מדד שכלול בפסקה SELECT. כברירת מחדל, המערכת משתמשת במטבע המקומי של החשבון. אם מגדירים את הפרמטר הזה, צריך להשתמש בקוד המטבע בן 3 האותיות בתקן ISO 4217. לדוגמה: USD, ‏ EUR.

השאילתה לדוגמה הזו מחזירה את המדד cost_micros במטבע המקומי של החשבון.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

השאילתה לדוגמה הזו מחזירה את המדד cost_micros בפסו צ'ילאני (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

הפעלת הרחבה של חשבון ניהול

כשמגדירים את הפרמטר enable_mcc_expansion לערך true, אפשר לכלול מדדים, שדות ופלחים מ-login_customer_id ומכל חשבונות השירות שמתחתיו, עבור המשאב שבפסקה FROM. התשובה תכלול את המטבע של login_customer_id, אלא אם צוין אחרת במפורש בפרמטר metrics_currency.

השאילתה לדוגמה הזו מחזירה את bidding_strategy.name, ‏ bidding_strategy.type ו-metrics.cost_micros מ-login_customer_id ומכל חשבונות השירות שמתחתיו, כי הפרמטר enable_mcc_expansion מוגדר כ-true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

מידע נוסף