Skip to content

Query Reference

Query builder for the Google Cloud Datastore ODM.

This module is structured into three layers: 1. AST Nodes: Simple objects that represent filter/order logic. 2. Logic Functions: Global AND/OR helpers to group Nodes. 3. Query Engine: The main class that translates Nodes into Datastore SDK calls.

Node

Base query node. Supports bitwise style: (Prop == x) & (Prop == y).

FilterNode(name, op, value)

Bases: Node

Stores the name, operator, and value of a single filter.

CompositeNode(op, filters)

Bases: Node

Stores a collection of nodes joined by logical and/or operators.

OrderNode(name, descending)

Stores sort direction for a property.

Query(model_cls, project=None, database=None, namespace=None)

projection(*args)

Sets the projection fields for the query.

distinct_on(*args)

Sets the distinct_on fields for the query.

keys_only()

Marks the query to return only Datastore Keys.

filter(*args)

Adds filters to the query. Supports both Node objects and raw strings.

order(*args)

Adds ordering. Accepts -Prop, Prop, or raw strings.

fetch(limit=None)

Yields hydrated Model instances (or Keys) from the Datastore.

fetch_page(page_size, start_cursor=None)

Fetches a specific page of results, returning metadata needed for pagination.

Returns:

Type Description
List[Union[Model, Any]]

Tuple containing:
Optional[bytes]
  • A list of hydrated Model instances (or Keys)
bool
  • The cursor bytes to fetch the next page (or None)
tuple[List[Union[Model, Any]], Optional[bytes], bool]
  • A boolean indicating if there are more results

get()

Executes the query and returns the first matching Model instance, or None if no results are found.

count()

Performs a server-side count aggregation (very fast).

sum(property_field)

Performs a fast server-side sum aggregation on a specific property.

avg(property_field)

Performs a fast server-side average aggregation on a specific property.

aggregate(**kwargs)

Performs multiple aggregations in a single Datastore RPC call.

Parameters:

Name Type Description Default
**kwargs Union[CountAggregation, SumAggregation, AvgAggregation]

Alias names mapped to Aggregation objects (Count, Sum, or Avg).

 {}

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: A dictionary mapping your aliases to their aggregated values.

and_(*filters)

Combines filters with AND logic.

or_(*filters)

Combines filters with OR logic.