שפת שאילתת החיפוש

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

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

  • מילות מפתח
  • צמדי שדה:ערך

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

חיפושים לפי מילות מפתח

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

  • כותרת
  • תגובות
  • שמות הקבצים המצורפים
  • שדות שמכילים משתמשים (לדוגמה, Assignee או CC)
  • שדות שמכילים מספר מזהה פנימי (לדוגמה, אלה שמציינים את הרכיב או את רשימות הבעיות שכוללות בעיה)
  • שדות שמכילים מספרי גרסאות
  • שדות מותאמים אישית

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

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

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

מערכת Issue Tracker מתייחסת לתו הרווחים שמפריד בין קריטריונים לחיפוש כאופרטור AND משתמע. אפשר להשתמש במירכאות (") כדי לציין שמחרוזת של כמה מילים נחשבת כמילת מפתח אחת. כל החיפושים ב-Issue Tracker לא תלוי אותיות רישיות, גם אם משתמשים במירכאות וגם אם לא.

חיפושים של צמדי שדה:ערך

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

לדוגמה, חיפוש של title:latency יתאים לבעיות עם המילה latency בשדה Title. חיפוש של priority:p0 מוצא בעיות עם רמת תעדוף p0.

כל שדה שלא מזוהה יפורש כחיפוש לפי מילת מפתח.

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

חיפוש ערכים מיוחדים באמצעות any ו-none

אפשר לשלוח שאילתות על שדות אופציונליים באמצעות הערכים המיוחדים any ו-none. any תואם לכל ערך שאינו null. none תואם לערכים null. רשימה של כל תוויות השדות הנתמכות בשפת שאילתת החיפוש מופיעה במאמר חומר עזר בנושא שאילתות חיפוש.

אופרטורים לוגיים

אופרטורים לוגיים מאפשרים לציין יותר מקריטריון אחד ולהצביע על הקשר ביניהם. תווים של רווחים מחוץ לסוגריים מסולסלים פועלים בתור אופרטורים AND משתמעים. ב-Issue Tracker יש תמיכה באופררטורים לוגיים נוספים ומפורשים:

מפעיל סמל חלופי תיאור דוגמה
וגם {whitespace} התאמה אם הבעיה מכילה את שני הקריטריונים star:true AND componentid:46046
או | התאמה אם הבעיה מכילה את אחד מהקריטריונים type:(Bug|feature_request)
NOT - התאמה אם הבעיה לא מכילה את הקריטריונים -assignee:jim
"..." תתבצע התאמה אם הבעיה מכילה ביטוי במירכאות (המילים במירכאות מופיעות באותו סדר) comment:"We have a problem"
( ) קיבוץ ערכים או קריטריונים לחיפוש status:open AND (priority:(p0|p1) OR severity:(s0|s1))

שימו לב לנקודות הבאות:

  • צריך להשתמש באותיות רישיות בלבד במאפיינים AND, ‏ OR ו-NOT.

  • לאופרטור NOT יש אותה משמעות אם הוא מופיע לפני שם השדה או לפני ערך השדה. כלומר, -assignee:jim ו-assignee:-jim זהים.

  • כדאי להשתמש בסוגריים כדי לקבץ מונחים בצורה ברורה בשאילתת החיפוש. כברירת מחדל, מערכת המעקב אחר בעיות משייכת את NOT רק למונח שמופיע אחריו, ומקבצת את OR עם שני המונחים שמופיעים בסוגריים. לדוגמה, שאילתת החיפוש title:(a OR b NOT c AND d) שווה ל-title:((a OR b) AND (NOT c) AND d).

מקפים

למקש המקף (-) יש משמעויות שונות בהתאם להקשר בשאילתת החיפוש:

  • מערכת המעקב אחר בעיות מתייחסת לקו המקדים למילה בחיפוש כאופרטור NOT. לדוגמה, קריטריוני החיפוש -assignee:none או assignee:-none מחזירים את כל הבעיות שהוקצו למשתמש.

  • מערכת המעקב אחר בעיות מתייחסת למחרוזות שמחוברות באמצעות מקף כמחרוזות שמוקפות במרכאות. לדוגמה, קריטריוני החיפוש state-of-the-art זהים ל-"state of the art".

  • מערכת מעקב הבעיות מתייחסת למילים עם מקף בשדה הבעיה כמילים עצמאיות שמפרידים ביניהן רווחים. כלומר, אם הבעיה מכילה את המילה state-of-the-art בכותרת שלה, והפעלתם את שאילתת החיפוש title:(of art state the) או title:("state of the art"), הבעיה תוחזר כחלק מתוצאות החיפוש.

אופרטורים יחסיים

התחביר הבסיסי של קריטריון חיפוש מסוג field:value הוא [field]:[value], כאשר התו פסיק נקודה (:) מציין שהשדה הנתון חייב להיות שווה לערך שצוין או להכיל אותו כדי שבעיה תוחזר בתוצאות החיפוש.

שדות שמכילים ערך זמן (created, ‏ modified, ‏ resolved, ‏ verified ושדות מותאמים אישית מסוימים) או ערך ספירה (duplicatecount, ‏ votecount,‏ commentcount ו-cccount) תומכים באופרטורים היחסיים הנוספים הבאים:

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

חיפושים לפי זמן

בשפת שאילתות החיפוש יש תחביר מיוחד להתאמת שדות שמכילים ערך זמן. כך אפשר לחפש ב-Issue Tracker טווח זמנים או זמנים יחסיים לפי הצורך.

פורמט זמן מוחלט

הפורמט לציון שעה הוא:

[yyyy]-[MM]-[dd]T[HH]:[mm]:[ss].

בפורמט הזה, [yyyy] היא השנה בת 4 הספרות, [MM] הוא החודש בן שתי הספרות, [dd] הוא היום בן שתי הספרות, [HH] הוא השעה בת שתי הספרות לפי שעון 24 שעות, [mm] הוא הדקה ו-[ss] היא השנייה. כל השעות בחיפושים מתורגמות לפי שעון UTC, גם אם בחרתם אזור זמן אחר בהגדרות התאריך והשעה.

אתם יכולים לציין את רמת הספציפיות של החיפוש של בעיות שנוצרו בזמן מסוים, לפני זמן מסוים או אחרי זמן מסוים. לדוגמה, אפשר לציין created:2014-06 כדי למצוא בעיות שנוצרו בכל שלב ביוני 2014. כדי לקבל חיפוש ספציפי יותר, אפשר להשתמש ב-created:2014-06-03T04 כדי למצוא בעיות שנוצרו ב-3 ביוני 2014 בשעה הרביעית (בין השעות 4:00 ל-5:00 (שעון UTC)).

טווחי זמן

אפשר להשתמש בשני תווים של נקודה (..) כדי לציין טווח זמן בקריטריונים לחיפוש מסוג field:value. התחביר הוא [field]:[start time]..[end time]. אפשר לציין את שעות ההתחלה והסיום ברמת הפירוט הרצויה. לדוגמה, הערך verified:2013..2015 מחזיר את כל הבעיות שאומתו בשנים 2013, 2014 או 2015.

פורמט זמן יחסי

אפשר גם לציין שעה לפי מספר ימים לפני היום. כדי לעשות זאת, צריך להשתמש בפורמט [days]d, כאשר [days] הוא מספר הימים בעבר שרוצים לכלול בתוצאות החיפוש. לדוגמה, אפשר להשתמש ב-modified:5d כדי למצוא בעיות ששונו בחמשת הימים האחרונים.

כשמשתמשים בפורמט זמן יחסי, האופרטור חייב להיות התו הנקודתיים (:), כמו created:5d. אם רוצים למצוא בעיות שלא נכללות בטווח, אפשר להשתמש באופרטור NOT או -.

לדוגמה, הפונקציה -verified:10d מחזירה בעיות שלא אומתו ב-10 הימים האחרונים. אם רוצים למצוא בעיות שאומתו, אבל לא ב-10 הימים האחרונים, אפשר להשתמש ב-(-verified:10d) AND status:verified.

חיפושים עם 'היום' עם אריתמטיקה של ימים

אפשר להשתמש באסימון today בחיפושים לפי זמן כתחליף לתאריך הנוכחי. הוא תומך בשימוש בחשבון ימים כמו today+10 ו-today-2. אפשר להשתמש באסימון today גם עם טווחי זמן כמו today-2..today+3. שימוש באסימון today בחיפושים השמורים עוזר להשתמש בשאילתה שוב.

דוגמאות:

  • created:today
  • modified<=today-10
  • nearestslo:today+10
  • resolved:2024-02-29..today+2
  • customfield1002:today..today+5

הערה: כפי שצוין בקטע פורמט זמן מוחלט, חיפושים לפי זמן ב-Issue Tracker מתבצעים לפי שעון UTC. אותו הדבר חל על חיפושים שמשתמשים ב-today.