Package google.firestore.v1beta1

Chỉ mục

Firestore

Dịch vụ Cloud Firestore.

Cloud Firestore là cơ sở dữ liệu tài liệu NoSQL nhanh, được quản lý đầy đủ, không máy chủ và dựa trên đám mây, giúp đơn giản hoá việc lưu trữ, đồng bộ hoá và truy vấn dữ liệu cho các ứng dụng di động, web và IoT của bạn trên quy mô toàn cầu. Thư viện ứng dụng của Google cung cấp tính năng đồng bộ hoá trực tiếp và hỗ trợ ngoại tuyến, đồng thời cung cấp các tính năng bảo mật và các công cụ tích hợp với Firebase và Google Cloud Platform giúp đẩy nhanh việc xây dựng các ứng dụng thực sự không cần máy chủ.

Loạt tài liệu

rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse)

Nhận nhiều tài liệu.

Google không đảm bảo việc trả lại tài liệu bằng phương thức này theo đúng thứ tự mà chúng tôi yêu cầu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Ghi hàng loạt

rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse)

Áp dụng một loạt thao tác ghi.

Phương thức BatchWrite không áp dụng từng bước các tác vụ ghi và có thể áp dụng các tác vụ đó không đúng thứ tự. Phương thức không cho phép ghi nhiều hơn một lần cho mỗi tài liệu. Mỗi lượt ghi có thể thực hiện thành công hoặc không thành công một cách độc lập. Xem BatchWriteResponse để biết trạng thái thành công của mỗi lượt ghi.

Nếu bạn cần một tập hợp các thao tác ghi được áp dụng tỉ mỉ, hãy sử dụng Commit.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Bắt đầu giao dịch

rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse)

Bắt đầu một giao dịch mới.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Xác nhận

rpc Commit(CommitRequest) returns (CommitResponse)

Xác nhận giao dịch, trong khi không bắt buộc cập nhật tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Tạo tài liệu

rpc CreateDocument(CreateDocumentRequest) returns (Document)

Tạo tài liệu mới.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Xoá tài liệu

rpc DeleteDocument(DeleteDocumentRequest) returns (Empty)

Xoá một tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Nhận tài liệu

rpc GetDocument(GetDocumentRequest) returns (Document)

Tải một tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Mã ListCollection

rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse)

Liệt kê tất cả mã bộ sưu tập bên dưới một tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Tài liệu dạng danh sách

rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse)

Liệt kê tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Nghe

rpc Listen(ListenRequest) returns (ListenResponse)

Lắng nghe các thay đổi. Phương thức này chỉ dùng được thông qua gRPC hoặc WebChannel (không phải REST).

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Truy vấn phân vùng

rpc PartitionQuery(PartitionQueryRequest) returns (PartitionQueryResponse)

Phân vùng truy vấn bằng cách trả về con trỏ phân vùng có thể dùng để chạy truy vấn song song. Con trỏ phân vùng được trả về là các điểm phân tách mà RunQuery có thể sử dụng làm điểm bắt đầu/kết thúc cho kết quả truy vấn.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Khôi phục

rpc Rollback(RollbackRequest) returns (Empty)

Khôi phục một giao dịch.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Truy vấn tổng hợp

rpc RunAggregationQuery(RunAggregationQueryRequest) returns (RunAggregationQueryResponse)

Chạy một truy vấn tổng hợp.

Thay vì tạo kết quả Document như Firestore.RunQuery, API này cho phép chạy tổng hợp để tạo một loạt AggregationResult phía máy chủ.

Ví dụ ở cấp cao:

-- Return the number of documents in table given a filter.
SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

RunQuery (Truy vấn chạy)

rpc RunQuery(RunQueryRequest) returns (RunQueryResponse)

Chạy một truy vấn.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Cập nhật tài liệu

rpc UpdateDocument(UpdateDocumentRequest) returns (Document)

Cập nhật hoặc chèn một tài liệu.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Viết

rpc Write(WriteRequest) returns (WriteResponse)

Phát trực tuyến các đợt cập nhật và xoá tài liệu theo thứ tự. Phương thức này chỉ dùng được thông qua gRPC hoặc WebChannel (không phải REST).

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

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

Để biết thêm thông tin, hãy xem bài viết Tổng quan về việc xác thực.

Kết quả tổng hợp

Kết quả của một bộ chứa trong một truy vấn tổng hợp trên Firestore.

Khoá của aggregate_fields là giống nhau cho tất cả kết quả trong một truy vấn tổng hợp, không giống như các truy vấn tài liệu có thể có các trường khác nhau cho mỗi kết quả.

Trường
aggregate_fields

map<string, Value>

Kết quả của các hàm tổng hợp, ví dụ: COUNT(*) AS total_docs.

Khoá là alias được gán cho hàm tổng hợp khi nhập vào và kích thước của tệp ánh xạ này bằng số hàm tổng hợp trong truy vấn.

Giá trị mảng

Một giá trị mảng.

Trường
values[]

Value

Giá trị trong mảng.

BatchGetDocumentsRequest

Yêu cầu cho Firestore.BatchGetDocuments.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

documents[]

string

Tên tài liệu cần truy xuất. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}. Yêu cầu sẽ không thành công nếu có bất kỳ tài liệu nào không phải là tài nguyên con của database đã cho. Những tên trùng lặp sẽ bị loại bỏ.

mask

DocumentMask

Các trường cần trả về. Nếu bạn không đặt chính sách này, hệ thống sẽ trả về tất cả các trường.

Nếu một tài liệu có một trường không có trong mặt nạ này, thì trường đó sẽ không được trả về trong phản hồi.

Trường kết hợp consistency_selector. Chế độ nhất quán cho giao dịch này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

bytes

Đọc tài liệu trong một giao dịch.

new_transaction

TransactionOptions

Bắt đầu một giao dịch mới và đọc tài liệu. Mặc định là giao dịch chỉ có thể đọc. Mã giao dịch mới sẽ được trả về dưới dạng phản hồi đầu tiên trong luồng.

read_time

Timestamp

Đọc tài liệu như tại thời điểm đã cho.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Phản hồi BatchGetDocumentsResponse

Đã truyền trực tuyến câu trả lời cho Firestore.BatchGetDocuments.

Trường
transaction

bytes

Giao dịch đã bắt đầu theo yêu cầu này. Sẽ chỉ được thiết lập trong phản hồi đầu tiên và chỉ khi BatchGetDocumentsRequest.new_transaction được thiết lập trong yêu cầu.

read_time

Timestamp

Thời gian tài liệu được đọc. Số liệu này có thể tăng lên một cách đơn điệu, trong trường hợp này, các tài liệu trước đó trong luồng kết quả được đảm bảo không thay đổi giữa thời gian đọc và thời gian đọc này.

Trường kết hợp result. Một kết quả duy nhất. Trường này có thể trống nếu máy chủ chỉ trả về một giao dịch. result chỉ có thể là một trong những trạng thái sau đây:
found

Document

Tài liệu đã được yêu cầu.

missing

string

Tên tài liệu đã được yêu cầu nhưng không tồn tại. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}.

BatchWriteRequest (Yêu cầu ghi lô)

Yêu cầu cho Firestore.BatchWrite.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

writes[]

Write

Các quyền cần ghi để áp dụng.

Phương thức không áp dụng cho việc ghi ở cấp độ nguyên tử và không đảm bảo thứ tự. Mỗi lượt ghi có thể thực hiện thành công hoặc không thành công một cách độc lập. Bạn không thể ghi vào cùng một tài liệu nhiều lần cho mỗi yêu cầu.

labels

map<string, string>

Các nhãn được liên kết với thao tác ghi hàng loạt này.

Phản hồi hàng loạt

Phản hồi của Firestore.BatchWrite.

Trường
write_results[]

WriteResult

Kết quả của việc áp dụng hoạt động ghi.

Kết quả ghi thứ i này tương ứng với lần ghi thứ i trong yêu cầu.

status[]

Status

Trạng thái áp dụng lượt ghi.

Trạng thái ghi thứ i này tương ứng với lần ghi thứ i trong yêu cầu.

Bắt đầu giao dịchRequest

Yêu cầu cho Firestore.BeginTransaction.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

options

TransactionOptions

Các tuỳ chọn cho giao dịch. Mặc định là giao dịch đọc-ghi.

Bắt đầu giao dịch phản hồi

Phản hồi cho Firestore.BeginTransaction.

Trường
transaction

bytes

Giao dịch đã được bắt đầu.

Trình tự bit

Một chuỗi bit, được mã hoá trong một mảng byte.

Mỗi byte trong mảng byte bitmap lưu trữ 8 bit của chuỗi. Ngoại lệ duy nhất là byte cuối cùng có thể lưu trữ 8 hoặc ít hơn bit. padding xác định số bit của byte cuối cùng bị bỏ qua dưới dạng "khoảng đệm". Giá trị của những "khoảng đệm" này bit không xác định và phải được bỏ qua.

Để truy xuất bit đầu tiên, bit 0, hãy tính: (bitmap[0] & 0x01) != 0. Để truy xuất bit thứ hai, bit 1, hãy tính: (bitmap[0] & 0x02) != 0. Để truy xuất bit thứ ba, bit 2, hãy tính: (bitmap[0] & 0x04) != 0. Để truy xuất bit thứ tư, bit 3, hãy tính: (bitmap[0] & 0x08) != 0. Để truy xuất bit n, hãy tính: (bitmap[n / 8] & (0x01 << (n % 8))) != 0.

