Package google.firestore.v1beta1

אינדקס

Firestore

שירות Cloud Firestore.

Cloud Firestore הוא מסד נתונים מסוג NoSQL מהיר, מנוהל ללא שרת ומבוסס-ענן, שהופך את האחסון, הסנכרון וההרצת שאילתות על נתונים מאפליקציות לנייד, לאינטרנט ול-IoT בקנה מידה גלובלי. ספריות הלקוח שלה מספקות סנכרון בזמן אמת ותמיכה אופליין. תכונות האבטחה והשילובים שלה עם Firebase ו-Google Cloud Platform מאיצים יצירה של אפליקציות ללא שרת (serverless).

BatchGetDocuments

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

מקבלת מספר מסמכים.

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

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

BatchWrite

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

מחיל קבוצה של פעולות כתיבה.

שיטת BatchWrite לא מחילה את פעולות הכתיבה באופן אטומי ויכולה להחיל אותן שלא לפי הסדר. השיטה לא מאפשרת כתיבה אחת לכל מסמך. כל כתיבה מצליחה או נכשלת בנפרד. בBatchWriteResponse ניתן לראות את סטטוס ההצלחה של כל כתיבה.

אם יש צורך בקבוצת כתבים שהוחלה באופן אטומי, צריך להשתמש במקום זאת ב-Commit.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

BeginTransaction

rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse)

התחלת עסקה חדשה.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

בצע

rpc Commit(CommitRequest) returns (CommitResponse)

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

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

CreateDocument

rpc CreateDocument(CreateDocumentRequest) returns (Document)

יצירת מסמך חדש.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

DeleteDocument

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

מחיקת מסמך.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

GetDocument

rpc GetDocument(GetDocumentRequest) returns (Document)

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

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

ListCollectionIds

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

הצגת כל מזהי האוספים מתחת למסמך.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

ListDocuments

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

הצגת רשימה של מסמכים.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

האזנה

rpc Listen(ListenRequest) returns (ListenResponse)

מקשיב לשינויים. השיטה הזו זמינה רק דרך gRPC או WebChannel (לא REST).

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

PartitionQuery

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse)

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

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

חזרה למצב קודם

rpc Rollback(RollbackRequest) returns (Empty)

מבטל את העסקה.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

RunAggregationQuery

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse)

מריצה שאילתת צבירה.

במקום להניב תוצאות מסוג Document כמו Firestore.RunQuery, ה-API הזה מאפשר להריץ נתוני צבירה כדי לייצר סדרה של AggregationResult בצד השרת.

דוגמה לרמה גבוהה:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

RunQuery

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

מריץ שאילתה.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

UpdateDocument

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

מעדכן או מוסיף מסמך.

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

כתיבה

rpc Write(WriteRequest) returns (WriteResponse)

משדרים קבוצות של עדכונים ומחיקה של מסמכים, לפי סדר. השיטה הזו זמינה רק דרך gRPC או WebChannel (לא REST).

היקפי הרשאות

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

  • https://www.googleapis.com/auth/datastore
  • https://www.googleapis.com/auth/cloud-platform

מידע נוסף זמין בסקירה הכללית על אימות.

AggregationResult

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

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

שדות
aggregate_fields

map<string, Value>

התוצאה של פונקציות הצבירה, לדוגמה: COUNT(*) AS total_docs.

המפתח הוא alias שהוקצה לפונקציית הצבירה בקלט, והגודל של המפה הזו שווה למספר פונקציות הצבירה בשאילתה.

ArrayValue

ערך של מערך.

שדות
values[]

Value

ערכים במערך.

BatchGetDocumentsRequest

הבקשה על Firestore.BatchGetDocuments.

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

documents[]

string

שמות המסמכים שיש לאחזר. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}. הבקשה תיכשל אם מסמך כלשהו אינו משאב צאצא של database הנתון. שמות כפולים יוסרו.

mask

DocumentMask

השדות שיש להחזיר. אם המדיניות לא מוגדרת, כל השדות מוחזרים.

אם מסמך כולל שדה שלא נמצא במסכה הזו, השדה הזה לא יוחזר.

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

bytes

קריאת מסמכים בעסקה.

new_transaction

TransactionOptions

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

read_time

Timestamp

קריאת מסמכים כפי שהם היו בזמן הנתון.

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

BatchGetDocumentsResponse

התשובה שהועברה בסטרימינג עבור Firestore.BatchGetDocuments.

שדות
transaction

bytes

העסקה שהתחילה כחלק מהבקשה הזו. תוגדר רק בתגובה הראשונה, ורק אם הוגדר BatchGetDocumentsRequest.new_transaction בבקשה.

read_time

Timestamp

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

שדה איחוד result. תוצאה אחת. השדה הזה יכול להיות ריק אם השרת רק מחזיר עסקה. result יכול להיות רק אחד מהבאים:
found

Document

המסמך המבוקש.

missing

string

שם המסמך שהתבקש, אבל לא קיים. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}.

BatchWriteRequest

הבקשה על Firestore.BatchWrite.

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

writes[]

Write

הכתיבה שצריך להחיל.

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

labels

map<string, string>

תוויות המשויכות לקיבוץ זה של כתיבה.

BatchWriteResponse

התשובה של Firestore.BatchWrite.

