Struct DocumentRankedEntries 

pub struct DocumentRankedEntries {
    pub starting_rank: u64,
    pub entries: Vec<RankedEntry>,
}

Verified ranked (GROUP BY … ORDER BY <aggregate> LIMIT n [OFFSET m]) result types. DocumentRankedEntries carries one entry per returned group in ranking order, plus the starting_rank that pins each entry to an absolute position; verify_ranked_top_k_proof is the tenderdash-composition wrapper that binds the proof’s reconstructed root hash to the signed app hash and returns the whole verified drive::query::RankedPage. One page of a GROUP BY … ORDER BY <aggregate> LIMIT n [OFFSET m] query: the ranked groups, plus the rank the page starts at.

Entry order is the ranking order — best-first for DESC, worst-first for ASC. Callers must not re-sort; ties (groups with equal aggregates) come back in group-key order in the direction of the walk, which is descending group-key order for DESC.

Fewer than n entries is normal — the index simply holds fewer groups than were asked for — and is not an error.

Each RankedEntry’s key is the raw index-key bytes of the GROUP BY property’s value (for a string property, its UTF-8 bytes); its value is the aggregate, one of RankedEntryValue::Count / RankedEntryValue::Sum / RankedEntryValue::AvgFixedPoint. Averages are fixed-point integers scaled by crate::RANKED_AVG_SCALE; divide by it (or call RankedEntryValue::as_f64) to render one.

The fixed point is exact on the proved path only. A page built by Self::from_verified carries the very integer the proof commits to; one built by Self::from_unproved_response carries a best-effort reconstruction from the wire’s double — see that method for what that costs.

Fields

starting_rank: u64

The 0-based rank of entries[0] — the query’s OFFSET, as actually honoured.

This is what turns a page back into a ranking: entry i is the group at rank starting_rank + i. Without it a caller who asked for ORDER BY avg(grade) DESC LIMIT 1 OFFSET 4 receives one entry and has no way to tell it really is the 5th-best group rather than the best.

On the proved path this is grovedb’s cryptographically attested count, re-derived by the verifier from the counted subtree commitments in the proof bytes rather than trusted from the response. It equals the requested offset unless the walk ran out of groups first, in which case entries is empty and this is a proof that the ranking holds exactly this many groups in total — an offset past the end is a positive answer, not an error.

On the unproven decode it is whatever the node put on the wire (0 when the field is absent), and carries no more weight than the entries beside it.

entries: Vec<RankedEntry>

The groups on this page, in ranking order.

Implementations

impl DocumentRankedEntries

pub fn from_verified(page: RankedPage) -> Self

Build a DocumentRankedEntries from a verifier-side RankedPage — the shape rs-drive’s merk-level verifier returns, carrying the attested skip alongside the entries.

Mirrors DocumentSplitCounts::from_verified, except that it is not the identity: RankedPage is rs-drive’s internal type and this is the client-facing one, so the rename of skipped → starting_rank happens here, where the value stops being “how far the walk skipped” and starts being “which rank you are looking at”.

pub fn from_unproved_response( response: &GetDocumentsResponse, ) -> Result<(Self, ResponseMetadata), Error>

Decode the unproven ranked payload of a getDocuments response — the ResultData.ranked variant a node returns for a ranked request sent with prove = false.

Order is preserved verbatim: the server emits entries in ranking order and this decoder never re-sorts.

This is a plain wire decode with no cryptographic guarantee whatsoever — it is the “trust the node” path, and that applies to Self::starting_rank every bit as much as to the entries: an unproven page claiming to start at rank 4 is a claim, not a fact. Prefer verify_ranked_top_k_proof (via rs-sdk’s DocumentRankedEntries::fetch) unless you are deliberately reading from a node you already trust.

A node that predates the wire skipped field leaves it unset; that decodes to starting_rank == 0, which is the right answer for the offset-less queries such a node could serve at all.

Averages come back approximate here

