[Intermediate]: Create docs/sdk_developers/training/query.md

[exploreriii]

🧩 Intermediate Contributors

This issue is intended for contributors who already have some familiarity with the
Hiero Python SDK codebase and contribution workflow.

You should feel comfortable:

• navigating existing source code and examples
• understanding SDK concepts without step-by-step guidance
• following the standard PR workflow without additional onboarding

If this is your very first contribution to the project, we recommend starting with a few
Good First Issues before working on this one.

🐞 Problem Description

Query is a child to executable and a parent of queries in the hiero python sdk.

this means all queries use Query, which uses Executable.
Methods from executable are inherited to Query and that is inherited to the query request being done

Query is a really important file but we lack explanation of what it does and offers

We are not looking for perfection, but something better than we currently have.

💡 Expected Solution

create docs/sdk_developers/training/query.md
based from the contents in:
src/hiero_sdk_python/query/query.py
and
examples/query

The assignee will have to study the contents at
src/hiero_sdk_python/query/query.py
and
examples/query
to understand more about how query works and document that.

When writing query.md, you may want to refer to an example in examples/query.md, or, you may even want to create your own example at examples/query/query.md.

🧠 Implementation Notes

The Query class is the base class for all Hedera network queries. Queries allow you to request data from the Hedera network, such as account balances, transaction information, or token info. Unlike transactions, queries do not change the network state, but some may require a payment to execute.

Query inherits from _Executable, meaning it benefits from the unified execution engine, including:

• Automatic retries
• Node selection and rotation
• gRPC network call orchestration
• Logging and error handling
• Child query classes implement query-specific behavior while _Executable handles the underlying execution mechanics.

Key Concepts

1. Execution Flow

• When a Query is executed, the following steps happen:
• Pre-execution setup (_before_execute):
• Assigns nodes and operator
• Determines query payment if required
• Request building (_make_request):
• Constructs the Protobuf request for the network
• Includes payment transaction if required
• gRPC call (_get_method + _execute_method):
• Sends the request to a selected node
• Handles retries and backoff on temporary failures
• Response mapping (_map_response):
• Converts raw network response into a usable SDK object
• Retry handling (_should_retry):
• Automatically retries queries with retryable statuses like BUSY or PLATFORM_NOT_ACTIVE
• Error mapping (_map_status_error):
• Converts response errors into Python exceptions like PrecheckError or ReceiptStatusError

2. Query Payment

Some queries require a payment. Payment is handled via a small CryptoTransfer transaction attached to the query request.

Use set_query_payment(amount: Hbar) to override the default payment

If no payment is set, the SDK can automatically query the cost using get_cost(client) before executing the query

from hiero_sdk_python.hbar import Hbar

query = AccountBalanceQuery(account_id)
query.set_query_payment(Hbar(1)) # Set custom payment to 1 Hbar

The SDK constructs a signed payment transaction using the operator’s private key.

3. Abstract Methods
   Subclasses must implement several methods:

Method	Purpose
_get_query_response(response)	Extracts the specific query response from the full network response
_make_request()	Builds the Protobuf request for the specific query
_get_method(channel)	Returns the gRPC method wrapper (_Method) to call for this query

Method	Purpose
_map_response(response, node_id, proto_request)	Customize how the response is returned to the user
_should_retry(response)	Customize retry logic if needed
_map_status_error(response)	Customize error mapping

4. Retry Logic
   Queries automatically handle retries for certain network issues:

Retryable statuses:

• BUSY
• PLATFORM_TRANSACTION_NOT_CREATED
• PLATFORM_NOT_ACTIVE
• The base _should_retry implementation handles these, but subclasses can extend it if necessary.

5. Cost Queries

If a query requires payment but no amount is set, Query automatically fetches the cost from the network:
cost = query.get_cost(client)
print(f"Query cost: {cost} Hbar")
The SDK performs a COST_ANSWER query, returning the required Hbars to pay for the actual query.

6. Building a Child Query

eg

from hiero_sdk_python.query.query import Query
from hiero_sdk_python.hapi.services import query_pb2, crypto_get_account_balance_pb2