שדות
write_results[]

WriteResult

התוצאה של החלת הכתיבה.

תוצאת הכתיבה ה-i תואמת לכתיבה ה-i שבבקשה.

status[]

Status

הסטטוס של החלת כתבי היד.

סטטוס הכתיבה ה-i-th תואם לכתיבה ה-i-th שבבקשה.

BeginTransactionRequest

הבקשה על Firestore.BeginTransaction.

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

options

TransactionOptions

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

BeginTransactionResponse

התשובה עבור Firestore.BeginTransaction.

שדות
transaction

bytes

העסקה שהתחילה.

BitSequence

רצף של ביטים שמקודדים במערך של בייטים.

כל בייט במערך של bitmap בייטים מאחסן 8 ביטים מהרצף. יוצא הדופן היחיד הוא הבייט האחרון, שעשוי לאחסן 8 או פחות ביטים. השדה padding מגדיר את מספר הביטים בבייט האחרון שהמערכת תתעלם מהם כ-'מרווח פנימי'. הערכים של הביטים האלה מסוג 'מרווח פנימי' לא צוינו וצריך להתעלם מהם.

כדי לאחזר את הביט הראשון, צריך לחשב את: (bitmap[0] & 0x01) != 0. כדי לאחזר את הביט השני, סיביות 1, מחשבים את: (bitmap[0] & 0x02) != 0. כדי לאחזר את הביט השלישי, סיביות 2, מחשבים את: (bitmap[0] & 0x04) != 0. כדי לאחזר את הביט הרביעי, סיביות 3, מחשבים את: (bitmap[0] & 0x08) != 0. כדי לאחזר את הביט n, צריך לחשב את: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

ה "גודל" של BitSequence (מספר הביטים שהוא מכיל) מחושב באמצעות הנוסחה הבאה: (bitmap.length * 8) - padding.

שדות
bitmap

bytes

הבייטים שמקודדים את רצף הביטים. יכול להיות שהאורך שלו הוא אפס.

padding

int32

מספר הביטים בבייט האחרון ב-bitmap שיש להתעלם מהם בתור 'מרווח פנימי'. אם האורך של bitmap הוא אפס, הערך הזה חייב להיות 0. אחרת, הערך הזה חייב להיות בין 0 ל-7, כולל.

BloomFilter

מסנן פריחה (https://en.wikipedia.org/wiki/Bloom_filter).

מסנן ה-Bloom מבצע גיבוב (hash) של הרשומות באמצעות MD5 ומתייחס לגיבוב שנוצר של 128 סיביות שמתקבל כ-2 ערכי גיבוב נפרדים של 64 סיביות, שמפוענחים כמספרים שלמים לא חתומים באמצעות קידוד השלמה של 2.

שני ערכי הגיבוב האלה, שנקראים h1 ו-h2, משמשים לאחר מכן לחישוב ערכי הגיבוב של hash_count באמצעות הנוסחה, החל מ-i=0:

h(i) = h1 + (i * h2)

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

שדות
bits

BitSequence

נתוני סינון הפריחה.

hash_count

int32

מספר הגיבובים שהאלגוריתם משתמש בהם.

CommitRequest

הבקשה על Firestore.Commit.

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

writes[]

Write

הכתיבה שצריך להחיל.

מופעל תמיד באופן אטומי ובסדר.

transaction

bytes

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

CommitResponse

התשובה עבור Firestore.Commit.

שדות
write_results[]

WriteResult

התוצאה של החלת הכתיבה.

תוצאת הכתיבה ה-i תואמת לכתיבה ה-i שבבקשה.

commit_time

Timestamp

השעה שבה התרחשה ההתחייבות. לכל קריאה עם ערך read_time שווה או גדול יותר מובטח לראות את ההשפעה של ההתחייבות.

CreateDocumentRequest

הבקשה על Firestore.CreateDocument.

שדות
parent

string

חובה. משאב ההורה. לדוגמה: projects/{project_id}/databases/{database_id}/documents או projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}

collection_id

string

חובה. מזהה הקולקציה, ביחס ל-parent, לרשימה. לדוגמה: chatrooms.

document_id

string

מזהה המסמך שהוקצה על ידי הלקוח וצריך להשתמש בו במסמך הזה.

זה שינוי אופציונלי. אם לא מציינים זאת, השירות יקצה מזהה.

document

Document

חובה. המסמך ליצירה. לא ניתן להגדיר name.

mask

DocumentMask

השדות שיש להחזיר. אם המדיניות לא מוגדרת, כל השדות מוחזרים.

אם המסמך כולל שדה שלא נמצא במסכה הזו, השדה הזה לא יוחזר.

סמן

מיקום בקבוצת תוצאות של שאילתה.

שדות
values[]

Value

הערכים שמייצגים מיקום, בסדר שבו הם מופיעים, לפי סדר המילים בשאילתה.

הערך יכול להכיל פחות ערכים שצוינו בסדר לפי סעיף.

before

bool

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

DeleteDocumentRequest

הבקשה על Firestore.DeleteDocument.

שדות
name

string

חובה. שם המשאב של המסמך למחיקה. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}.

current_document

Precondition

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

מסמך

מסמך של Firestore.

1MiB עד 4 בייטים.

