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

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

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

במונחים בסיסיים, כדי ליצור שאילתה:

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

סעיף SELECT

הסעיף SELECT:

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

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

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) של כל אופרטור.

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

מידע נוסף

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