class AccountBalanceQuery(Query):
    def __init__(self, account_id):
        super().__init__()
        self.account_id = account_id

    def _make_request(self):
        header = self._make_request_header()
        body = crypto_get_account_balance_pb2.CryptoGetAccountBalanceQuery(
            header=header,
            accountID=self.account_id._to_proto()
        )
        return query_pb2.Query(cryptoGetAccountBalance=body)

    def _get_query_response(self, response):
        return response.cryptoGetAccountBalance

    def _get_method(self, channel):
        return _Method(query_func=channel.crypto.get_account_balance)

query = AccountBalanceQuery(my_account_id)
balance = query.execute(client)
print(f"Account balance: {balance.balance} Hbar")

7. Key Takeaways

Query handles all network-level logic; subclasses only implement query-specific behavior.

Queries may require payment, which is handled transparently via _build_query_payment_transaction.

Automatic retry and error handling ensures queries are robust against network issues.

Subclasses must implement:

_make_request()

_get_query_response()

_get_method()

You can override retry logic and response mapping if needed.

✅ Acceptance Criteria

To merge this issue, the pull request must:

• Fully address the problem described above
• Follow existing project conventions and patterns
• Include tests or example updates where appropriate
• Pass all CI checks
• Include a valid changelog entry
• Use DCO and GPG-signed commits

📚 Additional Context or Resources

• SDK Developer Docs
• SDK Developer Training

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Possible Duplicates

• ISSUE-910

Related Issues

• Create docs/sdk_developers/training/query.md #910
• Create docs/sdk_developers/training/executable.md #909
• [Advanced]: Prompt code rabbit on how to review src/hiero_sdk_python/query #1237

🔗 Related PRs

#1190 - feat: Added doc on how to create token transaction. [merged]

👤 Suggested Assignees

• exploreriii
• Adityarya11

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Create comprehensive training documentation for the Query class at docs/sdk_developers/training/query.md, explaining how Query serves as the base class for all Hedera network queries, its relationship with _Executable, and how developers build concrete query implementations.

Observations

The Hiero Python SDK uses a class hierarchy where _Executable provides the execution engine (retry logic, node selection, error handling), Query extends _Executable to add query-specific functionality (payment handling, cost calculation, response processing), and concrete query classes (AccountBalanceQuery, TokenInfoQuery, etc.) implement query-specific behavior. Training documentation follows established conventions: hierarchical markdown structure with Table of Contents, code examples with language tags, tables for method comparisons, and mermaid diagrams for class hierarchies. Existing training docs (executable.md, coding_token_transactions.md) emphasize practical implementation details with 9-13 code examples per document.

Assumptions

Assumption 1: Should the documentation include a new standalone example or reference existing examples?

Options Considered:

• Reference existing examples (particularly examples/query/payment_query.py for payment handling, examples/query/account_balance_query.py for basic patterns)
• Create a new simple example at examples/query/query_example.py specifically for training purposes

Chosen Option: Reference existing examples throughout the documentation

Rationale: The 12 existing query examples already demonstrate all key patterns comprehensively. This approach reduces duplication, maintains consistency with other training docs that reference existing examples, and is easier to maintain. The documentation should link to payment_query.py for payment/cost examples and account_balance_query.py for basic query patterns.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Create Query Training Documentation

Create comprehensive markdown documentation following the structure and style conventions established in existing training docs, particularly executable.md and coding_token_transactions.md.

Task 1: Set Up Document Structure and Introduction

Create docs/sdk_developers/training/query.md with hierarchical markdown structure including document title, Table of Contents with anchor links, and introduction section explaining Query's role in the SDK architecture.

• Add H1 title "Understanding the Query Class"
• Create Table of Contents section with anchor links to all major sections (Overview, Class Hierarchy, Execution Flow, Query Payment, Abstract Methods, Building Child Queries, etc.)
• Write introduction paragraph explaining Query as the base class for all Hedera network queries, its inheritance from _Executable, and how it adds query-specific functionality on top of the execution engine
• Include a mermaid diagram showing the class hierarchy: _Executable → Query → [Concrete Query Classes like AccountBalanceQuery, TokenInfoQuery]
• Follow the pattern from docs/sdk_developers/training/executable.md for diagram style and introduction structure

