Module drive_document_sum_query 

A query to sum an integer property across documents using SumTree elements. Parallels drive_document_count_query for the sum surface — see book/src/drive/document-sum-trees.md for the design and book/src/drive/sum-index-examples.md for the worked example contract. DriveDocumentSumQuery — Drive’s sum-query surface.

Parallels crate::query::drive_document_count_query for the sum-tree family added in v3 (alongside grovedb PR 670’s Element::ProvableCountSumTree). The high-level shape mirrors count’s exactly:

• DocumentSumRequest carries the request (contract + document_type
  • sum_property + where/order/mode/limit/prove).
• DocumentSumResponse carries one of three response shapes (Aggregate(i64) / Entries(Vec<SumEntry>) / Proof(Vec<u8>)), picked by the dispatcher from query shape + flags.
• SumMode selects which executor handles the query (Aggregate / GroupByIn / GroupByRange / GroupByCompound).
• DriveDocumentSumQuery is the compiled query object passed to path-query builders + verifier wrappers; shared by prover and verifier as the single source of truth on the path-query shape (same pattern count uses).

The sum-specific wrinkle vs count: every sum request carries a sum_property field naming the integer property to aggregate. The dispatcher validates that the chosen covering index summable: "<x>" matches the request’s sum_property, and that the doctype-level documents_summable: "<x>" (if set) also matches. See book/src/drive/document-sum-trees.md for the design rationale.

The bench at packages/rs-drive/benches/document_sum_worst_case.rs targets these public types and the dispatcher entry — Q1–Q9 from the chapter all roundtrip on the real Drive.

Modules

drive_dispatcher

Sum-query dispatcher entry point.

execute_point_lookup

Point-lookup executor for sum queries. Parallels count’s execute_point_lookup.rs.

execute_range_sum

Range execution paths for the sum query. Parallels count’s execute_range_count.rs.

executors

Per-DocumentSumMode executor modules. Each module owns a single executor function and the helpers it needs. Mirrors count’s executors/ layout — file names parallel byte-for-byte.

index_picker

Sum-index pickers. Parallels count’s index_picker.rs.

mode_detection

Versioned mode detection for the sum-query dispatcher.

path_query

Path-query builders for the sum surface. Single source of truth for the PathQuery shape both the prover (in executors/*) and the verifier (in tests + bench’s display_proofs) construct.

Structs

DocumentSumRequest

Server-side request input for the sum dispatcher. Mirrors crate::query::drive_document_count_query::DocumentCountRequest with the addition of the sum_property field.

DriveDocumentSumQuery

Compiled sum-query object. Shared by prover and verifier — both build the same PathQuery via the path-query helpers on this struct, so the prover and the verifier can’t drift on shape. Parallels count’s DriveDocumentCountQuery.

RangeSumOptions

Server-side range-sum executor options, parallels crate::query::drive_document_count_query::RangeCountOptions.

SumEntry

A single per-key sum entry, parallels count’s SplitCountEntry.

Enums

DocumentSumMode

The lower-level routing decision the dispatcher reaches after detecting the query’s shape. Parallels count’s DocumentCountMode.

DocumentSumResponse

Server-side response from the sum dispatcher. Parallels count’s DocumentCountResponse.

SumMode

What kind of sum-query the dispatcher should run. Parallels crate::query::drive_document_count_query::CountMode.

Constants

MAX_CARRIER_AGGREGATE_OUTER_RANGE_LIMIT

Platform-wide cap on the outer walk of a carrier-aggregate range-outer sum proof, mirroring count’s MAX_CARRIER_AGGREGATE_OUTER_RANGE_LIMIT. The carrier-aggregate shape is the sum analog of count’s G8 — single proof carrying per-bucket aggregated sums for an outer range × inner range query. Bounded so a single proof’s outer enumeration can’t be made pathological by a caller.

MAX_LIMIT_AS_FAILSAFE

Failsafe cap on per-In-value fan-out, mirroring crate::query::drive_document_count_query::MAX_LIMIT_AS_FAILSAFE. WhereClause::in_values() already caps each In clause at 100 values, so this 1024 ceiling exists only as a defensive guard against pathological input that slipped past the upstream validator.

Functions

is_indexable_for_sum

True if the WhereOperator is supported on a summable index for the executor pickers. Parallels count’s is_indexable_for_count.

is_range_operator

Helper used by the verifier-side path-query rebuild to match the shape the prover used. Same role as count’s analog helper — we don’t want the prover and verifier to drift on which operator classification triggers which executor.