Package google.firestore.v1beta1

索引

• Firestore (介面)
• AggregationResult (訊息)
• ArrayValue (訊息)
• BatchGetDocumentsRequest (訊息)
• BatchGetDocumentsResponse (訊息)
• BatchWriteRequest (訊息)
• BatchWriteResponse (訊息)
• BeginTransactionRequest (訊息)
• BeginTransactionResponse (訊息)
• BitSequence (訊息)
• BloomFilter (訊息)
• CommitRequest (訊息)
• CommitResponse (訊息)
• CreateDocumentRequest (訊息)
• Cursor (訊息)
• DeleteDocumentRequest (訊息)
• Document (訊息)
• DocumentChange (訊息)
• DocumentDelete (訊息)
• DocumentMask (訊息)
• DocumentRemove (訊息)
• DocumentTransform (訊息)
• DocumentTransform.FieldTransform (訊息)
• DocumentTransform.FieldTransform.ServerValue (enum)
• ExecutionStats (訊息)
• ExistenceFilter (訊息)
• ExplainMetrics (訊息)
• ExplainOptions (訊息)
• GetDocumentRequest (訊息)
• ListCollectionIdsRequest (訊息)
• ListCollectionIdsResponse (訊息)
• ListDocumentsRequest (訊息)
• ListDocumentsResponse (訊息)
• ListenRequest (訊息)
• ListenResponse (訊息)
• MapValue (訊息)
• PartitionQueryRequest (訊息)
• PartitionQueryResponse (訊息)
• PlanSummary (訊息)
• Precondition (訊息)
• RollbackRequest (訊息)
• RunAggregationQueryRequest (訊息)
• RunAggregationQueryResponse (訊息)
• RunQueryRequest (訊息)
• RunQueryResponse (訊息)
• StructuredAggregationQuery (訊息)
• StructuredAggregationQuery.Aggregation (訊息)
• StructuredAggregationQuery.Aggregation.Avg (訊息)
• StructuredAggregationQuery.Aggregation.Count (訊息)
• StructuredAggregationQuery.Aggregation.Sum (訊息)
• StructuredQuery (訊息)
• StructuredQuery.CollectionSelector (訊息)
• StructuredQuery.CompositeFilter (訊息)
• StructuredQuery.CompositeFilter.Operator (enum)
• StructuredQuery.Direction (enum)
• StructuredQuery.FieldFilter (訊息)
• StructuredQuery.FieldFilter.Operator (enum)
• StructuredQuery.FieldReference (訊息)
• StructuredQuery.Filter (訊息)
• StructuredQuery.FindNearest (訊息)
• StructuredQuery.FindNearest.DistanceMeasure (enum)
• StructuredQuery.Order (訊息)
• StructuredQuery.Projection (訊息)
• StructuredQuery.UnaryFilter (訊息)
• StructuredQuery.UnaryFilter.Operator (enum)
• Target (訊息)
• Target.DocumentsTarget (訊息)
• Target.QueryTarget (訊息)
• TargetChange (訊息)
• TargetChange.TargetChangeType (enum)
• TransactionOptions (訊息)
• TransactionOptions.ReadOnly (訊息)
• TransactionOptions.ReadWrite (訊息)
• UpdateDocumentRequest (訊息)
• Value (訊息)
• Write (訊息)
• WriteRequest (訊息)
• WriteResponse (訊息)
• WriteResult (訊息)

Firestore

Cloud Firestore 服務。

Cloud Firestore 是快速、全代管、無伺服器且雲端原生的 NoSQL 文件資料庫，可針對全球規模的行動、網路和 IoT 應用程式簡化儲存、同步及查詢資料的程序。Cloud Firestore 的用戶端程式庫提供即時同步處理和離線支援；此外，Cloud Firestore 也具備安全性功能，且與 Firebase 和 Google Cloud Platform 整合，有助於加速建構真正的無伺服器應用程式。

BatchGetDocuments
rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (BatchGetDocumentsResponse) 取得多份文件。 此方法傳回的文件不一定會按照要求的順序傳回。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

BatchWrite
rpc BatchWrite(BatchWriteRequest) returns (BatchWriteResponse) 套用批次寫入作業。 BatchWrite 方法不會以不可分割的形式套用寫入作業，且可依序套用寫入作業。此方法不允許每份文件執行多次寫入。每項寫入作業成功或失敗。如要瞭解每次寫入的成功狀態，請參閱 BatchWriteResponse。 如果您需要以不可分割的形式套用一組寫入，請改用 Commit。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

開始交易
rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) 開始新的交易。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

修訂版本
rpc Commit(CommitRequest) returns (CommitResponse) 修訂交易，並視需要更新文件。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

CreateDocument
rpc CreateDocument(CreateDocumentRequest) returns (Document) 建立新文件。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

DeleteDocument
rpc DeleteDocument(DeleteDocumentRequest) returns (Empty) 刪除文件。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

GetDocument
rpc GetDocument(GetDocumentRequest) returns (Document) 取得單一文件。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

列出集合 ID
rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse) 列出文件下的所有集合 ID。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

ListDocuments
rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) 列出文件。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

