StructuredQuery

שאילתה של Firestore.

שלבי השאילתה מבוצעים בסדר הבא: 1. מתוך 2. כאשר 3. בוחרים 4. orderBy + startAt + endAt 5. היסט 6. limit

ייצוג JSON 
{
  "select": {
    object (Projection)
  },
  "from": [
    {
      object (CollectionSelector)
    }
  ],
  "where": {
    object (Filter)
  },
  "orderBy": [
    {
      object (Order)
    }
  ],
  "startAt": {
    object (Cursor)
  },
  "endAt": {
    object (Cursor)
  },
  "offset": integer,
  "limit": integer,
  "findNearest": {
    object (FindNearest)
  }
}
שדות
select

object (Projection)

קבוצת משנה אופציונלית של השדות שיש להחזיר.

הפעולה הזו פועלת כ-DocumentMask במסמכים שהוחזרו משאילתה. אם המדיניות לא מוגדרת, ההנחה היא שהמתקשר רוצה להחזיר את כל השדות.
from[]

object (CollectionSelector)

האוספים שיש להריץ עליהם שאילתות.
where

object (Filter)

המסנן שצריך להחיל.
orderBy[]

object (Order)

הסדר שבו המערכת תחיל את השאילתה על תוצאות השאילתה.

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

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

השדות מתווספים באותו כיוון מיון כמו הסדר האחרון שצוין, או 'ASCENDING' אם לא צוינה סדר. למשל:

  • ORDER BY a הופך ל-ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC הופך ל-ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 הופך ל-WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 הופך ל-WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
startAt

object (Cursor)

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

הסדר של קבוצת התוצאות מבוסס על הסעיף ORDER BY של השאילתה המקורית.

SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC;

תוצאות השאילתה הזו מסודרות לפי (b ASC, __name__ ASC).

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

בהמשך לדוגמה שלמעלה, לצירוף סמני ההתחלה הבאים תהיה השפעה שונה:

  • START BEFORE (2, /k/123): יש להתחיל את השאילתה ממש לפני a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): התחלת השאילתה מיד אחרי a = 1 AND b > 10.

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

אלה הדרישות שצריך לעמוד בהן:

  • מספר הערכים לא יכול להיות גדול ממספר השדות שצוין בסעיף ORDER BY.
endAt

object (Cursor)

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

היא דומה ל-START_AT אבל היא שולטת במיקום הסיום ולא במיקום ההתחלה.

אלה הדרישות שצריך לעמוד בהן:

  • מספר הערכים לא יכול להיות גדול ממספר השדות שצוין בסעיף ORDER BY.
offset

integer

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

הכלל הזה חל אחרי המגבלות שצוינו בסעיפים WHERE, START AT ו-END AT, אבל לפני הסעיף LIMIT.

אלה הדרישות שצריך לעמוד בהן:

  • אם צוין ערך, הערך צריך להיות גדול מאפס או שווה לו.
limit

integer

המספר המקסימלי של תוצאות שיש להחזיר.

המדיניות חלה אחרי כל שאר המגבלות.

אלה הדרישות שצריך לעמוד בהן:

  • אם צוין ערך, הערך צריך להיות גדול מאפס או שווה לו.
findNearest

object (FindNearest)

זה שינוי אופציונלי. חיפוש 'שכנים קרובים ביותר' פוטנציאלי.

ההגדרה חלה אחרי כל שאר המסננים והסידור.

מוצאת את הטמעות הווקטור הקרובות ביותר לווקטור השאילתה.

היטל

היטל שדות המסמך שיש להחזיר.

ייצוג JSON 
{
  "fields": [
    {
      object (FieldReference)
    }
  ]
}
שדות
fields[]

object (FieldReference)

השדות שיש להחזיר.

אם השדה יישאר ריק, יוחזרו כל השדות. כדי להחזיר רק את שם המסמך, יש להשתמש בפונקציה ['__name__'].

CollectionSelector

מבחר של אוסף, כמו messages as m1.

ייצוג JSON 
{
  "collectionId": string,
  "allDescendants": boolean
}
שדות
collectionId

string

מזהה הקולקציה. כשההגדרה מוגדרת, היא בוחרת רק קולקציות עם המזהה הזה.
allDescendants

boolean