שדות
name

string

שם המשאב של המסמך, למשל projects/{project_id}/databases/{database_id}/documents/{document_path}.

fields

map<string, Value>

create_time

Timestamp

פלט בלבד. השעה שבה המסמך נוצר.

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

update_time

Timestamp

פלט בלבד. מועד השינוי האחרון של המסמך.

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

DocumentChange

Document השתנה.

ייתכן שכתוצאה מכך writes מרובים, כולל מחיקות, הובילו בסופו של דבר לערך חדש עבור Document.

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

שדות
document

Document

המצב החדש של Document.

אם המדיניות mask מוגדרת, היא מכילה רק שדות שעודכנו או נוספו.

target_ids[]

int32

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

removed_target_ids[]

int32

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

DocumentDelete

בוצעה מחיקה של Document.

ייתכן שהסיבה היא writes מרובים, כולל עדכונים, שהאחרון בהם מחק את Document.

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

שדות
document

string

שם המשאב של Document שנמחק.

removed_target_ids[]

int32

קבוצה של מזהי יעדים של יעדים שתאמו בעבר לישות הזו.

read_time

Timestamp

חותמת הזמן של הקריאה שבה זוהתה פעולת המחיקה.

גדול או שווה ל-commit_time של המחיקה.

DocumentMask

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

שדות
field_paths[]

string

רשימה של נתיבי השדות במסכה. אפשר לראות הסבר על תחביר של נתיבי שדות בכתובת Document.fields.

DocumentRemove

Document הוסר מהתצוגה של היעדים.

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

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

שדות
document

string

שם המשאב של Document שלא נמצא בתצוגה.

removed_target_ids[]

int32

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

read_time

Timestamp

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

גדול או שווה ל-commit_time של השינוי/מחיקה/הסרה.

DocumentTransform

טרנספורמציה של מסמך.

שדות
document

string

שם המסמך להמרה.

field_transforms[]

FieldTransform

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

FieldTransform

טרנספורמציה של שדה במסמך.

שדות
field_path

string

הנתיב של השדה. מידע על תחביר של נתיבי שדות מופיע בכתובת Document.fields.

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

ServerValue

מגדיר את השדה לערך הנתון של השרת.

increment

Value

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

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

maximum

Value

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

חייב להיות מספר שלם או ערך כפול. אם השדה אינו מספר שלם או כפול, או אם השדה עדיין לא קיים, הטרנספורמציה תגדיר את השדה לערך הנתון. אם פעולה מקסימלית מיושמת כאשר השדה וערך הקלט הם מסוגים מעורבים (כלומר: אחד הוא מספר שלם ואחד הוא כפול), השדה הזה יקבל את סוג האופרנד הגדול יותר. אם האופרנדים הם שווי ערך (למשל 3 ו-3.0), השדה לא משתנה. הערכים 0, 0.0 ו-0.0 הם אפס. הערך המקסימלי של ערך מאוחסן של אפס וערך קלט של אפס הוא תמיד הערך שמאוחסן. הערך המקסימלי של כל ערך מספרי x ו-NaN הוא NaN.

minimum

Value

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

חייב להיות מספר שלם או ערך כפול. אם השדה אינו מספר שלם או כפול, או אם השדה עדיין לא קיים, הטרנספורמציה תגדיר את השדה לערך הקלט. אם פעולה מינימלית מיושמת כאשר השדה וערך הקלט הם מסוגים מעורבים (כלומר, אחד הוא מספר שלם ואחד הוא כפול), השדה קטן יותר לפי סוג האופרנד הקטן יותר. אם האופרנדים הם שווי ערך (למשל 3 ו-3.0), השדה לא משתנה. הערכים 0, 0.0 ו-0.0 הם אפס. הערך המינימלי של ערך מאוחסן של אפס וערך קלט של אפס הוא תמיד הערך שמאוחסן. המינימום של כל ערך מספרי x ו-NaN הוא NaN.

append_missing_elements

ArrayValue

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

מספרים שווים מסוגים שונים (למשל 3L ו-3.0) נחשבים שווים כשבודקים אם חסר ערך. NaN שווה ל-NaN, ו-Null שווה ל-Null. אם הקלט מכיל כמה ערכים שווים, רק הערך הראשון ייכלל.

תוצאת הטרנספורמציה המתאימה תהיה הערך null.

remove_all_from_array

ArrayValue

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

מספרים שווים מהסוגים השונים (למשל 3L ו-3.0) נחשבים שווים כשמחליטים אם להסיר רכיב. NaN שווה ל-NaN, ו-Null שווה ל-Null. פעולה זו תסיר את כל הערכים המקבילים אם יש כפילויות.

תוצאת הטרנספורמציה המתאימה תהיה הערך null.

ServerValue

ערך שמחושב על ידי השרת.

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

ExecutionStats

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

שדות
results_returned

int64

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

execution_duration

Duration

הזמן הכולל לביצוע השאילתה בקצה העורפי.

read_operations

int64

סך כל פעולות הקריאה הניתנות לחיוב.

debug_stats

Struct

ניפוי באגים של נתונים סטטיסטיים מהפעלת השאילתה. שימו לב שהנתונים הסטטיסטיים של ניפוי הבאגים עשויים להשתנות עם ההתפתחות של Firestore. It could include: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } }

