Registry / gcp / google-cloud-datastore

google-cloud-datastore

JSON →
library2.26.1pypypi✓ verified 30d ago

The `google-cloud-datastore` library is the official Python client for Google Cloud Datastore, a highly scalable NoSQL document database service. It provides APIs to store, query, and manage entities. This client also supports Firestore in Datastore mode. The current version is 2.24.0, and it follows the rapid release cadence of the broader `google-cloud-python` monorepo.

pip install google-cloud-datastore
INSTALL
IMPORT
SIG · GOOGLE-CLOUD-DATAS
G
google-cloud-datastore
gcppythonv2.26.1
Install
5.6s avg
Import
1486ms
Disk
69MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.26.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.764s · 70.8MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 5.6s · import 1.208s · 69MB
69MB installed
● package 69MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
✓ from google.cloud import datastore
The Client class is typically accessed via the top-level 'datastore' module.

This quickstart demonstrates how to instantiate a `Datastore` client, create an entity with a specific key, save it, and then query for entities of a given kind. Ensure your `GOOGLE_CLOUD_PROJECT` environment variable is set or replace `'your-project-id'` with your actual GCP Project ID, and that you have authentication configured (e.g., `GOOGLE_APPLICATION_CREDENTIALS`).

import os from google.cloud import datastore # Your Google Cloud Project ID. Set as environment variable GOOGLE_CLOUD_PROJECT or replace 'your-project-id'. project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id') # Instantiates a client client = datastore.Client(project=project_id) # The kind for the new entity kind = 'Task' # The name/ID for the new entity name = 'sampletask1' # The Cloud Datastore key for the new entity task_key = client.key(kind, name) # Prepares the new entity task = datastore.Entity(key=task_key) task['description'] = 'Buy groceries' task['priority'] = 5 task['done'] = False # Saves the entity client.put(task) print(f"Saved {task.key.name}: {task['description']}") # Query for entities of kind 'Task' query = client.query(kind=kind) results = list(query.fetch()) print('\nEntities found:') for entity in results: print(f" Key: {entity.key.name}, Description: {entity['description']}, Done: {entity['done']}")
Debug
Known issues
gotchaAuthentication is required. Applications typically authenticate using Application Default Credentials (ADC) by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file, or by running on a Google Cloud service with appropriate permissions (e.g., Compute Engine, Cloud Run).
fix
Ensure `GOOGLE_APPLICATION_CREDENTIALS` is set for local development, or use a service account with the `Datastore User` role (or equivalent) for deployed applications.
affects: >=2.0.0
gotchaThe `Datastore` client requires a project ID. While it can often be inferred from the environment, explicitly passing it to `datastore.Client(project='your-project-id')` or ensuring the `GOOGLE_CLOUD_PROJECT` environment variable is set avoids `google.api_core.exceptions.NotFound` or `DefaultCredentialsError` in ambiguous environments.
fix
Always initialize `datastore.Client()` with the `project` argument or set the `GOOGLE_CLOUD_PROJECT` environment variable.
affects: >=2.0.0
gotchaComplex queries (e.g., queries with multiple filters on different properties, filters and an order by clause, or inequality filters on different properties) require composite indexes to be defined. Failing to define these in `index.yaml` (or allowing automatic index management) will result in `google.api_core.exceptions.FailedPrecondition` errors at runtime.
fix
Review the Datastore documentation on indexes and ensure all necessary composite indexes for your queries are defined and deployed.
affects: >=2.0.0
gotchaQueries without an ancestor filter are eventually consistent by default, meaning that recently written data may not immediately appear in query results. If read-after-write consistency is crucial, consider using ancestor queries or transactional reads.
fix
For strong consistency, structure your data to allow ancestor queries (all related entities share a common root key) or perform reads within a transaction.
affects: >=2.0.0
gotchaThis library (`google-cloud-datastore`) specifically interacts with Google Cloud Datastore or Firestore in Datastore mode. If you intend to use Firestore in Native mode (which offers real-time updates and more flexible queries), you should use the `google-cloud-firestore` library instead, as their APIs are distinct.
fix
Verify whether your project uses Datastore or Firestore Native mode and install the appropriate client library (`google-cloud-datastore` vs `google-cloud-firestore`).
affects: All
Errors
Common errors & fixes
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.
The application cannot find valid Google Cloud credentials to authenticate with Datastore. This often happens when running locally without proper authentication setup.
fix
Run `gcloud auth application-default login` in your terminal to set up Application Default Credentials, or explicitly set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of a service account key file.
ModuleNotFoundError: No module named 'google.cloud'
The `google-cloud-datastore` library or its core `google-cloud` components are not installed in the Python environment where the code is being run, or there is an issue with the Python path.
fix
Ensure the library is installed in your active Python environment: `pip install google-cloud-datastore`.
403 Permission denied
The authenticated Google Cloud identity (user or service account) lacks the necessary IAM permissions (e.g., `roles/datastore.user`) to access the Datastore database in the specified project, or the Datastore API is not enabled for the project.
fix
Verify that the correct service account or user is being used, and ensure it has the `Cloud Datastore User` role (or equivalent custom role) on the project. Also, confirm that the Datastore API is enabled in the Google Cloud Console for your project.
rpc error: code = InvalidArgument desc = Inequality filter on X must also be a group by property when group by properties are set.
This error occurs when a Datastore query uses an inequality filter (e.g., `<`, `>`) on a property, and also uses `DistinctOn` or `OrderBy` on other properties, but the inequality-filtered property is not included in the `DistinctOn` or `OrderBy` clause. Datastore queries have specific limitations regarding inequality filters and ordering/grouping.
fix
Either include the property used in the inequality filter in all `DistinctOn` or `OrderBy` clauses, or remove `DistinctOn`/`OrderBy` clauses if they conflict with the inequality filter.
Errors indicating database not found or location not configured.
The Datastore database for the specified Google Cloud project has not been initialized, or its location has not been set in the Google Cloud Console. Datastore requires a database location to be configured before it can be used.
fix
Go to the Google Cloud Console, navigate to the Databases page (Datastore/Firestore in Datastore mode), and create or initialize the Datastore database, selecting a suitable location.
Upgrade
Version history
2.26.1latest on PyPI · released Aug 24, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
30 hits · last 30 days
node
22
OpenAI (training)
2
Resources
google-cloud-datastore — pip install google-cloud-datastore · libregistry