Skip to content
Skills Library
Programming · Building & coding

query-handler

/query-handler

Define a Protean query handler, a class that answers queries by reading from projections and returning results. Query handlers are the read-side counterpart to command handlers: they use the @read decorator (not @handle), are dispatched via domain.dispatch(), and RETURN values. They run with no Unit of Work and no side effects. A handler is associated with a projection via part_of and reads through current_domain.view_for(Projection). Use when you need to answer a query, implement the read side of CQRS, return data from a projection, wire a query to a result, or when the user asks to "create a

Repository
protean ↗
Licence
Apache-2.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: assets/query_handler_simple.py

What it does and when to use it

Define a Protean query handler, a class that answers queries by reading from projections and returning results. Query handlers are the read-side counterpart to command handlers: they use the @read decorator (not @handle), are dispatched via domain.dispatch(), and RETURN values. They run with no Unit of Work and no side effects. A handler is associated with a projection via part_of and reads through current_domain.view_for(Projection). Use when you need to answer a query, implement the read side of CQRS, return data from a projection, wire a query to a result, or when the user asks to "create a

Original author description

Define a Protean query handler, a class that answers queries by reading from projections and returning results. Query handlers are the read-side counterpart to command handlers: they use the @read decorator (not @handle), are dispatched via domain.dispatch(), and RETURN values. They run with no Unit of Work and no side effects. A handler is associated with a projection via part_of and reads through current_domain.view_for(Projection). Use when you need to answer a query, implement the read side of CQRS, return data from a projection, wire a query to a result, or when the user asks to "create a

How it works

  1. Basic structure
  2. Key rules
  3. Quick example: Multiple queries
  4. Dispatching queries
  5. Reading through viewfor
  6. Common mistakes
  7. Detailed references
  8. Verify your work
Original SKILL.md headings · 126 lines, 508 words
SKILL.md preview
---
name: query-handler
description: 'Define a Protean query handler, a class that answers queries by reading from projections and returning results. Query handlers are the read-side counterpart to command handlers: they use the @read decorator (not @handle), are dispatched via domain.dispatch(), and RETURN values. They run with no Unit of Work and no side effects. A handler is associated with a projection via part_of and reads through current_domain.view_for(Projection). Use when you need to answer a query, implement the read side of CQRS, return data from a projection, wire a query to a result, or when the user asks to "create a query handler", "handle a query", "answer a read request", or "return data for a query". Each handler method is decorated with @read(QueryClass).'
license: Apache-2.0
compatibility: Requires Python 3.11+, protean framework
metadata:
  author: proteanhq
  version: "0.1"
  category: element
  diagnostic_codes:
    - QUERY_HANDLER_WITHOUT_QUERY
---

# Query Handler

A query handler answers queries: it receives a query DTO, reads from a projection, and **returns** the result. It is the read-side mirror of a command handler, but it uses `@read` instead of `@handle`, runs no Unit of Work, and always returns a value.

## Basic structure

```python
from protean import Domain, current_domain, read
from protean.fields import Identifier, String

domain = Domain()

@domain.projection
class OrderSummary:
    order_id: Identifier(identifier=True)
    status: String(max_length=20)

@domain.query(part_of="OrderSummary")
class GetOrderById:
    order_id: Identifier(required=True)

@domain.query_handler(part_of="OrderSummary")
class OrderQueryHandler:
    @read(GetOrderById)
    def get_by_id(self, query: GetOrderById):
        return current_domain.view_for(OrderSummary).get(query.order_id)
```

## Key rules