ExistenceFilter

תקציר של כל המסמכים שתואמים ליעד מסוים.

שדות
target_id

int32

מזהה היעד שעליו המסנן חל.

count

int32

המספר הכולל של מסמכים שתואמים ל-target_id.

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

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

unchanged_names

BloomFilter

מסנן פריחה שלמרות השם שלו, מכיל קידודים מסוג UTF-8 בייטים של שמות המשאבים של כל המסמכים שתואמים ל-target_id, בצורה projects/{project_id}/databases/{database_id}/documents/{document_path}.

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

ExplainMetrics

הסבר למדדים של השאילתה.

שדות
plan_summary

PlanSummary

מידע על שלב התכנון עבור השאילתה.

execution_stats

ExecutionStats

נתונים סטטיסטיים מצטברים מביצוע השאילתה. מוצג רק אם המדיניות ExplainOptions.analyze מוגדרת כ-True.

ExplainOptions

להסביר את האפשרויות של השאילתה.

שדות
analyze

bool

זה שינוי אופציונלי. האם להפעיל את השאילתה הזו.

כשהערך הוא False (ברירת המחדל), השאילתה תתוזמן ויוצגו רק המדדים משלבי התכנון.

אם הערך הוא True, השאילתה תתוכננו ותבוצע, והיא תחזיר את תוצאות השאילתה המלאות יחד עם המדדים של שלב התכנון ושל הביצוע.

GetDocumentRequest

הבקשה על Firestore.GetDocument.

שדות
name

string

חובה. שם המשאב שיש לקבל במסמך. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}.

mask

DocumentMask

השדות שיש להחזיר. אם המדיניות לא מוגדרת, כל השדות מוחזרים.

אם המסמך כולל שדה שלא נמצא במסכה הזו, השדה הזה לא יוחזר.

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

bytes

קורא את המסמך בעסקה.

read_time

Timestamp

קורא את גרסת המסמך בזמן הנתון.

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

ListCollectionIdsRequest

הבקשה על Firestore.ListCollectionIds.

שדות
parent

string

חובה. מסמך ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}. לדוגמה: projects/my-project/databases/my-database/documents/chatrooms/my-chatroom.

page_size

int32

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

page_token

string

אסימון דף. חייב להיות ערך מ-ListCollectionIdsResponse.

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

Timestamp

קריאת מסמכים כפי שהם היו בזמן הנתון.

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

ListCollectionIdsResponse

התשובה של Firestore.ListCollectionIds.

שדות
collection_ids[]

string

מזהי הקולקציות

next_page_token

string

אסימון דף שיכול לשמש להמשך הרשימה.

ListDocumentsRequest

הבקשה על Firestore.ListDocuments.

שדות
parent

string

חובה. השם של משאב ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents או projects/{project_id}/databases/{database_id}/documents/{document_path}.

לדוגמה: projects/my-project/databases/my-database/documents או projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

collection_id

string

זה שינוי אופציונלי. מזהה הקולקציה, ביחס ל-parent, לרשימה.

לדוגמה: chatrooms או messages.

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

page_size

int32

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

Firestore עשוי להחזיר פחות מהערך הזה.

page_token

string

זה שינוי אופציונלי. אסימון דף שהתקבל מתגובה קודמת של ListDocuments.

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

order_by

string

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

לדוגמה: priority desc, __name__ desc.

הפעולה הזו משקפת את ORDER BY שנעשה בו שימוש בשאילתות של Firestore אבל בייצוג מחרוזות. אם חסר מידע, המסמכים יסודרו לפי __name__ ASC.

mask

DocumentMask

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

אם מסמך כולל שדה שלא נמצא במסכה הזו, השדה הזה לא יוחזר.

show_missing

bool

אם ברשימה אמורים להופיע מסמכים חסרים.

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

בבקשות עם show_missing אסור לציין where או order_by.

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

bytes

מבצעים את הקריאה כחלק מעסקה שכבר פעילה.

read_time

Timestamp

ביצוע הקריאה בזמן המתאים.

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

ListDocumentsResponse

התשובה עבור Firestore.ListDocuments.

שדות
documents[]

Document

המסמכים שנמצאו.

next_page_token

string

אסימון לאחזור דף המסמכים הבא.

אם השדה הזה יושמט, לא יהיו דפים עוקבים.

ListenRequest

בקשה עבור Firestore.Listen

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

labels

map<string, string>

תוויות שמשויכות ליעד הזה השתנו.

שדה איחוד target_change. היעדים הנתמכים משתנים. target_change יכול להיות רק אחד מהבאים:
add_target

Target

יעד שאפשר להוסיף לשידור הזה.

remove_target

int32

המזהה של היעד שיש להסיר ממקור הנתונים הזה.

ListenResponse

התשובה עבור Firestore.Listen.

שדות
שדה איחוד response_type. התשובות הנתמכות. response_type יכול להיות רק אחד מהבאים:
target_change

TargetChange

היעדים השתנו.

document_change

DocumentChange

Document השתנה.

document_delete

DocumentDelete

בוצעה מחיקה של Document.

document_remove

DocumentRemove

בוצעה הסרה של Document מהיעד (כי הוא כבר לא רלוונטי ליעד הזה).