"Kích thước" của BitSequence (số bit trong lớp) được tính theo công thức sau: (bitmap.length * 8) - padding.

Trường
bitmap

bytes

Các byte mã hoá chuỗi bit. Có thể có độ dài bằng 0.

padding

int32

Số bit của byte cuối cùng trong bitmap cần bỏ qua dưới dạng "khoảng đệm". Nếu độ dài của bitmap bằng 0 thì giá trị này phải là 0. Nếu không, giá trị này phải nằm trong khoảng từ 0 đến 7.

Bộ lọc BloomFilter

Bộ lọc hoa (https://en.wikipedia.org/wiki/Bloom_filter).

Bộ lọc nở băm các mục nhập bằng MD5 và coi hàm băm 128 bit kết quả là 2 giá trị băm 64 bit riêng biệt, được hiểu là số nguyên chưa ký bằng cách sử dụng mã hóa bổ sung của 2.

Hai giá trị hàm băm này (được đặt tên là h1h2) sau đó được dùng để tính toán các giá trị hàm băm hash_count bằng công thức, bắt đầu từ i=0:

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

Sau đó, các giá trị thu được này được lấy mô-đun số bit trong bộ lọc nở hoa để lấy các bit của bộ lọc nở hoa nhằm kiểm tra mục nhập nhất định.

Trường
bits

BitSequence

Dữ liệu về bộ lọc bông hoa.

hash_count

int32

Số lượng hàm băm mà thuật toán sử dụng.

Yêu cầu xác nhận

Yêu cầu cho Firestore.Commit.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

writes[]

Write

Các quyền cần ghi để áp dụng.

Luôn thực thi tỉ mỉ và theo thứ tự.

transaction

bytes

Nếu được đặt, sẽ áp dụng tất cả các lượt ghi trong giao dịch này và cam kết.

Phản hồi cam kết

Phản hồi cho Firestore.Commit.

Trường
write_results[]

WriteResult

Kết quả của việc áp dụng hoạt động ghi.

Kết quả ghi thứ i này tương ứng với lần ghi thứ i trong yêu cầu.

commit_time

Timestamp

Thời gian thực hiện cam kết. Bất kỳ lượt đọc nào có read_time bằng hoặc lớn hơn đều đảm bảo thấy được hiệu quả của lệnh xác nhận.

CreateDocumentRequest (Yêu cầu tạo tài liệu)

Yêu cầu cho Firestore.CreateDocument.

Trường
parent

string

Bắt buộc. Tài nguyên mẹ. Ví dụ: projects/{project_id}/databases/{database_id}/documents hoặc projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}

collection_id

string

Bắt buộc. Mã bộ sưu tập, so với parent, so với danh sách. Ví dụ: chatrooms.

document_id

string

Mã tài liệu do khách hàng chỉ định để sử dụng cho tài liệu này.

Không bắt buộc. Nếu bạn không chỉ định, dịch vụ sẽ gán một mã nhận dạng.

document

Document

Bắt buộc. Tài liệu cần tạo. Không được đặt name.

mask

DocumentMask

Các trường cần trả về. Nếu bạn không đặt chính sách này, hệ thống sẽ trả về tất cả các trường.

Nếu tài liệu có một trường không có trong mặt nạ này, thì trường đó sẽ không được trả về trong phản hồi.

Con trỏ

Một vị trí trong tập hợp kết quả truy vấn.

Trường
values[]

Value

Các giá trị đại diện cho một vị trí, theo thứ tự mà chúng xuất hiện theo thứ tự theo mệnh đề của truy vấn.

Có thể chứa ít giá trị hơn giá trị được chỉ định theo mệnh đề thứ tự theo.

before

bool

Nếu vị trí ngay trước hoặc ngay sau các giá trị đã cho, so với thứ tự sắp xếp mà truy vấn xác định.

Yêu cầu xoá tài liệu

Yêu cầu cho Firestore.DeleteDocument.

Trường
name

string

Bắt buộc. Tên tài nguyên của Tài liệu cần xoá. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}.

current_document

Precondition

Điều kiện tiên quyết (không bắt buộc) trên tài liệu. Yêu cầu sẽ không thành công nếu giá trị này được thiết lập nhưng tài liệu đích không đáp ứng.

Tài liệu

Tài liệu trên Firestore.

Không được vượt quá 1 MiB – 4 byte.

Trường
name

string

Tên tài nguyên của tài liệu, ví dụ: projects/{project_id}/databases/{database_id}/documents/{document_path}.

fields

map<string, Value>

create_time

Timestamp

Chỉ có đầu ra. Thời gian tạo tài liệu.

Giá trị này tăng đơn điệu khi một tài liệu bị xoá rồi tạo lại. Giá trị này cũng có thể được so sánh với giá trị trong các tài liệu khác và read_time của truy vấn.

update_time

Timestamp

Chỉ có đầu ra. Thời điểm tài liệu được thay đổi lần gần đây nhất.

Ban đầu, giá trị này được đặt thành create_time, sau đó tăng lên đơn điệu mỗi khi thực hiện thay đổi đối với tài liệu. Giá trị này cũng có thể được so sánh với giá trị trong các tài liệu khác và read_time của truy vấn.

Thay đổi tài liệu

Document đã thay đổi.

Có thể là kết quả của nhiều writes, bao gồm cả việc xoá, mà cuối cùng đã dẫn đến một giá trị mới cho Document.

Hệ thống có thể trả về nhiều thông báo DocumentChange cho cùng một thay đổi về logic nếu nhiều mục tiêu bị ảnh hưởng.

Trường
document

Document

Trạng thái mới của Document.

Nếu bạn đặt mask, thì chỉ chứa các trường đã được cập nhật hoặc thêm.

target_ids[]

int32

Một tập hợp mã mục tiêu của các mục tiêu phù hợp với tài liệu này.

removed_target_ids[]

int32

Một tập hợp mã mục tiêu cho các mục tiêu không còn khớp với tài liệu này.

Xoá tài liệu

Đã xoá một Document.

Có thể là do có nhiều writes, bao gồm cả nội dung cập nhật, lần cập nhật gần đây nhất đã xoá Document.

Hệ thống có thể trả về nhiều thông báo DocumentDelete cho cùng một thao tác xoá theo logic, nếu nhiều mục tiêu bị ảnh hưởng.

Trường
document

string

Tên tài nguyên của Document đã bị xoá.

removed_target_ids[]

int32

Một bộ mã mục tiêu cho các mục tiêu trước đây đã khớp với thực thể này.

read_time

Timestamp

Dấu thời gian đọc khi quan sát thấy thao tác xoá.

Lớn hơn hoặc bằng commit_time của thao tác xoá.

Mặt nạ tài liệu

Một tập hợp các đường dẫn trường trên một tài liệu. Dùng để hạn chế thao tác tải hoặc cập nhật trên một tài liệu ở một nhóm nhỏ các trường. Điều này khác với mặt nạ trường chuẩn vì luôn thuộc phạm vi của Document và có tính đến tính chất động của Value.

Trường
field_paths[]

string

Danh sách các đường dẫn trường trong mặt nạ. Hãy xem Document.fields để tham khảo cú pháp đường dẫn trường.

Xóa tài liệu

Đã xoá Document khỏi chế độ xem mục tiêu.

Được gửi nếu tài liệu không còn liên quan đến một mục tiêu và không nhìn thấy được. Có thể được gửi thay cho DocumentDelete hoặc DocumentChange nếu máy chủ không thể gửi giá trị mới của tài liệu.

Hệ thống có thể trả về nhiều thông báo DocumentRemove cho cùng một thao tác ghi hoặc xoá logic, nếu nhiều mục tiêu bị ảnh hưởng.

Trường
document

string

Tên tài nguyên của Document đã bị ẩn.

removed_target_ids[]

int32

Một bộ mã mục tiêu cho các mục tiêu trước đây đã khớp với tài liệu này.

read_time

Timestamp

Dấu thời gian đọc khi quan sát thấy hoạt động xoá.

Lớn hơn hoặc bằng commit_time của thay đổi/xoá/xoá.

DocumentTransform

Biến đổi tài liệu.

Trường
document

string

Tên của tài liệu cần chuyển đổi.

field_transforms[]

FieldTransform

Danh sách các phép biến đổi theo thứ tự áp dụng cho các trường trong tài liệu. Không được để trống trường này.

Chuyển đổi trường

Biến đổi một trường của tài liệu.

Trường
field_path

string

Đường dẫn của trường. Hãy xem Document.fields để tham khảo cú pháp đường dẫn trường.

Trường kết hợp transform_type. Phép biến đổi để áp dụng trên trường. transform_type chỉ có thể là một trong những trạng thái sau đây:
set_to_server_value

ServerValue

Đặt trường này thành giá trị máy chủ đã cho.

increment

Value

Cộng giá trị đã cho vào giá trị hiện tại của trường.

Đây phải là một số nguyên hoặc một giá trị kép. Nếu trường không phải là số nguyên hoặc giá trị kép hoặc nếu trường chưa tồn tại, phép biến đổi sẽ đặt trường này thành giá trị đã cho. Nếu một trong hai giá trị đã cho hoặc giá trị của trường hiện tại tăng gấp đôi, thì cả hai giá trị sẽ được hiểu là tăng gấp đôi. Số học kép và biểu diễn các giá trị kép tuân theo ngữ nghĩa của IEEE 754. Nếu bị tràn số nguyên dương/âm, thì trường này sẽ được phân giải thành số nguyên dương/âm có độ lớn lớn nhất.

