Google Cloud Datastore

Warnings

• gotcha 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).
  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.
• gotcha 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.
  Fix: Always initialize `datastore.Client()` with the `project` argument or set the `GOOGLE_CLOUD_PROJECT` environment variable.
• gotcha 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.
  Fix: Review the Datastore documentation on indexes and ensure all necessary composite indexes for your queries are defined and deployed.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Verify whether your project uses Datastore or Firestore Native mode and install the appropriate client library (`google-cloud-datastore` vs `google-cloud-firestore`).

Install

• pip install google-cloud-datastore Install stable version

Imports

• Client

  from google.cloud import datastore

  The Client class is typically accessed via the top-level 'datastore' module.

Quickstart

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']}")