filter

ExistenceFilter

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

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

MapValue

ערך מפה.

שדות
fields

map<string, Value>

השדות במפה.

מקשי המפה מייצגים שמות של שדות. שמות השדות התואמים לביטוי הרגולרי __.*__ שמורים. שמות שדות שמורים אסורים, מלבד בהקשרים מתועדים מסוימים. מפתחות המפה, המיוצגים כ-UTF-8, לא יכולים לחרוג מ-1,500 בייטים ולא יכולים להיות ריקים.

PartitionQueryRequest

הבקשה על Firestore.PartitionQuery.

שדות
parent

string

חובה. השם של משאב ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents. אין תמיכה בשמות של משאבי מסמכים. ניתן לציין רק שמות של משאבים של מסד נתונים.

partition_count

int64

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

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

page_token

string

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

לדוגמה, שתי קריאות עוקבות באמצעות page_token עשויות להחזיר:

  • סמן B, סמן M, סמן Q
  • סמן A, סמן U, סמן W

לקבלת קבוצת תוצאות מלאה לפי הסדר ביחס לתוצאות השאילתה שסופקה ל-partitionQuery, יש למזג את קבוצות התוצאות: סמן A, סמן B, סמן M, סמן Q, סמן U, סמן W

page_size

int32

מספר המחיצות המקסימלי שאפשר להחזיר בשיחה הזו, בכפוף ל-partition_count.

לדוגמה, אם partition_count = 10 ו-page_size = 8, הקריאה הראשונה ל-partitionQuery תחזיר עד 8 מחיצות ו-next_page_token אם קיימות תוצאות נוספות. קריאה שנייה ל-partitionQuery תחזיר עד שתי מחיצות, ותשלים את ה-10 שצוינו ב-partition_count.

שדה איחוד query_type. השאילתה לחלוקה למחיצות. query_type יכול להיות רק אחד מהבאים:
structured_query

StructuredQuery

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

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

Timestamp

קריאת מסמכים כפי שהם היו בזמן הנתון.

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

PartitionQueryResponse

התשובה עבור Firestore.PartitionQuery.

שדות
partitions[]

Cursor

תוצאות החלוקה. כל מחיצה היא נקודת פיצול שיכולה לשמש את RunQuery כנקודת התחלה או יעד של תוצאות השאילתה. בקשות RunQuery חייבות להתבצע עם אותה שאילתה שסופקה לבקשת ה-partitionQuery הזו. סמני המחיצות מסודרים לפי אותו סדר כמו תוצאות השאילתה שסופקו ל-partitionQuery.

לדוגמה, אם בקשתpartitionQuery מחזירה את סמני המחיצות A ו-B, הרצת שלוש השאילתות הבאות תחזיר את כל קבוצת התוצאות של השאילתה המקורית:

  • שאילתה, end_at A
  • שאילתה, start_at A, end_at B
  • שאילתה, start_at B

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

next_page_token

string

אסימון דף שיכול לשמש לבקשת קבוצה נוספת של תוצאות, עד למספר שצוין על ידי partition_count בבקשת ה-partitionQuery. אם השדה יישאר ריק, לא יהיו תוצאות נוספות.

PlanSummary

מידע על שלב התכנון עבור השאילתה.

שדות
indexes_used[]

Struct

האינדקסים שנבחרו לשאילתה. For example: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

תנאי מוקדם

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

שדות
שדה איחוד condition_type. הסוג של התנאי המוקדם. condition_type יכול להיות רק אחד מהבאים:
exists

bool

אם המדיניות מוגדרת לערך true, מסמך היעד חייב להיות קיים. כשמגדירים את הערך false, מסמך היעד לא יכול להיות קיים.

update_time

Timestamp

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

RollbackRequest

הבקשה על Firestore.Rollback.

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}.

transaction

bytes

חובה. העסקה להחזרה למצב הקודם.

RunAggregationQueryRequest

הבקשה על Firestore.RunAggregationQuery.

שדות
parent

string

חובה. השם של משאב ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents או projects/{project_id}/databases/{database_id}/documents/{document_path}. לדוגמה: projects/my-project/databases/my-database/documents או projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

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

שדה איחוד query_type. השאילתה להרצה. query_type יכול להיות רק אחד מהבאים:
structured_aggregation_query

StructuredAggregationQuery

שאילתת צבירה.

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

bytes

הפעל את הצבירה בתוך עסקה שכבר פעילה.

הערך כאן הוא מזהה העסקה השקוף שבו צריך לבצע את השאילתה.

new_transaction

TransactionOptions

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

מזהה העסקה החדש יוחזר כתגובה הראשונה בשידור.

read_time

Timestamp

מפעיל את השאילתה בחותמת הזמן הנתונה.

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

RunAggregationQueryResponse

התשובה עבור Firestore.RunAggregationQuery.

שדות
result

AggregationResult

תוצאת צבירה אחת.

לא קיים בדיווח על התקדמות חלקית.

transaction

bytes

העסקה שהתחילה כחלק מהבקשה הזו.

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

read_time

Timestamp

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

אם השאילתה לא מחזירה תוצאות, תישלח תשובה עם read_time וללא result, שמייצגת את השעה שבה השאילתה רצה.

explain_metrics