אם הערך הוא False, נבחרים רק אוספים שהם צאצאים מיידיים של parent שצוין ב-RunQueryRequest המכיל. אם הערך הוא True, המערכת בוחרת את כל אוספים הצאצאים.

סינון

מסנן.

ייצוג JSON 
{

  // Union field filter_type can be only one of the following:
  "compositeFilter": {
    object (CompositeFilter)
  },
  "fieldFilter": {
    object (FieldFilter)
  },
  "unaryFilter": {
    object (UnaryFilter)
  }
  // End of list of possible types for union field filter_type.
}
שדות
שדה איחוד filter_type. סוג המסנן. filter_type יכול להיות רק אחד מהבאים:
compositeFilter

object (CompositeFilter)

מסנן מורכב.
fieldFilter

object (FieldFilter)

מסנן בשדה של מסמך.
unaryFilter

object (UnaryFilter)

מסנן שלוקח רק ארגומנט אחד.

CompositeFilter

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

ייצוג JSON 
{
  "op": enum (Operator),
  "filters": [
    {
      object (Filter)
    }
  ]
}
שדות
op

enum (Operator)

האופרטור לשילוב מסננים מרובים.
filters[]

object (Filter)

רשימת המסננים לשילוב.

אלה הדרישות שצריך לעמוד בהן:

  • קיים מסנן אחד לפחות.

מפעיל

אופרטור של מסנן מרוכב.

טיפוסים בני מנייה (enums)
OPERATOR_UNSPECIFIED לא צוין. אי אפשר להשתמש בערך הזה.
AND המסמכים נדרשים כדי להתאים לכל המסננים המשולבים.
OR המסמכים נדרשים כדי להתאים לפחות לאחד מהמסננים המשולבים.

FieldFilter

מסנן בשדה מסוים.

ייצוג JSON 
{
  "field": {
    object (FieldReference)
  },
  "op": enum (Operator),
  "value": {
    object (Value)
  }
}
שדות
field

object (FieldReference)

השדה שלפיו רוצים לסנן.
op

enum (Operator)

האופרטור שלפיו רוצים לסנן.
value

object (Value)

הערך שאליו רוצים להשוות.

מפעיל

אופרטור של מסנן שדות.

טיפוסים בני מנייה (enums)
OPERATOR_UNSPECIFIED לא צוין. אי אפשר להשתמש בערך הזה.
LESS_THAN

הערך של field הנתון קטן מה-value הנתון.

אלה הדרישות שצריך לעמוד בהן:

  • field האלה הגיעו ראשונות ב-orderBy.
LESS_THAN_OR_EQUAL

field הנתון קטן מ-value הנתון או שווה לו.

אלה הדרישות שצריך לעמוד בהן:

  • field האלה הגיעו ראשונות ב-orderBy.
GREATER_THAN

הערך של field גדול מהערך הנתון ב-value.

אלה הדרישות שצריך לעמוד בהן:

  • field האלה הגיעו ראשונות ב-orderBy.
GREATER_THAN_OR_EQUAL

field הנתון גדול מ-value הנתון או שווה לו.

אלה הדרישות שצריך לעמוד בהן:

  • field האלה הגיעו ראשונות ב-orderBy.
EQUAL field הנתון שווה ל-value הנתון.
NOT_EQUAL

field הנתון לא שווה ל-value הנתון.

אלה הדרישות שצריך לעמוד בהן:

  • אין נתונים אחרים מסוג NOT_EQUAL, NOT_IN, IS_NOT_NULL או IS_NOT_NAN.
  • field מגיע ראשון בorderBy.
ARRAY_CONTAINS field הנתון הוא מערך שמכיל את value הנתון.
IN

הערך field הנתון שווה לפחות לערך אחד במערך הנתון.

אלה הדרישות שצריך לעמוד בהן:

  • השדה value הוא ArrayValue שאינו ריק, בכפוף למגבלות המניעה.
  • אין מסננים מסוג NOT_IN באותה שאילתה.
ARRAY_CONTAINS_ANY

field הנתון הוא מערך שמכיל כל אחד מהערכים של המערך הנתון.

