docs(reference): update query-syntax and DAPI endpoint docs for v3.1

[thephez]

Updates query-syntax.md and DAPI platform endpoint docs to reflect the current v3.1 implementation.

What was done?

docs/reference/query-syntax.md

• Rewrote Where Clause intro: clause is now optional (empty returns all docs), expanded system timestamp field examples to include $transferredAt, $createdAtBlockHeight, and $createdAtCoreBlockHeight
• Added Between, BetweenExcludeBounds, BetweenExcludeLeft, BetweenExcludeRight operators to the Range table
• Updated range-operator tip: normalisation behaviour now leads (two operators on the same field are merged); single-clause limit follows
• Documented = as an accepted alias for ==
• Removed incorrect startsWith 255-character limit (not enforced at the query layer)
• Removed incorrect orderBy "maximum: 2" constraint (no such hard limit exists; effective limit is the matched index's property count)
• Added Between operator example tab and offset modifier row
• Updated orderBy operator list to include Between* variants
• Replaced startAt/startAfter examples with plain document ID strings (removed Buffer.from(Identifier.from(...)) pattern)
• Added Evo SDK example tab alongside the query object tab; example uses doc?.toJSON() to handle potential undefined values

docs/reference/dapi-endpoints-platform-endpoints.md

• Removed getProofs section (internal DAPI-to-Drive endpoint; all external requests rejected)
• Fixed start_epoch type: Bytes → Integer

docs/reference/dapi-endpoints.md

• Removed getProofs row from the endpoint summary table

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

Summary by CodeRabbit

• Documentation
  • Added new range query operators: Between, BetweenExcludeBounds, BetweenExcludeLeft, and BetweenExcludeRight.
  • Made where clause optional in queries; omitting it returns all documents.
  • Introduced offset modifier for query result pagination.
  • Updated endpoint documentation and query syntax reference.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation updates across Dash Platform reference guides: revised getEpochsInfo parameter type, consolidated getProofs endpoint documentation with internal-use notices, and expanded query syntax documentation with new operators (Between* variants), modifiers, and examples.

Changes

Cohort / File(s)	Summary
getProofs endpoint consolidation docs/reference/dapi-endpoints-platform-endpoints.md, docs/reference/dapi-endpoints.md	Removed detailed getProofs documentation sections and endpoint listing; replaced with internal-use-only notices. Updated getEpochsInfo parameter type from Bytes to Integer.
Query syntax documentation expansion docs/reference/query-syntax.md	Added four new Between* range operators (Between, BetweenExcludeBounds, BetweenExcludeLeft, BetweenExcludeRight) with binding rules. Expanded system timestamp fields, equality operator aliases, query modifier combinations, and added offset modifier. Introduced new query examples including Between operator usage and Evo SDK integration patterns.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~18 minutes

Poem

🐰 With operators new, both broad and precise,
Between bounds flow like lettuce so nice,
getProofs now tucked in internal delight,
Documentation blooms, the queries take flight! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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 primary changes: documentation updates to query-syntax and DAPI endpoint references for v3.1 release.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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.}

[coderabbitai]

🧹 Nitpick comments (2)

docs/reference/query-syntax.md (2)

142-142: Use a complete sentence in the orderBy modifier description.

“Can only be used …” is a sentence fragment in the table text.

✏️ Suggested wording

-| `orderBy` | Returns records sorted by the field(s) provided. Sorting must be by the last indexed property. Can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` |
+| `orderBy` | Returns records sorted by the field(s) provided. Sorting must be by the last indexed property. It can only be used with `>`, `<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and `startsWith` queries. | `orderBy: [['normalizedLabel', 'asc']]` |

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/query-syntax.md` at line 142, The table entry for the orderBy
modifier contains a sentence fragment; update the description for `orderBy` to
be a complete sentence (e.g., start with a subject) and clearly state its
constraints and usage, referencing `orderBy` and the allowed query types (`>`,
`<`, `>=`, `<=`, `Between`, `BetweenExcludeBounds`, `BetweenExcludeLeft`,
`BetweenExcludeRight`, and `startsWith`) so the table cell becomes a full
sentence explaining that `orderBy` returns records sorted by the provided
field(s) and can only be used with those query types and when sorting by the
last indexed property.

---

66-66: Clarify the range-operator rule to avoid a mixed signal.

This line currently reads as both a strict prohibition and an allowed auto-normalization path. Tightening wording will reduce ambiguity for implementers.

✏️ Suggested wording

-- Only one range operator is allowed in a query. `Between` and its variants are single operators that replace a `>=`/`<=` pair — the engine also normalizes two range operators on the same field into the equivalent `Between*` form automatically
+- Only one effective range operator is applied per field in a query. If you provide lower/upper bounds on the same field (for example `>=` + `<=`), the engine normalizes them into the equivalent `Between*` form automatically.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/reference/query-syntax.md` at line 66, The current sentence "Only one
range operator..." is ambiguous; reword it to state explicitly that a query must
not contain more than one explicit range operator on the same field (e.g., you
may not supply both >= and > as separate range operators for a single field),
and also note that the engine will automatically normalize an equivalent >=/<=
pair into the single Between/Between* form for processing; reference the
existing phrase "Only one range operator" and the "Between" operator to locate
where to replace the sentence so implementers know to accept explicit Between
variants and normalized >=/<= pairs but reject multiple explicit range operators
on the same field.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/reference/query-syntax.md`:
- Line 142: The table entry for the orderBy modifier contains a sentence
fragment; update the description for `orderBy` to be a complete sentence (e.g.,
start with a subject) and clearly state its constraints and usage, referencing
`orderBy` and the allowed query types (`>`, `<`, `>=`, `<=`, `Between`,
`BetweenExcludeBounds`, `BetweenExcludeLeft`, `BetweenExcludeRight`, and
`startsWith`) so the table cell becomes a full sentence explaining that
`orderBy` returns records sorted by the provided field(s) and can only be used
with those query types and when sorting by the last indexed property.
- Line 66: The current sentence "Only one range operator..." is ambiguous;
reword it to state explicitly that a query must not contain more than one
explicit range operator on the same field (e.g., you may not supply both >= and
> as separate range operators for a single field), and also note that the engine
will automatically normalize an equivalent >=/<= pair into the single
Between/Between* form for processing; reference the existing phrase "Only one
range operator" and the "Between" operator to locate where to replace the
sentence so implementers know to accept explicit Between variants and normalized
>=/<= pairs but reject multiple explicit range operators on the same field.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a28a3ef1-1432-4bfb-bbe8-d874ffb3de87

📥 Commits

Reviewing files that changed from the base of the PR and between 19078a9 and 2390096.

📒 Files selected for processing (3)

• docs/reference/dapi-endpoints-platform-endpoints.md
• docs/reference/dapi-endpoints.md
• docs/reference/query-syntax.md

💤 Files with no reviewable changes (1)

• docs/reference/dapi-endpoints.md