ExplainMetrics

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

RunQueryRequest

הבקשה על Firestore.RunQuery.

שדות
parent

string

חובה. השם של משאב ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents או projects/{project_id}/databases/{database_id}/documents/{document_path}. לדוגמה: projects/my-project/databases/my-database/documents או projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

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

שדה איחוד query_type. השאילתה להרצה. query_type יכול להיות רק אחד מהבאים:
structured_query

StructuredQuery

שאילתה מובנית.

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

bytes

מריצים את השאילתה בעסקה שכבר פעילה.

הערך כאן הוא מזהה העסקה השקוף שבו צריך לבצע את השאילתה.

new_transaction

TransactionOptions

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

read_time

Timestamp

קריאת מסמכים כפי שהם היו בזמן הנתון.

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

RunQueryResponse

התשובה עבור Firestore.RunQuery.

שדות
transaction

bytes

העסקה שהתחילה כחלק מהבקשה הזו. אפשר להגדיר זאת רק בתגובה הראשונה, ורק אם הוגדר בבקשה RunQueryRequest.new_transaction. אם המדיניות מוגדרת, לא יוגדרו שדות אחרים בתגובה הזו.

document

Document

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

read_time

Timestamp

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

אם השאילתה לא מחזירה תוצאות, תישלח תשובה עם read_time וללא document, שמייצגת את השעה שבה השאילתה רצה.

skipped_results

int32

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

explain_metrics

ExplainMetrics

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

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

bool

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

StructuredAggregationQuery

שאילתה ב-Firestore להפעלת צבירה ב-StructuredQuery.

שדות
aggregations[]

Aggregation

זה שינוי אופציונלי. סדרת הצבירה שיחולו על התוצאות של structured_query.

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

  • לפחות צבירת נתונים אחת ועד חמישה צבירת נתונים לכל שאילתה.
שדה איחוד query_type. השאילתה הבסיסית לצבירה. query_type יכול להיות רק אחד מהבאים:
structured_query

StructuredQuery

שאילתה מובנית בתוך שאילתה.

צבירה

מגדירה צבירה שיוצרת תוצאה אחת.

שדות
alias

string

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

אם לא תספקו שם, Firestore תבחר שם ברירת מחדל בפורמט field_<incremental_id++>. למשל:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2),
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*)
OVER (
  ...
);

הופך ל:

AGGREGATE
  COUNT_UP_TO(1) AS count_up_to_1,
  COUNT_UP_TO(2) AS field_1,
  COUNT_UP_TO(3) AS count_up_to_3,
  COUNT(*) AS field_2
OVER (
  ...
);

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

  • המזהה צריך להיות ייחודי בכל כתובות האימייל החלופיות לצבירה.
  • צריך לפעול בהתאם להגבלות של document field name.
שדה איחוד operator. סוג הצבירה לבצע, נדרש. operator יכול להיות רק אחד מהבאים:
count

Count

אתר אגרגטור של ספירות.

sum

Sum

צובר סכומים.

avg

Avg

אתר אגרגטור ממוצע.

Avg

ממוצע הערכים של השדה המבוקש.

  • רק ערכים מספריים יצטברו. המערכת תדלג על כל הערכים הלא מספריים, כולל NULL.

  • אם הערכים המצטברים מכילים NaN, הפונקציה מחזירה NaN. מתמטית אינסופית עומדת בתקני IEEE-754.

  • אם קבוצת הערכים הנצברים ריקה, הפונקציה מחזירה NULL.

  • מחזירה תמיד את התוצאה כ-double.

שדות
field

FieldReference

השדה שבו תתבצע צבירה.

מספר פעמים

ספירת המסמכים שתואמים לשאילתה.

פונקציית הצבירה COUNT(*) פועלת על כל המסמך ולכן לא נדרשת הפניה לשדה.

שדות
up_to

Int64Value

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

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

המשמעות של 'לא צוין' היא 'ללא הגבלה'.

דוגמה לרמה גבוהה:

AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k );

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

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

סכום

סכום הערכים של השדה המבוקש.

  • רק ערכים מספריים יצטברו. המערכת תדלג על כל הערכים הלא מספריים, כולל NULL.

  • אם הערכים המצטברים מכילים NaN, הפונקציה מחזירה NaN. מתמטית אינסופית עומדת בתקני IEEE-754.

  • אם קבוצת הערכים הנצברים היא ריקה, הפונקציה מחזירה 0.

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

  • במקרה של תת-זרימה, צבירת נתונים בנקודה צפה (floating-point) אינה דטרמיניסטית. המשמעות היא שאם תריץ את אותה שאילתה שוב ושוב ללא שינויים בערכים הבסיסיים, תוכל להפיק תוצאות מעט שונות בכל פעם. במקרים כאלה, צריך לאחסן את הערכים כמספרים שלמים מעל למספרים עם נקודה צפה (floating-point).

שדות
field

FieldReference

השדה שבו תתבצע צבירה.

StructuredQuery

שאילתה של Firestore.

שלבי השאילתה מבוצעים בסדר הבא: 1. מתוך 2. כאשר 3. בוחרים 4. order_by + start_at + end_at 5. היסט 6. מגבלה

שדות
select

Projection

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

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

from[]

CollectionSelector

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

where

