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

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

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

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

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

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

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

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

יצירת מחרוזת שאילתה.
יוצרים SortOptions אם צריך.
יצירת QueryOptions.
יוצרים אובייקט Query שכולל את מחרוזת השאילתה ואת (האופציונלי) QueryOptions.
מבצעים קריאה לשיטת החיפוש באובייקט 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'. שני ערכים מוקצים לשדה 'צבע' של DocA בסדר (אדום, כחול), ושני ערכים מוקצים ל-DocB בסדר (ירוק, אדום). כשמבצעים מיון ומציינים את שדה הטקסט color, המסמך DocA ממוין לפי הערך red והמסמך DocB לפי הערך green. ערכי השדות האחרים לא משמשים למיון.

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

אם לא מציינים אפשרויות מיון, תוצאות החיפוש מוחזרות אוטומטית כשהן ממוינות לפי דירוג בסדר יורד. אין הגבלה על מספר המסמכים שמוחזרים במקרה הזה. אם מציינים אפשרויות מיון, המיון מתבצע אחרי שכל המסמכים התואמים נבחרו. יש מאפיין מפורש, 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. המחרוזת מכילה קטע מהערך של השדה body, עם הטקסט שתאם לשאילתה באותיות מודגשות.

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