databases

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

Overview

Name	databases
Type	Resource
Id	google.firestore.databases

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	The resource name of the Database. Format: projects/{project}/databases/{database}
appEngineIntegrationMode	string	The App Engine integration mode to use for this database.
cmekConfig	object	Optional. Presence indicates CMEK is enabled for this database. (id: GoogleFirestoreAdminV1CmekConfig)
concurrencyMode	string	The concurrency control mode to use for this database.
createTime	string (google-datetime)	Output only. The timestamp at which this database was created. Databases created before 2016 do not populate create_time.
databaseEdition	string	Immutable. The edition of the database.
deleteProtectionState	string	State of delete protection for the database.
deleteTime	string (google-datetime)	Output only. The timestamp at which this database was deleted. Only set if the database has been deleted.
earliestVersionTime	string (google-datetime)	Output only. The earliest timestamp at which older versions of the data can be read from the database. See [version_retention_period] above; this field is populated with now - version_retention_period. This value is continuously updated, and becomes stale the moment it is queried. If you are using this value to recover data, make sure to account for the time from the moment when the value is queried to the moment when you initiate the recovery.
etag	string	This checksum is computed by the server based on the value of other fields, and may be sent on update and delete requests to ensure the client has an up-to-date value before proceeding.
freeTier	boolean	Output only. Background: Free tier is the ability of a Firestore database to use a small amount of resources every day without being charged. Once usage exceeds the free tier limit further usage is charged. Whether this database can make use of the free tier. Only one database per project can be eligible for the free tier. The first (or next) database that is created in a project without a free tier database will be marked as eligible for the free tier. Databases that are created while there is a free tier database will not be eligible for the free tier.
keyPrefix	string	Output only. The key_prefix for this database. This key_prefix is used, in combination with the project ID ("") to construct the application ID that is returned from the Cloud Datastore APIs in Google App Engine first generation runtimes. This value may be empty in which case the appid to use for URL-encoded keys is the project_id (eg: foo instead of vfoo).
locationId	string	The location of the database. Available locations are listed at https://cloud.google.com/firestore/docs/locations.
pointInTimeRecoveryEnablement	string	Whether to enable the PITR feature on this database.
previousId	string	Output only. The database resource's prior database ID. This field is only populated for deleted databases.
sourceInfo	object	Output only. Information about the provenance of this database. (id: GoogleFirestoreAdminV1SourceInfo)
tags	object	Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing"
type	string	The type of the database. See https://cloud.google.com/datastore/docs/firestore-or-datastore for information about how to choose.
uid	string	Output only. The system-generated UUID4 for this Database.
updateTime	string (google-datetime)	Output only. The timestamp at which this database was most recently updated. Note this only includes updates to the database resource and not data contained by the database.
versionRetentionPeriod	string (google-duration)	Output only. The period during which past versions of data are retained in the database. Any read or query can specify a read_time within this window, and will read the state of the database at that time. If the PITR feature is enabled, the retention period is 7 days. Otherwise, the retention period is 1 hour.

list

Successful response

Name	Datatype	Description
databases	array	The databases in the project.
unreachable	array	In the event that data about individual databases cannot be listed they will be recorded here. An example entry might be: projects/some_project/locations/some_location This can happen if the Cloud Region that the Database resides in is currently unavailable. In this case we can't fetch all the details about the database. You may be able to get a more detailed error message (or possibly fetch the resource) by sending a 'Get' request for the resource or a 'List' request for the specific location.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, databasesId		Gets information about a database.
list	select	projectsId	showDeleted	List all the databases in the project.
create	insert	projectsId	databaseId	Create a database.
patch	update	projectsId, databasesId	updateMask	Updates a database.
bulk_delete_documents	delete	projectsId, databasesId		Bulk deletes a subset of documents from Google Cloud Firestore. Documents created or updated after the underlying system starts to process the request will not be deleted. The bulk delete occurs in the background and its progress can be monitored and managed via the Operation resource that is created. For more details on bulk delete behavior, refer to: https://cloud.google.com/firestore/docs/manage-data/bulk-delete
delete	delete	projectsId, databasesId	etag	Deletes a database.
export_documents	exec	projectsId, databasesId		Exports a copy of all or a subset of documents from Google Cloud Firestore to another storage system, such as Google Cloud Storage. Recent updates to documents may not be reflected in the export. The export occurs in the background and its progress can be monitored and managed via the Operation resource that is created. The output of an export may only be used once the associated operation is done. If an export operation is cancelled before completion it may leave partial data behind in Google Cloud Storage. For more details on export behavior and output format, refer to: https://cloud.google.com/firestore/docs/manage-data/export-import
import_documents	exec	projectsId, databasesId		Imports documents into Google Cloud Firestore. Existing documents with the same name are overwritten. The import occurs in the background and its progress can be monitored and managed via the Operation resource that is created. If an ImportDocuments operation is cancelled, it is possible that a subset of the data has already been imported to Cloud Firestore.
restore	exec	projectsId		Creates a new database by restoring from an existing backup. The new database must be in the same cloud region or multi-region location as the existing backup. This behaves similar to FirestoreAdmin.CreateDatabase except instead of creating a new empty database, a new database is created with the database type, index configuration, and documents from an existing backup. The long-running operation can be used to track the progress of the restore, with the Operation's metadata field type being the RestoreDatabaseMetadata. The response type is the Database if the restore was successful. The new database is not readable or writeable until the LRO has completed.
clone	exec	projectsId		Creates a new database by cloning an existing one. The new database must be in the same cloud region or multi-region location as the existing database. This behaves similar to FirestoreAdmin.CreateDatabase except instead of creating a new empty database, a new database is created with the database type, index configuration, and documents from an existing database. The long-running operation can be used to track the progress of the clone, with the Operation's metadata field type being the CloneDatabaseMetadata. The response type is the Database if the clone was successful. The new database is not readable or writeable until the LRO has completed.

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
databasesId	string
projectsId	string
databaseId	string
etag	string
showDeleted	boolean
updateMask	string (google-fieldmask)