監聽
rpc Listen(ListenRequest) returns (ListenResponse) 監聽變更。這個方法只能透過 gRPC 或 WebChannel (非 REST) 使用。 授權範圍 需要下列其中一種 OAuth 範圍： https://www.googleapis.com/auth/datastore https://www.googleapis.com/auth/cloud-platform 詳情請參閱驗證總覽一文。

分區查詢
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) 執行匯總查詢。 這個 API 不會產生類似 Firestore.RunQuery 的 Document 結果，而是允許執行匯總作業，產生一系列 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，而這個對應的大小等於查詢中的匯總函式數量。

ArrayValue

陣列值。

欄位
values[]	Value 陣列中的值。

BatchGetDocuments 要求

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 開始新的交易並讀取文件。預設為唯讀交易。系統會傳回新的交易 ID，做為串流中的第一個回應。
read_time	Timestamp 讀取特定時間的文件。 這個時間戳記須為過去 1 小時內的微秒精確度，或者如果已啟用時間點復原，也可以是過去 7 天內的整分鐘時間戳記。

BatchGetDocumentsResponse

針對 Firestore.BatchGetDocuments 的串流回應。

欄位
transaction	bytes 隨此要求所啟動的交易。只會在第一個回應中設定，且必須在要求中設定 BatchGetDocumentsRequest.new_transaction。
read_time	Timestamp 讀取文件的時間。這可能是單純增加的，在這種情況下，結果串流中的舊有文件保證在 read_time 和此檔案之間保持不變。
聯集欄位 result。單一結果。如果伺服器只會傳回交易，這個值可以留空。result 只能採用下列其中一種設定：
found	Document 要求的文件。
missing	string 要求但不存在的文件名稱。請採用下列格式：projects/{project_id}/databases/{database_id}/documents/{document_path}。

批次寫入要求

Firestore.BatchWrite 的要求。

欄位
database	string 執行個體類型，資料庫名稱。請採用下列格式：projects/{project_id}/databases/{database_id}。
writes[]	Write 要套用的寫入作業。 方法不會以不可分割的形式套用寫入，亦不保證排序。每項寫入作業成功或失敗。每次要求只能寫入同一份文件一次。
labels	map<string, string> 與這個批次寫入作業相關聯的標籤。

批次寫入回應

Firestore.BatchWrite 的回應。

欄位
write_results[]	WriteResult 套用寫入的結果。 這項 i-th 寫入結果與要求中的 i-th 寫入對應。
status[]	Status 套用寫入的狀態。 此 i-th 寫入狀態與要求中的 i-th 寫入對應。

BeginTransactionRequest

Firestore.BeginTransaction 的要求。

欄位
database	string 執行個體類型，資料庫名稱。請採用下列格式：projects/{project_id}/databases/{database_id}。
options	TransactionOptions 交易的選項。預設為讀寫交易。

開始交易回應

Firestore.BeginTransaction 的回應。

欄位
transaction	bytes 啟動的交易。

位元序列

透過位元組陣列編碼的位元序列。

bitmap 位元組陣列中的每個位元組都會儲存序列的 8 位元。唯一的例外狀況是最後一個位元組，可能會儲存 8 位元以下的位元。padding 將最後一個位元組的位元數定義為「邊框間距」。這些「邊框間距」的值位元未指定，且必須忽略。

如要擷取第一個位元 (位元 0)，請計算：(bitmap[0] & 0x01) != 0。如要擷取第二位元 (1 位元)，請計算 (bitmap[0] & 0x02) != 0。如要擷取第三個位元 (2 位元)，請計算 (bitmap[0] & 0x04) != 0。如要擷取第四位元 (位元 3)，請計算：(bitmap[0] & 0x08) != 0。如要擷取位元 n，請計算 (bitmap[n / 8] & (0x01 << (n % 8))) != 0。

「size」BitSequence (所含位元數) 的計算公式為 (bitmap.length * 8) - padding。

欄位
bitmap	bytes 為位元序列編碼的位元組。長度可能是 0。
padding	int32 bitmap 中最後一個位元組要忽略為「邊框間距」的位元數。如果 bitmap 的長度為 0，這個值必須為 0。否則這個值必須介於 0 到 7 (含) 之間。

鮮花濾鏡