Task 2: Document Query Execution Flow

Explain the complete lifecycle of query execution from initialization through response processing, referencing inherited _Executable behavior where appropriate.

• Create "Execution Flow" section with H2 heading
• Document the execution pipeline stages as an ordered list: Pre-execution setup (_before_execute), Request building (_make_request), gRPC call (via _Executable), Response mapping (_map_response), and Error handling
• For each stage, explain what happens and which class (Query vs _Executable) handles it
• Include code example showing a simple query execution pattern from examples/query/account_balance_query.py
• Reference docs/sdk_developers/training/executable.md for details on inherited retry and node selection behavior
• Add callout noting that Query handles query-specific logic while _Executable handles network orchestration

Task 3: Explain Query Payment Mechanism

Document how query payment works, including payment-required vs free queries, automatic cost calculation, and custom payment setting.

• Create "Query Payment" section with H2 heading
• Explain that some queries require payment (TokenInfoQuery, AccountInfoQuery) while others are free (AccountBalanceQuery)
• Document the set_query_payment(amount: Hbar) method for custom payment amounts
• Explain automatic cost calculation with get_cost(client) when no payment is set
• Show code example from examples/query/payment_query.py demonstrating both free queries and payment-required queries with cost calculation
• Document the internal payment transaction construction mechanism (brief explanation that Query builds a CryptoTransfer transaction using _build_query_payment_transaction)
• Add table comparing free vs paid query types with examples

Task 4: Document Abstract Methods and Subclass Requirements

Explain the three required abstract methods that concrete query classes must implement, with clear examples and purposes.

• Create "Abstract Methods" section with H2 heading
• Create table listing the three required methods (_make_request(), _get_query_response(), _get_method()) with descriptions of their purposes
• For each method, provide implementation example from src/hiero_sdk_python/query/account_balance_query.py showing actual code patterns
• Create second table for optional override methods (_map_response(), _should_retry(), _map_status_error()) that subclasses can customize
• Explain when and why developers would override optional methods vs using default implementations
• Reference the pattern from docs/sdk_developers/training/coding_token_transactions.md for explaining abstract method requirements

Task 5: Provide Concrete Query Implementation Guide

Walk through building a complete concrete query class, showing how all pieces fit together with a realistic example.

• Create "Building a Child Query" section with H2 heading
• Show complete implementation example of AccountBalanceQuery including: class definition inheriting from Query, init method, all three required abstract methods, helper methods like set_account_id(), and execute() method
• Annotate the code example with comments explaining each method's role
• Add "Usage Example" subsection showing how developers would use the query in practice
• Include explanation of protobuf imports and usage pattern (importing *_pb2 modules, using CopyFrom() for nested fields, wrapping in query_pb2.Query)
• Reference validation pattern (raising ValueError for missing required fields) seen in existing queries

Task 6: Document Retry Logic and Cost Queries

Explain automatic retry behavior inherited from _Executable and the cost query mechanism for payment calculation.

• Create "Retry Logic" section with H2 heading documenting retryable status codes (BUSY, PLATFORM_TRANSACTION_NOT_CREATED, PLATFORM_NOT_ACTIVE)
• Explain that retry logic is primarily inherited from _Executable but Query's _should_retry() can extend it
• Create "Cost Queries" section with H2 heading explaining the COST_ANSWER mechanism
• Show code example of using get_cost() before execution from examples/query/payment_query.py
• Explain that cost queries are automatic when no payment is set but payment is required
• Add note about the responseType field in query headers (ANSWER_ONLY vs COST_ANSWER)

Task 7: Add Key Takeaways and References

Summarize the most important concepts and provide links to related documentation and examples.