maximum

Value

Đặt trường thành giá trị tối đa hiện tại của trường và giá trị đã cho.

Đây phải là một số nguyên hoặc một giá trị kép. Nếu trường không phải là số nguyên hoặc giá trị kép hoặc nếu trường chưa tồn tại, phép biến đổi sẽ đặt trường này thành giá trị đã cho. Nếu áp dụng phép toán tối đa khi trường và giá trị đầu vào thuộc kiểu kết hợp (nghĩa là một là số nguyên và một là số nhân đôi), thì trường sẽ nhận kiểu của toán hạng lớn hơn. Nếu các toán hạng là tương đương (ví dụ: 3 và 3.0), thì trường sẽ không thay đổi. 0, 0.0 và -0.0 đều bằng 0. Giá trị tối đa của một giá trị được lưu trữ bằng 0 và giá trị đầu vào bằng 0 luôn là giá trị được lưu trữ. Giá trị lớn nhất của giá trị số x và NaN bất kỳ là NaN.

minimum

Value

Đặt trường thành giá trị nhỏ nhất của giá trị hiện tại và giá trị đã cho.

Đây phải là một số nguyên hoặc một giá trị kép. Nếu trường không phải là số nguyên hoặc giá trị kép hoặc nếu trường chưa tồn tại, phép biến đổi sẽ đặt trường này thành giá trị đầu vào. Nếu áp dụng một phép toán tối thiểu khi trường và giá trị đầu vào thuộc kiểu hỗn hợp (nghĩa là một là số nguyên và một là số nhân đôi), thì trường sẽ nhận kiểu của toán hạng nhỏ hơn. Nếu các toán hạng là tương đương (ví dụ: 3 và 3.0), thì trường sẽ không thay đổi. 0, 0.0 và -0.0 đều bằng 0. Giá trị tối thiểu của một giá trị được lưu trữ bằng 0 và giá trị đầu vào bằng 0 luôn là giá trị được lưu trữ. Giá trị nhỏ nhất của giá trị số x và NaN bất kỳ là NaN.

append_missing_elements

ArrayValue

Thêm các phần tử đã cho theo thứ tự nếu chúng chưa có trong giá trị trường hiện tại. Nếu trường không phải là một mảng hoặc nếu trường này chưa tồn tại, thì trước tiên trường đó được đặt cho mảng trống.

Các số tương đương của các loại khác nhau (ví dụ: 3L và 3.0) được coi là bằng nhau khi kiểm tra xem có thiếu giá trị nào không. NaN bằng NaN và rỗng bằng với Null. Nếu giá trị nhập vào chứa nhiều giá trị tương đương, thì chỉ có giá trị đầu tiên được xem xét.

Biến đổi_kết_quả tương ứng sẽ là giá trị rỗng.

remove_all_from_array

ArrayValue

Xoá tất cả các phần tử đã cho khỏi mảng trong trường. Nếu trường không phải là một mảng hoặc nếu trường chưa tồn tại, thì trường sẽ được đặt thành mảng trống.

Số lượng tương đương của các loại khác nhau (ví dụ: 3L và 3.0) được coi là bằng nhau khi quyết định có nên xóa một phần tử hay không. NaN bằng NaN và rỗng bằng với Null. Thao tác này sẽ xoá tất cả các giá trị tương đương nếu có trùng lặp.

Biến đổi_kết_quả tương ứng sẽ là giá trị rỗng.

Giá trị máy chủ

Một giá trị do máy chủ tính toán.

Enum
SERVER_VALUE_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
REQUEST_TIME Thời gian máy chủ xử lý yêu cầu với độ chính xác từng mili giây. Nếu được sử dụng trên nhiều trường (cùng hoặc khác tài liệu) trong một giao dịch, thì tất cả các trường sẽ có cùng dấu thời gian máy chủ.

Thống kê thực thi

Số liệu thống kê về việc thực thi truy vấn.

Trường
results_returned

int64

Tổng số kết quả được trả về, bao gồm tài liệu, phép chiếu, kết quả tổng hợp, khoá.

execution_duration

Duration

Tổng thời gian thực thi truy vấn trong phần phụ trợ.

read_operations

int64

Tổng số hoạt động đọc có thể tính phí.

debug_stats

Struct

Gỡ lỗi số liệu thống kê khỏi quá trình thực thi truy vấn. Xin lưu ý rằng số liệu thống kê gỡ lỗi có thể thay đổi khi Firestore phát triển. Thông tin này có thể bao gồm: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" }

Bộ lọc tồn tại

Chuỗi đại diện của tất cả các tài liệu phù hợp với một mục tiêu nhất định.

Trường
target_id

int32

Mã mục tiêu được áp dụng bộ lọc này.

count

int32

Tổng số tài liệu khớp với target_id.

Nếu khác với số lượng tài liệu trong ứng dụng trùng khớp, thì khách hàng phải xác định thủ công những tài liệu nào không còn khớp với mục tiêu.

Ứng dụng có thể sử dụng bộ lọc nở hoa unchanged_names để hỗ trợ việc xác định này bằng cách kiểm tra TẤT CẢ tên tài liệu so với bộ lọc; nếu tên tài liệu KHÔNG có trong bộ lọc, thì có nghĩa là tài liệu đó không còn khớp với mục tiêu.

unchanged_names

BloomFilter

Bộ lọc nở hoa, bất kể tên của bộ lọc, chứa mã hoá byte UTF-8 cho tên tài nguyên của TẤT CẢ các tài liệu khớp với target_id, ở dạng projects/{project_id}/databases/{database_id}/documents/{document_path}.

Bộ lọc nở có thể được bỏ qua theo quyết định của máy chủ, chẳng hạn như nếu máy khách cho rằng máy khách sẽ không sử dụng bộ lọc đó hoặc nếu việc tính toán hoặc truyền tải quá tốn kém. Ứng dụng phải xử lý linh hoạt trường này khi không có trường này bằng cách quay lại logic được sử dụng trước khi trường này tồn tại; tức là thêm lại mục tiêu mà không có mã thông báo sơ yếu lý lịch để xác định xem tài liệu nào trong bộ nhớ đệm của ứng dụng không đồng bộ hoá.

Giải thích chỉ số

Giải thích các chỉ số cho truy vấn.

Trường
plan_summary

PlanSummary

Thông tin về giai đoạn lập kế hoạch cho truy vấn.

execution_stats

ExecutionStats

Số liệu thống kê tổng hợp từ việc thực thi truy vấn. Chỉ hiển thị khi ExplainOptions.analyze được đặt thành true.

Giải thíchTuỳ chọn

Giải thích các tuỳ chọn cho truy vấn.

Trường
analyze

bool

Không bắt buộc. Liệu có thực thi truy vấn này hay không.

Khi giá trị là false (mặc định), truy vấn sẽ được lập kế hoạch, chỉ trả về các chỉ số trong giai đoạn lập kế hoạch.

Khi đúng, truy vấn sẽ được lên kế hoạch và thực thi, trả về kết quả truy vấn đầy đủ cùng với cả chỉ số giai đoạn lập kế hoạch và thực thi.

GetDocumentRequest

Yêu cầu cho Firestore.GetDocument.

Trường
name

string

Bắt buộc. Tên tài nguyên của Tài liệu cần tải. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}.

mask

DocumentMask

Các trường cần trả về. Nếu bạn không đặt chính sách này, hệ thống sẽ trả về tất cả các trường.

Nếu tài liệu có một trường không có trong mặt nạ này, thì trường đó sẽ không được trả về trong phản hồi.

Trường kết hợp consistency_selector. Chế độ nhất quán cho giao dịch này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

bytes

Đọc tài liệu trong một giao dịch.

read_time

Timestamp

Đọc phiên bản của tài liệu tại một thời điểm nhất định.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Yêu cầu ListCollectionIds

Yêu cầu cho Firestore.ListCollectionIds.

Trường
parent

string

Bắt buộc. Tài liệu gốc. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}. Ví dụ: projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

page_size

int32

Số lượng kết quả tối đa cần trả về.

page_token

string

Mã thông báo trang. Phải là một giá trị từ ListCollectionIdsResponse.

Trường kết hợp consistency_selector. Chế độ nhất quán cho yêu cầu này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
read_time

Timestamp

Đọc tài liệu như tại thời điểm đã cho.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Phản hồi ListCollectionIds

Phản hồi của Firestore.ListCollectionIds.

Trường
collection_ids[]

string

Mã bộ sưu tập.

next_page_token

string

Mã thông báo trang có thể được dùng để tiếp tục danh sách.

Yêu cầu danh sách tài liệu

Yêu cầu cho Firestore.ListDocuments.

Trường
parent

string

Bắt buộc. Tên tài nguyên mẹ. Ở định dạng: projects/{project_id}/databases/{database_id}/documents hoặc projects/{project_id}/databases/{database_id}/documents/{document_path}.

Ví dụ: projects/my-project/databases/my-database/documents hoặc projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

collection_id

string

Không bắt buộc. Mã bộ sưu tập, so với parent, so với danh sách.

Ví dụ: chatrooms hoặc messages.

Đây là việc không bắt buộc. Nếu không được cung cấp, Firestore sẽ liệt kê tài liệu từ mọi bộ sưu tập trong parent được cung cấp.

page_size

int32

Không bắt buộc. Số tài liệu tối đa được trả về trong một phản hồi.