花朵濾鏡 (https://en.wikipedia.org/wiki/Bloom_filter)。

bloom 篩選器會使用 MD5 對項目進行雜湊處理，並將產生的 128 位元雜湊視為 2 個不同的 64 位元雜湊值，使用 2 的互補編碼，解讀為無正負號的整數。

接著，這兩個雜湊值 (名為 h1 和 h2) 會用於透過公式 (從 i=0 開始) 計算 hash_count 雜湊值：

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

系統隨後會擷取這些產生的值，取出血液濾鏡中的位元數，取得 Bloom 濾鏡的位元數以測試給定項目。

欄位
bits	BitSequence 花卉篩選器資料。
hash_count	int32 演算法使用的雜湊數量。

CommitRequest

Firestore.Commit 的要求。

欄位
database	string 執行個體類型，資料庫名稱。請採用下列格式：projects/{project_id}/databases/{database_id}。
writes[]	Write 要套用的寫入作業。 一律以不可分割的形式，依序執行。
transaction	bytes 如果已設定，則會套用並修訂此交易中的所有寫入作業。

CommitResponse

Firestore.Commit 的回應。

欄位
write_results[]	WriteResult 套用寫入的結果。 這項 i-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 執行個體類型，要清單的集合 ID (相對於 parent)。例如：chatrooms。
document_id	string 要用於這份文件的用戶端指派文件 ID。 選用設定。如未指定，服務會指派 ID。
document	Document 執行個體類型，要建立的文件。無法設定「name」。
mask	DocumentMask 要傳回的欄位。如未設定，則會傳回所有欄位。 如果文件的某個欄位不在這個遮罩中，則不會在回應中傳回該欄位。

Cursor

查詢結果集中的排名。

欄位
values[]	Value 代表位置的值，按照查詢子句中的顯示順序排列。 可以包含的值數量少於使用子子句指定的順序。
before	bool 如果位置緊接在指定值之前或之後 (相對於查詢所定義的排序順序)。

DeleteDocumentRequest

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 進行比較。

DocumentChange

Document 已變更。

可能是多個 writes (包含刪除) 的結果，進而為 Document 產生新的值。

如果有多個目標受到影響，系統可能會針對同一項邏輯變更傳回多則 DocumentChange 訊息。

欄位
document	Document Document 的新狀態。 如果已設定 mask，則僅包含更新或新增的欄位。
target_ids[]	int32 與這份文件相符的目標 ID 組合。
removed_target_ids[]	int32 與這份文件不再相符的目標 ID 組合。

文件刪除

已刪除Document。

這可能是多個 writes 的結果 (包括更新)，這是上次刪除 Document 的結果。

如果有多個目標受到影響，系統可能會針對同一個邏輯刪除傳回多則 DocumentDelete 訊息。

欄位
document	string 刪除的 Document 資源名稱。
removed_target_ids[]	int32 先前與這個實體相符的目標 ID 組合。
read_time	Timestamp 偵測到刪除作業的讀取時間戳記。 大於或等於刪除項目的 commit_time。

DocumentMask

文件中的一組欄位路徑。用於將文件的 get 或更新作業限制在文件的子集。這與標準欄位遮罩不同，因為其範圍一律限定為 Document，且會考量 Value 的動態性質。

欄位
field_paths[]	string 遮罩中的欄位路徑清單。如需欄位路徑語法參考資料，請參閱 Document.fields。

文件移除

Document 已從目標檢視畫面中移除。

如果文件不再與特定目標相關且不在檢視範圍，系統會傳送。如果伺服器無法傳送文件的新值，可以改為傳送，而不是 DocumentDelete 或 DocumentChange。

如果有多個目標受到影響，系統可能會針對同一項邏輯寫入或刪除作業傳回多則 DocumentRemove 訊息。

欄位
document	string 已從檢視畫面中出現的 Document 資源名稱。
removed_target_ids[]	int32 先前與這份文件相符的目標 ID 組合。
read_time	Timestamp 偵測到移除作業的讀取時間戳記。 大於或等於變更/刪除/移除的 commit_time。

Document 轉換

文件的轉換。

欄位
document	string 要轉換的文件名稱。
field_transforms[]	FieldTransform 要依序套用至文件欄位的轉換清單。不得留空。

欄位轉換

文件欄位的轉換。

欄位
field_path	string 欄位路徑。如需欄位路徑語法參考資料，請參閱 Document.fields。
聯集欄位 transform_type。要套用至欄位的轉換。transform_type 只能採用下列其中一種設定：
set_to_server_value	ServerValue 將欄位設為指定的伺服器值。
increment	Value 將指定值加到欄位目前的值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值，或是欄位不存在，轉換會將欄位設為指定值。如果指定值或目前欄位值是雙精度浮點值，兩個值都會解讀為雙精度浮點值。雙精度浮點數和雙精度表示法依 IEEE 754 語意。如果有正/負整數溢位，該欄位會解析為最大的正/負整數。
maximum	Value 將欄位設為目前值和指定值的最大值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值，或是欄位不存在，轉換會將欄位設為指定值。如果套用最大運算值，且欄位和輸入值屬於混合型別 (例如 - 一個為整數，而 1 為雙精度)，欄位就會採用較大運算元的類型。如果運算元相等 (例如 3 和 3.0)，欄位就不會變更。0、0.0 和 -0.0 都是零。儲存值上限零或輸入值一律為儲存的值。x 和 NaN 的任何數值上限為 NaN。
minimum	Value 將欄位設為目前值和指定值的最小值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值，或是欄位不存在，轉換會將欄位設為輸入值。如果套用最小運算值，且欄位和輸入值屬於混合型別 (也就是 - 一個為整數，而 1 為雙精度浮點值)，欄位就會採用較小的運算元類型。如果運算元相等 (例如 3 和 3.0)，欄位就不會變更。0、0.0 和 -0.0 都是零。儲存值下限為 0 且輸入值為 0 的最小值一律為儲存的值。任何數值 x 及 NaN 的最小值為 NaN。
append_missing_elements	ArrayValue 如果指定元素目前未出現在目前的欄位值中，請依序附加這些元素。如果欄位不是陣列，或欄位尚不存在，則會先設為空陣列。 檢查是否缺少值時，系統會將不同型別的數量 (例如 3L 和 3.0) 視為相等。NaN 等於 NaN，而空值等於空值。如果輸入值包含多個相等的值，系統只會採用第一個值。 對應的 transform_result 將為空值。
remove_all_from_array	ArrayValue 移除欄位陣列中的所有特定元素。如果欄位不是陣列，或是欄位不存在，則會設為空白陣列。 在決定是否應移除元素時，系統會將各種類型的相等數量 (例如 3L 和 3.0) 視為相等。NaN 等於 NaN，而空值等於空值。如有重複的值，系統就會移除所有相等的值。 對應的 transform_result 將為空值。

伺服器值

伺服器計算的值。

列舉
SERVER_VALUE_UNSPECIFIED	未指定。不能使用這個值。
REQUEST_TIME	伺服器處理要求的時間 (精確度高達毫秒)。如果在單一交易中的多個欄位 (相同或不同的文件) 使用，所有欄位都會獲得相同的伺服器時間戳記。

執行統計資料

查詢的執行統計資料。

欄位
results_returned	int64 傳回的結果總數，包括文件、投影、匯總結果和鍵。
execution_duration	Duration 在後端執行查詢的總時間長度。
read_operations	int64 計費讀取作業總數。
debug_stats	Struct 對執行查詢的統計資料進行偵錯。請注意，由於 Firestore 不斷發展，偵錯統計資料可能會有所變動。其中可能包含：{ "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details"：{ "documents_可計費": "20", "index_entries_可計費": "1000", "min_query_cost": "0"} }

存在篩選器

符合指定目標的所有文件摘要。

欄位
target_id	int32 要套用此篩選器的目標 ID。
count	int32 符合 target_id 的文件總數。 如果用戶端中的文件數量不同，用戶端必須手動判斷哪些文件不再符合目標。 用戶端可以使用 unchanged_names 花卉篩選器，根據篩選器測試所有文件名稱，以協助判斷結果；如果文件名稱不在篩選器中，則表示文件不再與目標相符。
unchanged_names	BloomFilter 這個 Bloom 篩選器包含符合 target_id 的「所有」文件資源名稱的 UTF-8 位元組編碼，格式為 projects/{project_id}/databases/{database_id}/documents/{document_path}。 伺服器可自行斟酌是否要省略這個 Bloom 篩選器，例如判定用戶端不會使用，或是計算或傳輸的運算成本過高。用戶端必須改回使用此欄位前使用的邏輯，妥善處理缺少這個欄位的情況；也就是說，請在不使用履歷符記的情況下重新加入目標，找出用戶端快取中有哪些文件未保持同步。

說明指標

說明查詢的指標。

欄位
plan_summary	PlanSummary 查詢的規劃階段資訊。
execution_stats	ExecutionStats 執行查詢的匯總統計資料。只有在 ExplainOptions.analyze 設為 true 時才會顯示。

說明選項

說明查詢的選項。

欄位
analyze	bool 選用設定。是否執行這項查詢。 設為 false (預設值) 時，系統將針對查詢進行規劃，只傳回規劃階段的指標。 如果為 true，系統會規劃並執行查詢，傳回完整的查詢結果，以及規劃和執行階段指標。

GetDocumentRequest

Firestore.GetDocument 的要求。

欄位
name	string 執行個體類型，要取得之文件的資源名稱。請採用下列格式：projects/{project_id}/databases/{database_id}/documents/{document_path}。
mask	DocumentMask 要傳回的欄位。如未設定，則會傳回所有欄位。 如果文件的某個欄位不在這個遮罩中，則不會在回應中傳回該欄位。
聯集欄位 consistency_selector。這筆交易的一致性模式。如果未設定，則會預設為同步一致性。consistency_selector 只能採用下列其中一種設定：
transaction	bytes 在交易中讀取文件。
read_time	Timestamp 讀取指定時間的文件版本。 這個時間戳記須為過去 1 小時內的微秒精確度，或者如果已啟用時間點復原，也可以是過去 7 天內的整分鐘時間戳記。

列出集合 ID 要求

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 天內的整分鐘時間戳記。

列出集合編號回應

Firestore.ListCollectionIds 的回應。

欄位
collection_ids[]	string 集合 ID。
next_page_token	string 網頁權杖可用於繼續清單。

ListDocumentsRequest

Firestore.ListDocuments 的要求。

欄位
parent	string 執行個體類型，父項資源名稱。格式：projects/{project_id}/databases/{database_id}/documents 或 projects/{project_id}/databases/{database_id}/documents/{document_path}。 例如 projects/my-project/databases/my-database/documents 或 projects/my-project/databases/my-database/documents/chatrooms/my-chatroom
collection_id	string 選用設定。要清單的集合 ID (相對於 parent)。 例如 chatrooms 或 messages。 這是選用項目，如未提供，Firestore 會在指定 parent 下列出所有集合的文件。
page_size	int32 選用設定。單次回應中傳回的文件數量上限。 Firestore 傳回的值可能會小於這個值。
page_token	string 選用設定。屬於接收自前一個 ListDocuments 回應的網頁權杖。 提供此項目即可擷取後續網頁。進行分頁時，所有其他參數 (page_size 除外) 都必須與產生網頁權杖的要求中設定的值相符。
order_by	string 選用設定。要傳回文件的選用順序。 例如 priority desc, __name__ desc。 這與 Firestore 查詢中使用的 ORDER BY 一模一樣，但是以字串表示。如果找不到，系統會根據 __name__ ASC 排序文件。
mask	DocumentMask 選用設定。要傳回的欄位。如未設定，則會傳回所有欄位。 如果文件含有不在這個遮罩中的欄位，則不會在回應中傳回該欄位。
show_missing	bool 如果清單應顯示缺漏的文件， 如果文件不存在，但文件底下有子文件，則不會顯示。如果設為 True，這類遺漏的文件會以鍵的形式傳回，但不會設定欄位、create_time 或 update_time。 含有 show_missing 的要求不得指定 where 或 order_by。
聯集欄位 consistency_selector。這筆交易的一致性模式。如果未設定，則會預設為同步一致性。consistency_selector 只能採用下列其中一種設定：
transaction	bytes 在運作中的交易中執行讀取作業。
read_time	Timestamp 於指定時間執行讀取作業。 這個時間戳記須為過去 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 要從這個串流中移除的目標 ID。

聆聽回應

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 個位元組，且不得留空。

PartitionQueryRequest

Firestore.PartitionQuery 的要求。

欄位
parent	string 執行個體類型，父項資源名稱。請採用下列格式：projects/{project_id}/databases/{database_id}/documents。不支援文件資源名稱；只能指定資料庫資源名稱。
partition_count	int64 所需的分區點數量上限。多個結果頁面可能會傳回分區。數字必須是正數。實際傳回的分區數量可能較少。 舉例來說，設定可以設為只執行平行查詢數量的一個，或是執行資料管道工作中的數量少於可用的工作站或運算執行個體數量。
page_token	string 之前對 PartitionQuery 的呼叫傳回的 next_page_token 值，可用於取得另一組結果。結果組合之間沒有排序保證。因此，使用多組結果時，就需要合併不同的結果集。 舉例來說，使用 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 個分區，以完成 partition_count 中指定的 10 個分區。
聯集欄位 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，執行下列三個查詢將會傳回原始查詢的完整結果集： 查詢，end_at A 查詢，start_at A、end_at B 查詢，start_at B 空白結果可能表示該查詢沒有可分區的結果，或是查詢尚未支援分區。
next_page_token	string 頁面權杖，可用於要求其他一組結果，上限為 PartitionQuery 要求中的 partition_count 指定的數字。如果留空，表示沒有其他結果。

規劃摘要

查詢的規劃階段資訊。

欄位
indexes_used[]	Struct 為查詢選取的索引。例如：[ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ]

Precondition

文件的先決條件，用於條件式作業。

欄位
聯集欄位 condition_type。先決條件的類型。condition_type 只能採用下列其中一種設定：
exists	bool 設為 true 時，目標文件必須存在。設為 false 時，不可存在目標文件。
update_time	Timestamp 設定時，目標文件必須存在，且在此時已更新。時間戳記必須以微秒為單位對齊。

RollbackRequest

Firestore.Rollback 的要求。

欄位
database	string 執行個體類型，資料庫名稱。請採用下列格式：projects/{project_id}/databases/{database_id}。
transaction	bytes 執行個體類型，要復原的交易。

執行匯總查詢要求

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 在現有交易中執行匯總。 此處的值是執行查詢的不透明交易 ID。
new_transaction	TransactionOptions 在查詢中開始新的交易，預設為唯讀。 系統會傳回新的交易 ID，做為串流中的第一個回應。
read_time	Timestamp 在指定時間戳記執行查詢。 這個時間戳記須為過去 1 小時內的微秒精確度，或者如果已啟用時間點復原，也可以是過去 7 天內的整分鐘時間戳記。

執行匯總查詢回應

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 在有效交易內執行查詢。 此處的值是執行查詢的不透明交易 ID。
new_transaction	TransactionOptions 開始新的交易並讀取文件。預設為唯讀交易。系統會傳回新的交易 ID，做為串流中的第一個回應。
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 已完成要求，就不會再傳回其他文件。

StructuredAggregationQuery

用於對 StructuredQuery 執行匯總作業的 Firestore 查詢。

欄位
aggregations[]	Aggregation 選用設定。要套用至 structured_query 結果的一系列匯總。 需求條件： 每項查詢至少一項和最多五個匯總。
聯集欄位 query_type。要匯總的基礎查詢。query_type 只能採用下列其中一種設定：
structured_query	StructuredQuery 巢狀結構化查詢。

匯總

定義會產生單一結果的匯總。

欄位
alias	string 選用設定。用來儲存匯總結果的欄位名稱。 如未提供，Firestore 將按照 field_<incremental_id++> 格式選擇預設名稱。例如： AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2), COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) OVER ( ... ); 會變成： AGGREGATE COUNT_UP_TO(1) AS count_up_to_1, COUNT_UP_TO(2) AS field_1, COUNT_UP_TO(3) AS count_up_to_3, COUNT(*) AS field_2 OVER ( ... ); 需求條件： 所有匯總別名的名稱不得重複。 遵循 document field name 的限制。
聯集欄位 operator。要執行的匯總類型 (必要步驟)。operator 只能採用下列其中一種設定：
count	Count 計數匯總器。
sum	Sum 加總。
avg	Avg 一般集結網站。