אלה הדרישות שצריך לעמוד בהן:

  • השדה value הוא ArrayValue שאינו ריק, בכפוף למגבלות המניעה.
  • אין עוד מסננים של ARRAY_CONTAINS_ANY באותו הפרדה.
  • אין מסננים מסוג NOT_IN באותה שאילתה.
NOT_IN

הערך של field לא נמצא במערך הנתון.

אלה הדרישות שצריך לעמוד בהן:

  • השדה value הוא ArrayValue לא ריק עם 10 ערכים לכל היותר.
  • אין נתונים אחרים מסוג OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL או IS_NOT_NAN.
  • field מגיע ראשון בorderBy.

UnaryFilter

מסנן עם אופרנד יחיד.

ייצוג JSON 
{
  "op": enum (Operator),

  // Union field operand_type can be only one of the following:
  "field": {
    object (FieldReference)
  }
  // End of list of possible types for union field operand_type.
}
שדות
op

enum (Operator)

האופרטור Unary יש להחיל.
שדה איחוד operand_type. הארגומנט של המסנן. operand_type יכול להיות רק אחד מהבאים:
field

object (FieldReference)

השדה שעליו יש להחיל את האופרטור.

מפעיל

אופרטור אונרי.

טיפוסים בני מנייה (enums)
OPERATOR_UNSPECIFIED לא צוין. אי אפשר להשתמש בערך הזה.
IS_NAN field הנתון שווה ל-NaN.
IS_NULL field הנתון שווה ל-NULL.
IS_NOT_NAN

field הנתון לא שווה ל-NaN.

אלה הדרישות שצריך לעמוד בהן:

  • אין נתונים אחרים מסוג NOT_EQUAL, NOT_IN, IS_NOT_NULL או IS_NOT_NAN.
  • field מגיע ראשון בorderBy.
IS_NOT_NULL

field הנתון לא שווה ל-NULL.

אלה הדרישות שצריך לעמוד בהן:

  • NOT_EQUAL, NOT_IN, IS_NOT_NULL, או IS_NOT_NAN.
  • field מגיע ראשון בorderBy.

הזמנה

הזמנה בשדה.

ייצוג JSON 
{
  "field": {
    object (FieldReference)
  },
  "direction": enum (Direction)
}
שדות
field

object (FieldReference)

השדה שלפיו רוצים לסדר.
direction

enum (Direction)

הכיוון שלפיו יש לסדר. ברירת המחדל היא ASCENDING.

כיוון

כיוון המיון.

טיפוסים בני מנייה (enums)
DIRECTION_UNSPECIFIED לא צוין.
ASCENDING סדר עולה.
DESCENDING בסדר יורד.

FindNearest

הגדרת החיפוש 'בשכנים הקרובים ביותר'.

ייצוג JSON 
{
  "vectorField": {
    object (FieldReference)
  },
  "queryVector": {
    object (Value)
  },
  "distanceMeasure": enum (DistanceMeasure),
  "limit": integer
}
שדות
vectorField

object (FieldReference)

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

object (Value)

חובה. וקטור השאילתה שאנחנו מחפשים. חייב להיות וקטור של עד 2,048 מאפיינים.
distanceMeasure

enum (DistanceMeasure)

חובה. מידת המרחק שבה יש להשתמש, חובה.
limit

integer

חובה. מספר השכנים הקרובים ביותר שיש להחזיר. מספר שלם חיובי שאינו עולה על 1000.

DistanceMeasure

מידת המרחק לשימוש בעת השוואה בין וקטורים.

טיפוסים בני מנייה (enums)
DISTANCE_MEASURE_UNSPECIFIED לא צריך להיות מוגדר.
EUCLIDEAN מדידת המרחק של האיחוד האירופי (EUCLIDEAN) בין הווקטורים. למידע נוסף, ראו אוקלידית
COSINE משווה בין וקטורים על סמך הזווית ביניהם, מה שמאפשר לכם למדוד דמיון שלא מבוסס על גודל הווקטורים. מומלץ להשתמש ב-DOT_PRODUCT עם וקטורים מנורמלים של יחידות במקום מרחק COSINE, שהוא שווה ערך מתמטי עם ביצועים טובים יותר. למידע נוסף, ראה Cosineמאפיינים דומים.
DOT_PRODUCT דומה לקוסינוס אבל מושפע מגודל הווקטורים. מידע נוסף זמין ב-Dot Product.