SELECT examples

get

Gets information about a database.

SELECT
name,
appEngineIntegrationMode,
cmekConfig,
concurrencyMode,
createTime,
databaseEdition,
deleteProtectionState,
deleteTime,
earliestVersionTime,
etag,
freeTier,
keyPrefix,
locationId,
pointInTimeRecoveryEnablement,
previousId,
sourceInfo,
tags,
type,
uid,
updateTime,
versionRetentionPeriod
FROM google.firestore.databases
WHERE projectsId = '{{ projectsId }}' -- required
AND databasesId = '{{ databasesId }}' -- required;

list

List all the databases in the project.

SELECT
databases,
unreachable
FROM google.firestore.databases
WHERE projectsId = '{{ projectsId }}' -- required
AND showDeleted = '{{ showDeleted }}';

INSERT examples

create

Create a database.

INSERT INTO google.firestore.databases (
data__name,
data__locationId,
data__type,
data__concurrencyMode,
data__pointInTimeRecoveryEnablement,
data__appEngineIntegrationMode,
data__deleteProtectionState,
data__cmekConfig,
data__tags,
data__etag,
data__databaseEdition,
projectsId,
databaseId
)
SELECT 
'{{ name }}',
'{{ locationId }}',
'{{ type }}',
'{{ concurrencyMode }}',
'{{ pointInTimeRecoveryEnablement }}',
'{{ appEngineIntegrationMode }}',
'{{ deleteProtectionState }}',
'{{ cmekConfig }}',
'{{ tags }}',
'{{ etag }}',
'{{ databaseEdition }}',
'{{ projectsId }}',
'{{ databaseId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: databases
  props:
    - name: projectsId
      value: string
      description: Required parameter for the databases resource.
    - name: name
      value: string
      description: >
        The resource name of the Database. Format: `projects/{project}/databases/{database}`
        
    - name: locationId
      value: string
      description: >
        The location of the database. Available locations are listed at https://cloud.google.com/firestore/docs/locations.
        
    - name: type
      value: string
      description: >
        The type of the database. See https://cloud.google.com/datastore/docs/firestore-or-datastore for information about how to choose.
        
      valid_values: ['DATABASE_TYPE_UNSPECIFIED', 'FIRESTORE_NATIVE', 'DATASTORE_MODE']
    - name: concurrencyMode
      value: string
      description: >
        The concurrency control mode to use for this database.
        
      valid_values: ['CONCURRENCY_MODE_UNSPECIFIED', 'OPTIMISTIC', 'PESSIMISTIC', 'OPTIMISTIC_WITH_ENTITY_GROUPS']
    - name: pointInTimeRecoveryEnablement
      value: string
      description: >
        Whether to enable the PITR feature on this database.
        
      valid_values: ['POINT_IN_TIME_RECOVERY_ENABLEMENT_UNSPECIFIED', 'POINT_IN_TIME_RECOVERY_ENABLED', 'POINT_IN_TIME_RECOVERY_DISABLED']
    - name: appEngineIntegrationMode
      value: string
      description: >
        The App Engine integration mode to use for this database.
        
      valid_values: ['APP_ENGINE_INTEGRATION_MODE_UNSPECIFIED', 'ENABLED', 'DISABLED']
    - name: deleteProtectionState
      value: string
      description: >
        State of delete protection for the database.
        
      valid_values: ['DELETE_PROTECTION_STATE_UNSPECIFIED', 'DELETE_PROTECTION_DISABLED', 'DELETE_PROTECTION_ENABLED']
    - name: cmekConfig
      value: object
      description: >
        Optional. Presence indicates CMEK is enabled for this database.
        
    - name: tags
      value: object
      description: >
        Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing"
        
    - name: etag
      value: string
      description: >
        This checksum is computed by the server based on the value of other fields, and may be sent on update and delete requests to ensure the client has an up-to-date value before proceeding.
        
    - name: databaseEdition
      value: string
      description: >
        Immutable. The edition of the database.
        
      valid_values: ['DATABASE_EDITION_UNSPECIFIED', 'STANDARD', 'ENTERPRISE']
    - name: databaseId
      value: string