• Create "Key Takeaways" section with H2 heading listing 5-7 bullet points covering: Query handles network-level logic, payment handling is transparent, automatic retry for robustness, required abstract method implementation, relationship with _Executable
• Create "Additional Resources" section with links to related training docs (executable.md, coding_token_transactions.md), example files (examples/query/payment_query.py, examples/query/account_balance_query.py), and source code (src/hiero_sdk_python/query/query.py)
• Add "Next Steps" subsection suggesting readers explore concrete query implementations and try modifying existing examples
• Follow the conclusion pattern from docs/sdk_developers/training/executable.md

🤖 Prompt for AI agents

Create comprehensive Query class training documentation at
`docs/sdk_developers/training/query.md` following established SDK training
documentation patterns.

Structure the document with:
- H1 title "Understanding the Query Class" with full Table of Contents
- Introduction explaining Query as base class for Hedera network queries,
inheriting from _Executable, with mermaid class hierarchy diagram
- Execution Flow section documenting lifecycle stages (pre-execution, request
building, gRPC call, response mapping, error handling) with code examples from
`account_balance_query.py`
- Query Payment section explaining free vs paid queries, `set_query_payment()`,
`get_cost()`, automatic cost calculation, and internal payment transaction
construction, with examples from `payment_query.py` and comparison table
- Abstract Methods section with tables listing required methods
(`_make_request()`, `_get_query_response()`, `_get_method()`) and optional
overrides (`_map_response()`, `_should_retry()`, `_map_status_error()`), with
implementation examples from AccountBalanceQuery
- Building a Child Query section with complete annotated AccountBalanceQuery
implementation showing class definition, methods, protobuf patterns, and usage
example
- Retry Logic section documenting retryable status codes and inheritance from
_Executable
- Cost Queries section explaining COST_ANSWER mechanism and responseType field
- Key Takeaways section with 5-7 bullet points summarizing core concepts
- Additional Resources section linking to `executable.md`,
`coding_token_transactions.md`, example files, and source code
- Next Steps subsection encouraging exploration of concrete implementations

Follow conventions from `executable.md` and `coding_token_transactions.md` for
structure, code formatting, tables, and diagrams.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Create comprehensive Query class training documentation at
`docs/sdk_developers/training/query.md` following established SDK training
documentation patterns.

Structure the document with:
- H1 title "Understanding the Query Class" with full Table of Contents
- Introduction explaining Query as base class for Hedera network queries,
inheriting from _Executable, with mermaid class hierarchy diagram
- Execution Flow section documenting lifecycle stages (pre-execution, request
building, gRPC call, response mapping, error handling) with code examples from
`account_balance_query.py`
- Query Payment section explaining free vs paid queries, `set_query_payment()`,
`get_cost()`, automatic cost calculation, and internal payment transaction
construction, with examples from `payment_query.py` and comparison table
- Abstract Methods section with tables listing required methods
(`_make_request()`, `_get_query_response()`, `_get_method()`) and optional
overrides (`_map_response()`, `_should_retry()`, `_map_status_error()`), with
implementation examples from AccountBalanceQuery
- Building a Child Query section with complete annotated AccountBalanceQuery
implementation showing class definition, methods, protobuf patterns, and usage
example
- Retry Logic section documenting retryable status codes and inheritance from
_Executable
- Cost Queries section explaining COST_ANSWER mechanism and responseType field
- Key Takeaways section with 5-7 bullet points summarizing core concepts
- Additional Resources section linking to `executable.md`,
`coding_token_transactions.md`, example files, and source code
- Next Steps subsection encouraging exploration of concrete implementations

Follow conventions from `executable.md` and `coding_token_transactions.md` for
structure, code formatting, tables, and diagrams.

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[undefinedIsMyLife]

Hi! If it’s okay to take on two issues at once, I’d be happy to work on creating docs/sdk_developers/training/query.md as well. If not, no worries at all. Thanks!

[exploreriii]

Hi @undefinedIsMyLife thank you for asking! Yes, we do allow two issues - sometimes it is necessary while you wait for your PRs to be reviewed but typically only encourage that at a late phase after the first one

[undefinedIsMyLife]

Hi! I started working on this now currently reviewing query.py and the existing examples to understand the execution flow. Planning to draft docs/sdk_developers/training/query.md soon. Thanks!