אפשרויות של שאילתות ומיון

כשקוראים לשיטה search() באמצעות מחרוזת שאילתה בלבד, התוצאות מוחזרות בהתאם לאפשרויות ברירת המחדל של השאילתה:

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

אפשר להשתמש במופע של המחלקה של המחלקה Query כארגומנט לפונקציה search() כדי לשנות את האפשרויות האלה.

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

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

חיפוש באמצעות המחלקה Query

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

  1. יוצרים מחרוזת שאילתה.
  2. יוצרים SortOptions אם צריך.
  3. יצירת QueryOptions.
  4. יוצרים אובייקט Query שכולל את מחרוזת השאילתה ואת (האופציונלי) QueryOptions.
  5. מבצעים קריאה לשיטת החיפוש באובייקט Query.

הקונסטרוקטורים QueryOptions ו-SortOptions משתמשים בארגומנטים בעלי שם, כמו בדוגמה הזו:

def query_options():
    index = search.Index('products')
    query_string = "product: piano AND price < 5000"

    # Create sort options to sort on price and brand.
    sort_price = search.SortExpression(
        expression='price',
        direction=search.SortExpression.DESCENDING,
        default_value=0)
    sort_brand = search.SortExpression(
        expression='brand',
        direction=search.SortExpression.DESCENDING,
        default_value="")
    sort_options = search.SortOptions(expressions=[sort_price, sort_brand])

    # Create field expressions to add new fields to the scored documents.
    price_per_note_expression = search.FieldExpression(
        name='price_per_note', expression='price/88')
    ivory_expression = search.FieldExpression(
        name='ivory', expression='snippet("ivory", summary, 120)')

    # Create query options using the sort options and expressions created
    # above.
    query_options = search.QueryOptions(
        limit=25,
        returned_fields=['model', 'price', 'description'],
        returned_expressions=[price_per_note_expression, ivory_expression],
        sort_options=sort_options)

    # Build the Query and run the search
    query = search.Query(query_string=query_string, options=query_options)
    results = index.search(query)
    for scored_document in results:
        print(scored_document)

QueryOptions

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

מאפיין (property) תיאור ברירת מחדל מקסימום
limit המספר המקסימלי של מסמכים שיוחזרו בתוצאות. 20 ‫1000 number_found_accuracy
offset ההיסט של המסמך הראשון בתוצאות שיוחזרו. ‫0. התוצאות יכללו את כל המסמכים התואמים (עד למגבלה). 1,000
cursor אפשר להשתמש בסמן במקום בהיסט כדי לאחזר קבוצות של מסמכים בסדר ממוין. הסמן מתעדכן כשהוא מועבר אל שאילתות עוקבות ומחוצה להן, וכך מאפשר להמשיך כל חיפוש חדש מהסוף של החיפוש הקודם. מידע על מיקום הסמן וההיסט זמין בדף טיפול בתוצאות . Null. התוצאות יכללו את כל המסמכים התואמים (עד למגבלה). -
sort_options מגדירים SortOptions object כדי לשלוט בסדר של תוצאות החיפוש. למופע של SortOptions יש קבוצה משלו של מאפיינים שמתוארים בהמשך. Null. מיון לפי דירוג המסמך בסדר יורד. -

המאפיינים האלה קובעים אילו שדות של המסמך יופיעו בתוצאות.

מאפיין (property) תיאור ברירת מחדל
ids_only ההגדרה היא True או False . אם True , המסמכים שיוחזרו בתוצאות יכילו רק מזהים, ללא שדות. False (החזרת כל השדות).
returned_fields מציינים אילו שדות במסמך ייכללו בתוצאות. אפשר לציין עד 100 שדות. החזרת כל השדות במסמך (עד 100 שדות).
returned_expressions ביטויי שדות שמתארים שדות מחושבים שנוספים לכל מסמך שמוחזר בתוצאות החיפוש. השדות האלה מתווספים לנכס expressions של המסמך. ערך השדה מצוין על ידי כתיבת ביטוי שיכול לכלול שדה אחד או יותר של המסמך. ללא
snippeted_fields רשימה של שמות שדות טקסט. לכל שדה נוצר קטע קוד. זהו שדה מחושב שנוסף לנכס expressions של המסמכים בתוצאות החיפוש. שם השדה של התקציר זהה לשם שדה המקור.

האפשרות הזו משתמשת באופן מרומז בפונקציית התקציר עם שני ארגומנטים בלבד, ויוצרת תקציר עם מחרוזת אחת לכל היותר שתואמת למחרוזת השאילתה ששימשה את החיפוש לאחזור התוצאות: snippet("query-string", field-name).

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

SortOptions

המאפיינים של SortOptions שולטים בסדר ובניקוד של תוצאות החיפוש.

מאפיין (property) תיאור ברירת מחדל
expressions רשימת של SortExpressions שמייצגת מיון רב-ממדי של מסמכים. ללא
match_scorer אובייקט אופציונלי מסוג MatchScorer . אם הפרמטר הזה קיים, המסמכים ידורגו לפי התדירות של מונח החיפוש. הציון יהיה זמין כשדה _score. הניקוד של מסמכים עלול להיות יקר (גם מבחינת פעולות לחיוב וגם מבחינת זמן ביצוע) ולהאט את החיפושים. השתמשו בניקוד במשורה. ללא
limit המספר המקסימלי של אובייקטים לדירוג או למיון. הערך לא יכול להיות גבוה מ-10,000. 1,000

מיון לפי כמה מפתחות

