{"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":"python","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,"search_vec":"'2.24.0':47 'also':37 'api':28 'broader':57 'cadenc':54 'client':14,36 'cloud':2,7,17,60,65 'current':44 'databas':24,68 'datastor':3,8,18,41,66 'document':23 'entiti':34 'firestor':39 'follow':50 'gcp':69 'googl':1,6,16,59,64 'google-cloud':63 'google-cloud-datastor':5 'google-cloud-python':58 'high':20 'librari':9 'manag':33 'mode':42 'monorepo':62 'nosql':22,67 'offici':12 'provid':27 'python':13,61 'queri':31 'rapid':52 'releas':53 'scalabl':21 'servic':25 'store':30 'support':38 'version':45","created_at":"2026-04-09T03:50:21.394786+00:00","updated_at":"2026-04-16T15:21:21.746018+00:00","problems":[{"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.","cause":"The application cannot find valid Google Cloud credentials to authenticate with Datastore. This often happens when running locally without proper authentication setup.","error":"google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials."},{"fix":"Ensure the library is installed in your active Python environment: `pip install google-cloud-datastore`.","cause":"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.","error":"ModuleNotFoundError: No module named 'google.cloud'"},{"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.","cause":"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.","error":"403 Permission denied"},{"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.","cause":"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.","error":"rpc error: code = InvalidArgument desc = Inequality filter on X must also be a group by property when group by properties are set."},{"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.","cause":"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.","error":"Errors indicating database not found or location not configured."}],"ecosystem":"pypi","meta_description":null,"install_score":95,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.26.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://cloud.google.com/datastore","github":"https://github.com/googleapis/google-cloud-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/google-cloud-datastore/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["gcp","database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}