The wire’s avg is a double, deliberately: these entries only exist on this path, and a proof-verifying client reconstructs the exact fixed point from the proof instead. To keep one RankedEntryValue type across both paths this decoder multiplies the double back up by crate::RANKED_AVG_SCALE and rounds, so the RankedEntryValue::AvgFixedPoint it yields is a best-effort reconstruction, not the committed integer — its low digits are noise beyond f64’s ~15–16 significant decimal digits. Render it, compare it loosely, but do not treat it as the value grovedb ranked on; ask for the proof if you need that.

Errors

• Error::EmptyVersion when the response carries no version.
• Error::ResponseDecodeError when the response is a V0 response (which has no ranked shape), carries a proof rather than data, or carries a non-ranked ResultData variant.
• Error::ResponseDecodeError when an entry’s value oneof is unset, or its avg is not a finite double that scales into i128 range.

Trait Implementations

impl Clone for DocumentRankedEntries

fn clone(&self) -> DocumentRankedEntries

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DocumentRankedEntries

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DocumentRankedEntries

fn default() -> DocumentRankedEntries

Returns the “default value” for a type.

impl Eq for DocumentRankedEntries

impl<'dq, Q> FromProof<Q> for DocumentRankedEntries

where Q: TryInto<DriveDocumentQuery<'dq>> + Clone + 'dq, Q::Error: Display,

Reject the generic FromProof entry point for DocumentRankedEntries.

DocumentRankedEntries is reached from rs-sdk via the FromProof<DocumentQuery> impl defined alongside the SDK’s DocumentQuery type (see rs-sdk/src/platform/documents/document_ranked_entries.rs), which resolves the (axis, descending, k, offset) tuple and the covering index from the request’s (select, group_by, order_by, limit, offset) shape plus the data contract. The generic FromProof<Q: TryInto<DriveDocumentQuery>> path carries neither — DriveDocumentQuery has no notion of a ranking — so it errors out explicitly rather than verifying the wrong thing; calling this impl directly is a programmer mistake.

type Request = Q

Request type for which this trait is implemented.

type Response = GetDocumentsResponse

Response type for which this trait is implemented.

fn maybe_from_proof_with_metadata<'a, I: Into<Self::Request>, O: Into<Self::Response>>( _request: I, _response: O, _network: Network, _platform_version: &PlatformVersion, _provider: &'a dyn ContextProvider, ) -> Result<(Option<Self>, ResponseMetadata, Proof), Error>

where Self: 'a,

Parse and verify the received proof and retrieve the requested object, if any.

fn maybe_from_proof<'a, I: Into<Self::Request>, O: Into<Self::Response>>( request: I, response: O, network: Network, platform_version: &PlatformVersion, provider: &'a dyn ContextProvider, ) -> Result<Option<Self>, Error>

where Self: Sized + 'a,

Parse and verify the received proof and retrieve the requested object, if any.

fn from_proof<'a, I: Into<Self::Request>, O: Into<Self::Response>>( request: I, response: O, network: Network, platform_version: &PlatformVersion, provider: &'a dyn ContextProvider, ) -> Result<Self, Error>

where Self: Sized + 'a,

Retrieve the requested object from the proof.

fn from_proof_with_metadata<'a, I: Into<Self::Request>, O: Into<Self::Response>>( request: I, response: O, network: Network, platform_version: &PlatformVersion, provider: &'a dyn ContextProvider, ) -> Result<(Self, ResponseMetadata), Error>

where Self: Sized + 'a,

Retrieve the requested object from the proof with metadata.

fn from_proof_with_metadata_and_proof<'a, I: Into<Self::Request>, O: Into<Self::Response>>( request: I, response: O, network: Network, platform_version: &PlatformVersion, provider: &'a dyn ContextProvider, ) -> Result<(Self, ResponseMetadata, Proof), Error>

where Self: Sized + 'a,

Retrieve the requested object from the proof with metadata.

impl PartialEq for DocumentRankedEntries

fn eq(&self, other: &DocumentRankedEntries) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for DocumentRankedEntries