אפשר להזמין את תוצאות החיפוש לפי כמה מפתחות מיון. כל מפתח יכול להיות שם שדה פשוט או ערך שמחושב מכמה שדות.הערה: המונח 'ביטוי' משמש עם כמה משמעויות כשמדברים על אפשרויות מיון: ל-SortOption עצמו יש מאפיין expressions. המאפיין הזה הוא רשימה של SortExpression אובייקטים שתואמים למפתחות מיון. לבסוף, כל אובייקט SortExpression מכיל מאפיין expression שמציין איך לחשב את הערך של מפתח המיון. הביטוי הזה בנוי לפי הכללים שמפורטים בקטע הבא.

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

מאפיין (property) תיאור ברירת מחדל
expression ביטוי שיוערך כשממיינים את התוצאות של כל מסמך תואם. ללא
direction הכיוון למיון תוצאות החיפוש, ASCENDING או DESCENDING. DESCENDING
default_value ערך ברירת המחדל של הביטוי, אם לא קיים שדה ולא ניתן לחשב אותו עבור מסמך. צריך לציין ערך טקסט למיון טקסט. במיון מספרי צריך לציין ערך מספרי. ללא

מיון בשדות מרובי-ערכים

כשממיינים לפי שדה רב-ערכי מסוג מסוים, המערכת משתמשת רק בערך הראשון שהוקצה לשדה. לדוגמה, נניח שיש שני מסמכים, DocA ו-DocB, שלשניהם יש שדה טקסט בשם 'color'. שני ערכים מוקצים לשדה 'color' של DocA בסדר (red, blue), ושני ערכים ל-DocB בסדר (green, red). כשמבצעים מיון ומציינים את שדה הטקסט 'צבע', DocA ממוין לפי הערך 'אדום' ו-DocB לפי הערך 'ירוק'. הערכים בשדות האחרים לא משמשים למיון.

למיין או לא למיין

אם לא מציינים אפשרויות מיון, תוצאות החיפוש מוחזרות אוטומטית כשהן ממוינות לפי דירוג בסדר יורד. במקרה כזה, אין הגבלה על מספר המסמכים שמוחזרים. אם מציינים אפשרויות מיון, המיון מתבצע אחרי שכל המסמכים התואמים נבחרו. יש מאפיין מפורש, SortOptions.limit , ששולט בגודל המיון. אי אפשר למיין יותר מ-10,000 מסמכים, וערך ברירת המחדל הוא 1,000. אם יש יותר מסמכים שתואמים למספר שצוין על ידי SortOptions.limit , החיפוש יאחזר, ימיין ויחזיר רק את המספר המוגבל הזה. הוא בוחר את המסמכים למיון מתוך רשימת כל המסמכים התואמים, שמסודרת בסדר יורד לפי דירוג. יכול להיות ששאילתה תבחר יותר מסמכים תואמים ממה שאפשר למיין. אם אתם משתמשים באפשרויות מיון וחשוב לכם לאחזר כל מסמך שתואם לשאילתה, כדאי לוודא שהשאילתה לא תחזיר יותר מסמכים ממה שניתן למיין.

כתיבת ביטויים

משתמשים בביטויים כדי להגדיר ביטויי שדות (שמוגדרים ב- QueryOptions ) וביטויי מיון, שמוגדרים ב-SortOptions. הם נכתבים כמחרוזות:

"price * quantity"
"(men + women)/2"
"min(daily_use, 10) * rate"
"snippet('rose', flower, 120)"

בביטויים שכוללים שדות מספריים אפשר להשתמש באופרטורים אריתמטיים (+, -, *, /) ובפונקציות המספריות המובנות שמפורטות בהמשך. בביטויים שכוללים שדות של נקודות גיאוגרפיות אפשר להשתמש בפונקציות geopoint ו-distance. בביטויים של שדות טקסט ו-HTML אפשר להשתמש בפונקציית קטע הקוד.

ביטויים יכולים לכלול גם את המונחים המיוחדים הבאים:

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

פונקציות מספריות

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

תפקיד תיאור דוגמה
max הפונקציה מחזירה את הארגומנט הגדול ביותר. max(recommended_retail_price, discount_price, wholesale_price)
min הפונקציה מחזירה את הארגומנט הקטן ביותר. min(height, width, length)
log הפונקציה מחזירה את הלוגריתם הטבעי. log(x)
abs הפונקציה מחזירה את הערך המוחלט. abs(x)
pow מקבלת שני ארגומנטים מספריים. הקריאה pow(x, y)‎ מחשבת את הערך של x בחזקת y. pow(x, 2)
count מקבל שם שדה כארגומנט. הפונקציה מחזירה את מספר השדות במסמך עם השם הזה. חשוב לזכור שמסמך יכול להכיל כמה שדות מסוגים שונים עם אותו שם. הערה: אפשר להשתמש ב-count רק ב-FieldExpressions. הוא לא יכול להופיע ב-SortExpressions. count(user)

פונקציות של נקודות גיאוגרפיות

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

תפקיד תיאור דוגמה
geopoint מגדיר נקודה גיאוגרפית לפי קו רוחב וקו אורך. geopoint(-31.3, 151.4)
distance הפונקציה מחשבת את המרחק במטרים בין שתי נקודות גיאוגרפיות. שימו לב שאחד משני הארגומנטים יכול להיות השם של שדה של נקודה גיאוגרפית או קריאה לפונקציה של נקודה גיאוגרפית. עם זאת, רק ארגומנט אחד יכול להיות שם של שדה. distance(geopoint(23, 134), store_location)

קטעי קוד

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

snippet(query, body, [max_chars])

query
מחרוזת שאילתה עם מרכאות שמציינת את הטקסט לחיפוש בשדה.
body
השם של שדה טקסט, HTML או atom.
max_chars
מספר התווים המקסימלי שיוחזרו בתקציר. הארגומנט הזה הוא אופציונלי, וברירת המחדל שלו היא 160 תווים.

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