השאילתה מורכבת מכמה סעיפים: 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) כברירת מחדל בכל אופרטור.
התלות באותיות רישיות כברירת מחדל | |
---|---|
=/!= |
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"