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

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

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

השדה 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-sensitive) כברירת מחדל בכל אופרטור.

התלות באותיות רישיות כברירת מחדל
=/!=	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"

מידע נוסף

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