平均

所要求欄位值的平均值。

• 系統只會匯總數值。會略過包括 NULL 在內的所有非數字值。

• 如果匯總值包含 NaN，就會傳回 NaN。Infinity 數學遵循 IEEE-754 標準。

• 如果設定的匯總值空白，則會傳回 NULL。

• 一律以雙精度傳回結果。

欄位
field	FieldReference 要匯總的欄位。

數量

符合查詢的文件數量。

COUNT(*) 匯總函式會針對整份文件進行操作，因此不需要欄位參照。

欄位
up_to	Int64Value 選用設定。(選用) 限制要計算的文件數量上限。 這樣就能設定要掃描的文件數量上限、限制延遲時間和費用。 如未指定，會解譯為無界限。 高階範例： AGGREGATE COUNT_UP_TO(1000) OVER ( SELECT * FROM k ); 需求條件： 存在時必須大於零。

總和

所要求欄位值的總和。

• 系統只會匯總數值。會略過包括 NULL 在內的所有非數字值。

• 如果匯總值包含 NaN，就會傳回 NaN。Infinity 數學遵循 IEEE-754 標準。

• 如果匯總值設為空白，就會傳回 0。

• 如果所有匯總數字都是整數，且總和結果未溢位，則會傳回 64 位元整數。否則會以雙精度浮點數傳回結果。請注意，即使所有匯總值是整數，如果結果無法符合 64 位元帶正負號整數，就會傳回雙倍結果。發生這種情況時，傳回的值就會失去精確度。