Firestore có thể trả về ít hơn giá trị này.

page_token

string

Không bắt buộc. Mã thông báo trang, đã nhận được từ phản hồi trước đó của ListDocuments.

Cung cấp mã này để truy xuất trang tiếp theo. Khi phân trang, tất cả các thông số khác (ngoại trừ page_size) phải khớp với các giá trị được đặt trong yêu cầu đã tạo mã thông báo trang.

order_by

string

Không bắt buộc. Thứ tự trả lại chứng từ (không bắt buộc).

Ví dụ: priority desc, __name__ desc.

Điều này phản ánh ORDER BY được dùng trong các truy vấn Firestore nhưng ở dạng chuỗi. Khi không có, giấy tờ sẽ được sắp xếp dựa trên __name__ ASC.

mask

DocumentMask

Không bắt buộc. Các trường cần trả về. Nếu bạn không đặt chính sách này, hệ thống sẽ trả về tất cả các trường.

Nếu một tài liệu có một trường không có trong mặt nạ này, thì trường đó sẽ không được trả về trong phản hồi.

show_missing

bool

Nếu danh sách hiển thị các tài liệu còn thiếu.

Tài liệu bị thiếu nếu không tồn tại nhưng có các tài liệu phụ được lồng bên dưới. Nếu đúng, những tài liệu bị thiếu đó sẽ được trả về bằng một khoá nhưng sẽ không có các trường, create_time hoặc update_time được đặt.

Yêu cầu có show_missing không được chỉ định where hoặc order_by.

Trường kết hợp consistency_selector. Chế độ nhất quán cho giao dịch này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

bytes

Thực hiện việc đọc như một phần của giao dịch đang hoạt động.

read_time

Timestamp

Thực hiện việc đọc tại thời gian được cung cấp.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Phản hồi danh sách tài liệu

Phản hồi cho Firestore.ListDocuments.

Trường
documents[]

Document

Đã tìm thấy Tài liệu.

next_page_token

string

Mã thông báo để truy xuất trang tiếp theo của tài liệu.

Nếu trường này bị bỏ qua thì sẽ không có trang tiếp theo.

ListenRequest

Yêu cầu cho Firestore.Listen

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

labels

map<string, string>

Nhãn được liên kết với thay đổi mục tiêu này.

Trường kết hợp target_change. Mục tiêu được hỗ trợ sẽ thay đổi. target_change chỉ có thể là một trong những trạng thái sau đây:
add_target

Target

Một mục tiêu để thêm vào luồng này.

remove_target

int32

Mã của mục tiêu cần xoá khỏi luồng này.

ListenResponse

Phản hồi cho Firestore.Listen.

Trường
Trường kết hợp response_type. Câu trả lời được hỗ trợ. response_type chỉ có thể là một trong những trạng thái sau đây:
target_change

TargetChange

Các mục tiêu đã thay đổi.

document_change

DocumentChange

Document đã thay đổi.

document_delete

DocumentDelete

Đã xoá một Document.

document_remove

DocumentRemove

Document đã bị xoá khỏi một mục tiêu (vì không còn liên quan đến mục tiêu đó nữa).

filter

ExistenceFilter

Một bộ lọc để áp dụng cho tập hợp các tài liệu đã được trả về trước đó cho mục tiêu đã cho.

Được trả về khi tài liệu có thể đã bị xoá khỏi mục tiêu cho trước, nhưng không xác định được chính xác tài liệu.

Giá trị ánh xạ

Giá trị ánh xạ.

Trường
fields

map<string, Value>

Các trường trên bản đồ.

Các khoá bản đồ biểu thị tên trường. Tên trường khớp với biểu thức chính quy __.*__ sẽ được dành riêng. Cấm các tên trường dành riêng ngoại trừ trong một số ngữ cảnh được ghi chép nhất định. Các khoá ánh xạ, được biểu thị dưới dạng UTF-8, không được vượt quá 1.500 byte và không được để trống.

Yêu cầu phân vùng

Yêu cầu cho Firestore.PartitionQuery.

Trường
parent

string

Bắt buộc. Tên tài nguyên mẹ. Ở định dạng: projects/{project_id}/databases/{database_id}/documents. Tên tài nguyên tài liệu không được hỗ trợ; chỉ có thể chỉ định tên tài nguyên cơ sở dữ liệu.

partition_count

int64

Số điểm phân vùng tối đa mong muốn. Các phân vùng có thể được trả về trên nhiều trang kết quả. Số phải là số dương. Số lượng phân vùng thực tế được trả về có thể ít hơn.

Ví dụ: giá trị này có thể được đặt ít hơn 1 so với số lượng truy vấn song song sẽ chạy, hoặc khi chạy một công việc quy trình dữ liệu, ít hơn một so với số lượng worker hoặc thực thể điện toán có sẵn.

page_token

string

Giá trị next_page_token được trả về từ lệnh gọi trước đó tới PartitionQuery. Giá trị này có thể dùng để nhận thêm một tập hợp kết quả. Không có sự đảm bảo về thứ tự giữa các tập hợp kết quả. Do đó, việc sử dụng nhiều tập hợp kết quả sẽ đòi hỏi phải hợp nhất các tập hợp kết quả khác nhau.

Ví dụ: hai lệnh gọi tiếp theo sử dụng page_token có thể trả về:

  • con trỏ B, con trỏ M, con trỏ Q
  • con trỏ A, con trỏ U, con trỏ W

Để có được tập hợp kết quả hoàn chỉnh theo thứ tự tương ứng với kết quả của truy vấn được cung cấp cho Phân vùng, các tập hợp kết quả phải được hợp nhất: con trỏ A, con trỏ B, con trỏ M, con trỏ Q, con trỏ U, con trỏ W

page_size

int32

Số lượng phân vùng tối đa cần trả về trong lệnh gọi này, tuỳ thuộc vào partition_count.

Ví dụ: nếu partition_count = 10 và page_size = 8, lệnh gọi đầu tiên đến PartitionQuery sẽ trả về tối đa 8 phân vùng và một next_page_token nếu tồn tại nhiều kết quả hơn. Lệnh gọi thứ hai đến PartitionQuery sẽ trả về tối đa 2 phân vùng để hoàn thành tổng cộng 10 phân vùng được chỉ định trong partition_count.

Trường kết hợp query_type. Truy vấn để phân vùng. query_type chỉ có thể là một trong những trạng thái sau đây:
structured_query

StructuredQuery

Truy vấn có cấu trúc. Truy vấn phải chỉ định tập hợp gồm tất cả các thành phần con và được sắp xếp theo tên tăng dần. Các bộ lọc, thứ tự by, giới hạn, độ lệch và con trỏ bắt đầu/kết thúc khác không được hỗ trợ.

Trường kết hợp consistency_selector. Chế độ nhất quán cho yêu cầu này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
read_time

Timestamp

Đọc tài liệu như tại thời điểm đã cho.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Phân vùng truy vấn phản hồi

Phản hồi cho Firestore.PartitionQuery.

Trường
partitions[]

Cursor

Kết quả phân vùng. Mỗi phân vùng là một điểm phân tách có thể được RunQuery sử dụng làm điểm bắt đầu hoặc điểm kết thúc cho kết quả truy vấn. Các yêu cầu RunQuery phải được thực hiện bằng cùng một truy vấn được cung cấp cho yêu cầu Phân vùng này. Các con trỏ phân vùng sẽ được sắp xếp theo cùng thứ tự như kết quả của truy vấn được cung cấp cho PartitionQuery.

Ví dụ: nếu yêu cầu PartitionQuery trả về con trỏ phân vùng A và B, thì việc chạy ba truy vấn sau sẽ trả về toàn bộ tập hợp kết quả của truy vấn ban đầu:

  • truy vấn, end_at A
  • truy vấn, bắt đầu_tại A, kết thúc_tại B
  • truy vấn, bắt đầu_tại B

Kết quả trống có thể cho biết truy vấn có quá ít kết quả để phân vùng hoặc truy vấn chưa được hỗ trợ để phân vùng.

next_page_token

string

Mã thông báo trang có thể dùng để yêu cầu một tập hợp kết quả bổ sung, lên tới số lượng do partition_count chỉ định trong yêu cầu Phân vùng. Nếu trống thì không có kết quả nào khác.

Tóm tắt kế hoạch

Thông tin về giai đoạn lập kế hoạch cho truy vấn.

Trường
indexes_used[]

Struct

Các chỉ mục được chọn cho truy vấn. Ví dụ: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

Điều kiện tiên quyết

Điều kiện tiên quyết trên tài liệu, dùng cho các thao tác có điều kiện.

Trường
Trường kết hợp condition_type. Loại điều kiện tiên quyết. condition_type chỉ có thể là một trong những trạng thái sau đây:
exists

bool

Khi đặt thành true, tài liệu đích phải tồn tại. Khi đặt thành false, tài liệu đích không được tồn tại.

update_time

Timestamp

Khi được đặt, tài liệu đích phải tồn tại và được cập nhật lần gần đây nhất vào thời điểm đó. Dấu thời gian phải được căn chỉnh theo micrô giây.

Yêu cầu khôi phục

Yêu cầu cho Firestore.Rollback.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}.

transaction

bytes

Bắt buộc. Giao dịch được khôi phục.

Run tổng hợpQueryRequest

Yêu cầu cho Firestore.RunAggregationQuery.

Trường
parent

string

