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

שאילתה מורכבת ממספר תנאים: 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.

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

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

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

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

הערה: לא לכל המשאבים יש משאבים משויכים. הקטע Reference כולל פרטים על המשאבים המשויכים שזמינים לכל משאב.

השדה 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

הערה: אם המשאב בסעיף FROM מציין משאב אחר כ-segment, בחירת כל המאפיינים של המשאב תשמש כפלח.

תנאי 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

הערה: אפשר להשתמש במפריד AND רק בין תנאי אופרטורים (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE"), ולא בתוך תנאי אופרטור יחיד (WHERE segments.device != "DESKTOP" AND "MOBILE").

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

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

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

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

תלות אותיות רישיות (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"

מידע נוסף

• דקדוק שאילתות