Filter

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

order_by[]

Order

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

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

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

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.
end_at

Cursor

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

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

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

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

int32

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

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

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

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

Int32Value

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

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

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

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

FindNearest

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

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

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

CollectionSelector

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

שדות
collection_id

string

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

all_descendants

bool

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

CompositeFilter

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

שדות
op

Operator

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

filters[]

Filter

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

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

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

מפעיל

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

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

כיוון

כיוון המיון.

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

FieldFilter

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

שדות
field

FieldReference

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

op

Operator

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

value

Value

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

מפעיל

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • אין נתונים אחרים מסוג NOT_EQUAL, NOT_IN, IS_NOT_NULL או IS_NOT_NAN.
  • field מגיע ראשון בorder_by.
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 מגיע ראשון בorder_by.

FieldReference

הפניה לשדה במסמך, לדוגמה: stats.operations.

שדות
field_path

string

הפניה לשדה במסמך.

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

  • מחרוזת קטעים מופרדת באמצעות נקודות (.), שבה כל מקטע עומד במגבלות של document field name.

סינון

מסנן.

שדות
שדה איחוד filter_type. סוג המסנן. filter_type יכול להיות רק אחד מהבאים:
composite_filter

CompositeFilter

מסנן מורכב.

field_filter

FieldFilter

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

unary_filter

UnaryFilter

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

FindNearest

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

שדות
vector_field

FieldReference

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

query_vector

Value

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

distance_measure

DistanceMeasure

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

limit

Int32Value

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

DistanceMeasure

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

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

הזמנה

הזמנה בשדה.

שדות
field

FieldReference

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

direction

Direction

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

היטל

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

שדות
fields[]

FieldReference

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

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

UnaryFilter

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

שדות
op

Operator

האופרטור Unary יש להחיל.

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

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 מגיע ראשון בorder_by.
IS_NOT_NULL

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

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

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

לטירגוט

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

שדות
target_id

int32

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

אם הערך של target_id הוא 0 (או שלא צוין), השרת יקצה מזהה ליעד הזה ויחזיר אותו באירוע TargetChange::ADD. לאחר הוספת יעד עם target_id=0, כל היעדים הבאים חייבים לכלול גם target_id=0. אם בקשת AddTarget עם target_id != 0 נשלחת לשרת לאחר שנוסף יעד עם target_id=0, השרת ישלח באופן מיידי תגובה עם אירוע TargetChange::Remove.

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

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

once

bool

אם צריך להסיר את היעד אחרי שהוא עדכני ועקבי.

expected_count

Int32Value

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

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

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

QueryTarget

יעד שצוין על ידי שאילתה.

documents

DocumentsTarget

יעד שצוין על ידי קבוצה של שמות מסמכים.

שדה איחוד resume_type. מתי להתחיל להאזין.

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

resume_token

bytes

אסימון קורות חיים מתאריך TargetChange קודם ליעד זהה.

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

read_time

Timestamp

התחלת ההאזנה אחרי read_time ספציפי.

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

DocumentsTarget

יעד שצוין על ידי קבוצה של שמות מסמכים.

שדות
documents[]

string

שמות המסמכים שיש לאחזר. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}. הבקשה תיכשל אם מסמך כלשהו אינו משאב צאצא של database הנתון. שמות כפולים יוסרו.

QueryTarget

יעד שצוין על ידי שאילתה.

שדות
parent

string

השם של משאב ההורה. בפורמט: projects/{project_id}/databases/{database_id}/documents או projects/{project_id}/databases/{database_id}/documents/{document_path}. לדוגמה: projects/my-project/databases/my-database/documents או projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

שדה איחוד query_type. השאילתה להרצה. query_type יכול להיות רק אחד מהבאים:
structured_query

StructuredQuery

שאילתה מובנית.

TargetChange

היעדים למעקב השתנו.

שדות
target_change_type

TargetChangeType

סוג השינוי שהתרחש.

target_ids[]

int32

מזהי היעדים של היעדים שהשתנו.

אם השדה ריק, השינוי יחול על כל היעדים.

לא הוגדר הסדר של מזהי היעדים.

cause

Status

השגיאה שגרמה לשינוי הזה, אם רלוונטי.

resume_token

bytes

אסימון שניתן להשתמש בו כדי להמשיך את השידור עבור target_ids הנתון, או עבור כל היעדים אם target_ids ריק.

לא מוגדר בכל שינוי ביעד.

read_time

Timestamp

הערך העקבי read_time עבור target_ids הנתון (מושמט כשמזהי target_id לא נמצאים בתמונת מצב עקבית).

השידור מבטיח לשלוח read_time עם target_ids ריק בכל פעם שכל השידור מגיע לתמונת מצב עקבית חדשה. הודעות ADD , CURRENT ו-RESET מובטחות (בסופו של דבר) יובילו ליצירת תמונת מצב חדשה ועקבית (בעוד שהודעות NO_CHANGE ו-REMOVE אינן פועלות).

בשידור נתון, הערך של read_time צפוי לעלות באופן מונוטוני.

TargetChangeType

סוג השינוי.

טיפוסים בני מנייה (enums)
NO_CHANGE לא התרחש שינוי. משמש רק לשליחת resume_token מעודכן.
ADD היעדים נוספו.
REMOVE היעדים הוסרו.
CURRENT

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

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

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

