Skip to main content

documents

Creates, updates, deletes, gets or lists a documents resource.

Overview​

Namedocuments
TypeResource
Idgoogle.firestore.documents

Fields​

The following fields are returned by SELECT queries:

Successful response

NameDatatypeDescription
namestringThe resource name of the document, for example projects/{project_id}/databases/{database_id}/documents/{document_path}.
createTimestring (google-datetime)Output only. The time at which the document was created. This value increases monotonically when a document is deleted then recreated. It can also be compared to values from other documents and the read_time of a query.
fieldsobjectThe document's fields. The map keys represent field names. Field names matching the regular expression __.*__ are reserved. Reserved field names are forbidden except in certain documented contexts. The field names, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty. Field paths may be used in other contexts to refer to structured fields defined here. For map_value, the field path is represented by a dot-delimited (.) string of segments. Each segment is either a simple field name (defined below) or a quoted field name. For example, the structured field "foo" : { map_value: { "x&y" : { string_value: "hello" }}} would be represented by the field path foo.`x&y`. A simple field name contains only characters a to z, A to Z, 0 to 9, or _, and must not start with 0 to 9. For example, foo_bar_17. A quoted field name starts and ends with ` and may contain any character. Some characters, including `, must be escaped using a \. For example, `x&y` represents x&y and `bak\`tik` represents bak`tik.
updateTimestring (google-datetime)Output only. The time at which the document was last changed. This value is initially set to the create_time then increases monotonically with each change to the document. It can also be compared to values from other documents and the read_time of a query.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
listselectprojectsId, databasesId, documentsId, documentsId1, collectionIdpageSize, pageToken, orderBy, mask.fieldPaths, transaction, readTime, showMissingLists documents.
getselectprojectsId, databasesId, documentsId, documentsId1mask.fieldPaths, transaction, readTimeGets a single document.
list_documentsselectprojectsId, databasesId, collectionIdpageSize, pageToken, orderBy, mask.fieldPaths, transaction, readTime, showMissingLists documents.
listenselectprojectsId, databasesIdListens to changes. This method is only available via gRPC or WebChannel (not REST).
create_documentinsertprojectsId, databasesId, documentsId, collectionIddocumentId, mask.fieldPathsCreates a new document.
patchupdateprojectsId, databasesId, documentsId, documentsId1updateMask.fieldPaths, mask.fieldPaths, currentDocument.exists, currentDocument.updateTimeUpdates or inserts a document.
deletedeleteprojectsId, databasesId, documentsId, documentsId1currentDocument.exists, currentDocument.updateTimeDeletes a document.
batch_getexecprojectsId, databasesIdGets multiple documents. Documents returned by this method are not guaranteed to be returned in the same order that they were requested.
begin_transactionexecprojectsId, databasesIdStarts a new transaction.
commitexecprojectsId, databasesIdCommits a transaction, while optionally updating documents.
rollbackexecprojectsId, databasesIdRolls back a transaction.
run_queryexecprojectsId, databasesId, documentsId, documentsId1Runs a query.
run_aggregation_queryexecprojectsId, databasesId, documentsId, documentsId1Runs an aggregation query. Rather than producing Document results like Firestore.RunQuery, this API allows running an aggregation to produce a series of AggregationResult server-side. High-Level Example: -- Return the number of documents in table given a filter. SELECT COUNT(*) FROM ( SELECT * FROM k where a = true );
partition_queryexecprojectsId, databasesId, documentsId, documentsId1Partitions a query by returning partition cursors that can be used to run the query in parallel. The returned partition cursors are split points that can be used by RunQuery as starting/end points for the query results.
writeexecprojectsId, databasesIdStreams batches of document updates and deletes, in order. This method is only available via gRPC or WebChannel (not REST).
batch_writeexecprojectsId, databasesIdApplies a batch of write operations. The BatchWrite method does not apply the write operations atomically and can apply them out of order. Method does not allow more than one write per document. Each write succeeds or fails independently. See the BatchWriteResponse for the success status of each write. If you require an atomically applied set of writes, use Commit instead.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
collectionIdstring
databasesIdstring
documentsIdstring
documentsId1string
projectsIdstring
currentDocument.existsboolean
currentDocument.updateTimestring (google-datetime)
documentIdstring
mask.fieldPathsstring
orderBystring
pageSizeinteger (int32)
pageTokenstring
readTimestring (google-datetime)
showMissingboolean
transactionstring (byte)
updateMask.fieldPathsstring

SELECT examples​

Lists documents.

SELECT
name,
createTime,
fields,
updateTime
FROM google.firestore.documents
WHERE projectsId = '{{ projectsId }}' -- required
AND databasesId = '{{ databasesId }}' -- required
AND documentsId = '{{ documentsId }}' -- required
AND documentsId1 = '{{ documentsId1 }}' -- required
AND collectionId = '{{ collectionId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND orderBy = '{{ orderBy }}'
AND mask.fieldPaths = '{{ mask.fieldPaths }}'
AND transaction = '{{ transaction }}'
AND readTime = '{{ readTime }}'
AND showMissing = '{{ showMissing }}';

INSERT examples​

Creates a new document.

INSERT INTO google.firestore.documents (
data__name,
data__fields,
data__createTime,
data__updateTime,
projectsId,
databasesId,
documentsId,
collectionId,
documentId,
mask.fieldPaths
)
SELECT 
'{{ name }}',
'{{ fields }}',
'{{ createTime }}',
'{{ updateTime }}',
'{{ projectsId }}',
'{{ databasesId }}',
'{{ documentsId }}',
'{{ collectionId }}',
'{{ documentId }}',
'{{ mask.fieldPaths }}'
RETURNING
name,
createTime,
fields,
updateTime
;

UPDATE examples​

Updates or inserts a document.

UPDATE google.firestore.documents
SET 
data__name = '{{ name }}',
data__fields = '{{ fields }}',
data__createTime = '{{ createTime }}',
data__updateTime = '{{ updateTime }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND databasesId = '{{ databasesId }}' --required
AND documentsId = '{{ documentsId }}' --required
AND documentsId1 = '{{ documentsId1 }}' --required
AND updateMask.fieldPaths = '{{ updateMask.fieldPaths}}'
AND mask.fieldPaths = '{{ mask.fieldPaths}}'
AND currentDocument.exists = {{ currentDocument.exists}}
AND currentDocument.updateTime = '{{ currentDocument.updateTime}}'
RETURNING
name,
createTime,
fields,
updateTime;

DELETE examples​

Deletes a document.

DELETE FROM google.firestore.documents
WHERE projectsId = '{{ projectsId }}' --required
AND databasesId = '{{ databasesId }}' --required
AND documentsId = '{{ documentsId }}' --required
AND documentsId1 = '{{ documentsId1 }}' --required
AND currentDocument.exists = '{{ currentDocument.exists }}'
AND currentDocument.updateTime = '{{ currentDocument.updateTime }}';

Lifecycle Methods​

Gets multiple documents. Documents returned by this method are not guaranteed to be returned in the same order that they were requested.

EXEC google.firestore.documents.batch_get 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"documents": "{{ documents }}", 
"mask": "{{ mask }}", 
"transaction": "{{ transaction }}", 
"newTransaction": "{{ newTransaction }}", 
"readTime": "{{ readTime }}"
}';