• 發生欠位的情況時，浮點匯總作業不具確定性。也就是說，在不變更基礎值的情況下重複執行相同的查詢，每次結果都可能略有不同。在這種情況下，值應以整數的形式儲存在浮點數上方。

欄位
field	FieldReference 要匯總的欄位。

StructuredQuery

Firestore 查詢。

查詢階段的執行順序如下：1. 從 2. 3. 選取 4. order_by + start_at + end_at 5。偏移 6. 限制

欄位
select	Projection 可傳回欄位的選用子集合。 就像 DocumentMask 一樣，適用於查詢傳回的文件。如未設定，則假設呼叫端希望傳回所有欄位。
from[]	CollectionSelector 要查詢的集合。
where	Filter 要套用的篩選器。
order_by[]	Order 要套用至查詢結果的順序。 Firestore 可讓呼叫端提供完整訂購、部分排序或完全不排序。在所有情況下，Firestore 都會透過下列規則確保以穩定的方式排序： 必須使用 order_by 才能參照使用不等式篩選器的所有欄位。 所有必填欄位都必須位於 order_by 中，但目前並未填寫的欄位，都會依照欄位名稱的字母順序排列。 如未指定 __name__ 的訂單，系統會依預設附加訂單。 欄位的排序方向會與最後指定的順序相同，或「ASCENDING」(如果未指定順序)。例如： ORDER BY a 變成 ORDER BY a ASC, __name__ ASC ORDER BY a DESC 變成 ORDER BY a DESC, __name__ DESC WHERE a > 1 變成 WHERE a > 1 ORDER BY a ASC, __name__ ASC WHERE __name__ > ... AND a > 1 變成 WHERE __name__ > ... AND a > 1 ORDER BY a ASC, __name__ ASC
start_at	Cursor 結果集內可能開始查詢的位置前置字元。 結果集的排序依據原始查詢的 ORDER BY 子句。 SELECT * FROM k WHERE a = 1 AND b > 2 ORDER BY b ASC, __name__ ASC; 這項查詢的結果是按 (b ASC, __name__ ASC) 排序。 遊標可以參照完整順序或位置的前置字串，但參照的欄位數量不能超過提供的 ORDER BY 值。 延續上述範例，附加以下起始遊標會產生不同的影響： START BEFORE (2, /k/123)：在 a = 1 AND b > 2 AND __name__ > /k/123 之前開始查詢。 START AFTER (10)：在 a = 1 AND b > 10 之後開始查詢。 需要掃描前 N 個結果才能略過，但 OFFSET 不同，起始遊標可讓查詢從邏輯位置開始。這個位置不需要與實際結果相符，系統就會從這個位置往前掃描，尋找下一份文件。 需求條件： 值的數量不得大於 ORDER BY 子句中指定的欄位數量。
end_at	Cursor 結果集中位置的可能前置字串，查詢結束位置。 這與 START_AT 類似，但前者會控制結束位置，而非起始位置。 需求條件： 值的數量不得大於 ORDER BY 子句中指定的欄位數量。
offset	int32 傳回第一個結果前略過的文件數量。 此情況會在 WHERE、START AT 和END AT，但在 LIMIT 子句之前。 需求條件： 指定的值必須大於或等於零 (如有)。
limit	Int32Value 要傳回的結果數上限。 在所有其他限制後方套用。 需求條件： 指定的值必須大於或等於零 (如有)。
find_nearest	FindNearest 選用設定。可能的鄰近地區搜尋。 系統會先套用所有其他篩選器和排序，再套用這項設定。 找出最接近指定查詢向量的向量嵌入。

