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	pageToken, transaction, recursive, orderBy, showMissing, pageSize, mask.fieldPaths, readTime	Lists documents.
get	select	projectsId, databasesId, documentsId, documentsId1	mask.fieldPaths, transaction, readTime	Gets a single document.
list_documents	select	projectsId, databasesId, collectionId	showMissing, recursive, orderBy, transaction, pageToken, pageSize, mask.fieldPaths, readTime	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	Creates a new document.
patch	update	projectsId, databasesId, documentsId, documentsId1	currentDocument.updateTime, mask.fieldPaths, updateMask.fieldPaths, currentDocument.exists	Updates or inserts a document.
delete	delete	projectsId, databasesId, documentsId, documentsId1	currentDocument.updateTime, currentDocument.exists	Deletes a document.
begin_transaction	exec	projectsId, databasesId		Starts a new transaction.
write	exec	projectsId, databasesId		Streams batches of document updates and deletes, in order. This method is only available via gRPC or WebChannel (not REST).
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 );
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.
execute_pipeline	exec	projectsId, databasesId		Executes a pipeline query.
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.
run_query	exec	projectsId, databasesId, documentsId, documentsId1		Runs a query.
rollback	exec	projectsId, databasesId		Rolls back a transaction.
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.
commit	exec	projectsId, databasesId		Commits a transaction, while optionally updating documents.

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

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 transaction = '{{ transaction }}'
AND readTime = '{{ readTime }}'
;

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

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__name,
data__updateTime,
data__fields,
projectsId,
databasesId,
documentsId,
collectionId,
documentId,
mask.fieldPaths
)
SELECT 
'{{ createTime }}',
'{{ name }}',
'{{ updateTime }}',
'{{ fields }}',
'{{ projectsId }}',
'{{ databasesId }}',
'{{ documentsId }}',
'{{ collectionId }}',
'{{ documentId }}',
'{{ mask.fieldPaths }}'
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: 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: 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: documentId
    value: "{{ documentId }}"
  - name: mask.fieldPaths
    value: "{{ mask.fieldPaths }}"

UPDATE examples

patch

Updates or inserts a document.

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

Lifecycle Methods

begin_transaction

Starts a new transaction.

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

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 }}", 
"streamId": "{{ streamId }}", 
"streamToken": "{{ streamToken }}", 
"writes": "{{ writes }}"
}'
;

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

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=
'{
"partitionCount": "{{ partitionCount }}", 
"pageToken": "{{ pageToken }}", 
"structuredQuery": "{{ structuredQuery }}", 
"pageSize": {{ pageSize }}, 
"readTime": "{{ readTime }}"
}'
;

execute_pipeline

Executes a pipeline query.

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

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

run_query

Runs a query.

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

rollback

Rolls back a transaction.

EXEC google.firestore.documents.rollback 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"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=
'{
"writes": "{{ writes }}", 
"labels": "{{ labels }}"
}'
;

commit

Commits a transaction, while optionally updating documents.

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