Bắt buộc. Tên tài nguyên mẹ. Ở định dạng: projects/{project_id}/databases/{database_id}/documents hoặc projects/{project_id}/databases/{database_id}/documents/{document_path}. Ví dụ: projects/my-project/databases/my-database/documents hoặc projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Không bắt buộc. Giải thích các tuỳ chọn cho truy vấn. Nếu được đặt, số liệu thống kê truy vấn bổ sung sẽ được trả về. Nếu không, hệ thống sẽ chỉ trả về kết quả truy vấn.

Trường kết hợp query_type. Truy vấn cần chạy. query_type chỉ có thể là một trong những trạng thái sau đây:
structured_aggregation_query

StructuredAggregationQuery

Truy vấn tổng hợp.

Trường kết hợp consistency_selector. Chế độ nhất quán cho truy vấn, mặc định là nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

bytes

Chạy tính năng tổng hợp trong một giao dịch đang hoạt động.

Giá trị ở đây là mã giao dịch mờ để thực thi truy vấn.

new_transaction

TransactionOptions

Bắt đầu một giao dịch mới trong truy vấn, chế độ mặc định là chỉ có thể đọc.

Mã giao dịch mới sẽ được trả về dưới dạng phản hồi đầu tiên trong luồng.

read_time

Timestamp

Thực thi truy vấn tại dấu thời gian cụ thể.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Run tổng hợpQueryResponse

Phản hồi cho Firestore.RunAggregationQuery.

Trường
result

AggregationResult

Một kết quả tổng hợp duy nhất.

Không xuất hiện khi báo cáo một phần tiến trình.

transaction

bytes

Giao dịch đã bắt đầu theo yêu cầu này.

Chỉ xuất hiện trong phản hồi đầu tiên khi yêu cầu được yêu cầu bắt đầu một giao dịch mới.

read_time

Timestamp

Thời điểm tính toán kết quả tổng hợp. Tỷ lệ này luôn tăng đơn điệu; trong trường hợp này, SyntheticResult trước đó trong luồng kết quả được đảm bảo không thay đổi giữa read_time và kết quả này.

Nếu truy vấn không trả về kết quả nào, thì phản hồi có read_time và không có result sẽ được gửi, đồng thời thể hiện thời gian chạy truy vấn.

explain_metrics

ExplainMetrics

Truy vấn giải thích về các chỉ số. Điều này chỉ có khi RunAggregationQueryRequest.explain_options được cung cấp và chỉ được gửi một lần cùng với phản hồi cuối cùng trong luồng.

RunQueryRequest

Yêu cầu cho Firestore.RunQuery.

Trường
parent

string

Bắt buộc. Tên tài nguyên mẹ. Ở định dạng: projects/{project_id}/databases/{database_id}/documents hoặc projects/{project_id}/databases/{database_id}/documents/{document_path}. Ví dụ: projects/my-project/databases/my-database/documents hoặc projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

explain_options

ExplainOptions

Không bắt buộc. Giải thích các tuỳ chọn cho truy vấn. Nếu được đặt, số liệu thống kê truy vấn bổ sung sẽ được trả về. Nếu không, hệ thống sẽ chỉ trả về kết quả truy vấn.

Trường kết hợp query_type. Truy vấn cần chạy. query_type chỉ có thể là một trong những trạng thái sau đây:
structured_query

StructuredQuery

Truy vấn có cấu trúc.

Trường kết hợp consistency_selector. Chế độ nhất quán cho giao dịch này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
transaction

bytes

Chạy truy vấn trong một giao dịch đang hoạt động.

Giá trị ở đây là mã giao dịch mờ để thực thi truy vấn.

new_transaction

TransactionOptions

Bắt đầu một giao dịch mới và đọc tài liệu. Mặc định là giao dịch chỉ có thể đọc. Mã giao dịch mới sẽ được trả về dưới dạng phản hồi đầu tiên trong luồng.

read_time

Timestamp

Đọc tài liệu như tại thời điểm đã cho.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

RunQueryResponse

Phản hồi cho Firestore.RunQuery.

Trường
transaction

bytes

Giao dịch đã bắt đầu theo yêu cầu này. Chỉ có thể thiết lập trong phản hồi đầu tiên và chỉ khi RunQueryRequest.new_transaction được đặt trong yêu cầu. Nếu được đặt, sẽ không có trường nào khác được đặt trong phản hồi này.

document

Document

Kết quả truy vấn, không được đặt khi báo cáo tiến trình một phần.

read_time

Timestamp

Thời gian tài liệu được đọc. Con số này có thể tăng lên một cách đơn điệu; trong trường hợp này, các tài liệu trước đó trong luồng kết quả được đảm bảo không thay đổi giữa read_time và tài liệu này.

Nếu truy vấn không trả về kết quả nào, thì phản hồi có read_time và không có document sẽ được gửi, đồng thời thể hiện thời gian chạy truy vấn.

skipped_results

int32

Số lượng kết quả đã bị bỏ qua do chênh lệch giữa phản hồi cuối cùng và phản hồi hiện tại.

explain_metrics

ExplainMetrics

Truy vấn giải thích về các chỉ số. Điều này chỉ có khi RunQueryRequest.explain_options được cung cấp và chỉ được gửi một lần cùng với phản hồi cuối cùng trong luồng.

Trường kết hợp continuation_selector. Chế độ tiếp tục cho truy vấn. Nếu có, thì trạng thái này cho biết luồng phản hồi truy vấn hiện tại đã kết thúc. Bạn có thể đặt thuộc tính này có hoặc không có document, nhưng khi đặt giá trị này, hệ thống sẽ không trả về kết quả nào khác. continuation_selector chỉ có thể là một trong những trạng thái sau đây:
done

bool

Nếu có, Firestore đã hoàn tất yêu cầu và sẽ không trả lại tài liệu nào nữa.

Truy vấn tổng hợp có cấu trúc

Truy vấn trên Firestore để chạy tổng hợp trên StructuredQuery.

Trường
aggregations[]

Aggregation

Không bắt buộc. Chuỗi các hàm tổng hợp cần áp dụng cho kết quả của structured_query.

Yêu cầu:

  • Tối thiểu một và tối đa năm dữ liệu tổng hợp cho mỗi truy vấn.
Trường kết hợp query_type. Truy vấn cơ sở để tổng hợp. query_type chỉ có thể là một trong những trạng thái sau đây:
structured_query

StructuredQuery

Truy vấn có cấu trúc lồng nhau.

Tổng hợp

Xác định dữ liệu tổng hợp tạo ra một kết quả duy nhất.

Trường
alias

string

Không bắt buộc. Tên trường không bắt buộc dùng để lưu trữ kết quả tổng hợp.

Nếu không được cung cấp, Firestore sẽ chọn một tên mặc định theo định dạng field_<incremental_id++>. Ví dụ:

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 (
  ...
);

trở thành:

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 (
  ...
);

Yêu cầu:

  • Phải là duy nhất trên tất cả các bí danh tổng hợp.
  • Tuân thủ document field name giới hạn.
Trường kết hợp operator. Loại tổng hợp cần thực hiện, bắt buộc. operator chỉ có thể là một trong những trạng thái sau đây:
count

Count

Đơn vị tổng hợp số lượng.

sum

Sum

Trang web tổng hợp số liệu.

avg

Avg

Trang web tổng hợp trung bình.

Avg

Giá trị trung bình của các trường được yêu cầu.

  • Hệ thống chỉ tổng hợp các giá trị dạng số. Tất cả giá trị không phải số, bao gồm cả NULL, đều bị bỏ qua.

  • Nếu giá trị tổng hợp chứa NaN, hàm sẽ trả về NaN. Toán học của Infinity tuân theo tiêu chuẩn IEEE-754.

  • Nếu tập hợp giá trị tổng hợp trống, trả về NULL.

  • Luôn trả về kết quả dưới dạng kép.

Trường
field

FieldReference

Trường để tổng hợp.

Số lượng

Số lượng tài liệu khớp với truy vấn.

Hàm tổng hợp COUNT(*) hoạt động trên toàn bộ tài liệu nên không yêu cầu tham chiếu trường.

Trường
up_to

Int64Value

Không bắt buộc. Quy tắc ràng buộc không bắt buộc về số lượng tài liệu tối đa cần đếm.

Đây là một cách để đặt giới hạn trên cho số lượng tài liệu cần quét, hạn chế độ trễ và chi phí.

Không xác định được hiểu là không có ràng buộc.

Ví dụ ở cấp cao:

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

Yêu cầu:

  • Phải lớn hơn 0 khi hiển thị.

Tổng

Tổng giá trị của trường được yêu cầu.

  • Hệ thống chỉ tổng hợp các giá trị dạng số. Tất cả giá trị không phải số, bao gồm cả NULL, đều bị bỏ qua.

  • Nếu giá trị tổng hợp chứa NaN, hàm sẽ trả về NaN. Toán học của Infinity tuân theo tiêu chuẩn IEEE-754.

  • Nếu tập hợp giá trị tổng hợp trống, trả về 0.

  • Trả về số nguyên 64 bit nếu tất cả các số tổng hợp là số nguyên và kết quả tổng không bị tràn. Nếu không, kết quả sẽ được trả về dưới dạng kép. Lưu ý rằng ngay cả khi tất cả giá trị tổng hợp đều là số nguyên, kết quả vẫn được trả về dưới dạng số kép nếu không thể nằm trong phạm vi số nguyên 64 bit đã ký. Khi điều này xảy ra, giá trị được trả về sẽ mất độ chính xác.

  • Khi xảy ra hiện tượng sụt giảm, phương pháp tổng hợp dấu phẩy động là không xác định. Điều này có nghĩa là mỗi lần chạy cùng một truy vấn mà không có bất kỳ thay đổi nào đối với các giá trị cơ bản có thể cho ra kết quả hơi khác nhau. Trong những trường hợp đó, các giá trị phải được lưu trữ dưới dạng số nguyên thay vì số dấu phẩy động.

