documents

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

Overview

Name	documents
Type	Resource
Id	google.firestore.documents

Fields

The following fields are returned by SELECT queries:

list

Name	Datatype	Description
name	string	The resource name of the document, for example projects/{project_id}/databases/{database_id}/documents/{document_path}.
createTime	string (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.
fields	object	The 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.
updateTime	string (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.

get

Name	Datatype	Description
name	string	The resource name of the document, for example projects/{project_id}/databases/{database_id}/documents/{document_path}.
createTime	string (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.
fields	object	The 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.
updateTime	string (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.

list_documents

Name	Datatype	Description
name	string	The resource name of the document, for example projects/{project_id}/databases/{database_id}/documents/{document_path}.
createTime	string (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.
fields	object	The 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.
updateTime	string (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.

listen

Name	Datatype	Description
documentChange	object	A Document has changed. (id: DocumentChange)
documentDelete	object	A Document has been deleted. (id: DocumentDelete)
documentRemove	object	A Document has been removed from a target (because it is no longer relevant to that target). (id: DocumentRemove)
filter	object	A filter to apply to the set of documents previously returned for the given target. Returned when documents may have been removed from the given target, but the exact documents are unknown. (id: ExistenceFilter)
targetChange	object	Targets have changed. (id: TargetChange)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	projectsId, databasesId, documentsId, documentsId1, collectionId	mask.fieldPaths, orderBy, pageSize, pageToken, readTime, recursive, requestOptions.requestTags, showMissing, transaction	Lists documents.
get	select	projectsId, databasesId, documentsId, documentsId1	mask.fieldPaths, readTime, requestOptions.requestTags, transaction	Gets a single document.
list_documents	select	projectsId, databasesId, collectionId	mask.fieldPaths, orderBy, pageSize, pageToken, readTime, recursive, requestOptions.requestTags, showMissing, transaction	Lists documents.
listen	select	projectsId, databasesId		Listens to changes. This method is only available via gRPC or WebChannel (not REST).
create_document	insert	projectsId, databasesId, documentsId, collectionId	documentId, mask.fieldPaths, requestOptions.requestTags	Creates a new document.
patch	update	projectsId, databasesId, documentsId, documentsId1	currentDocument.exists, currentDocument.updateTime, mask.fieldPaths, requestOptions.requestTags, updateMask.fieldPaths	Updates or inserts a document.
delete	delete	projectsId, databasesId, documentsId, documentsId1	currentDocument.exists, currentDocument.updateTime, requestOptions.requestTags	Deletes a document.
batch_get	exec	projectsId, databasesId		Gets multiple documents. Documents returned by this method are not guaranteed to be returned in the same order that they were requested.
batch_write	exec	projectsId, databasesId		Applies 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.
begin_transaction	exec	projectsId, databasesId		Starts a new transaction.
commit	exec	projectsId, databasesId		Commits a transaction, while optionally updating documents.
execute_pipeline	exec	projectsId, databasesId		Executes a pipeline query.
partition_query	exec	projectsId, databasesId, documentsId, documentsId1		Partitions 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.
rollback	exec	projectsId, databasesId		Rolls back a transaction.
run_aggregation_query	exec	projectsId, databasesId, documentsId, documentsId1		Runs 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 );
run_query	exec	projectsId, databasesId, documentsId, documentsId1		Runs a query.
write	exec	projectsId, databasesId		Streams batches of document updates and deletes, in order. This method is only available via gRPC or WebChannel (not REST).

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.

Name	Datatype	Description
collectionId	string
databasesId	string
documentsId	string
documentsId1	string
projectsId	string
currentDocument.exists	boolean
currentDocument.updateTime	string (google-datetime)
documentId	string
mask.fieldPaths	string
orderBy	string
pageSize	integer (int32)
pageToken	string
readTime	string (google-datetime)
recursive	boolean
requestOptions.requestTags	string
showMissing	boolean
transaction	string (byte)
updateMask.fieldPaths	string

SELECT examples

list

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 mask.fieldPaths = '{{ mask.fieldPaths }}'
AND orderBy = '{{ orderBy }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND readTime = '{{ readTime }}'
AND recursive = '{{ recursive }}'
AND requestOptions.requestTags = '{{ requestOptions.requestTags }}'
AND showMissing = '{{ showMissing }}'
AND transaction = '{{ transaction }}'
;

get

Gets a single document.

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 mask.fieldPaths = '{{ mask.fieldPaths }}'
AND readTime = '{{ readTime }}'
AND requestOptions.requestTags = '{{ requestOptions.requestTags }}'
AND transaction = '{{ transaction }}'
;

list_documents

Lists documents.

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

listen

Listens to changes. This method is only available via gRPC or WebChannel (not REST).

SELECT
documentChange,
documentDelete,
documentRemove,
filter,
targetChange
FROM google.firestore.documents
WHERE projectsId = '{{ projectsId }}' -- required
AND databasesId = '{{ databasesId }}' -- required
;

INSERT examples

create_document

Creates a new document.

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

Manifest

# Description fields are for documentation purposes
- name: documents
props:
  - name: projectsId
    value: "{{ projectsId }}"
    description: Required parameter for the documents resource.
  - name: databasesId
    value: "{{ databasesId }}"
    description: Required parameter for the documents resource.
  - name: documentsId
    value: "{{ documentsId }}"
    description: Required parameter for the documents resource.
  - name: collectionId
    value: "{{ collectionId }}"
    description: Required parameter for the documents resource.
  - name: createTime
    value: "{{ createTime }}"
    description: |
      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.
  - name: fields
    value: "{{ fields }}"
    description: |
      The 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 ``.
  - name: name
    value: "{{ name }}"
    description: |
      The resource name of the document, for example `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
  - name: updateTime
    value: "{{ updateTime }}"
    description: |
      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.
  - name: documentId
    value: "{{ documentId }}"
  - name: mask.fieldPaths
    value: "{{ mask.fieldPaths }}"
  - name: requestOptions.requestTags
    value: "{{ requestOptions.requestTags }}"

UPDATE examples

patch

Updates or inserts a document.

UPDATE google.firestore.documents
SET 
data__createTime = '{{ createTime }}',
data__fields = '{{ fields }}',
data__name = '{{ name }}',
data__updateTime = '{{ updateTime }}'
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}}'
AND mask.fieldPaths = '{{ mask.fieldPaths}}'
AND requestOptions.requestTags = '{{ requestOptions.requestTags}}'
AND updateMask.fieldPaths = '{{ updateMask.fieldPaths}}'
RETURNING
name,
createTime,
fields,
updateTime;

DELETE examples

delete

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 }}'
AND requestOptions.requestTags = '{{ requestOptions.requestTags }}'
;

Lifecycle Methods

batch_get

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 }}", 
"newTransaction": "{{ newTransaction }}", 
"readTime": "{{ readTime }}", 
"requestOptions": "{{ requestOptions }}", 
"transaction": "{{ transaction }}"
}'
;

batch_write

Applies 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.

EXEC google.firestore.documents.batch_write 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"labels": "{{ labels }}", 
"requestOptions": "{{ requestOptions }}", 
"writes": "{{ writes }}"
}'
;

begin_transaction

Starts a new transaction.

EXEC google.firestore.documents.begin_transaction 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"options": "{{ options }}", 
"requestOptions": "{{ requestOptions }}"
}'
;

commit

Commits a transaction, while optionally updating documents.

EXEC google.firestore.documents.commit 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"requestOptions": "{{ requestOptions }}", 
"transaction": "{{ transaction }}", 
"writes": "{{ writes }}"
}'
;

execute_pipeline

Executes a pipeline query.

EXEC google.firestore.documents.execute_pipeline 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"autoCommitTransaction": {{ autoCommitTransaction }}, 
"newTransaction": "{{ newTransaction }}", 
"readTime": "{{ readTime }}", 
"requestOptions": "{{ requestOptions }}", 
"structuredPipeline": "{{ structuredPipeline }}", 
"transaction": "{{ transaction }}"
}'
;

partition_query

Partitions 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.

EXEC google.firestore.documents.partition_query 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required, 
@documentsId='{{ documentsId }}' --required, 
@documentsId1='{{ documentsId1 }}' --required 
@@json=
'{
"pageSize": {{ pageSize }}, 
"pageToken": "{{ pageToken }}", 
"partitionCount": "{{ partitionCount }}", 
"readTime": "{{ readTime }}", 
"requestOptions": "{{ requestOptions }}", 
"structuredQuery": "{{ structuredQuery }}"
}'
;

rollback

Rolls back a transaction.

EXEC google.firestore.documents.rollback 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"requestOptions": "{{ requestOptions }}", 
"transaction": "{{ transaction }}"
}'
;

run_aggregation_query

Runs 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 );

EXEC google.firestore.documents.run_aggregation_query 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required, 
@documentsId='{{ documentsId }}' --required, 
@documentsId1='{{ documentsId1 }}' --required 
@@json=
'{
"explainOptions": "{{ explainOptions }}", 
"newTransaction": "{{ newTransaction }}", 
"readTime": "{{ readTime }}", 
"requestOptions": "{{ requestOptions }}", 
"structuredAggregationQuery": "{{ structuredAggregationQuery }}", 
"transaction": "{{ transaction }}"
}'
;

run_query

Runs a query.

EXEC google.firestore.documents.run_query 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required, 
@documentsId='{{ documentsId }}' --required, 
@documentsId1='{{ documentsId1 }}' --required 
@@json=
'{
"explainOptions": "{{ explainOptions }}", 
"newTransaction": "{{ newTransaction }}", 
"readTime": "{{ readTime }}", 
"requestOptions": "{{ requestOptions }}", 
"structuredQuery": "{{ structuredQuery }}", 
"transaction": "{{ transaction }}"
}'
;

write

Streams batches of document updates and deletes, in order. This method is only available via gRPC or WebChannel (not REST).

EXEC google.firestore.documents.write 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"labels": "{{ labels }}", 
"requestOptions": "{{ requestOptions }}", 
"streamId": "{{ streamId }}", 
"streamToken": "{{ streamToken }}", 
"writes": "{{ writes }}"
}'
;