RESET

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

לאחר השלמת המצב הראשוני, השדה CURRENT יוחזר גם אם היעד צוין בעבר כ-CURRENT.

TransactionOptions

אפשרויות ליצירת עסקה חדשה.

שדות
שדה איחוד mode. המצב של העסקה. mode יכול להיות רק אחד מהבאים:
read_only

ReadOnly

ניתן להשתמש בעסקה רק לפעולות קריאה.

read_write

ReadWrite

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

ReadOnly

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

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

Timestamp

קריאת מסמכים בזמן הנתון.

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

ReadWrite

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

Firestore לא מאפשר לבקשות אימות של צד שלישי ליצור עסקאות קריאה-כתיבה.

שדות
retry_transaction

bytes

טרנזקציה אופציונלית שיש לנסות שוב.

UpdateDocumentRequest

הבקשה על Firestore.UpdateDocument.

שדות
document

Document

חובה. המסמך המעודכן. יצירת המסמך אם הוא עדיין לא קיים.

update_mask

DocumentMask

השדות שצריך לעדכן. אף אחד מנתיבי השדות במסכה לא יכול להכיל שם שמור.

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

mask

DocumentMask

השדות שיש להחזיר. אם המדיניות לא מוגדרת, כל השדות מוחזרים.

אם המסמך כולל שדה שלא נמצא במסכה הזו, השדה הזה לא יוחזר.

current_document

Precondition

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

תמורה לכסף

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

שדות
שדה איחוד value_type. חייב להיות מוגדר ערך. value_type יכול להיות רק אחד מהבאים:
null_value

NullValue

ערך null.

boolean_value

bool

ערך בוליאני.

integer_value

int64

ערך מסוג מספר שלם.

double_value

double

ערך כפול.

timestamp_value

Timestamp

ערך של חותמת זמן.

מדויק רק למיליוניות השנייה. אחרי השמירה, כל רמת דיוק נוספת תעוגל כלפי מטה.

string_value

string

ערך מחרוזת.

המחרוזת, שמיוצגת כ-UTF-8, לא יכולה לחרוג מ- 1MiB – 89 בייטים. רק 1,500 הבייטים הראשונים של הייצוג UTF-8 מובאים בחשבון על ידי שאילתות.

bytes_value

bytes

ערך בייטים.

מקסימום 1MiB עד 89 בייטים. בשאילתות נלקחות בחשבון רק 1,500 הבייטים הראשונים.

reference_value

string

הפניה למסמך. לדוגמה: projects/{project_id}/databases/{database_id}/documents/{document_path}.

geo_point_value

LatLng

ערך של נקודה גיאוגרפית שמייצג נקודה על פני השטח של כדור הארץ.

array_value

ArrayValue

ערך של מערך.

לא ניתן להכיל ישירות ערך נוסף של מערך, אך הוא יכול להכיל מפה שמכילה מערך אחר.

map_value

MapValue

ערך מפה.

כתיבה

כתיבה על מסמך.

שדות
update_mask

DocumentMask

השדות שצריך לעדכן בכתיבה הזו.

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

update_transforms[]

FieldTransform

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

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

current_document

Precondition

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

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

שדה איחוד operation. הפעולה שצריך לבצע. operation יכול להיות רק אחד מהבאים:
update

Document

מסמך לכתיבה.

delete

string

שם של מסמך למחיקה. בפורמט: projects/{project_id}/databases/{database_id}/documents/{document_path}.

transform

DocumentTransform

מחילה טרנספורמציה על מסמך.

WriteRequest

הבקשה על Firestore.Write.

הבקשה הראשונה יוצרת שידור או מחדשת שידור קיים מאסימון.

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

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

שדות
database

string

חובה. שם מסד הנתונים. בפורמט: projects/{project_id}/databases/{database_id}. צריך לעשות זאת רק בהודעה הראשונה.

stream_id

string

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

writes[]

Write

הכתיבה שצריך להחיל.

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

stream_token

bytes

אסימון שידור שנשלח בעבר על ידי השרת.

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

אם יש יותר מדי תגובות שאינן מאושרות, השרת עשוי לסגור את הסטרימינג.

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

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

labels

map<string, string>

תוויות שמשויכות לבקשת הכתיבה הזו.

WriteResponse

התשובה עבור Firestore.Write.

שדות
stream_id

string

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

stream_token

bytes

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

השדה הזה תמיד מוגדר.

write_results[]

WriteResult

התוצאה של החלת הכתיבה.

תוצאת הכתיבה ה-i תואמת לכתיבה ה-i שבבקשה.

commit_time

Timestamp

השעה שבה התרחשה ההתחייבות. לכל קריאה עם ערך read_time שווה או גדול יותר מובטח לראות את השפעת הכתיבה.

WriteResult

התוצאה של החלת פעולת כתיבה.

שדות
update_time

Timestamp

שעת העדכון האחרונה של המסמך לאחר החלת הכתיבה. לא מוגדרת אחרי delete.

אם הכתיבה לא שינתה את המסמך בפועל, יהיה הערך הקודם של update_time.

transform_results[]

Value

התוצאות של החלת כל DocumentTransform.FieldTransform, באותו סדר.