Trường
field

FieldReference

Trường để tổng hợp.

Truy vấn có cấu trúc

Một truy vấn trên Firestore.

Các giai đoạn truy vấn được thực hiện theo thứ tự sau: 1. từ 2. trong đó 3. chọn 4. order_by + start_at + end_at 5. offset 6. giới hạn

Trường
select

Projection

Tập hợp con không bắt buộc gồm các trường cần trả về.

Tham số này hoạt động như một DocumentMask trên các tài liệu được trả về từ truy vấn. Khi bạn không đặt chính sách này, hãy giả định rằng phương thức gọi muốn trả về tất cả các trường.

from[]

CollectionSelector

Các tập hợp cần truy vấn.

where

Filter

Bộ lọc để áp dụng.

order_by[]

Order

Thứ tự áp dụng cho các kết quả truy vấn.

Firestore cho phép người gọi đặt hàng đầy đủ, đặt hàng một phần hoặc không đặt hàng. Trong mọi trường hợp, Firestore đảm bảo thứ tự ổn định thông qua các quy tắc sau:

  • order_by là bắt buộc để tham chiếu tất cả các trường được dùng với bộ lọc bất đẳng thức.
  • Tất cả các trường bắt buộc phải có trong order_by nhưng chưa có thì sẽ được nối theo thứ tự từ điển của tên trường.
  • Nếu bạn không chỉ định đơn đặt hàng trên __name__, đơn đặt hàng sẽ được thêm vào theo mặc định.

Các trường được nối với cùng hướng sắp xếp như thứ tự gần đây nhất được chỉ định hoặc "DỰA VÀO" nếu không có đơn đặt hàng nào được chỉ định. Ví dụ:

  • ORDER BY a trở thành ORDER BY a ASC, __name__ ASC
  • ORDER BY a DESC trở thành ORDER BY a DESC, __name__ DESC
  • WHERE a > 1 trở thành WHERE a > 1 ORDER BY a ASC, __name__ ASC
  • WHERE __name__ > ... AND a > 1 trở thành WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
start_at

Cursor

Tiền tố tiềm năng của vị trí trong tập hợp kết quả để bắt đầu truy vấn.

Thứ tự của nhóm kết quả dựa trên mệnh đề ORDER BY của truy vấn ban đầu.

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

Kết quả của truy vấn này được sắp xếp theo (b ASC, __name__ ASC).

Con trỏ có thể tham chiếu thứ tự đầy đủ hoặc tiền tố của vị trí, mặc dù con trỏ không thể tham chiếu nhiều trường hơn những trường có trong ORDER BY được cung cấp.

Tiếp tục ví dụ trên, việc đính kèm các con trỏ bắt đầu sau đây sẽ có tác động khác nhau:

  • START BEFORE (2, /k/123): bắt đầu truy vấn ngay trước a = 1 AND b > 2 AND __name__ > /k/123.
  • START AFTER (10): bắt đầu truy vấn ngay sau a = 1 AND b > 10.

Không giống như OFFSET yêu cầu quét qua N kết quả đầu tiên để bỏ qua, con trỏ bắt đầu cho phép truy vấn bắt đầu tại vị trí logic. Vị trí này không bắt buộc phải khớp với kết quả thực tế, nó sẽ quét phía trước từ vị trí này để tìm tài liệu tiếp theo.

Yêu cầu:

  • Số lượng giá trị không được lớn hơn số lượng trường được chỉ định trong mệnh đề ORDER BY.
end_at

Cursor

Tiền tố tiềm năng của vị trí trong kết quả được đặt để kết thúc truy vấn tại.

Hàm này tương tự như START_AT nhưng với việc kiểm soát vị trí kết thúc thay vì vị trí bắt đầu.

Yêu cầu:

  • Số lượng giá trị không được lớn hơn số lượng trường được chỉ định trong mệnh đề ORDER BY.
offset

int32

Số tài liệu cần bỏ qua trước khi trả về kết quả đầu tiên.

Điều này áp dụng sau các điều kiện ràng buộc do WHERE, START ATEND AT nhưng trước mệnh đề LIMIT.

Yêu cầu:

  • Giá trị phải lớn hơn hoặc bằng 0 nếu được chỉ định.
limit

Int32Value

Số lượng kết quả tối đa cần trả về.

Áp dụng sau tất cả các quy tắc ràng buộc khác.

Yêu cầu:

  • Giá trị phải lớn hơn hoặc bằng 0 nếu được chỉ định.
find_nearest

FindNearest

Không bắt buộc. Một người hàng xóm gần nhất có thể đang tìm kiếm.

Áp dụng sau tất cả các bộ lọc và thứ tự khác.

Tìm các vectơ nhúng gần nhất với vectơ truy vấn đã cho.

Bộ chọn bộ sưu tập

Một lựa chọn trong một tập hợp, chẳng hạn như messages as m1.

Trường
collection_id

string

Mã bộ sưu tập. Khi đặt giá trị này, chỉ chọn các bộ sưu tập có mã nhận dạng này.

all_descendants

bool

Khi đặt là false, chỉ chọn các tập hợp là con trực tiếp của parent được chỉ định trong vùng chứa RunQueryRequest. Khi giá trị là true, sẽ chọn tất cả các tập hợp con.

Bộ lọc tổng hợp

Bộ lọc hợp nhất nhiều bộ lọc khác bằng toán tử cho trước.

Trường
op

Operator

Toán tử để kết hợp nhiều bộ lọc.

filters[]

Filter

Danh sách bộ lọc cần kết hợp.

Yêu cầu:

  • Có ít nhất một bộ lọc.

Toán tử

Toán tử bộ lọc tổng hợp.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
AND Giấy tờ phải đáp ứng tất cả các bộ lọc kết hợp.
OR Giấy tờ phải đáp ứng ít nhất một trong các bộ lọc kết hợp.

Hướng

Hướng sắp xếp.

Enum
DIRECTION_UNSPECIFIED Không xác định.
ASCENDING Tăng dần.
DESCENDING Giảm dần.

Bộ lọc trường

Bộ lọc trên một trường cụ thể.

Trường
field

FieldReference

Trường để lọc theo.

op

Operator

Toán tử bạn muốn lọc theo.

value

Value

Giá trị cần so sánh.

Toán tử

Một toán tử lọc trường.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
LESS_THAN

field đã cho nhỏ hơn value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở order_by.
LESS_THAN_OR_EQUAL

field đã cho nhỏ hơn hoặc bằng value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở order_by.
GREATER_THAN

field đã cho lớn hơn value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở order_by.
GREATER_THAN_OR_EQUAL

field đã cho lớn hơn hoặc bằng value đã cho.

Yêu cầu:

  • field đó xuất hiện trước ở order_by.
EQUAL field đã cho bằng với value đã cho.
NOT_EQUAL

field đã cho không bằng value đã cho.

Yêu cầu:

  • Không có NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN nào khác.
  • field đó đứng đầu trong order_by.
ARRAY_CONTAINS field đã cho là một mảng chứa value đã cho.
IN

field đã cho bằng ít nhất một giá trị trong mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống và phải tuân theo giới hạn phân tách.
  • Không có bộ lọc NOT_IN nào trong cùng một truy vấn.
ARRAY_CONTAINS_ANY

field đã cho là một mảng chứa bất kỳ giá trị nào trong các mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống và phải tuân theo giới hạn phân tách.
  • Không có bộ lọc ARRAY_CONTAINS_ANY nào khác trong cùng phân tách.
  • Không có bộ lọc NOT_IN nào trong cùng một truy vấn.
NOT_IN

Giá trị của field không nằm trong mảng đã cho.

Yêu cầu:

  • value đó là một ArrayValue không trống có tối đa 10 giá trị.
  • Không có OR, IN, ARRAY_CONTAINS_ANY, NOT_IN, NOT_EQUAL, IS_NOT_NULL hoặc IS_NOT_NAN khác.
  • field đó đứng đầu trong order_by.

Tham chiếu trường

Nội dung tham chiếu đến một trường trong tài liệu, ví dụ: stats.operations.

Trường
field_path

string

Tham chiếu đến một trường trong tài liệu.

Yêu cầu:

  • PHẢI là một chuỗi phân đoạn được phân tách bằng dấu chấm (.), trong đó mỗi phân đoạn phải tuân thủ document field name giới hạn.

Bộ lọc

Bộ lọc.

Trường
Trường kết hợp filter_type. Loại bộ lọc. filter_type chỉ có thể là một trong những trạng thái sau đây:
composite_filter

CompositeFilter

Bộ lọc tổng hợp.

field_filter

FieldFilter

Bộ lọc trên một trường tài liệu.

unary_filter

UnaryFilter

Bộ lọc nhận đúng một đối số.

Tìm gần nhất

Cấu hình tìm kiếm lân cận gần nhất.

Trường
vector_field

FieldReference

