索引
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
(列舉)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
(列舉)StructuredQuery.Direction
(列舉)StructuredQuery.FieldFilter
(訊息)StructuredQuery.FieldFilter.Operator
(列舉)StructuredQuery.FieldReference
(訊息)StructuredQuery.Filter
(訊息)StructuredQuery.FindNearest
(訊息)StructuredQuery.FindNearest.DistanceMeasure
(列舉)StructuredQuery.Order
(訊息)StructuredQuery.Projection
(訊息)StructuredQuery.UnaryFilter
(訊息)StructuredQuery.UnaryFilter.Operator
(列舉)Target
(訊息)Target.DocumentsTarget
(訊息)Target.QueryTarget
(訊息)TargetChange
(訊息)TargetChange.TargetChangeType
(列舉)TransactionOptions
(訊息)TransactionOptions.ReadOnly
(訊息)TransactionOptions.ReadWrite
(訊息)UpdateDocumentRequest
(訊息)Value
(訊息)Write
(訊息)WriteRequest
(訊息)WriteResponse
(訊息)WriteResult
(訊息)
Firestore
Cloud Firestore 服務。
Cloud Firestore 是快速、全代管、無伺服器且雲端原生的 NoSQL 文件資料庫,可針對全球規模的行動、網路和 IoT 應用程式簡化儲存、同步及查詢資料的程序。Cloud Firestore 的用戶端程式庫不但提供即時同步處理和離線支援,還具備安全性功能,且已與 Firebase 和 Google Cloud Platform 整合,能讓您加速建構完全無伺服器的應用程式。
BatchGetDocuments |
---|
取得多份文件。 此方法傳回的文件不一定會按照要求的順序傳回。
|
BatchWrite |
---|
套用批次寫入作業。 BatchWrite 方法不會自動套用寫入作業,而且可能會按順序套用。這個方法規定每份文件只能寫入一次。每項寫入作業都會獨立成功或失敗。如要瞭解每次寫入的成功狀態,請參閱 如果需要一組以不可分割的形式套用的寫入作業,請改用
|
BeginTransaction |
---|
開始新的交易。
|
修訂 |
---|
修訂交易,並視需要更新文件。
|
CreateDocument |
---|
建立新文件。
|
DeleteDocument |
---|
刪除文件。
|
GetDocument |
---|
取得單一文件。
|
ListCollectionIds |
---|
列出文件下的所有集合 ID。
|
ListDocuments |
---|
列出文件。
|
聆聽 |
---|
監聽變更。此方法只能透過 gRPC 或 WebChannel (非 REST) 使用。
|
PartitionQuery |
---|
傳回可用來平行執行查詢的分區遊標,將查詢分區。傳回的分區遊標是分割點,可由 RunQuery 使用,做為查詢結果的起點/終點。
|
復原 |
---|
復原交易。
|
RunAggregationQuery |
---|
執行匯總查詢。 這個 API 不會產生 高階範例:
|
RunQuery |
---|
執行查詢。
|
UpdateDocument |
---|
更新或插入文件。
|
撰寫 |
---|
系統會按照順序分批處理文件更新和刪除作業。此方法只能透過 gRPC 或 WebChannel (非 REST) 使用。
|
AggregationResult
Firestore 匯總查詢中單一值區的結果。
匯總查詢中所有結果的 aggregate_fields
金鑰都相同,這一點與在每份結果中可能會有不同欄位的文件查詢不同。
欄位 | |
---|---|
aggregate_fields |
匯總函式的結果,例如: 索引鍵是在輸入時指派給匯總函式的 |
ArrayValue
陣列值。
欄位 | |
---|---|
values[] |
陣列中的值。 |
BatchGetDocumentsRequest
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
documents[] |
要擷取的文件名稱,請採用下列格式: |
mask |
要傳回的欄位。如果沒有設定,系統會傳回所有欄位。 如果文件的某個欄位未列於這個遮罩中,系統不會在回應中傳回該欄位。 |
聯集欄位 consistency_selector 。這筆交易的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
這個外掛程式能在交易中讀取文件。 |
new_transaction |
開始新交易並讀取文件。預設為唯讀交易。新的交易 ID 將傳回,做為串流中的第一個回應。 |
read_time |
這個外掛程式能在指定時間讀取文件。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
BatchGetDocumentsResponse
Firestore.BatchGetDocuments
的串流回應。
欄位 | |
---|---|
transaction |
在這個要求中啟動的交易。只會在第一個回應中設定,且只有在要求中設有 |
read_time |
讀取文件的時間。這也許只會增加一點,也就是在本例中,結果串流中的舊文件在 read_time 和此文件之間不會進行變更。 |
聯集欄位 result 。單筆結果。如果伺服器只是傳回交易,這個值就會留空。result 只能是下列其中一項: |
|
found |
要求的文件。 |
missing |
已要求但不存在的文件名稱。請採用下列格式: |
BatchWriteRequest
Firestore.BatchWrite
的要求。
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
writes[] |
要套用的寫入內容。 這個方法不會自動套用寫入作業,不保證會排序。每項寫入作業都會獨立成功或失敗。每項要求最多只能寫入同一份文件一次。 |
labels |
與這項批次寫入作業相關聯的標籤。 |
BatchWriteResponse
Firestore.BatchWrite
的回應。
欄位 | |
---|---|
write_results[] |
套用寫入的結果。 這個 i-th 寫入結果對應要求中的第 i 次寫入。 |
status[] |
套用寫入的狀態。 這個 i-th 寫入狀態對應至要求中的第 i 次寫入。 |
BeginTransactionRequest
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
options |
交易的選項。預設為讀寫交易。 |
BeginTransactionResponse
欄位 | |
---|---|
transaction |
開始的交易。 |
BitSequence
以位元組陣列編碼的一串位元。
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
。
BitSequence
的「大小」(其中所含的位元數) 是由以下公式計算而得:(bitmap.length * 8) - padding
。
欄位 | |
---|---|
bitmap |
將位元序列編碼的位元組。長度可能是 0。 |
padding |
|
BloomFilter
Bloom 篩選器 (https://en.wikipedia.org/wiki/Bloom_filter)。
Bloom 篩選器會使用 MD5 對項目進行雜湊,並將產生的 128 位元雜湊值視為 2 個不同的 64 位元雜湊值,並使用 2 的補字編碼,將其解讀為無正負號整數。
h1
和 h2
這兩個雜湊值隨後將用於使用公式計算 hash_count
雜湊值 (從 i=0
開始):
h(i) = h1 + (i * h2)
接著,這些結果值會對 Bloom 篩選器的位元數進行模數,以取得 Bloom 篩選器的位元以測試指定項目。
欄位 | |
---|---|
bits |
花朵篩選器資料。 |
hash_count |
演算法使用的雜湊數量。 |
CommitRequest
Firestore.Commit
的要求。
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
writes[] |
要套用的寫入內容。 一律會依序執行。 |
transaction |
如有設定,請套用並修訂這項交易中的所有寫入作業。 |
CommitResponse
Firestore.Commit
的回應。
欄位 | |
---|---|
write_results[] |
套用寫入的結果。 這個 i-th 寫入結果對應要求中的第 i 次寫入。 |
commit_time |
修訂版本發生的時間。只要讀取具有相同或大於 |
CreateDocumentRequest
欄位 | |
---|---|
parent |
必要欄位。父項資源。例如 |
collection_id |
必要欄位。要列出的集合 ID (相對於 |
document_id |
要用於這個文件的用戶端指派的文件 ID。 選用設定。如未指定,服務將會指派 ID。 |
document |
必要欄位。要建立的文件。請勿設定「 |
mask |
要傳回的欄位。如果沒有設定,系統會傳回所有欄位。 如果文件的某個欄位未列於這個遮罩中,系統不會在回應中傳回該欄位。 |
Cursor
查詢結果集內的位置。
欄位 | |
---|---|
values[] |
代表位置的值,會按照查詢的子句的順序排列。 包含的值可以少於子句按照子句排序。 |
before |
如果位置早於指定值之前或之後,即相對於查詢定義的排序順序。 |
DeleteDocumentRequest
欄位 | |
---|---|
name |
必要欄位。所刪除文件的資源名稱。請採用下列格式: |
current_document |
文件上的選用先決條件。如果已設定此設定,但未為目標文件達成,要求就會失敗。 |
文件
Firestore 文件。
不得超過 1 MiB 至 4 個位元組。
欄位 | |
---|---|
name |
文件的資源名稱,例如 |
fields |
|
create_time |
僅供輸出。建立文件的時間。 刪除後重新建立文件時,這個值會單調遞增。也可以比較其他文件的值和查詢的 |
update_time |
僅供輸出。文件上次變更的時間。 這個值最初設為 |
DocumentChange
Document
已變更。
這可能是多個 writes
的結果 (包括刪除),最終為 Document
產生新的值。
如果有多個目標受到影響,同一項邏輯變更可能會傳回多則 DocumentChange
訊息。
欄位 | |
---|---|
document |
如果有設定 |
target_ids[] |
與這份文件相符的一組目標 ID。 |
removed_target_ids[] |
與此文件不再相符的目標 ID 組合。 |
DocumentDelete
已刪除 Document
。
這可能是多個 writes
的結果,包括更新,最近一次刪除 Document
。
如果有多個目標受到影響,同一個邏輯刪除作業可能會傳回多則 DocumentDelete
訊息。
欄位 | |
---|---|
document |
已刪除 |
removed_target_ids[] |
先前與這個實體相符的目標 ID。 |
read_time |
觀察到刪除作業的讀取時間戳記。 大於或等於刪除的 |
DocumentMask
文件中的一組欄位路徑。用於限製文件的 get 或更新作業,只能執行其部分欄位。這與標準欄位遮罩不同,因為這個範圍一律會限定為 Document
,並且會將 Value
的動態性質納入考量。
欄位 | |
---|---|
field_paths[] |
遮罩中的欄位路徑清單。如需欄位路徑語法參考資料,請參閱 |
DocumentRemove
Document
已從目標的檢視畫面中移除。
文件與目標不再相關且無法查看時傳送。如果伺服器無法傳送文件的新值,可將新值改為傳送至 DocumentDelete 或 DocumentChange。
如果有多個目標受到影響,系統可能會針對相同的邏輯寫入或刪除作業傳回多則 DocumentRemove
訊息。
欄位 | |
---|---|
document |
已不在檢視畫面的 |
removed_target_ids[] |
先前與這份文件相符的目標 ID。 |
read_time |
觀察到移除作業的讀取時間戳記。 大於或等於變更/刪除/移除的 |
DocumentTransform
轉換文件。
欄位 | |
---|---|
document |
要轉換的文件名稱。 |
field_transforms[] |
要依序套用至文件欄位的轉換清單。此屬性不得留空。 |
FieldTransform
轉換文件欄位。
欄位 | |
---|---|
field_path |
欄位路徑。如需欄位路徑語法參考資料,請參閱 |
聯集欄位 transform_type 。要套用至欄位的轉換。transform_type 只能是下列其中一項: |
|
set_to_server_value |
將欄位設為指定的伺服器值。 |
increment |
將指定值新增至欄位目前的值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值,或是該欄位不存在,則轉換會將欄位設為指定值。如果指定值或目前的欄位值是雙精度浮點數,兩個值都會被解讀為雙精度浮點值。雙值的雙算和表示會遵循 IEEE 754 語意。如果有正整數溢位現象,欄位會解析為最大的大小正負整數/負整數。 |
maximum |
將欄位設為目前值與指定值的最大值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值,或是該欄位不存在,則轉換會將欄位設為指定值。如果欄位和輸入值是混合型別 (也就是 1 是整數,1 是雙精度浮點數),卻套用最大運算,欄位會採用較大運算元的類型。如果運算元相等 (例如 3 和 3.0),則欄位不會變更。0、0.0 和 -0.0 都是零。零儲存值和輸入值的最大值一律為儲存值。x 和 NaN 的任何數值上限為 NaN。 |
minimum |
將欄位設為目前值和指定值的最小值。 必須是整數或雙精度浮點值。如果欄位不是整數或雙精度浮點值,或是該欄位不存在,則轉換會將欄位設為輸入值。如果欄位和輸入值是混合型別 (也就是 - 一個是整數,1 為雙精度浮點數),則欄位會採用最小運算元類型。如果運算元相等 (例如 3 和 3.0),則欄位不會變更。0、0.0 和 -0.0 都是零。零值和零輸入值的最小值一律為儲存值。x 和 NaN 的任何數值的最小值為 NaN。 |
append_missing_elements |
如果指定元素尚未出現在目前的欄位值中,請依序附加這些元素。如果欄位不是陣列,或是該欄位不存在,則會先設為空白陣列。 檢查是否缺少值時,系統會將不同類型的不同類型 (例如 3L 和 3.0) 相等。NaN 等於 NaN,而空值等於空值。如果輸入包含多個對等的值,系統只會採用第一個值。 對應的 transform_result 為空值。 |
remove_all_from_array |
從欄位的陣列中移除所有指定元素。如果欄位不是陣列,或是該欄位不存在,則會設為空白的陣列。 判斷元素是否應移除時,不同類型 (例如 3L 和 3.0) 的相等數會視為相等。NaN 等於 NaN,而空值等於空值。這會移除所有重複的值。 對應的 transform_result 為空值。 |
ServerValue
伺服器計算的值。
列舉 | |
---|---|
SERVER_VALUE_UNSPECIFIED |
未指定。請勿使用這個值。 |
REQUEST_TIME |
伺服器處理要求的時間 (精確度可達毫秒)。如果您在交易的多個欄位 (相同或不同的文件) 中使用,所有欄位都會獲得相同的伺服器時間戳記。 |
ExecutionStats
查詢的執行統計資料。
欄位 | |
---|---|
results_returned |
傳回的結果總數,包括文件、投影、匯總結果和鍵。 |
execution_duration |
在後端執行查詢的總時間。 |
read_operations |
可計費讀取作業總數。 |
debug_stats |
針對執行查詢的統計資料進行偵錯。請注意,隨著 Firestore 演進,偵錯統計資料可能會有所變動。It could include: { "indexes_entries_scanned": "1000", "documents_scanned": "20", "billing_details" : { "documents_billable": "20", "index_entries_billable": "1000", "min_query_cost": "0" } } |
ExistenceFilter
符合指定目標的所有文件摘要。
欄位 | |
---|---|
target_id |
這個篩選器要套用的目標 ID。 |
count |
符合 如果與用戶端中符合的文件數量不同,用戶端必須手動判定哪些文件不再與目標相符。 用戶端可以使用 |
unchanged_names |
這個 Bloom 篩選器雖然名稱,但會包含「所有」符合 伺服器可自行斟酌是否省略這個 Bloom 篩選器,例如我們判定用戶端不會使用該篩選器,或者計算或傳輸的運算成本過高。用戶端必須改回採用這個欄位之前使用的邏輯,以便妥善處理缺少這個欄位;也就是說,在沒有履歷符記的情況下重新加入目標,以找出用戶端快取中的哪些文件不同步。 |
ExplainMetrics
說明查詢的指標。
欄位 | |
---|---|
plan_summary |
查詢的規劃階段資訊。 |
execution_stats |
執行查詢後匯總的統計資料。只有在 |
ExplainOptions
說明查詢的選項。
欄位 | |
---|---|
analyze |
選用設定。是否要執行這項查詢。 如果設為 False (預設值),系統會規劃查詢,讓系統只傳回規劃階段的指標。 如果為 true,將會規劃並執行查詢,並傳回完整的查詢結果,以及規劃和執行階段指標。 |
GetDocumentRequest
欄位 | |
---|---|
name |
必要欄位。要取得的文件資源名稱,請採用下列格式: |
mask |
要傳回的欄位。如果沒有設定,系統會傳回所有欄位。 如果文件的某個欄位未列於這個遮罩中,系統不會在回應中傳回該欄位。 |
聯集欄位 consistency_selector 。這筆交易的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
在交易中讀取文件。 |
read_time |
讀取指定時間的文件版本。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
ListCollectionIdsRequest
欄位 | |
---|---|
parent |
必要欄位。父項文件。請採用下列格式: |
page_size |
要傳回的結果數上限。 |
page_token |
網頁權杖。必須是來自 |
聯集欄位 consistency_selector 。這項要求的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
read_time |
這個外掛程式能在指定時間讀取文件。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
ListCollectionIdsResponse
欄位 | |
---|---|
collection_ids[] |
集合 ID。 |
next_page_token |
可用來繼續列出清單的網頁權杖。 |
ListDocumentsRequest
欄位 | |
---|---|
parent |
必要欄位。父項資源名稱。格式為: 例如 |
collection_id |
選用設定。要列出的集合 ID (相對於 例如 此為選用項目。如未提供,Firestore 會在提供的 |
page_size |
選用設定。單一回應中傳回的文件數量上限。 Firestore 傳回的值可能會少於這個值。 |
page_token |
選用設定。接收自先前 提供此項目即可擷取後續網頁。進行分頁時,所有其他參數 ( |
order_by |
選用設定。可選擇傳回文件的順序。 例如 這會反映 Firestore 查詢中使用的 |
mask |
選用設定。要傳回的欄位。如果沒有設定,系統會傳回所有欄位。 如果文件的某個欄位未列於這個遮罩中,系統不會在回應中傳回該欄位。 |
show_missing |
清單是否應顯示遺漏的文件。 文件不存在時就不見了,但下方有子文件巢狀結構。如果設為「是」,系統將傳回缺少的這類文件以及鍵,但不會設定欄位、 含有 |
聯集欄位 consistency_selector 。這筆交易的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
在既有交易中執行讀取作業。 |
read_time |
在提供的時間點執行讀取作業。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
ListDocumentsResponse
欄位 | |
---|---|
documents[] |
找到的文件。 |
next_page_token |
用於擷取下一頁文件的權杖。 如果省略這個欄位,就不會有後續頁面。 |
ListenRequest
「Firestore.Listen
」提出的要求
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
labels |
與這項目標變更相關聯的標籤。 |
聯集欄位 target_change 。支援的目標有所變更。target_change 只能是下列其中一項: |
|
add_target |
要新增至這個串流的目標。 |
remove_target |
要從這個串流中移除的目標 ID。 |
ListenResponse
Firestore.Listen
的回應。
欄位 | |
---|---|
聯集欄位 response_type 。支援的回應。response_type 只能是下列其中一項: |
|
target_change |
目標已變更。 |
document_change |
|
document_delete |
已刪除 |
document_remove |
|
filter |
這個篩選器會套用至先前針對指定目標傳回的文件組合。 如果文件已從指定目標中移除,但文件內容不明,系統會傳回這個值。 |
MapValue
對應值。
欄位 | |
---|---|
fields |
地圖的欄位。 對應鍵代表欄位名稱。系統會保留與 |
PartitionQueryRequest
欄位 | |
---|---|
parent |
必要欄位。父項資源名稱。請採用下列格式: |
partition_count |
所需的分區點數量上限。分區可能會在結果的多個頁面中傳回。數字必須為正數。實際傳回的分區數量可能較少。 舉例來說,這個項目可以設為少於平行查詢數量的一個,或在執行資料管道工作時,設為少於 1 個,低於可用的工作站或運算執行個體數量。 |
page_token |
先前呼叫 PartitionQuery 時傳回的 舉例來說,使用 page_token 進行的後續呼叫可能會傳回:
如要針對提供給 PartitionQuery 的查詢結果取得完整結果集,請合併結果集:遊標 A、遊標 B、遊標 M、遊標 Q、遊標 U、遊標 W |
page_size |
這項呼叫中要傳回的分區數量上限 (取決於 舉例來說,如果 |
聯集欄位 query_type 。要分區的查詢。query_type 只能是下列其中一項: |
|
structured_query |
結構化查詢。查詢必須指定所有子系的集合,並依名稱遞增排序。不支援其他篩選器、排序依據、限制、偏移和開始/結束遊標。 |
聯集欄位 consistency_selector 。這項要求的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
read_time |
這個外掛程式能在指定時間讀取文件。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
PartitionQueryResponse
欄位 | |
---|---|
partitions[] |
分區結果。每個分區都是一個分割點,可由 RunQuery 使用做為查詢結果的起點或終點。發出 RunQuery 要求時,必須使用向這個 PartitionQuery 要求提供的相同查詢。分區遊標的順序與提供給 PartitionQuery 查詢結果的順序相同。 舉例來說,如果 PartitionQuery 要求傳回分區遊標 A 和 B,執行以下三項查詢就會傳回原始查詢的整個結果集:
空白結果可能表示查詢的結果太少,無法分區,或是查詢尚未支援分區。 |
next_page_token |
可用來要求一組額外結果的網頁權杖,上限為 PartitionQuery 要求中 |
PlanSummary
查詢的規劃階段資訊。
欄位 | |
---|---|
indexes_used[] |
為查詢選取的索引。For example: [ {"query_scope": "Collection", "properties": "(foo ASC, name ASC)"}, {"query_scope": "Collection", "properties": "(bar ASC, name ASC)"} ] |
Precondition
文件的先決條件,用於條件運算。
欄位 | |
---|---|
聯集欄位 condition_type 。先決條件的類型。condition_type 只能是下列其中一項: |
|
exists |
如果設為 |
update_time |
設定時,目標文件必須存在,且在該時間已更新。時間戳記必須對齊微秒。 |
RollbackRequest
Firestore.Rollback
的要求。
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
transaction |
必要欄位。要復原的交易。 |
RunAggregationQueryRequest
欄位 | |
---|---|
parent |
必要欄位。父項資源名稱。格式為: |
explain_options |
選用設定。說明查詢的選項。如果有設定,系統就會傳回額外的查詢統計資料。否則,系統只會傳回查詢結果。 |
聯集欄位 query_type 。要執行的查詢。query_type 只能是下列其中一項: |
|
structured_aggregation_query |
匯總查詢。 |
聯集欄位 consistency_selector 。查詢的一致性模式預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
在既有交易中執行匯總作業。 這裡的值是執行查詢的不透明交易 ID。 |
new_transaction |
在查詢中開始新交易,預設為唯讀。 新的交易 ID 將傳回,做為串流中的第一個回應。 |
read_time |
按照指定的時間戳記執行查詢。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
RunAggregationQueryResponse
欄位 | |
---|---|
result |
單一匯總結果。 回報部分進度時不會顯示。 |
transaction |
在這個要求中啟動的交易。 只有在要求展開新交易時,才會出現在第一個回應中。 |
read_time |
計算匯總結果的時間。該數值一律會單調增加;在這種情況下,結果串流中先前的 AggregationResult 不保證在其 如果查詢未傳回任何結果,則會收到含有 |
explain_metrics |
查詢說明指標。只有在提供 |
RunQueryRequest
Firestore.RunQuery
的要求。
欄位 | |
---|---|
parent |
必要欄位。父項資源名稱。格式為: |
explain_options |
選用設定。說明查詢的選項。如果有設定,系統就會傳回額外的查詢統計資料。否則,系統只會傳回查詢結果。 |
聯集欄位 query_type 。要執行的查詢。query_type 只能是下列其中一項: |
|
structured_query |
結構化查詢。 |
聯集欄位 consistency_selector 。這筆交易的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
transaction |
在既有交易中執行查詢。 這裡的值是執行查詢的不透明交易 ID。 |
new_transaction |
開始新交易並讀取文件。預設為唯讀交易。新的交易 ID 將傳回,做為串流中的第一個回應。 |
read_time |
這個外掛程式能在指定時間讀取文件。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
RunQueryResponse
Firestore.RunQuery
的回應。
欄位 | |
---|---|
transaction |
在這個要求中啟動的交易。只能在第一個回應中設定,且要求中必須設有 |
document |
查詢結果,回報部分進度時未設定。 |
read_time |
讀取文件的時間。這可能單純增加;在這種情況下,結果串流中的舊文件在其 如果查詢未傳回任何結果,則會收到含有 |
skipped_results |
因上次回應與目前回應之間偏移而略過的結果數。 |
explain_metrics |
查詢說明指標。只有在提供 |
聯集欄位 continuation_selector 。查詢的接續模式。如有顯示,表示目前的查詢回應串流已完成。無論是否包含 document ,都可以進行設定,但設定完畢後,系統就不會傳回其他結果。continuation_selector 只能採用下列其中一種設定: |
|
done |
如果存在,Firestore 就會完成要求,不會再傳回其他文件。 |
StructuredAggregationQuery
用於執行 StructuredQuery
匯總的 Firestore 查詢。
欄位 | |
---|---|
aggregations[] |
選用設定。要套用至 需求:
|
聯集欄位 query_type 。要匯總的基本查詢。query_type 只能是下列其中一項: |
|
structured_query |
巢狀結構化查詢。 |
匯總
定義產生單一結果的匯總。
欄位 | |
---|---|
alias |
選用設定。選填的欄位名稱,用於儲存匯總結果。 如未提供,Firestore 會按照
會變成:
需求:
|
聯集欄位 operator 。要執行的匯總類型 (必要)。operator 只能是下列其中一項: |
|
count |
計數集結網站。 |
sum |
加總資料集結網站。 |
avg |
平均集結網站。 |
Avg
所要求欄位值的平均值。
只會匯總數字值。系統會略過包括
NULL
在內的所有非數值。如果匯總值包含
NaN
,就會傳回NaN
。Infinity 數學符合 IEEE-754 標準。如果匯總值為空白,就會傳回
NULL
。一律以雙精度浮點值傳回結果。
欄位 | |
---|---|
field |
要匯總依據的欄位。 |
數量
符合查詢的文件數量。
COUNT(*)
匯總函式適用於整份文件,因此不需要欄位參照。
欄位 | |
---|---|
up_to |
選用設定。視需要設定文件數量上限。 這個方式可用來設定要掃描的文件數上限,進而限制延遲時間和費用。 未指定為未繫結。 高階範例:
需求:
|
總和
要求欄位值的總和。
只會匯總數字值。系統會略過包括
NULL
在內的所有非數值。如果匯總值包含
NaN
,就會傳回NaN
。Infinity 數學符合 IEEE-754 標準。如果匯總值為空白,就會傳回 0。
如果所有匯總數字都是整數,且總和結果未溢位,會傳回 64 位元整數。否則,結果會以雙精度浮點值傳回。請注意,即使所有匯總值都是整數,如果結果超出 64 位元帶正負號整數,系統仍會將結果傳回為雙精度浮點值。發生這種情況時,傳回的值會失去精確度。
發生反向溢位時,浮點匯總不具確定性,也就是說,重複執行相同的查詢時,如果基礎值沒有變更,每次產生的結果可能略有不同。在這種情況下,值應以整數形式儲存在浮點數上。
欄位 | |
---|---|
field |
要匯總依據的欄位。 |
StructuredQuery
Firestore 查詢。
查詢階段會以下列順序執行:1. 從 2. 開始,其中 3. 選取 4. order_by + start_at 5。偏移 6. 上限
欄位 | |
---|---|
select |
針對要傳回的欄位 (選用) 子集合。 對查詢傳回的文件而言,這會是 |
from[] |
要查詢的集合。 |
where |
要套用的篩選器。 |
order_by[] |
要套用至查詢結果的順序。 Firestore 可讓呼叫端提供完整訂購、部分訂購或完全不排序。無論在何種情況下,Firestore 都會透過下列規則保證具有穩定的排序:
欄位會附加與最後一個指定順序相同的排序方向,如未指定順序,則會附加「ASCENDING」。例如:
|
start_at |
查詢集內位置的可能前置字串,用於查詢起始位置。 結果集的排序是以原始查詢的
此查詢的結果是依 遊標可以參照完整排序或地點的前置字元,但只能參照所提供的 延續上方範例,附加下列開始遊標會造成不同的影響:
需求:
|
end_at |
在結果集中,為查詢結束位置的潛在前置字串。 這與 需求:
|
offset |
傳回第一個結果前要略過的文件數量。 此情況會在 需求:
|
limit |
要傳回的結果數上限。 在所有限制之後套用。 需求:
|
find_nearest |
選用設定。可能的鄰近搜尋。 套用到所有其他篩選條件和排序。 尋找最接近指定查詢向量的向量嵌入。 |
CollectionSelector
一組集合,例如 messages as m1
。
欄位 | |
---|---|
collection_id |
集合 ID。設定後,只會選取這個 ID 的集合。 |
all_descendants |
如果設為 False,則只會選取其在包含 |
CompositeFilter
使用指定運算子合併多個其他篩選器的篩選器。
欄位 | |
---|---|
op |
用於合併多個篩選器的運算子。 |
filters[] |
要合併的篩選器清單。 需求:
|
運算子
複合式篩選器運算子。
列舉 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。請勿使用這個值。 |
AND |
文件必須符合所有合併的篩選條件。 |
OR |
文件至少須符合其中一個合併篩選條件。 |
方向
排序方向。
列舉 | |
---|---|
DIRECTION_UNSPECIFIED |
未指明 |
ASCENDING |
遞增。 |
DESCENDING |
遞減。 |
FieldFilter
特定欄位的篩選器。
欄位 | |
---|---|
field |
要做為篩選依據的欄位。 |
op |
做為篩選依據的運算子。 |
value |
要比較的值。 |
運算子
欄位篩選器運算子。
列舉 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。請勿使用這個值。 |
LESS_THAN |
指定的 需求:
|
LESS_THAN_OR_EQUAL |
指定的 需求:
|
GREATER_THAN |
指定的 需求:
|
GREATER_THAN_OR_EQUAL |
指定的 需求:
|
EQUAL |
指定 field 等於指定的 value 。 |
NOT_EQUAL |
指定的 需求:
|
ARRAY_CONTAINS |
指定的 field 是包含指定 value 的陣列。 |
IN |
指定的 需求:
|
ARRAY_CONTAINS_ANY |
指定的 需求:
|
NOT_IN |
需求:
|
FieldReference
文件中欄位的參照,例如:stats.operations
。
欄位 | |
---|---|
field_path |
文件中欄位的參照。 需求:
|
篩選器
篩選器。
欄位 | |
---|---|
聯集欄位 filter_type 。篩選器類型。filter_type 只能是下列其中一項: |
|
composite_filter |
複合篩選器。 |
field_filter |
文件欄位的篩選器。 |
unary_filter |
只接收一個引數的篩選器。 |
FindNearest
「臨近鄰」搜尋設定。
欄位 | |
---|---|
vector_field |
必要欄位。要搜尋的已建立索引向量欄位。系統只能傳回維度與 query_vector 相符向量的文件。 |
query_vector |
必要欄位。系統搜尋的查詢向量。必須為大小不超過 2048 個維度的向量。 |
distance_measure |
必要欄位。要使用的距離量 (必要)。 |
limit |
必要欄位。要傳回的最鄰近鄰點數量。必須是不超過 1000 的正整數。 |
DistanceMeasure
比較向量時使用的距離測量值。
列舉 | |
---|---|
DISTANCE_MEASURE_UNSPECIFIED |
請勿設定。 |
EUCLIDEAN |
可測量向量之間的 EUCLIDEAN 距離。詳情請參閱歐幾亞 |
COSINE |
根據向量間的角度比較向量,這樣就能評估並非以向量大小為依據的相似度。建議您使用 DOT_PRODUCT 搭配單位正規化向量而非 COSINE 距離,這在數學上等同於在數學上,效能更佳。詳情請參閱餘弦相似度。 |
DOT_PRODUCT |
與餘弦相似,但會受到向量大小影響。詳情請參閱 Dot 產品。 |
訂單
欄位上的訂單。
欄位 | |
---|---|
field |
要排序的欄位。 |
direction |
排序依據的方向。預設值為 |
投影
要傳回的文件欄位投影。
欄位 | |
---|---|
fields[] |
要傳回的欄位。 如果留空,系統會傳回所有欄位。如果只要傳回文件名稱,請使用 |
UnaryFilter
包含單一運算元的篩選器。
欄位 | |
---|---|
op |
要套用的一元運算子。 |
聯集欄位 operand_type 。篩選器的引數。operand_type 只能是下列其中一項: |
|
field |
要套用運算子的欄位。 |
運算子
一元運算子。
列舉 | |
---|---|
OPERATOR_UNSPECIFIED |
未指定。請勿使用這個值。 |
IS_NAN |
指定 field 等於 NaN 。 |
IS_NULL |
指定 field 等於 NULL 。 |
IS_NOT_NAN |
指定的 需求:
|
IS_NOT_NULL |
指定的 需求:
|
目標
要監聽的一組文件規格,
欄位 | |
---|---|
target_id |
用於識別串流上目標的目標 ID。必須為正數,且非零。 如果 請注意,如果用戶端傳送多個沒有 ID 的 如果 |
once |
如果目標處於最新狀態且一致,應將其移除。 |
expected_count |
履歷權杖或讀取時,上次與查詢相符的文件數量。 只有在提供 |
聯集欄位 target_type 。要監聽的目標類型。target_type 只能是下列其中一項: |
|
query |
查詢指定的目標。 |
documents |
由一組文件名稱指定的目標。 |
聯集欄位 如果有指定,系統只會傳回在 |
|
resume_token |
先前 系統不支援採用不同目標的履歷權杖,而且可能會失敗。 |
read_time |
在特定 用戶端目前必須知道相符文件的狀態。 |
DocumentsTarget
由一組文件名稱指定的目標。
欄位 | |
---|---|
documents[] |
要擷取的文件名稱,請採用下列格式: |
QueryTarget
查詢指定的目標。
欄位 | |
---|---|
parent |
父項資源名稱。格式為: |
聯集欄位 query_type 。要執行的查詢。query_type 只能是下列其中一項: |
|
structured_query |
結構化查詢。 |
TargetChange
監控的目標已變更。
欄位 | |
---|---|
target_change_type |
發生的變更類型。 |
target_ids[] |
已變更目標的目標 ID。 如果留空,變更會套用至所有目標。 未定義目標 ID 的順序。 |
cause |
導致這項變更的錯誤 (如適用)。 |
resume_token |
可用來繼續執行指定 每次目標變更時都不會設定。 |
read_time |
指定 每當整個串流達到新的一致快照時,串流一定會傳送含有 針對特定串流, |
TargetChangeType
變更類型。
列舉 | |
---|---|
NO_CHANGE |
沒有任何變更。僅用於傳送更新後的 resume_token 。 |
ADD |
已新增目標。 |
REMOVE |
已移除目標。 |
CURRENT |
目標會反映出在目標新增至串流之前進行的所有變更。 此動作會在 如果需要使用「寫入後讀取」語意,事件監聽器可等待這項變更。 |
RESET |
目標已重設,系統會在後續變更時傳回目標的新初始狀態。 在初始狀態完成後,即使目標先前指定為 |
TransactionOptions
建立新交易的選項。
欄位 | |
---|---|
聯集欄位 mode 。交易的模式。mode 只能是下列其中一項: |
|
read_only |
交易只能用於讀取作業。 |
read_write |
交易可用於讀取和寫入作業。 |
ReadOnly
只能用於讀取文件的交易選項。
欄位 | |
---|---|
聯集欄位 consistency_selector 。這筆交易的一致性模式。如果未設定,則預設為同步一致性。consistency_selector 只能是下列其中一項: |
|
read_time |
在指定時間讀取文件。 這個值必須是過去 1 小時內的微秒精確度,如果已啟用「時間點復原」功能,則可以是過去 7 天內的整分鐘時間戳記。 |
ReadWrite
可用於讀取及寫入文件的交易選項。
Firestore 不允許第三方驗證要求建立讀取/寫入交易。
欄位 | |
---|---|
retry_transaction |
要重試的選擇性交易。 |
UpdateDocumentRequest
欄位 | |
---|---|
document |
必要欄位。更新的文件。如果文件不存在,會建立文件。 |
update_mask |
要更新的欄位。遮罩中沒有任何欄位路徑可能包含保留名稱。 如果文件存在於伺服器上,且遮罩中有未參照的欄位,則文件會維持不變。遮罩中參照的欄位,但輸入文件中沒有該欄位,系統會從伺服器上的文件刪除這些欄位。 |
mask |
要傳回的欄位。如果沒有設定,系統會傳回所有欄位。 如果文件的某個欄位未列於這個遮罩中,系統不會在回應中傳回該欄位。 |
current_document |
文件上的選用先決條件。如果已設定此設定,但未為目標文件達成,要求就會失敗。 |
值
可容納任何支援值類型的訊息。
欄位 | |
---|---|
聯集欄位 value_type 。必須設定值。value_type 只能是下列其中一項: |
|
null_value |
空值。 |
boolean_value |
布林值。 |
integer_value |
整數值。 |
double_value |
雙值。 |
timestamp_value |
時間戳記值。 僅具備微秒的精確度。儲存之後,其他精確度會無條件捨去至整數。 |
string_value |
字串值。 以 UTF-8 表示的字串不得超過 1 MiB 到 89 個位元組。查詢只會考量 UTF-8 表示法的前 1,500 個位元組。 |
bytes_value |
位元組值。 不得超過 1 MiB 至 89 個位元組。查詢只會考量前 1,500 個位元組。 |
reference_value |
文件的參照。例如 |
geo_point_value |
代表地球表面上的點的地理點值。 |
array_value |
陣列值。 不能直接包含其他陣列值,但可包含包含其他陣列的地圖。 |
map_value |
對應值。 |
撰寫
在文件上寫字。
欄位 | |
---|---|
update_mask |
要在這項寫入作業中更新的欄位。 這個欄位只有在作業為 |
update_transforms[] |
更新後要執行的轉換。 這個欄位只有在作業為 |
current_document |
文件上的選用先決條件。 如果未設定,但目標文件並未達成,寫入作業就會失敗。 |
聯集欄位 operation 。要執行的作業。operation 只能是下列其中一項: |
|
update |
要寫入的文件。 |
delete |
要刪除的文件名稱。請採用下列格式: |
transform |
將轉換套用至文件。 |
WriteRequest
Firestore.Write
的要求。
第一個要求會建立串流,或者透過權杖繼續執行現有串流。
建立新串流時,伺服器會回覆只包含一個 ID 和符記的回應,以便在下一個要求中使用。
繼續串流時,伺服器會先串流比指定權杖以後的回應,再串流僅包含最新權杖的回應,以便在下一個要求中使用。
欄位 | |
---|---|
database |
必要欄位。資料庫名稱。請採用下列格式: |
stream_id |
要繼續執行的寫入串流 ID。這只會在第一則訊息中設定。如果留空,系統會建立新的寫入串流。 |
writes[] |
要套用的寫入內容。 一律會依序執行。第一個要求必須留空。最後一個要求可能會空白。其他要求一律不得留空。 |
stream_token |
伺服器先前傳送的串流權杖。 用戶端應將這個欄位設為從收到的最新 如果發生太多未確認的回應,伺服器可能會關閉串流。 建立新的串流時,請不要設定這個欄位。如要在特定時間點繼續串流,請設定這個欄位和 建立新的串流時,請不要設定這個欄位。 |
labels |
與這項寫入要求相關聯的標籤。 |
WriteResponse
Firestore.Write
的回應。
欄位 | |
---|---|
stream_id |
串流的 ID。只有在建立新串流時,才會設定第一則訊息。 |
stream_token |
代表此回應在串流中位置的權杖。此時,用戶端可使用這個參數繼續串流。 系統一律會設定這個欄位。 |
write_results[] |
套用寫入的結果。 這個 i-th 寫入結果對應要求中的第 i 次寫入。 |
commit_time |
修訂版本發生的時間。任何具有等於或大於 |
WriteResult
套用寫入的結果。
欄位 | |
---|---|
update_time |
套用寫入後的文件上次更新時間。不會在 如果寫入內容實際上並未變更文件,這會是先前的 update_time。 |
transform_results[] |
按相同順序套用各個 |