docs(reference): document v3.1 getDocuments v0/v1 and aggregate queries

[thephez]

Summary

• Rewrite the getDocuments reference for v3.1: covers the legacy v0 CBOR surface and the new v1 typed surface, with Fetch / Count / Sum / Average sub-modes via sphinx-design tab sets. Aggregate examples are placeholders pending a real testnet contract.
• Add doctype-level aggregate query flags to data-contract-document (documentsCountable, rangeCountable, documentsSummable, rangeSummable, documentsAverageable, rangeAverageable).
• Add an Aggregate Queries section to query-syntax.md covering select × groupBy and the schema requirements that gate each mode.
• Annotate the getDocuments row on the dapi-endpoints.md overview with **Updated in Dash Platform v3.1.0**.
• Add a ## DAPI endpoint reference block to CLAUDE.md and a new RELEASE.md capturing year-round vs. per-release endpoint conventions.

Preview build: https://dash-docs-platform--149.org.readthedocs.build/en/149/

Summary by CodeRabbit

• New Features

  • getDocuments now supports aggregate queries returning count, sum, and average values over matched document sets in Dash Platform v3.1.0.

• Documentation

  • Added comprehensive aggregate query syntax and examples documentation.
  • Updated getDocuments endpoint reference with typed v1 request surface, aggregate select modes, and request/response examples.
  • Expanded internal documentation guidelines for endpoint management and release processes.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ebf7209d-be92-4583-aaca-f20c95ee6ce5

📥 Commits

Reviewing files that changed from the base of the PR and between a07df37 and 27a5b9c.

📒 Files selected for processing (8)

• CLAUDE.md
• RELEASE.md
• conf.py
• docs/protocol-ref/data-contract-document.md
• docs/protocol-ref/data-contract.md
• docs/reference/dapi-endpoints-platform-endpoints.md
• docs/reference/dapi-endpoints.md
• docs/reference/query-syntax.md

---

📝 Walkthrough

Walkthrough

This PR documents Dash Platform v3.1.0 aggregate query capabilities across the endpoint reference, query syntax guide, and schema documentation. It introduces support for COUNT, SUM, and AVG operations via updated getDocuments v1 request/response surfaces, legacy v0 CBOR compatibility, and required document-type schema flags. Supporting process documentation defines how to maintain endpoint references going forward.

Changes

Aggregate Query Feature and Process Documentation

Layer / File(s)	Summary
Aggregate Query Flags Schema docs/protocol-ref/data-contract-document.md, docs/protocol-ref/data-contract.md	New "Aggregate Query Flags" section defines document-type-level and per-index-range flags (documents*, range*) that enable COUNT/SUM/AVG support, with flag dependencies, average-flag desugaring, version/schema validation, and a link to getDocuments reference. Cross-reference in data-contract.md is expanded to explicitly point to aggregate-query-flags subsection.
Query Syntax and Endpoint Overview docs/reference/query-syntax.md, docs/reference/dapi-endpoints.md	New "Aggregate Queries" section (v3.1.0) documents select/groupBy modes that return COUNT(*), SUM(), or AVG() aggregates, with schema flag requirements and unsupported features listed. getDocuments endpoint table updated to describe both document retrieval and aggregate count/sum/average behavior.
getDocuments Endpoint Reference docs/reference/dapi-endpoints-platform-endpoints.md	Expands getDocuments documentation to introduce v1 typed request fields (where/order/select with aggregate modes DOCUMENTS/COUNT/SUM/AVG), document v0 CBOR envelope support, example gRPCurl requests for v1 and v0, JavaScript dapi-client example call shape updates, and comprehensive response documentation including aggregate Count/Sum/Average modes with required constraints, response shapes, examples, and a note on client-side AVG computation from count and sum.
Documentation Maintenance Process CLAUDE.md, RELEASE.md, conf.py	CLAUDE.md introduces guidance for maintaining the DAPI endpoint reference with links and version annotation conventions. RELEASE.md provides a concise per-release checklist for reviewing endpoint changes, updating documentation pages, validating testnet requests, and refreshing examples. conf.py is updated to exclude RELEASE.md from the Sphinx documentation build.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🐰 Platform v3.1.0 brings aggregate queries,
COUNT and SUM and AVG—the features!
Flags dance in documents, schemas sing,
And docs now guide each maintaining thing. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main objective of the PR: documenting the v3.1 getDocuments endpoint with both v0/v1 surfaces and aggregate query capabilities.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[thephez]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.