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

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

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

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

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

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

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

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