UPDATE examples

patch

Updates a database.

UPDATE google.firestore.databases
SET 
data__name = '{{ name }}',
data__locationId = '{{ locationId }}',
data__type = '{{ type }}',
data__concurrencyMode = '{{ concurrencyMode }}',
data__pointInTimeRecoveryEnablement = '{{ pointInTimeRecoveryEnablement }}',
data__appEngineIntegrationMode = '{{ appEngineIntegrationMode }}',
data__deleteProtectionState = '{{ deleteProtectionState }}',
data__cmekConfig = '{{ cmekConfig }}',
data__tags = '{{ tags }}',
data__etag = '{{ etag }}',
data__databaseEdition = '{{ databaseEdition }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND databasesId = '{{ databasesId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

bulk_delete_documents

Bulk deletes a subset of documents from Google Cloud Firestore. Documents created or updated after the underlying system starts to process the request will not be deleted. The bulk delete occurs in the background and its progress can be monitored and managed via the Operation resource that is created. For more details on bulk delete behavior, refer to: https://cloud.google.com/firestore/docs/manage-data/bulk-delete

DELETE FROM google.firestore.databases
WHERE projectsId = '{{ projectsId }}' --required
AND databasesId = '{{ databasesId }}' --required;

delete

Deletes a database.

DELETE FROM google.firestore.databases
WHERE projectsId = '{{ projectsId }}' --required
AND databasesId = '{{ databasesId }}' --required
AND etag = '{{ etag }}';

Lifecycle Methods

export_documents

Exports a copy of all or a subset of documents from Google Cloud Firestore to another storage system, such as Google Cloud Storage. Recent updates to documents may not be reflected in the export. The export occurs in the background and its progress can be monitored and managed via the Operation resource that is created. The output of an export may only be used once the associated operation is done. If an export operation is cancelled before completion it may leave partial data behind in Google Cloud Storage. For more details on export behavior and output format, refer to: https://cloud.google.com/firestore/docs/manage-data/export-import

EXEC google.firestore.databases.export_documents 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"collectionIds": "{{ collectionIds }}", 
"outputUriPrefix": "{{ outputUriPrefix }}", 
"namespaceIds": "{{ namespaceIds }}", 
"snapshotTime": "{{ snapshotTime }}"
}';

import_documents

Imports documents into Google Cloud Firestore. Existing documents with the same name are overwritten. The import occurs in the background and its progress can be monitored and managed via the Operation resource that is created. If an ImportDocuments operation is cancelled, it is possible that a subset of the data has already been imported to Cloud Firestore.

EXEC google.firestore.databases.import_documents 
@projectsId='{{ projectsId }}' --required, 
@databasesId='{{ databasesId }}' --required 
@@json=
'{
"collectionIds": "{{ collectionIds }}", 
"inputUriPrefix": "{{ inputUriPrefix }}", 
"namespaceIds": "{{ namespaceIds }}"
}';

restore

Creates a new database by restoring from an existing backup. The new database must be in the same cloud region or multi-region location as the existing backup. This behaves similar to FirestoreAdmin.CreateDatabase except instead of creating a new empty database, a new database is created with the database type, index configuration, and documents from an existing backup. The long-running operation can be used to track the progress of the restore, with the Operation's metadata field type being the RestoreDatabaseMetadata. The response type is the Database if the restore was successful. The new database is not readable or writeable until the LRO has completed.

EXEC google.firestore.databases.restore 
@projectsId='{{ projectsId }}' --required 
@@json=
'{
"databaseId": "{{ databaseId }}", 
"backup": "{{ backup }}", 
"encryptionConfig": "{{ encryptionConfig }}", 
"tags": "{{ tags }}"
}';

clone

Creates a new database by cloning an existing one. The new database must be in the same cloud region or multi-region location as the existing database. This behaves similar to FirestoreAdmin.CreateDatabase except instead of creating a new empty database, a new database is created with the database type, index configuration, and documents from an existing database. The long-running operation can be used to track the progress of the clone, with the Operation's metadata field type being the CloneDatabaseMetadata. The response type is the Database if the clone was successful. The new database is not readable or writeable until the LRO has completed.

EXEC google.firestore.databases.clone 
@projectsId='{{ projectsId }}' --required 
@@json=
'{
"databaseId": "{{ databaseId }}", 
"pitrSnapshot": "{{ pitrSnapshot }}", 
"encryptionConfig": "{{ encryptionConfig }}", 
"tags": "{{ tags }}"
}';