Package google.firestore.v1beta1

ดัชนี

Firestore

บริการ Cloud Firestore

Cloud Firestore เป็นฐานข้อมูลเอกสาร NoSQL แบบ Serverless ที่ดำเนินการบนระบบคลาวด์ที่เร็วและมีการจัดการครบวงจร ซึ่งช่วยให้จัดเก็บ ซิงค์ และค้นหาข้อมูลสำหรับอุปกรณ์เคลื่อนที่ เว็บ และแอป 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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

เขียนเป็นกลุ่ม

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

ใช้ชุดการดำเนินการเขียน

เมธอด BatchWrite ไม่ได้นำการดำเนินการเขียนไปใช้อย่างเป็นสัดส่วนและนำไปใช้ได้ไม่ถูกต้อง เมธอดไม่อนุญาตให้มีการเขียนมากกว่า 1 รายการต่อเอกสาร การเขียนแต่ละรายการประสบความสำเร็จหรือล้มเหลวโดยอิสระ ดูสถานะความสําเร็จของการเขียนแต่ละรายการได้ที่BatchWriteResponse

หากต้องการชุดการเขียนที่ใช้แบบอะตอม ให้ใช้ Commit แทน

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

เริ่มธุรกรรม

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

สร้างเอกสาร

rpc CreateDocument(CreateDocumentRequest) returns (Document)

สร้างเอกสารใหม่

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

ลบเอกสาร

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

ลบเอกสาร

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

รับเอกสาร

rpc GetDocument(GetDocumentRequest) returns (Document)

รับเอกสารรายการเดียว

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

รหัส ListCollection

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

แสดงรหัสคอลเล็กชันทั้งหมดภายใต้เอกสาร

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

แสดงรายการเอกสาร

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

การค้นหาพาร์ติชัน

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

คำค้นหาที่เรียกใช้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

การเรียกใช้คำค้นหา

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

ทำการค้นหา

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth รายการใดรายการหนึ่งต่อไปนี้

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

อัปเดตเอกสาร

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

สำหรับข้อมูลเพิ่มเติม โปรดดูที่ภาพรวมการตรวจสอบสิทธิ์

ผลลัพธ์การรวม

ผลลัพธ์ของที่เก็บข้อมูลเดียวจากการค้นหาการรวม Firestore

คีย์ของ aggregate_fields เหมือนกันสำหรับผลลัพธ์ทั้งหมดในคำค้นหาการรวม ซึ่งต่างจากคำค้นหาในเอกสารที่สามารถแสดงช่องที่ต่างกันสำหรับผลการค้นหาแต่ละรายการ

ช่อง
aggregate_fields

map<string, Value>

ผลลัพธ์ของฟังก์ชันการรวมข้อมูล เช่น COUNT(*) AS total_docs

คีย์คือ alias ที่กำหนดให้กับฟังก์ชันการรวมข้อมูลในอินพุต และขนาดของแผนที่นี้เท่ากับจำนวนของฟังก์ชันการรวมข้อมูลในการค้นหา

ค่าอาร์เรย์

ค่าอาร์เรย์

ช่อง
values[]

Value

ค่าในอาร์เรย์

คำขอรับเอกสารแบบกลุ่ม

คำขอสำหรับ 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

อ่านเอกสารตามที่อยู่ในเวลาที่กำหนด

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

รับเอกสารแบบแบตช์

คำตอบที่สตรีมสำหรับ 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}

คำขอเขียนแบตช์

คำขอสำหรับ Firestore.BatchWrite

ช่อง
database

string

ต้องระบุ ชื่อฐานข้อมูล ในรูปแบบ: projects/{project_id}/databases/{database_id}

writes[]

Write

การเขียนที่จะใช้

เมธอดไม่ได้ใช้การเขียนแบบอะตอมและไม่รับประกันการเรียงลำดับ การเขียนแต่ละรายการประสบความสำเร็จหรือล้มเหลวโดยอิสระ คุณไม่สามารถเขียนไปยังเอกสารเดียวกันมากกว่า 1 ครั้งต่อคำขอ

labels

map<string, string>

ป้ายกำกับที่เชื่อมโยงกับการเขียนแบบกลุ่มนี้

เขียนคำตอบแบบกลุ่ม

คำตอบจาก Firestore.BatchWrite

ช่อง
write_results[]

WriteResult

ผลลัพธ์ของการใช้การเขียน

ผลการเขียน i-th นี้สอดคล้องกับการเขียน i-th ในคำขอ

status[]

Status

สถานะของการใช้การเขียน

สถานะการเขียน i-th นี้สอดคล้องกับการเขียน i-th ในคำขอ

StartTransactionRequest

คำขอสำหรับ Firestore.BeginTransaction

ช่อง
database

string

ต้องระบุ ชื่อฐานข้อมูล ในรูปแบบ: projects/{project_id}/databases/{database_id}

options

TransactionOptions

ตัวเลือกสำหรับธุรกรรม ค่าเริ่มต้นคือธุรกรรมแบบอ่าน-เขียน

เริ่ม TransactionResponse

การตอบกลับสำหรับ Firestore.BeginTransaction

ช่อง
transaction

bytes

ธุรกรรมที่เริ่มต้นแล้ว

BitSequence

ลำดับบิตที่เข้ารหัสในอาร์เรย์ไบต์

แต่ละไบต์ในอาร์เรย์ bitmap ไบต์จะเก็บ 8 บิตของลำดับ ข้อยกเว้นเพียงอย่างเดียวคือไบต์สุดท้าย ซึ่งอาจเก็บได้ 8 บิตหรือน้อยกว่า padding กำหนดจำนวนบิตของไบต์สุดท้ายที่จะละเว้นเป็น "Padding" ค่าของ "ระยะห่างจากขอบ" เหล่านี้ ไม่ได้ระบุบิตและต้องละเว้น

หากต้องการเรียกบิตแรก บิต 0 ให้คำนวณดังนี้ (bitmap[0] & 0x01) != 0 หากต้องการเรียกบิตที่ 2 บิต 1 ให้คำนวณดังนี้ (bitmap[0] & 0x02) != 0 หากต้องการเรียกบิตที่ 3 บิต 2 ให้คำนวณดังนี้ (bitmap[0] & 0x04) != 0 หากต้องการเรียกบิตที่ 4 บิต 3 ให้คำนวณดังนี้ (bitmap[0] & 0x08) != 0 หากต้องการเรียกบิต n ให้คำนวณดังนี้ (bitmap[n / 8] & (0x01 << (n % 8))) != 0

"ขนาด" ของ BitSequence (จำนวนบิตที่มีอยู่) จะคำนวณด้วยสูตร (bitmap.length * 8) - padding

ช่อง
bitmap

bytes

ไบต์ที่เข้ารหัสลำดับบิต อาจมีความยาวเป็น 0