集合選取器

一個集合，例如 messages as m1。

欄位
collection_id	string 集合 ID。設定後，請只選取具備這個 ID 的集合。
all_descendants	bool 設為 false 時，僅選取所屬 RunQueryRequest 所含 parent 直系子項的集合。如果為 true，系統會選取所有子集合。

CompositeFilter

使用指定運算子合併多個其他篩選器的篩選器。

欄位
op	Operator 用於合併多個篩選器的運算子。
filters[]	Filter 要合併的篩選器清單。 需求條件： 至少有一個篩選器。

運算子

複合篩選器運算子。

列舉
OPERATOR_UNSPECIFIED	未指定。不能使用這個值。
AND	文件須符合所有合併的篩選條件。
OR	文件必須至少符合其中一個合併的篩選條件。

方向

排序方向。

列舉
DIRECTION_UNSPECIFIED	未指定。
ASCENDING	遞增。
DESCENDING	遞減。

欄位篩選器

特定欄位的篩選器。

欄位
field	FieldReference 篩選依據的欄位。
op	Operator 要做為篩選依據的運算子。
value	Value 要比較的值。

運算子

欄位篩選器運算子。

列舉
OPERATOR_UNSPECIFIED	未指定。不能使用這個值。
LESS_THAN	指定的 field 小於指定的 value。 需求條件： 那field在 order_by 首位。
LESS_THAN_OR_EQUAL	指定的 field 小於或等於指定的 value。 需求條件： 那field在 order_by 首位。
GREATER_THAN	指定的 field 大於指定的 value。 需求條件： 那field在 order_by 首位。
GREATER_THAN_OR_EQUAL	指定的 field 大於或等於指定的 value。 需求條件： 那field在 order_by 首位。
EQUAL	指定的 field 等於指定的 value。
NOT_EQUAL	指定的 field 不等於指定的 value。 需求條件： 沒有其他 NOT_EQUAL、NOT_IN、IS_NOT_NULL 或 IS_NOT_NAN。 第一個field在 order_by 首度。
ARRAY_CONTAINS	指定的 field 是包含指定 value 的陣列。
IN	指定的 field 等於指定陣列中的至少一個值。 需求條件： 該 value 是非空白的 ArrayValue，有消防限制。 同一查詢中沒有任何 NOT_IN 篩選器。
ARRAY_CONTAINS_ANY	指定的 field 是一個陣列，其中包含指定陣列中的任一值。 需求條件： 該 value 是非空白的 ArrayValue，有消防限制。 同一串場內沒有其他 ARRAY_CONTAINS_ANY 篩選器。 同一查詢中沒有任何 NOT_IN 篩選器。
NOT_IN	field 的值不在指定的陣列中。 需求條件： 該 value 是非空白的 ArrayValue，最多有 10 個值。 沒有其他 OR、IN、ARRAY_CONTAINS_ANY、NOT_IN、NOT_EQUAL、IS_NOT_NULL 或 IS_NOT_NAN。 第一個field在 order_by 首度。

