{"id":1494,"library":"google-cloud-datastore","title":"Google Cloud Datastore","description":"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.","status":"active","version":"2.24.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-datastore","tags":["google-cloud","datastore","nosql","database","gcp"],"install":[{"cmd":"pip install google-cloud-datastore","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"The Client class is typically accessed via the top-level 'datastore' module.","symbol":"Client","correct":"from google.cloud import datastore"}],"quickstart":{"code":"import os\nfrom google.cloud import datastore\n\n# Your Google Cloud Project ID. Set as environment variable GOOGLE_CLOUD_PROJECT or replace 'your-project-id'.\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id') \n\n# Instantiates a client\nclient = datastore.Client(project=project_id)\n\n# The kind for the new entity\nkind = 'Task'\n# The name/ID for the new entity\nname = 'sampletask1'\n# The Cloud Datastore key for the new entity\ntask_key = client.key(kind, name)\n\n# Prepares the new entity\ntask = datastore.Entity(key=task_key)\ntask['description'] = 'Buy groceries'\ntask['priority'] = 5\ntask['done'] = False\n\n# Saves the entity\nclient.put(task)\nprint(f\"Saved {task.key.name}: {task['description']}\")\n\n# Query for entities of kind 'Task'\nquery = client.query(kind=kind)\nresults = list(query.fetch())\n\nprint('\\nEntities found:')\nfor entity in results:\n    print(f\"  Key: {entity.key.name}, Description: {entity['description']}, Done: {entity['done']}\")","lang":"python","description":"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`)."},"warnings":[{"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.","message":"Authentication 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).","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Always initialize `datastore.Client()` with the `project` argument or set the `GOOGLE_CLOUD_PROJECT` environment variable.","message":"The `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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Review the Datastore documentation on indexes and ensure all necessary composite indexes for your queries are defined and deployed.","message":"Complex 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Queries 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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Verify whether your project uses Datastore or Firestore Native mode and install the appropriate client library (`google-cloud-datastore` vs `google-cloud-firestore`).","message":"This 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}