1. **part_of is the projection**: Associate the handler with the projection it reads: `@domain.query_handler(part_of="OrderSummary")` (the read model, not an aggregate)
2. **Use the `@read` decorator**: Each method is decorated `@read(QueryClass)` (the read-side counterpart to `@handle`); import it: `from protean import read`
3. **Handlers RETURN values**: A query handler always returns its result, unlike an event handler, which never returns a value to a caller; a command handler only returns one when processed synchronously. `domain.dispatch(query)` hands the query handler's result back to the caller
4. **One method per query**: Each query type is answered by exactly one `@read` method
5. **Method signature is `(self, query)`**: The dispatched query instance is passed in
6. **No Unit of Work, no side effects**: Reads are stateless; never mutate state or persist from a query handler
7. **Read through `view_for`**: Use `current_domain.view_for(Projection)` to get a read-only query interface: `.get(id)`, `.query.filter(...).all()`, `.count()`, `.exists(id)`
8. **Dispatch with `domain.dispatch(query)`**: This routes the query to its handler and returns the result (synchronous)

## Quick example: Multiple queries

```python
from protean import Domain, current_domain, read
from protean.fields import Identifier, String

domain = Domain()

@domain.projection
class OrderSummary:
    order_id: Identifier(identifier=True)
    status: String(max_length=20)

@domain.query(part_of="OrderSummary")
class GetOrderById:
    order_id: Identifier(required=True)

@domain.query(part_of="OrderSummary")
class ListOrdersByStatus:
    status: String(required=True)

@domain.query_handler(part_of="OrderSummary")
class OrderQueryHandler:
    @read(GetOrderById)
    def get_by_id(self, query: GetOrderById):
        return current_domain.view_for(OrderSummary).get(query.order_id)

    @read(ListOrdersByStatus)
    def list_by_status(self, query: ListOrdersByStatus):
        view = current_domain.view_for(OrderSummary)
        return view.query.filter(status=query.status).all().items
```

## Dispatching queries

```python
domain.init(traverse=False)

with domain.domain_context():
    domain.repository_for(OrderSummary).add(
        OrderSummary(order_id="ORD-1", status="placed")
    )

    # Returns the handler's return value directly (synchronous)
    order = domain.dispatch(GetOrderById(order_id="ORD-1"))
    placed = domain.dispatch(ListOrdersByStatus(status="placed"))
```

## Reading through view_for

`current_domain.view_for(Projection)` returns a read-only interface:

```python
with domain.domain_context():
    view = current_domain.view_for(OrderSummary)
    view.get("ORD-1")                                  # single record by id
    view.query.filter(status="placed").all().items     # filtered list
    view.query.filter(status="placed").count()         # flat count
    view.exists("ORD-1")                               # is there a record with this id?
```

## Common mistakes

### Query handler with no query to serve

A projection with a query handler but no `@domain.query(part_of=...)` registered for it has a read path nothing can invoke. `check` reports this as `QUERY_HANDLER_WITHOUT_QUERY`. Register a query for the handler to serve, or remove the query handler if the projection needs no read path.

## Detailed references

- [Anti-patterns](references/anti-patterns.md): Common mistakes and how to avoid them

### Complete examples

- [Simple Query Handler](assets/query_handler_simple.py): Projection, queries, handler, dispatch

### Related skills

- `query`: The read-intent DTO a handler answers
- `projection`: The read model the handler reads from
- `projector`: Populates the projection from domain events
- `command-handler`: The write-side counterpart (uses `@handle`, runs a UoW)

## Verify your work

- [Verify with check](../../references/verify-with-check.md): run `check` and resolve what it reports
Files in this package (3)
  • SKILL.md 6 KB
  • assets/query_handler_simple.py 2 KB
  • references/anti-patterns.md 2 KB

Versions

The database has no other skills named query-handler.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 048af7070223 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100query
    Define a Protean query, an immutable DTO representing a read intent against a projection (read model). Queries carry the parameters needed to fetch data on the read side of CQRS and are answered by query handlers via domain.dispatch(). Queries are associated with a projection…
  • 100command-handler
    Define a Protean command handler, a class responsible for receiving domain commands and orchestrating state changes in aggregates. Command handlers extract data from commands, load or create aggregates, invoke aggregate methods, and persist state changes. They are always…
  • 100projection-patterns
    Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.
  • 100projection-patterns
    Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.
  • 100projection-patterns
    Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.
  • 100projection-patterns
    Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.