Bắt buộc. Trường vectơ được lập chỉ mục để tìm kiếm. Chỉ có thể trả về những tài liệu chứa vectơ có kích thước khớp với query_vector.

query_vector

Value

Bắt buộc. Vectơ truy vấn mà chúng ta đang tìm kiếm. Phải là vectơ có không quá 2048 chiều.

distance_measure

DistanceMeasure

Bắt buộc. Số đo khoảng cách cần sử dụng, bắt buộc.

limit

Int32Value

Bắt buộc. Số người lân cận gần nhất để trả về. Phải là một số nguyên dương không quá 1000.

Đo khoảng cách

Phép đo khoảng cách cần sử dụng khi so sánh các vectơ.

Enum
DISTANCE_MEASURE_UNSPECIFIED Không nên đặt.
EUCLIDEAN Đo khoảng cách EUCLIDEAN giữa các vectơ. Xem Euclide để tìm hiểu thêm
COSINE So sánh các vectơ dựa trên góc giữa chúng, cho phép bạn đo được sự tương đồng không dựa trên độ lớn của vectơ. Chúng tôi khuyên bạn nên sử dụng DOT_PRODUCT với vectơ chuẩn hoá đơn vị thay vì khoảng cách cosINE, tương đương về mặt toán học với hiệu suất tốt hơn. Xem phần Tính tương tự Cosine để tìm hiểu thêm.
DOT_PRODUCT Tương tự như cosin nhưng bị ảnh hưởng bởi độ lớn của vectơ. Xem Dot Product để tìm hiểu thêm.

Gọi món

Thứ tự trên một trường.

Trường
field

FieldReference

Trường để sắp xếp thứ tự.

direction

Direction

Hướng dẫn sắp xếp thứ tự. Giá trị mặc định là ASCENDING.

Dự đoán

Phép chiếu các trường của tài liệu cần trả về.

Trường
fields[]

FieldReference

Các trường cần trả về.

Nếu trống, tất cả các trường sẽ được trả về. Để chỉ trả về tên của tài liệu, hãy sử dụng ['__name__'].

Bộ lọc đơn sắc

Một bộ lọc có một toán hạng duy nhất.

Trường
op

Operator

Toán tử một ngôi để áp dụng.

Trường kết hợp operand_type. Đối số cho bộ lọc. operand_type chỉ có thể là một trong những trạng thái sau đây:
field

FieldReference

Trường mà bạn muốn áp dụng toán tử.

Toán tử

Một toán tử đơn phân.

Enum
OPERATOR_UNSPECIFIED Không xác định. Không được sử dụng giá trị này.
IS_NAN field đã cho bằng NaN.
IS_NULL field đã cho bằng NULL.
IS_NOT_NAN

field đã cho không bằng NaN.

Yêu cầu:

  • Không có NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN nào khác.
  • field đó đứng đầu trong order_by.
IS_NOT_NULL

field đã cho không bằng NULL.

Yêu cầu:

  • Một NOT_EQUAL, NOT_IN, IS_NOT_NULL hoặc IS_NOT_NAN.
  • field đó đứng đầu trong order_by.

Nhắm mục tiêu

Nội dung đặc tả của nhóm tài liệu cần nghe.

Trường
target_id

int32

Mã mục tiêu xác định mục tiêu trên luồng. Phải là một số dương và khác 0.

Nếu target_id là 0 (hoặc chưa được chỉ định), máy chủ sẽ gán một mã nhận dạng cho mục tiêu này và trả về mã đó trong sự kiện TargetChange::ADD. Sau khi thêm một mục tiêu có target_id=0, tất cả các mục tiêu tiếp theo cũng phải có target_id=0. Nếu một yêu cầu AddTargettarget_id != 0 được gửi đến máy chủ sau khi mục tiêu có target_id=0 được thêm, thì máy chủ sẽ ngay lập tức gửi một phản hồi có sự kiện TargetChange::Remove.

Xin lưu ý rằng nếu ứng dụng gửi nhiều yêu cầu AddTarget mà không có mã nhận dạng, thì thứ tự của các mã nhận dạng được trả về trong TargetChage.target_ids sẽ không được xác định. Do đó, ứng dụng nên cung cấp mã mục tiêu thay vì dựa vào máy chủ để chỉ định mã này.

Nếu target_id khác 0, thì không được có mục tiêu đang hoạt động nào trên luồng này có cùng mã.

once

bool

Liệu bạn có cần xoá mục tiêu khi mục tiêu đó hiện tại và nhất quán hay không.

expected_count

Int32Value

Số tài liệu khớp với truy vấn gần đây nhất tại mã thông báo sơ yếu lý lịch hoặc thời gian đọc.

Giá trị này chỉ phù hợp khi bạn cung cấp resume_type. Giá trị này đang hiện diện và lớn hơn 0 tín hiệu cho thấy ứng dụng muốn đưa ExistenceFilter.unchanged_names vào phản hồi.

Trường kết hợp target_type. Kiểu mục tiêu cần nghe. target_type chỉ có thể là một trong những trạng thái sau đây:
query

QueryTarget

Mục tiêu được xác định bởi truy vấn.

documents

DocumentsTarget

Một mục tiêu được xác định bởi một nhóm tên tài liệu.

Trường kết hợp resume_type. Thời điểm bắt đầu nghe.

Nếu bạn chỉ định, thì chỉ những Tài liệu trùng khớp đã được cập nhật SAU KHI resume_token hoặc read_time được trả về. Nếu không, tất cả các Tài liệu trùng khớp sẽ được trả về trước mọi thay đổi tiếp theo. resume_type chỉ có thể là một trong những trạng thái sau đây:

resume_token

bytes

Mã thông báo tiếp tục từ TargetChange trước đó cho cùng một mục tiêu.

Việc sử dụng mã thông báo tiếp tục có mục tiêu khác không được hỗ trợ và có thể không thành công.

read_time

Timestamp

Bắt đầu nghe sau một read_time cụ thể.

Khách hàng phải biết trạng thái của các chứng từ trùng khớp vào lúc này.

Mục tiêu tài liệu

Một mục tiêu được xác định bởi một nhóm tên tài liệu.

Trường
documents[]

string

Tên tài liệu cần truy xuất. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}. Yêu cầu sẽ không thành công nếu có bất kỳ tài liệu nào không phải là tài nguyên con của database đã cho. Những tên trùng lặp sẽ bị loại bỏ.

Mục tiêu truy vấn

Mục tiêu được xác định bởi truy vấn.

Trường
parent

string

Tên tài nguyên mẹ. Ở định dạng: projects/{project_id}/databases/{database_id}/documents hoặc projects/{project_id}/databases/{database_id}/documents/{document_path}. Ví dụ: projects/my-project/databases/my-database/documents hoặc projects/my-project/databases/my-database/documents/chatrooms/my-chatroom

Trường kết hợp query_type. Truy vấn cần chạy. query_type chỉ có thể là một trong những trạng thái sau đây:
structured_query

StructuredQuery

Truy vấn có cấu trúc.

Thay đổi mục tiêu

Các mục tiêu được xem đã thay đổi.

Trường
target_change_type

TargetChangeType

Loại thay đổi đã xảy ra.

target_ids[]

int32

Mã mục tiêu của các mục tiêu đã thay đổi.

Nếu trống, thay đổi sẽ áp dụng cho tất cả các mục tiêu.

Không xác định được thứ tự của các mã mục tiêu.

cause

Status

Lỗi đã dẫn đến thay đổi này, nếu có.

resume_token

bytes

Có thể dùng mã thông báo để tiếp tục truyền phát cho target_ids đã cho hoặc tất cả các mục tiêu nếu target_ids trống.

Không được đặt cho mọi thay đổi về mục tiêu.

read_time

Timestamp

read_time nhất quán cho target_ids đã cho (bị bỏ qua khi target_ids không nằm trên một bản tổng quan nhanh nhất quán).

Luồng được đảm bảo sẽ gửi một read_time với target_ids trống bất cứ khi nào toàn bộ luồng đạt đến một ảnh chụp nhanh nhất quán mới. Các thông báo THÊM, HIỆN TẠI và ĐẶT LẠI được đảm bảo (cuối cùng) sẽ dẫn đến ảnh chụp nhanh nhất quán mới (trong khi thông báo NO_CHANGE và REMOVE thì không).

Đối với một luồng nhất định, read_time được đảm bảo sẽ tăng đơn điệu.

Loại thay đổi mục tiêu

Loại thay đổi.

Enum
NO_CHANGE Không có thay đổi nào. Chỉ dùng để gửi resume_token đã cập nhật.
ADD Đã thêm các mục tiêu.
REMOVE Các mục tiêu đã bị xoá.
CURRENT

Mục tiêu phản ánh tất cả các thay đổi đã cam kết trước khi mục tiêu được thêm vào luồng.

Mã này sẽ được gửi sau hoặc kèm theo read_time lớn hơn hoặc bằng thời điểm thêm các mục tiêu.

Trình nghe có thể chờ thay đổi này nếu muốn có ngữ nghĩa đọc sau khi ghi.

RESET

Mục tiêu đã được đặt lại và trạng thái ban đầu mới cho mục tiêu sẽ được trả về trong các thay đổi tiếp theo.

Sau khi hoàn tất trạng thái ban đầu, CURRENT sẽ được trả về ngay cả khi trước đó mục tiêu đã được chỉ định là CURRENT.

Giao dịch Tùy chọn

Các lựa chọn để tạo giao dịch mới.