欄位參照

文件中欄位的參照，例如：stats.operations。

欄位
field_path	string 文件中欄位的參照。 需求條件： 必須是以點分隔的區隔字串 (.)，且每個區隔都符合 document field name 限制。

篩選器

篩選器。

欄位
聯集欄位 filter_type。篩選器類型。filter_type 只能採用下列其中一種設定：
composite_filter	CompositeFilter 複合篩選器。
field_filter	FieldFilter 文件欄位的篩選器。
unary_filter	UnaryFilter 僅使用一個引數的篩選器。

尋找最近的

「最鄰近項目」搜尋設定。

欄位
vector_field	FieldReference 執行個體類型，要搜尋的已建立索引向量欄位。文件必須包含維度與 query_vector 相符的向量。
query_vector	Value 執行個體類型，我們所搜尋的查詢向量。必須是不超過 2048 個尺寸的向量。
distance_measure	DistanceMeasure 執行個體類型，要使用的距離量，必要項目。
limit	Int32Value 執行個體類型，要傳回的最鄰點數量。必須是不超過 1000 的正整數。

距離測量結果

比較向量時使用的距離。

列舉
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 要套用運算子的欄位。

運算子

一元運算子。

列舉
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 用來在串流中識別目標的目標 ID。必須是正數，且不得為零。 如果 target_id 為 0 (或未指定)，伺服器會為這個目標指派 ID，並在 TargetChange::ADD 事件中傳回。新增含有 target_id=0 的目標後，所有後續目標也必須同時具備 target_id=0。如果在新增含有 target_id=0 的目標後，傳送含有 target_id != 0 的 AddTarget 要求至伺服器，伺服器會立即傳送包含 TargetChange::Remove 事件的回應。 請注意，如果用戶端傳送多個沒有 ID 的 AddTarget 要求，則 TargetChage.target_ids 中傳回的 ID 順序為未定義。因此，客戶應提供目標 ID，而不是依賴伺服器來指派。 如果 target_id 不是零，則這個串流中不得有相同 ID 的有效目標。
once	bool 如果目標在當前且一致的狀態後就應移除。
expected_count	Int32Value 上次在履歷符記或讀取時間與查詢相符的文件數量。 只有在提供 resume_type 時，這個值才有關聯性。此值存在，且大於用戶端想在回應中加入 ExistenceFilter.unchanged_names 的信號。
聯集欄位 target_type。要監聽的目標類型。target_type 只能採用下列其中一種設定：
query	QueryTarget 查詢所指定的目標。
documents	DocumentsTarget 由一組文件名稱指定的目標。
聯集欄位 resume_type。何時開始聆聽。 指定時，系統只會傳回 resume_token 或 read_time 「之後」已更新的相符文件。否則，系統會在進行後續變更前傳回所有相符的文件。resume_type 只能採用下列其中一種設定：
resume_token	bytes 來自相同目標的舊版 TargetChange 重新啟用權杖。 系統不支援使用其他目標的履歷權杖，因此可能會失敗。
read_time	Timestamp 特定read_time後開始聆聽。 用戶端必須目前知道相符文件的狀態。