padding

int32

จำนวนบิตของไบต์สุดท้ายใน bitmap ที่จะละเว้นเป็น "ระยะห่างจากขอบ" หากความยาวของ bitmap เป็น 0 ค่านี้ต้องเป็น 0 มิเช่นนั้น ค่านี้ต้องอยู่ระหว่าง 0 ถึง 7 เท่านั้น

ตัวกรองบลูม

ฟิลเตอร์ดอกไม้ (https://en.wikipedia.org/wiki/Bloom_filter)

ตัวกรองบลูมจะแฮชรายการที่มี MD5 และถือว่าแฮช 128 บิตที่ได้เป็นค่าแฮช 64 บิตที่แตกต่างกัน 2 ค่า ซึ่งระบบจะตีความเป็นจำนวนเต็มที่ไม่มีเครื่องหมายโดยใช้การเข้ารหัสเสริม 2

จากนั้นระบบจะใช้ค่าแฮช 2 รายการนี้ชื่อว่า h1 และ h2 เพื่อคำนวณค่าแฮช hash_count โดยใช้สูตร โดยเริ่มต้นที่ i=0

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

ค่าที่ได้เหล่านี้ก็จะเป็นโมดูโลจำนวนบิตในฟิลเตอร์ดอกไม้เพื่อรับค่าบิตของฟิลเตอร์บลูมเพื่อทดสอบกับค่าที่ป้อน

ช่อง
bits

BitSequence

ข้อมูลตัวกรองดอกไม้

hash_count

int32

จำนวนแฮชที่อัลกอริทึมใช้

ส่งคำขอ

คำขอสำหรับ Firestore.Commit

ช่อง
database

string

ต้องระบุ ชื่อฐานข้อมูล ในรูปแบบ: projects/{project_id}/databases/{database_id}

writes[]

Write

การเขียนที่จะใช้

ดำเนินการโดยอัตโนมัติเสมอและเรียงตามลำดับ

transaction

bytes

หากมีการตั้งค่า จะใช้การเขียนทั้งหมดในธุรกรรมนี้และตกลง

CommitResponse

การตอบกลับสำหรับ Firestore.Commit

ช่อง
write_results[]

WriteResult

ผลลัพธ์ของการใช้การเขียน

ผลการเขียน i-th นี้สอดคล้องกับการเขียน i-th ในคำขอ

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

หากตำแหน่งอยู่ก่อนหรือหลังค่าที่ระบุ สัมพันธ์กับลำดับการจัดเรียงที่กำหนดโดยการค้นหา

ลบคำขอเอกสาร

คำขอสำหรับ Firestore.DeleteDocument

ช่อง
name

string

ต้องระบุ ชื่อทรัพยากรของเอกสารที่จะลบ ในรูปแบบ: projects/{project_id}/databases/{database_id}/documents/{document_path}

current_document

Precondition

เงื่อนไขที่ต้องดำเนินการก่อนในเอกสาร (ไม่บังคับ) คำขอจะล้มเหลวหากตั้งค่าไว้แต่ไม่บรรลุผลโดยเอกสารเป้าหมาย

เอกสาร

เอกสาร Firestore

ต้องไม่เกิน 1 MiB - 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 ของการค้นหาได้ด้วย

เปลี่ยนเอกสาร

Document มีการเปลี่ยนแปลง

อาจเป็นผลมาจาก writes หลายรายการ (รวมถึงการลบ) ซึ่งสุดท้ายแล้วจะทำให้เกิดค่าใหม่สำหรับ Document

ระบบอาจแสดงผลข้อความ DocumentChange หลายรายการสำหรับการเปลี่ยนแปลงเชิงตรรกะเดียวกัน หากมีหลายเป้าหมายได้รับผลกระทบ

ช่อง
document

Document

สถานะใหม่ของ Document

หากตั้งค่า mask ไว้ จะมีเฉพาะช่องที่ได้รับการอัปเดตหรือเพิ่มแล้ว

target_ids[]

int32

ชุดรหัสเป้าหมายของเป้าหมายที่ตรงกับเอกสารนี้

removed_target_ids[]

int32

ชุดรหัสเป้าหมายสำหรับเป้าหมายที่ไม่ตรงกับเอกสารนี้อีกต่อไป

ลบเอกสาร

ลบ Document แล้ว

อาจเป็นผลมาจาก writes หลายรายการ รวมถึงการอัปเดตต่างๆ ซึ่งรายการสุดท้ายที่ลบ Document

ระบบอาจแสดงผลข้อความ DocumentDelete หลายรายการสำหรับการลบเชิงตรรกะเดียวกัน หากมีหลายเป้าหมายได้รับผลกระทบ

ช่อง
document

string

ชื่อทรัพยากรของ Document ที่ลบไปแล้ว

removed_target_ids[]

int32

ชุดรหัสเป้าหมายสำหรับเป้าหมายที่ตรงกับเอนทิตีนี้ก่อนหน้านี้

read_time

Timestamp

การประทับเวลาการอ่านที่พบการลบ

มากกว่าหรือเท่ากับ commit_time ของการลบ

มาสก์เอกสาร

ชุดของเส้นทางช่องในเอกสาร ใช้เพื่อจำกัดการดำเนินการรับหรืออัปเดตในเอกสารไปยังช่องชุดย่อยในเอกสาร ซึ่งแตกต่างจากมาสก์ของช่องมาตรฐาน เนื่องจากจะกำหนดขอบเขตเป็น Document เสมอ และคำนึงถึงลักษณะแบบไดนามิกของ Value

ช่อง
field_paths[]

string

รายการเส้นทางช่องในมาสก์ ดู Document.fields สำหรับการอ้างอิงไวยากรณ์เส้นทางช่อง

นำเอกสารออก

นำ Document ออกจากมุมมองของเป้าหมายแล้ว

ส่งหากเอกสารไม่เกี่ยวข้องกับเป้าหมายอีกต่อไปและไม่แสดงผล สามารถส่งแทน DocumentDelete หรือ DocumentChange ได้ ถ้าเซิร์ฟเวอร์ไม่สามารถส่งค่าใหม่ของเอกสาร

ระบบอาจแสดงผลข้อความ DocumentRemove หลายรายการสำหรับการเขียนหรือลบอย่างตรรกะเดียวกัน หากมีหลายเป้าหมายได้รับผลกระทบ

ช่อง
document

string

ชื่อทรัพยากรของ Document หายไปแล้ว

removed_target_ids[]

int32

ชุดรหัสเป้าหมายสำหรับเป้าหมายที่ตรงกับเอกสารนี้ก่อนหน้านี้

read_time

Timestamp

การประทับเวลาการอ่านที่พบการนำออก

มากกว่าหรือเท่ากับ commit_time ของการเปลี่ยนแปลง/ลบ/นำออก

เปลี่ยนรูปแบบเอกสาร

การเปลี่ยนรูปแบบของเอกสาร

ช่อง
document

string

ชื่อเอกสารที่จะแปลง

field_transforms[]

FieldTransform

รายการการเปลี่ยนรูปแบบที่จะนำไปใช้กับช่องของเอกสารตามลำดับ ต้องระบุข้อมูล

เปลี่ยนรูปแบบฟิลด์

การเปลี่ยนรูปแบบของช่องของเอกสาร

ช่อง
field_path

string

เส้นทางของช่อง ดู Document.fields สำหรับการอ้างอิงไวยากรณ์ของเส้นทางช่อง

ช่องการรวม transform_type การเปลี่ยนรูปแบบที่จะใช้ในฟิลด์ transform_type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
set_to_server_value

ServerValue

ตั้งค่าช่องนี้เป็นค่าเซิร์ฟเวอร์ที่ระบุ

increment

Value

เพิ่มค่าที่ระบุลงในค่าปัจจุบันของช่อง

ค่านี้ต้องเป็นจำนวนเต็มหรือค่าเลขทศนิยม หากช่องนี้ไม่ใช่จำนวนเต็มหรือเลขคู่ หรือยังไม่มีช่องนี้ การเปลี่ยนรูปแบบจะตั้งค่าช่องนี้เป็นค่าที่ระบุ หากค่าที่ระบุหรือค่าในช่องปัจจุบันเป็นเลขคู่ ระบบจะตีความทั้ง 2 ค่าเป็นเลขคู่ เลขคณิตคู่และการแทนค่าคู่จะเป็นไปตามอรรถศาสตร์ IEEE 754 ถ้ามีจำนวนเต็มบวก/ลบ ฟิลด์จะได้รับการแก้เป็นค่าจำนวนเต็มบวก/ลบที่มีค่ามากที่สุด

maximum

Value

ตั้งค่าช่องนี้เป็นค่าสูงสุดของค่าปัจจุบันและค่าที่ระบุ

ค่านี้ต้องเป็นจำนวนเต็มหรือค่าเลขทศนิยม หากช่องนี้ไม่ใช่จำนวนเต็มหรือเลขคู่ หรือยังไม่มีช่องนี้ การเปลี่ยนรูปแบบจะตั้งค่าช่องนี้เป็นค่าที่ระบุ หากใช้การดำเนินการสูงสุดในตำแหน่งที่ช่องและค่าอินพุตเป็นประเภทผสม (กล่าวคือ 1 เป็นจำนวนเต็มและ 1 เป็นเลขคู่) ช่องจะใช้ประเภทตัวถูกดำเนินการที่ใหญ่กว่า หากตัวถูกดำเนินการมีค่าเท่ากัน (เช่น 3 และ 3.0) ฟิลด์จะไม่เปลี่ยนแปลง 0, 0.0 และ -0.0 ถือเป็น 0 ทั้งหมด โดยค่าสูงสุดซึ่งเก็บค่าที่เท่ากับ 0 และค่าอินพุตเป็น 0 จะเป็นค่าที่จัดเก็บไว้เสมอ ค่าสูงสุดของค่าตัวเลข x และ NaN คือ NaN

minimum

Value

ตั้งค่าฟิลด์เป็นค่าต่ำสุดของค่าปัจจุบันและค่าที่ระบุ

ค่านี้ต้องเป็นจำนวนเต็มหรือค่าเลขทศนิยม หากช่องนี้ไม่ใช่จำนวนเต็มหรือเลขคู่ หรือยังไม่มีช่องนี้ การเปลี่ยนรูปแบบจะตั้งค่าช่องนี้เป็นค่าอินพุต หากใช้การดำเนินการขั้นต่ำในกรณีที่ช่องและค่าอินพุตเป็นประเภทผสม (กล่าวคือ 1 เป็นจำนวนเต็มและ 1 รายการเป็นเลขคู่) ช่องจะใช้ประเภทตัวถูกดำเนินการที่น้อยกว่า หากตัวถูกดำเนินการมีค่าเท่ากัน (เช่น 3 และ 3.0) ฟิลด์จะไม่เปลี่ยนแปลง 0, 0.0 และ -0.0 ถือเป็น 0 ทั้งหมด ค่าขั้นต่ำที่จัดเก็บเป็น 0 และค่าอินพุตเป็น 0 จะเป็นค่าที่จัดเก็บไว้เสมอ ค่าต่ำสุดของค่าตัวเลข x และ NaN คือ NaN

append_missing_elements

ArrayValue

เพิ่มองค์ประกอบที่กำหนดต่อท้ายองค์ประกอบที่กำหนดหากองค์ประกอบนั้นไม่อยู่ในค่าปัจจุบัน หากช่องนี้ไม่ใช่อาร์เรย์หรือยังไม่มีฟิลด์ ให้ตั้งเป็นอาร์เรย์ว่างเปล่าก่อน

จำนวนที่เทียบเท่าของประเภทต่างๆ (เช่น 3L และ 3.0) จะถือว่าเท่ากันเมื่อตรวจสอบว่าค่าขาดหายไปหรือไม่ NaN เท่ากับ NaN และ Null เท่ากับ Null หากอินพุตมีค่าที่เทียบเท่าหลายค่า ระบบจะพิจารณาเฉพาะค่าแรกเท่านั้น

transform_result ที่เกี่ยวข้องจะเป็นค่าว่าง

remove_all_from_array

ArrayValue

นำองค์ประกอบที่ระบุทั้งหมดออกจากอาร์เรย์ในช่อง หากช่องนี้ไม่ใช่อาร์เรย์หรือยังไม่มีช่องนี้ ให้ตั้งเป็นอาร์เรย์ว่างเปล่า

จำนวนที่เทียบเท่ากันของประเภทต่างๆ (เช่น 3L และ 3.0) จะถือว่าเท่ากันเมื่อตัดสินว่าควรนำองค์ประกอบออกหรือไม่ NaN เท่ากับ NaN และ Null เท่ากับ Null การดำเนินการนี้จะนำค่าที่เทียบเท่ากันทั้งหมดออกหากมีค่าที่ซ้ำกัน

transform_result ที่เกี่ยวข้องจะเป็นค่าว่าง

ค่าเซิร์ฟเวอร์

ค่าที่เซิร์ฟเวอร์คำนวณ

Enum
SERVER_VALUE_UNSPECIFIED ไม่ระบุ ต้องไม่ใช้ค่านี้
REQUEST_TIME เวลาที่เซิร์ฟเวอร์ประมวลผลคำขอ มีความแม่นยำเป็นมิลลิวินาที หากใช้ในหลายช่อง (เอกสารเดียวกันหรือต่างกัน) ในธุรกรรม ทุกช่องจะได้รับการประทับเวลาของเซิร์ฟเวอร์เหมือนกัน

สถิติการดำเนินการ

สถิติการดำเนินการสำหรับคำค้นหา

ช่อง
results_returned

int64

จำนวนของผลลัพธ์ทั้งหมดที่ส่งคืน รวมถึงเอกสาร การคาดการณ์ ผลลัพธ์การรวม คีย์

execution_duration

Duration

เวลาทั้งหมดในการดำเนินการค้นหาในแบ็กเอนด์

read_operations

int64

การดำเนินการอ่านที่เรียกเก็บเงินได้ทั้งหมด

debug_stats

Struct

การแก้ไขข้อบกพร่องของสถิติจากการดำเนินการค้นหา โปรดทราบว่าสถิติการแก้ไขข้อบกพร่องอาจมีการเปลี่ยนแปลงเมื่อ Firestore พัฒนาขึ้น โดยอาจมี { "indexes_entries_sthese": "1000", "documents_sสิ่งเหล่านี้": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" }

ตัวกรองที่มีอยู่

สรุปของเอกสารทั้งหมดที่ตรงกับเป้าหมายที่ระบุ

ช่อง
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}

ตัวกรองบลูมนี้อาจถูกละเว้นโดยการพิจารณาตามที่เห็นสมควรของเซิร์ฟเวอร์ เช่น ถ้าพิจารณาแล้วว่าลูกค้าจะไม่ใช้ประโยชน์จากตัวกรองบลูมนี้ หรือมีค่าใช้จ่ายสําหรับการคำนวณหรือส่งข้อมูลที่แพงเกินไป ไคลเอ็นต์ต้องจัดการฟิลด์นี้ที่ไม่มีข้อมูลได้โดยย้อนกลับไปยังตรรกะที่ใช้ก่อนที่จะมีช่องนี้ กล่าวคือ ให้เพิ่มเป้าหมายอีกครั้งโดยไม่ต้องใช้โทเค็นสำหรับประวัติการทำงานเพื่อดูว่าเอกสารใดในแคชของไคลเอ็นต์ที่ไม่ซิงค์กัน

คำอธิบายเมตริก

อธิบายเมตริกสำหรับการค้นหา

ช่อง
plan_summary

PlanSummary

ข้อมูลระยะการวางแผนสำหรับการค้นหา

execution_stats

ExecutionStats

สถิติรวมจากการดำเนินการค้นหา แสดงเมื่อตั้งค่า ExplainOptions.analyze เป็น "จริง" เท่านั้น

ตัวเลือกคำอธิบาย

อธิบายตัวเลือกต่างๆ สำหรับการค้นหา

ช่อง
analyze

bool

ไม่บังคับ ต้องการเรียกใช้การค้นหานี้หรือไม่

เมื่อเป็นเท็จ (ค่าเริ่มต้น) ระบบจะวางแผนการค้นหาโดยแสดงผลเฉพาะเมตริกจากขั้นตอนการวางแผน

เมื่อเป็นจริง ระบบจะวางแผนและดำเนินการค้นหา โดยแสดงผลการค้นหาทั้งหมดพร้อมทั้งเมตริกขั้นตอนการวางแผนและการดำเนินการ

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

อ่านเอกสารตามฉบับ ณ เวลาที่ระบุ

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

คำขอ ListCollectionIds

คำขอสำหรับ 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

อ่านเอกสารตามที่อยู่ในเวลาที่กำหนด

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

คำตอบของ ListCollectionId

คำตอบจาก Firestore.ListCollectionIds

ช่อง
collection_ids[]

string

รหัสคอลเล็กชัน

next_page_token

string

โทเค็นหน้าเว็บที่อาจใช้เพื่อดำเนินรายการต่อ

คำขอ ListDocuments

คำขอสำหรับ 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

กรณีที่รายการควรแสดงเอกสารที่ขาดหายไป

เอกสารหายไปถ้าไม่มีอยู่ แต่มีเอกสารย่อยฝังอยู่ใต้นั้น เมื่อเป็นจริง ระบบจะแสดงผลเอกสารที่ขาดหายไปดังกล่าวพร้อมคีย์ แต่จะไม่มีช่อง create_time หรือ update_time ที่ตั้งค่าไว้

คำขอที่มี show_missing ไม่สามารถระบุ where หรือ order_by

ช่องการรวม consistency_selector โหมดความสอดคล้องสำหรับธุรกรรมนี้ หากไม่ได้ตั้งค่า ระบบจะใช้ความสอดคล้องที่อัปเดตเป็นค่าเริ่มต้น consistency_selector ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
transaction

bytes

ดำเนินการอ่านโดยเป็นส่วนหนึ่งของธุรกรรมที่ใช้งานอยู่แล้ว

read_time

Timestamp

อ่านตามเวลาที่ระบุไว้

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

ListDocumentsResponse

การตอบกลับสำหรับ Firestore.ListDocuments

ช่อง
documents[]

Document

เอกสารที่พบ

next_page_token

string

โทเค็นสำหรับเรียกหน้าถัดไปของเอกสาร

หากเว้นช่องนี้ไว้ จะไม่มีหน้าลำดับต่อมา

คำขอฟัง

คำขอสำหรับ Firestore.Listen

ช่อง
database

string

ต้องระบุ ชื่อฐานข้อมูล ในรูปแบบ: projects/{project_id}/databases/{database_id}

labels

map<string, string>

ป้ายกำกับที่เชื่อมโยงกับการเปลี่ยนแปลงเป้าหมายนี้

ช่องการรวม target_change การเปลี่ยนแปลงเป้าหมายที่รองรับ target_change ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
add_target

Target

เป้าหมายที่จะเพิ่มไปยังสตรีมนี้

remove_target

int32

รหัสของเป้าหมายที่จะนำออกจากสตรีมนี้

การตอบกลับสำหรับฟัง

การตอบกลับสำหรับ Firestore.Listen

ช่อง
ช่องการรวม response_type คำตอบที่รองรับ response_type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
target_change

TargetChange

เป้าหมายมีการเปลี่ยนแปลง

document_change

DocumentChange

Document มีการเปลี่ยนแปลง

document_delete

DocumentDelete

ลบ Document แล้ว

document_remove

DocumentRemove

นำ Document ออกจากเป้าหมายแล้ว (เนื่องจากไม่เกี่ยวข้องกับเป้าหมายนั้นแล้ว)

filter

ExistenceFilter

ตัวกรองที่จะใช้กับชุดของเอกสารที่แสดงผลก่อนหน้านี้สำหรับเป้าหมายที่ระบุ

แสดงผลเมื่อเอกสารอาจถูกนำออกจากเป้าหมายที่ระบุ แต่ไม่ทราบเอกสารที่แน่นอน

ค่าแผนที่

ค่าแมป

ช่อง
fields

map<string, Value>

ฟิลด์ของแผนที่

คีย์แผนที่จะแสดงชื่อช่อง ชื่อช่องที่ตรงกับนิพจน์ทั่วไป __.*__ เป็นชื่อที่สงวนไว้ ไม่อนุญาตให้ใช้ชื่อช่องที่สงวนไว้ ยกเว้นในบางบริบทที่มีการบันทึกไว้ คีย์แผนที่ซึ่งแสดงเป็น UTF-8 ต้องมีขนาดไม่เกิน 1,500 ไบต์และต้องไม่ว่างเปล่า

คำขอการค้นหาพาร์ติชัน

คำขอสำหรับ Firestore.PartitionQuery

ช่อง
parent

string

ต้องระบุ ชื่อทรัพยากรระดับบนสุด ในรูปแบบ: projects/{project_id}/databases/{database_id}/documents ระบบไม่รองรับชื่อทรัพยากรของเอกสาร ระบุได้เฉพาะชื่อทรัพยากรฐานข้อมูล

partition_count

int64

จำนวนจุดพาร์ติชันสูงสุดที่ต้องการ พาร์ติชันอาจแสดงในผลลัพธ์หลายหน้า ตัวเลขต้องเป็นค่าบวก จำนวนพาร์ติชันจริงที่แสดงผลอาจน้อยกว่า

เช่น อาจตั้งค่าเป็น 1 น้อยกว่าจำนวนการค้นหาแบบขนานที่จะเรียกใช้ หรือในการเรียกใช้งานไปป์ไลน์ข้อมูล น้อยกว่าจำนวนผู้ปฏิบัติงานหรืออินสแตนซ์การประมวลผลที่พร้อมใช้งาน 1 รายการ

page_token

string

ค่า next_page_token ที่แสดงผลจากการเรียกไปยัง PartitionQuery ก่อนหน้านี้ ซึ่งอาจนำไปใช้เพื่อรับชุดผลลัพธ์เพิ่มเติม ไม่มีการรับประกันการสั่งซื้อระหว่างชุดผลลัพธ์ ดังนั้น การใช้ผลลัพธ์หลายชุดจึงต้องรวมชุดผลลัพธ์ที่แตกต่างกันเข้าด้วยกัน

ตัวอย่างเช่น การเรียก 2 ครั้งครั้งต่อๆ มาโดยใช้ 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 ครั้งที่ 2 จะแสดงผลพาร์ติชันสูงสุด 2 พาร์ติชัน ซึ่งทำให้มีทั้งหมด 10 พาร์ติชันที่ระบุไว้ใน partition_count

ช่องการรวม query_type การค้นหาที่จะแบ่งพาร์ติชัน query_type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
structured_query

StructuredQuery

การค้นหาแบบมีโครงสร้าง การค้นหาต้องระบุคอลเล็กชันที่มีองค์ประกอบสืบทอดทั้งหมด และเรียงลำดับตามชื่อจากน้อยไปหามาก ระบบไม่รองรับตัวกรองอื่นๆ การเรียงลำดับตาม ขีดจำกัด ออฟเซ็ต และเคอร์เซอร์เริ่มต้น/สิ้นสุด

ช่องการรวม consistency_selector โหมดความสอดคล้องสำหรับคำขอนี้ หากไม่ได้ตั้งค่า ระบบจะใช้ความสอดคล้องที่อัปเดตเป็นค่าเริ่มต้น consistency_selector ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
read_time

Timestamp

อ่านเอกสารตามที่อยู่ในเวลาที่กำหนด

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

การตอบกลับคำค้นหาของพาร์ติชัน

การตอบกลับสำหรับ Firestore.PartitionQuery

ช่อง
partitions[]

Cursor

ผลลัพธ์การแบ่งพาร์ติชัน แต่ละพาร์ติชันคือจุดแยกที่สามารถใช้โดย RunQuery เป็นจุดเริ่มต้นหรือจุดสิ้นสุดสำหรับผลการค้นหา คำขอ RunQuery ต้องสร้างขึ้นด้วยคำค้นหาเดียวกันกับที่ระบุให้กับคำขอ PartitionQuery นี้ เคอร์เซอร์พาร์ติชันจะเรียงลำดับตามลำดับเดียวกับผลลัพธ์ของการค้นหาที่ระบุให้กับ PartitionQuery

ตัวอย่างเช่น หากคำขอ PartitionQuery แสดงผลเคอร์เซอร์พาร์ติชัน A และ B การเรียกใช้การค้นหาสามแบบต่อไปนี้จะแสดงชุดผลลัพธ์ทั้งหมดของคำค้นหาเดิม:

  • คำค้นหา, สิ้นสุดที่ A
  • คำค้นหา, เริ่มต้นที่ A, สิ้นสุดที่ B
  • คำค้นหา, เริ่มต้นที่ B

ผลลัพธ์ที่ว่างเปล่าอาจบ่งชี้ว่าการค้นหามีผลลัพธ์น้อยเกินไปที่จะแบ่งพาร์ติชัน หรือการค้นหายังไม่รองรับการแบ่งพาร์ติชัน

next_page_token

string

โทเค็นหน้าเว็บที่อาจใช้เพื่อขอชุดผลลัพธ์เพิ่มเติม ตามจำนวนที่ระบุโดย partition_count ในคำขอ PartitionQuery หากเว้นว่างไว้ จะไม่มีผลลัพธ์เพิ่มเติม

สรุปแผน

ข้อมูลระยะการวางแผนสำหรับการค้นหา

ช่อง
indexes_used[]

Struct

ดัชนีที่เลือกสำหรับการค้นหา ตัวอย่างเช่น [ {"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

เมื่อตั้งค่าแล้ว เอกสารเป้าหมายต้องมีอยู่และได้รับการอัปเดตล่าสุดในขณะนั้น การประทับเวลาต้องสอดคล้องกับไมโครวินาที

คำขอย้อนกลับ

คำขอสำหรับ 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

ดำเนินการค้นหาในการประทับเวลาที่ระบุ

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

RunAggregationQueryResponse การตอบกลับ

การตอบกลับสำหรับ Firestore.RunAggregationQuery

ช่อง
result

AggregationResult

ผลลัพธ์ซึ่งเป็นการรวมข้อมูลเดียว

ไม่แสดงเมื่อรายงานความคืบหน้าบางส่วน

transaction

bytes

ธุรกรรมที่เริ่มต้นโดยเป็นส่วนหนึ่งของคำขอนี้

แสดงในคำตอบแรกเมื่อคำขอขอให้เริ่มธุรกรรมใหม่เท่านั้น

read_time

Timestamp

เวลาที่มีการคำนวณผลลัพธ์รวม ซึ่งเพิ่มขึ้นอย่างต่อเนื่อง ในกรณีนี้ AggregationResult ก่อนหน้าในสตรีมผลลัพธ์ในสตรีมผลลัพธ์จะไม่มีการเปลี่ยนแปลงระหว่าง read_time กับค่านี้

หากการค้นหาไม่แสดงผลลัพธ์ใดๆ ระบบจะส่งคำตอบที่มี read_time และไม่มี result และแสดงเวลาที่เรียกใช้การค้นหา

explain_metrics

ExplainMetrics

ข้อความค้นหาอธิบายเมตริก ซึ่งจะปรากฏก็ต่อเมื่อระบุ RunAggregationQueryRequest.explain_options และจะส่งเพียงครั้งเดียวพร้อมกับคำตอบสุดท้ายในสตรีม

ส่งคำขอเรียกใช้

คำขอสำหรับ 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

อ่านเอกสารตามที่อยู่ในเวลาที่กำหนด

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

เรียกใช้การตอบกลับข้อความค้นหา

การตอบกลับสำหรับ 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 ได้ดำเนินการตามคำขอเสร็จสมบูรณ์แล้วและจะไม่มีการส่งคืนเอกสารเพิ่มเติม

คำค้นหาการรวมข้อมูลที่มีโครงสร้าง

คำค้นหา Firestore สำหรับการเรียกใช้การรวมผ่าน StructuredQuery

ช่อง
aggregations[]

Aggregation

ไม่บังคับ ชุดของการรวมที่จะใช้กับผลลัพธ์ของ structured_query

ข้อกำหนด

  • การรวมอย่างน้อย 1 รายการต่อการค้นหา 1 รายการ
ช่องการรวม 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

ผู้รวบรวมข้อมูลโดยเฉลี่ย

เฉลี่ย

ค่าเฉลี่ยของค่าในช่องที่ขอ

  • ระบบจะรวมเฉพาะค่าที่เป็นตัวเลขเท่านั้น ระบบจะข้ามค่าที่ไม่ใช่ตัวเลขทั้งหมด ซึ่งรวมถึง NULL

  • หากค่าที่รวมมี NaN จะแสดงผล NaN คณิตศาสตร์ Infinity เป็นไปตามมาตรฐาน IEEE-754

  • หากชุดค่ารวมว่างเปล่า จะแสดงผล NULL

  • แสดงผลลัพธ์เป็นเลขทศนิยมซ้ำเสมอ

ช่อง
field

FieldReference

ฟิลด์ที่จะรวบรวมข้อมูล

จำนวน

จำนวนเอกสารที่ตรงกับการค้นหา

ฟังก์ชันการรวม COUNT(*) จะทำงานกับทั้งเอกสาร ดังนั้นจึงไม่จำเป็นต้องอ้างอิงช่อง

ช่อง
up_to

Int64Value

ไม่บังคับ ข้อจำกัดที่ไม่บังคับสำหรับจำนวนเอกสารสูงสุดที่จะนับ

วิธีนี้ช่วยในการกำหนดขีดจำกัดสูงสุดของจำนวนเอกสารที่จะสแกน โดยการจำกัดเวลาในการตอบสนองและค่าใช้จ่าย

"ไม่ระบุ" จะตีความว่าไม่มีขอบเขต

ตัวอย่างระดับสูง:

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

ข้อกำหนด

  • ต้องมากกว่า 0 เมื่ออยู่

ผลรวม

ผลรวมของค่าของช่องที่ขอ

  • ระบบจะรวมเฉพาะค่าที่เป็นตัวเลขเท่านั้น ระบบจะข้ามค่าที่ไม่ใช่ตัวเลขทั้งหมด ซึ่งรวมถึง NULL

  • หากค่าที่รวมมี NaN จะแสดงผล NaN คณิตศาสตร์ Infinity เป็นไปตามมาตรฐาน IEEE-754

  • หากชุดค่ารวมว่างเปล่า จะแสดงผลเป็น 0

  • แสดงผลจำนวนเต็ม 64 บิตหากจำนวนรวมทั้งหมดเป็นจำนวนเต็ม และผลลัพธ์ผลรวมไม่เกินขีดจำกัด มิฉะนั้น ผลลัพธ์จะแสดงค่าเป็นเลขทศนิยม โปรดทราบว่าแม้ว่าค่าที่รวมทั้งหมดจะเป็นจำนวนเต็ม แต่ผลลัพธ์จะแสดงผลเป็นเลขทศนิยมหากจำนวนดังกล่าวไม่สามารถอยู่ภายในจำนวนเต็มแบบมีเครื่องหมาย 64 บิต ในกรณีนี้ ค่าที่ส่งกลับจะสูญเสียความแม่นยํา

  • เมื่อเกิดการรั่วไหลของจุดลอยตัวขึ้น การรวมจุดลอยตัวนั้นไม่สามารถกำหนดได้ ซึ่งหมายความว่าการเรียกใช้คำค้นหาเดียวกันซ้ำๆ โดยไม่มีการเปลี่ยนแปลงค่าที่สำคัญอาจให้ผลลัพธ์ที่แตกต่างกันเล็กน้อยในแต่ละครั้ง ในกรณีดังกล่าว คุณควรจัดเก็บค่าเป็นจำนวนเต็มของจำนวนทศนิยม

ช่อง
field

FieldReference

ฟิลด์ที่จะรวบรวมข้อมูล

การค้นหาแบบมีโครงสร้าง

การค้นหา 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

ข้อกำหนด

  • ค่าต้องมากกว่าหรือเท่ากับ 0 หากระบุไว้
limit

Int32Value

จำนวนผลลัพธ์สูงสุดที่จะแสดง

ใช้หลังจากข้อจำกัดอื่นๆ ทั้งหมด

ข้อกำหนด

  • ค่าต้องมากกว่าหรือเท่ากับ 0 หากระบุไว้
find_nearest

FindNearest

ไม่บังคับ ค้นหาเพื่อนบ้านที่อาจจะอยู่ใกล้ที่สุด

ใช้หลังจากตัวกรองและลำดับอื่นๆ ทั้งหมด

ค้นหาเวกเตอร์ที่ใกล้เคียงที่สุดที่ฝังกับเวกเตอร์การค้นหาที่ระบุ

ตัวเลือกคอลเล็กชัน

คอลเล็กชันที่เลือก เช่น messages as m1

ช่อง
collection_id

string

รหัสคอลเล็กชัน เมื่อตั้งค่าแล้ว ระบบจะเลือกเฉพาะคอลเล็กชันที่มีรหัสนี้

all_descendants

bool

เมื่อเป็นเท็จ เลือกเฉพาะคอลเล็กชันที่เป็นรายการย่อยของ parent ที่ระบุไว้ใน RunQueryRequest ที่มี เมื่อเป็น "จริง" เลือกคอลเล็กชันองค์ประกอบสืบทอดทั้งหมด

ตัวกรองผสม

ตัวกรองที่รวมตัวกรองอื่นๆ หลายรายการโดยใช้โอเปอเรเตอร์ที่ระบุ

ช่อง
op

Operator

โอเปอเรเตอร์สำหรับการรวมตัวกรองหลายรายการ

filters[]

Filter

รายการตัวกรองที่จะรวม

ข้อกำหนด

  • ใช้ตัวกรองอยู่อย่างน้อย 1 รายการ

โอเปอเรเตอร์

โอเปอเรเตอร์ตัวกรองผสม

Enum
OPERATOR_UNSPECIFIED ไม่ระบุ ต้องไม่ใช้ค่านี้
AND ต้องใช้เอกสารตามตัวกรองที่รวมกันทั้งหมด
OR ต้องใช้เอกสารเพื่อใช้ตัวกรองรวมกันอย่างน้อย 1 รายการ

ทิศทาง

ทิศทางการจัดเรียง

Enum
DIRECTION_UNSPECIFIED ไม่ระบุ
ASCENDING จากน้อยไปมาก
DESCENDING มากไปน้อย

ตัวกรองฟิลด์

ตัวกรองในช่องที่เจาะจง

ช่อง
field

FieldReference

ช่องที่ใช้กรอง

op

Operator

โอเปอเรเตอร์ที่ใช้กรอง

value

Value

ค่าที่จะเปรียบเทียบ

โอเปอเรเตอร์

โอเปอเรเตอร์ตัวกรองช่อง

Enum
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 ที่ระบุเท่ากับอย่างน้อย 1 ค่าในอาร์เรย์ที่ระบุ

ข้อกำหนด

  • 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

การอ้างอิงฟิลด์

การอ้างอิงไปยังช่องในเอกสาร เช่น stats.operations

ช่อง
field_path

string

การอ้างอิงช่องในเอกสาร

ข้อกำหนด

  • ต้องเป็นสตริงที่คั่นด้วยจุด (.) ของกลุ่ม โดยที่แต่ละกลุ่มสอดคล้องกับข้อจำกัด document field name

กรอง

ตัวกรอง

ช่อง
ช่องการรวม filter_type ประเภทของตัวกรอง filter_type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
composite_filter

CompositeFilter

ตัวกรองผสม

field_filter

FieldFilter

ตัวกรองในช่องเอกสาร

unary_filter

UnaryFilter

ตัวกรองที่มีอาร์กิวเมนต์เพียง 1 รายการ

ค้นหาที่ใกล้ที่สุด

การกำหนดค่าการค้นหา Neighbor ที่ใกล้ที่สุด

ช่อง
vector_field

FieldReference

ต้องระบุ ฟิลด์เวกเตอร์ที่จัดทำดัชนีสำหรับใช้ค้นหา ส่งกลับเอกสารที่มีเวกเตอร์ที่มีมิติข้อมูลตรงกับ query_vector เท่านั้น

query_vector

Value

ต้องระบุ เวกเตอร์ของคำค้นหาที่เรากำลังค้นหา ต้องเป็นเวกเตอร์ที่มีมิติข้อมูลไม่เกิน 2048 รายการ

distance_measure

DistanceMeasure

ต้องระบุ ต้องระบุมาตรวัดระยะทางที่จะใช้

limit

Int32Value

ต้องระบุ จำนวนเพื่อนบ้านที่ใกล้ที่สุดที่จะส่งคืน ต้องเป็นจำนวนเต็มบวกที่ไม่เกิน 1000

การวัดระยะทาง

การวัดระยะทางที่จะใช้เมื่อเปรียบเทียบเวกเตอร์

Enum
DISTANCE_MEASURE_UNSPECIFIED ไม่ควรตั้งค่า
EUCLIDEAN วัดระยะห่าง EUCLIDEAN ระหว่างเวกเตอร์ ดู Euclidean เพื่อเรียนรู้เพิ่มเติม
COSINE เปรียบเทียบเวกเตอร์โดยอิงตามมุมระหว่างเวกเตอร์ ซึ่งจะช่วยให้คุณวัดความคล้ายคลึงกันที่ไม่ได้อิงตามขนาดของเวกเตอร์ได้ เราขอแนะนำให้ใช้ DOT_PRODUCT กับหน่วยเวกเตอร์มาตรฐานแทนระยะทาง COSINE ซึ่งเทียบเท่าทางคณิตศาสตร์และเพิ่มประสิทธิภาพที่ดีกว่า ดูข้อมูลเพิ่มเติมได้ที่ความคล้ายคลึงกันของโคไซน์
DOT_PRODUCT คล้ายกับโคไซน์ แต่ได้รับผลกระทบจากขนาดของเวกเตอร์ โปรดดูที่ Dot Product เพื่อเรียนรู้เพิ่มเติม

สั่งซื้อ

คำสั่งซื้อในช่อง

ช่อง
field

FieldReference

ฟิลด์ที่จะเรียงลำดับ

direction

Direction

ทิศทางในการเรียงลำดับ ค่าเริ่มต้นคือ ASCENDING

การคาดคะเน

การคาดการณ์ช่องของเอกสารที่จะแสดงผล

ช่อง
fields[]

FieldReference

ช่องที่จะแสดง

หากเว้นว่างไว้ ระบบจะแสดงผลทุกช่อง หากต้องการแสดงเฉพาะชื่อเอกสาร ให้ใช้ ['__name__']

ตัวกรองเดี่ยว

ตัวกรองที่มีตัวถูกดำเนินการเดียว

ช่อง
op

Operator

โอเปอเรเตอร์แบบเดี่ยวที่จะใช้

ช่องการรวม operand_type อาร์กิวเมนต์ของตัวกรอง operand_type ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
field

FieldReference

ฟิลด์ที่จะใช้โอเปอเรเตอร์

โอเปอเรเตอร์

โอเปอเรเตอร์แบบเอกภาค

Enum
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

รหัสเป้าหมายที่ระบุเป้าหมายในสตรีม ต้องเป็นจำนวนบวกและไม่ใช่ 0

หาก 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 ไม่ใช่ 0 ต้องไม่มีเป้าหมายที่ใช้งานอยู่ในสตรีมนี้ที่มีรหัสเดียวกัน

once

bool

ควรนำเป้าหมายออกเมื่อเป้าหมายเป็นปัจจุบันและสอดคล้องกันหรือไม่

expected_count

Int32Value

จำนวนเอกสารที่ตรงกับคำค้นหาล่าสุดในโทเค็นประวัติงานหรือเวลาที่อ่าน

ค่านี้จะมีความเกี่ยวข้องเมื่อมีการระบุ resume_type เท่านั้น ค่านี้มีค่ามากกว่า 0 สัญญาณที่ไคลเอ็นต์ต้องการให้รวม 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 ที่เฉพาะเจาะจง

ในขณะนี้ลูกค้าต้องทราบสถานะของเอกสารที่ตรงกัน

เป้าหมายเอกสาร

เป้าหมายที่ระบุโดยชุดชื่อเอกสาร

ช่อง
documents[]

string

ชื่อเอกสารที่จะเรียกดู ในรูปแบบ: projects/{project_id}/databases/{database_id}/documents/{document_path} คำขอจะล้มเหลวหากเอกสารใดไม่ใช่ทรัพยากรย่อยของ database ที่ระบุ โดยจะไม่มีการลบชื่อที่ซ้ำกัน

เป้าหมายการค้นหา

เป้าหมายที่ระบุโดยการค้นหา

ช่อง
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

การค้นหาแบบมีโครงสร้าง

การเปลี่ยนแปลงเป้าหมาย

เป้าหมายที่กำลังดูมีการเปลี่ยนแปลง

ช่อง
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 จะเพิ่มขึ้นแบบโดดๆ

ประเภทการเปลี่ยนแปลงเป้าหมาย

ประเภทของการเปลี่ยนแปลง

Enum
NO_CHANGE ไม่มีการเปลี่ยนแปลงใดๆ เกิดขึ้น ใช้เพื่อส่ง resume_token ที่อัปเดตแล้วเท่านั้น
ADD เพิ่มเป้าหมายแล้ว
REMOVE นำเป้าหมายออกแล้ว
CURRENT

เป้าหมายจะแสดงการเปลี่ยนแปลงทั้งหมดที่กระทำก่อนเพิ่มเป้าหมายไปยังสตรีม

ระบบจะส่งข้อมูลนี้หลังจากหรือด้วย read_time ที่มากกว่าหรือเท่ากับเวลาที่เพิ่มเป้าหมาย

ผู้ฟังสามารถรอการเปลี่ยนแปลงนี้ได้หากต้องการความหมายการอ่านหลังการเขียน

RESET

รีเซ็ตเป้าหมายแล้ว และระบบจะส่งคืนสถานะเริ่มต้นใหม่สำหรับเป้าหมายในการเปลี่ยนแปลงครั้งต่อๆ ไป

หลังจากสถานะเริ่มต้นเสร็จสมบูรณ์ ระบบจะแสดงผล CURRENT แม้ว่าเป้าหมายจะระบุไว้ว่าเป็น CURRENT ก่อนหน้านี้ก็ตาม

ตัวเลือกธุรกรรม

ตัวเลือกสำหรับการสร้างธุรกรรมใหม่

ช่อง
ช่องการรวม mode โหมดของธุรกรรม mode ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
read_only

ReadOnly

ธุรกรรมนี้สามารถใช้สำหรับการดำเนินการอ่านเท่านั้น

read_write

ReadWrite

ธุรกรรมนี้สามารถนำไปใช้ทั้งการดำเนินการอ่านและเขียน

อ่านอย่างเดียว

ตัวเลือกสำหรับธุรกรรมที่สามารถใช้อ่านเอกสารได้เท่านั้น

ช่อง
ช่องการรวม consistency_selector โหมดความสอดคล้องสำหรับธุรกรรมนี้ หากไม่ได้ตั้งค่า ระบบจะใช้ความสอดคล้องที่อัปเดตเป็นค่าเริ่มต้น consistency_selector ต้องเป็นค่าใดค่าหนึ่งต่อไปนี้
read_time

Timestamp

อ่านเอกสารในเวลาที่ระบุ

โดยต้องเป็นการประทับเวลาที่มีความแม่นยำระดับไมโครวินาทีในช่วง 1 ชั่วโมงที่ผ่านมา หรือหากมีการเปิดใช้การกู้คืนช่วงเวลา ก็อาจเป็นการประทับเวลาแบบเต็มนาทีภายใน 7 วันที่ผ่านมาได้

อ่านเขียน

ตัวเลือกสำหรับธุรกรรมที่ใช้อ่านและเขียนเอกสารได้

Firestore ไม่อนุญาตให้คำขอการตรวจสอบสิทธิ์ของบุคคลที่สามสร้างแบบอ่าน-เขียน ธุรกรรม

ช่อง
retry_transaction

bytes

ธุรกรรมที่ไม่บังคับที่จะลองอีกครั้ง

อัปเดตเอกสารคำขอ

คำขอสำหรับ 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

ค่า Double

timestamp_value

Timestamp

ค่าการประทับเวลา

เจาะจงเฉพาะไมโครวินาที เมื่อจัดเก็บ ระบบจะปัดเศษความแม่นยำเพิ่มเติมลง

string_value

string

ค่าสตริง

สตริงที่แสดงเป็น UTF-8 ต้องมีขนาดไม่เกิน 1 MiB - 89 ไบต์ เฉพาะการค้นหา 1,500 ไบต์แรกของการแสดงแบบ UTF-8 เท่านั้น

bytes_value

bytes

ค่าไบต์

ต้องไม่เกิน 1 MiB - 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

ใช้การเปลี่ยนรูปแบบกับเอกสาร

เขียนคำขอ

คำขอสำหรับ 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>

ป้ายกำกับที่เชื่อมโยงกับคำขอเขียนนี้

เขียนคำตอบ

การตอบกลับสำหรับ Firestore.Write

ช่อง
stream_id

string

รหัสของสตรีม กำหนดไว้ในข้อความแรกเท่านั้น เมื่อมีการสร้างสตรีมใหม่

stream_token

bytes

โทเค็นที่แสดงตำแหน่งของคำตอบนี้ในสตรีม ในกรณีนี้ ลูกค้าสามารถสตรีมต่อได้

ตั้งค่าช่องนี้ไว้เสมอ

write_results[]

WriteResult

ผลลัพธ์ของการใช้การเขียน

ผลการเขียน i-th นี้สอดคล้องกับการเขียน i-th ในคำขอ

commit_time

Timestamp

เวลาที่การคอมมิตเกิดขึ้น การอ่านที่มี read_time เท่ากันหรือมากกว่าได้เห็นผลของการเขียน

ผลลัพธ์ของการเขียน

ผลลัพธ์ของการใช้การเขียน

ช่อง
update_time

Timestamp

เวลาอัปเดตเอกสารครั้งล่าสุดหลังจากใช้การเขียน ไม่ได้ตั้งค่าหลังจาก delete

หากการเขียนไม่ได้เปลี่ยนแปลงเอกสารจริงๆ นี่จะเป็นupdate_time ก่อนหน้า

transform_results[]

Value

ผลลัพธ์ของการใช้ DocumentTransform.FieldTransform แต่ละรายการในลำดับเดียวกัน