Trường
Trường kết hợp mode. Phương thức giao dịch. mode chỉ có thể là một trong những trạng thái sau đây:
read_only

ReadOnly

Bạn chỉ có thể sử dụng giao dịch cho hoạt động đọc.

read_write

ReadWrite

Có thể dùng giao dịch cho cả thao tác đọc và ghi.

Chỉ Ðọc

Các tuỳ chọn cho một giao dịch chỉ có thể dùng để đọc tài liệu.

Trường
Trường kết hợp consistency_selector. Chế độ nhất quán cho giao dịch này. Nếu bạn không đặt chính sách này, hệ thống sẽ đặt mặc định là tính nhất quán cao. consistency_selector chỉ có thể là một trong những trạng thái sau đây:
read_time

Timestamp

Đọc tài liệu tại thời điểm cụ thể.

Đây phải là một dấu thời gian có độ chính xác là micrô giây trong vòng 1 giờ qua, hoặc nếu tính năng Khôi phục tại một thời điểm đang bật, thì đây cũng có thể là dấu thời gian cả phút trong vòng 7 ngày qua.

Đọc/ghi

Các tuỳ chọn cho một giao dịch có thể dùng để đọc và ghi tài liệu.

Firestore không cho phép các yêu cầu xác thực của bên thứ ba tạo đọc-ghi. giao dịch.

Trường
retry_transaction

bytes

Một giao dịch không bắt buộc để thử lại.

Yêu cầu cập nhật tài liệu

Yêu cầu cho Firestore.UpdateDocument.

Trường
document

Document

Bắt buộc. Tài liệu đã cập nhật. Tạo tài liệu nếu tài liệu chưa tồn tại.

update_mask

DocumentMask

Các trường cần cập nhật. Không có đường dẫn trường nào trong mặt nạ có thể chứa tên dành riêng.

Nếu tài liệu tồn tại trên máy chủ và có các trường không được tham chiếu trong mặt nạ, các trường này sẽ không thay đổi. Các trường được tham chiếu trong mặt nạ nhưng không có trong tài liệu nhập sẽ bị xoá khỏi tài liệu trên máy chủ.

mask

DocumentMask

Các trường cần trả về. Nếu bạn không đặt chính sách này, hệ thống sẽ trả về tất cả các trường.

Nếu tài liệu có một trường không có trong mặt nạ này, thì trường đó sẽ không được trả về trong phản hồi.

current_document

Precondition

Điều kiện tiên quyết (không bắt buộc) trên tài liệu. Yêu cầu sẽ không thành công nếu giá trị này được thiết lập nhưng tài liệu đích không đáp ứng.

Giá trị

Một thông báo có thể chứa bất kỳ loại giá trị nào được hỗ trợ.

Trường
Trường kết hợp value_type. Phải có bộ giá trị. value_type chỉ có thể là một trong những trạng thái sau đây:
null_value

NullValue

Một giá trị rỗng.

boolean_value

bool

Một giá trị boolean.

integer_value

int64

Một giá trị số nguyên.

double_value

double

Giá trị kép.

timestamp_value

Timestamp

Một giá trị dấu thời gian.

Chỉ chính xác đến micrô giây. Khi được lưu trữ, mọi độ chính xác bổ sung sẽ được làm tròn xuống.

string_value

string

Một giá trị chuỗi.

Chuỗi (được biểu thị dưới dạng UTF-8) không được vượt quá 1 MiB – 89 byte. Chỉ 1.500 byte đầu tiên của cách biểu diễn UTF-8 được xem xét trong các truy vấn.

bytes_value

bytes

Một giá trị byte.

Không được vượt quá 1 MiB – 89 byte. Chỉ 1.500 byte đầu tiên được xem xét bởi các truy vấn.

reference_value

string

Tham chiếu đến một tài liệu. Ví dụ: projects/{project_id}/databases/{database_id}/documents/{document_path}.

geo_point_value

LatLng

Một giá trị điểm địa lý đại diện cho một điểm trên bề mặt Trái Đất.

array_value

ArrayValue

Một giá trị mảng.

Không thể trực tiếp chứa một giá trị mảng khác, mặc dù có thể chứa bản đồ chứa một mảng khác.

map_value

MapValue

Giá trị ánh xạ.

Viết

Viết trên tài liệu.

Trường
update_mask

DocumentMask

Các trường cần cập nhật trong nội dung ghi này.

Bạn chỉ có thể đặt trường này khi thực hiện thao tác là update. Nếu bạn không đặt mặt nạ cho update và tài liệu tồn tại, thì mọi dữ liệu hiện có sẽ bị ghi đè. Nếu bạn đặt mặt nạ và tài liệu trên máy chủ có các trường không bị mặt nạ che phủ, thì các trường đó sẽ không thay đổi. Các trường được tham chiếu trong mặt nạ nhưng không có trong tài liệu nhập sẽ bị xoá khỏi tài liệu trên máy chủ. Đường dẫn trường trong mặt nạ này không được chứa tên trường dành riêng.

update_transforms[]

FieldTransform

Các biến đổi để thực hiện sau khi cập nhật.

Bạn chỉ có thể đặt trường này khi thực hiện thao tác là update. Nếu có, thao tác ghi này tương đương với việc thực hiện updatetransform cho cùng một tài liệu về tỷ lệ và thứ tự.

current_document

Precondition

Điều kiện tiên quyết (không bắt buộc) trên tài liệu.

Thao tác ghi sẽ không thành công nếu bạn đặt giá trị này nhưng tài liệu đích không đáp ứng yêu cầu này.

Trường kết hợp operation. Thao tác cần thực thi. operation chỉ có thể là một trong những trạng thái sau đây:
update

Document

Tài liệu cần viết.

delete

string

Tên tài liệu cần xoá. Ở định dạng: projects/{project_id}/databases/{database_id}/documents/{document_path}.

transform

DocumentTransform

Áp dụng một phép biến đổi cho một tài liệu.

Ghi yêu cầu

Yêu cầu cho Firestore.Write.

Yêu cầu đầu tiên sẽ tạo một luồng hoặc tiếp tục một luồng hiện có từ mã thông báo.

Khi tạo một luồng mới, máy chủ sẽ phản hồi bằng phản hồi chỉ chứa mã nhận dạng và mã thông báo để dùng trong yêu cầu tiếp theo.

Khi tiếp tục truyền trực tuyến, trước tiên, máy chủ sẽ truyền phát mọi phản hồi muộn hơn mã thông báo đã cho, sau đó là phản hồi chỉ chứa mã thông báo cập nhật để dùng trong yêu cầu tiếp theo.

Trường
database

string

Bắt buộc. Tên cơ sở dữ liệu. Ở định dạng: projects/{project_id}/databases/{database_id}. Bạn chỉ phải cung cấp thông tin này trong thông báo đầu tiên.

stream_id

string

Mã nhận dạng của luồng ghi cần tiếp tục. Bạn chỉ có thể đặt chế độ này trong thông báo đầu tiên. Khi để trống, một luồng ghi mới sẽ được tạo.

writes[]

Write

Các quyền cần ghi để áp dụng.

Luôn thực thi tỉ mỉ và theo thứ tự. Bạn phải để trống trường này trong yêu cầu đầu tiên. Trường này có thể trống trong yêu cầu mới nhất. Không được để trống trường này trên tất cả các yêu cầu khác.

stream_token

bytes

Mã thông báo luồng đã được máy chủ gửi trước đó.

Ứng dụng phải đặt trường này thành mã thông báo từ WriteResponse gần đây nhất mà ứng dụng nhận được. Điều này xác nhận rằng ứng dụng đã nhận được phản hồi đến mã thông báo này. Sau khi gửi mã thông báo này, bạn không thể dùng những mã thông báo cũ nữa.

Máy chủ có thể đóng luồng nếu có quá nhiều phản hồi không được xác nhận.

Bạn không nên đặt trường này khi tạo sự kiện phát trực tiếp mới. Để tiếp tục phát trực tiếp tại một điểm cụ thể, hãy đặt trường này và trường stream_id.

Bạn không nên đặt trường này khi tạo sự kiện phát trực tiếp mới.

labels

map<string, string>

Các nhãn liên kết với yêu cầu ghi này.

Ghi phản hồi

Phản hồi cho Firestore.Write.

Trường
stream_id

string

Mã của luồng. Chỉ đặt cho tin nhắn đầu tiên, khi luồng mới được tạo.

stream_token

bytes

Mã thông báo đại diện cho vị trí của phản hồi này trong luồng. Ứng dụng có thể sử dụng thông tin này để tiếp tục sự kiện phát trực tiếp vào thời điểm này.

Trường này luôn được đặt.

write_results[]

WriteResult

Kết quả của việc áp dụng hoạt động ghi.

Kết quả ghi thứ i này tương ứng với lần ghi thứ i trong yêu cầu.

commit_time

Timestamp

Thời gian thực hiện cam kết. Bất kỳ lượt đọc nào có read_time bằng hoặc lớn hơn đều đảm bảo thấy được tác động của việc ghi.

Ghi kết quả

Kết quả của việc áp dụng một thao tác ghi.

Trường
update_time

Timestamp

Thời gian cập nhật tài liệu gần đây nhất sau khi áp dụng chế độ ghi. Không được đặt sau delete.

Nếu việc ghi không thực sự thay đổi tài liệu, đây sẽ là update_time trước đó.

transform_results[]

Value

Kết quả khi áp dụng từng DocumentTransform.FieldTransform theo cùng một thứ tự.