DocumentsTarget

由一組文件名稱指定的目標。

欄位
documents[]	string 要擷取的文件名稱。請採用下列格式：projects/{project_id}/databases/{database_id}/documents/{document_path}。如果文件有任何文件不是指定 database 的子項資源，要求就會失敗。系統會省略重複的名稱。

查詢目標

查詢所指定的目標。

欄位
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 已變更指定目標的目標 ID。 如果留空，變更會套用到所有指定目標。 未定義目標 ID 的順序。
cause	Status 促成這項變更的錯誤 (如適用)。
resume_token	bytes 可用來針對指定 target_ids 繼續執行串流的權杖，如果 target_ids 為空白，則適用於所有目標。 並非每次目標變更時都要設定。
read_time	Timestamp 指定 target_ids 的 read_time 版本一致 (當 target_ids 的快照不穩定時，就會省略)。 當整個串流達到新的一致快照時，串流保證會傳送 target_ids 空白的 read_time。系統保證 ADD、CURRENT 和 RESET 訊息一定會 (最後) 產生一致的快照，但不能有 NO_CHANGE 和 REMOVE 訊息。 針對特定串流，read_time 保證只會單調遞增。

目標變更類型

變更類型。

列舉
NO_CHANGE	沒有發生任何變更。僅適用於傳送更新的 resume_token。
ADD	已新增目標。
REMOVE	已移除目標。
CURRENT	目標會反映所有在串流新增至串流前做出的變更。 這會在 read_time 大於或等於新增目標的時間之後或後方傳送。 如果需要執行寫入後讀取語意，事件監聽器可以等待這項變更。
RESET	已重設目標，並在後續變更中傳回目標的新初始狀態。 初始狀態完成後，即使目標先前已指定為 CURRENT，仍會傳回 CURRENT。

TransactionOptions

建立新交易的選項。

欄位
聯集欄位 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 空值。
boolean_value	bool 布林值。
integer_value	int64 整數值。
double_value	double 雙精度浮點值。
timestamp_value	Timestamp 時間戳記值。 精準至微秒。儲存時，其他所有精確度都會無條件捨去。
string_value	string 字串值。 字串 (以 UTF-8 表示) 不得超過 1 MiB 至 89 個位元組。查詢只會考慮 UTF-8 表示法的前 1,500 個位元組。
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 的要求。

第一個要求會建立串流，或從權杖繼續執行現有串流。

建立新串流時，伺服器會以只包含 ID 和權杖的回應做為回覆，以便在下一個要求中使用。

繼續執行串流時，伺服器會先串流晚於指定權杖的回應，然後串流只含有最新權杖的回應，以便在下一個要求中使用。

欄位
database	string 執行個體類型，資料庫名稱。請採用下列格式：projects/{project_id}/databases/{database_id}。這只需要在第一則訊息中填寫。
stream_id	string 要重新啟用的寫入串流 ID。這可能只能在第一則訊息中設定。如果留空，系統會建立新的寫入串流。
writes[]	Write 要套用的寫入作業。 一律以不可分割的形式，依序執行。第一個要求中必須留空。在最後一個要求中，這個項目可能空白。所有其他要求均不得留空。
stream_token	bytes 伺服器先前傳送的串流權杖。 用戶端應將這個欄位設為最近收到的 WriteResponse 中的權杖。確認用戶端已收到此權杖的回應。傳送這個權杖後，先前的權杖就無法再使用。 如果未確認的回應過多，伺服器就可能會關閉串流。 建立新串流時，不必設定這個欄位。如要在特定時間點繼續串流，請設定這個欄位和 stream_id 欄位。 建立新串流時，不必設定這個欄位。
labels	map<string, string> 與這項寫入要求相關聯的標籤。

寫入回應

Firestore.Write 的回應。

欄位
stream_id	string 串流 ID。只在建立新直播時，於第一則訊息中設定。
stream_token	bytes 代表此回應在串流中位置的符記。用戶端可使用此 ID 繼續進行串流作業。 系統會一律設定這個欄位。
write_results[]	WriteResult 套用寫入的結果。 這項 i-th 寫入結果與要求中的 i-th 寫入對應。
commit_time	Timestamp 修訂版本發生的時間。只要 read_time 等於或大於此值，就保證能看到寫入的效果。

WriteResult

套用寫入的結果。

欄位
update_time	Timestamp 套用寫入後，文件上次更新的時間。未在 delete 之後設定。 如果寫入內容實際上並未變更文件，那麼這將會是之前的 update_time。
transform_results[]	Value 以相同的順序套用每個 DocumentTransform.FieldTransform 的結果。