Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
fix(cosmosdb): resume a partition whose query result spans several pages (#21888)
Danny Xu0ae7702f9556
diff --git a/backend/plugin/db/cosmosdb/cosmosdb_test.go b/backend/plugin/db/cosmosdb/cosmosdb_test.goindex 07dfeaf4f2..af21aa9fb9 100644--- a/backend/plugin/db/cosmosdb/cosmosdb_test.go+++ b/backend/plugin/db/cosmosdb/cosmosdb_test.go@@ -33,6 +33,7 @@ import ("fmt""net/http""os"+ "slices""sync""testing""time"@@ -536,28 +537,28 @@ func seedCrossPartition(endpoint string) (*Driver, int, error) {if err != nil {return nil, 0, errors.Wrap(err, "marshal a fixture city")}- if _, err := container.CreateItem(ctx, azcosmos.NewPartitionKeyString(country), item, nil); err != nil && !alreadyExists(err) {+ if err := seedItem(ctx, container, country, item); err != nil {return nil, 0, errors.Wrapf(err, "seed %s-%d", country, i)}}}- ranges, err := countPartitionKeyRanges(endpoint)+ ranges, err := countContainerRanges(endpoint, crossPartitionContainer)if err != nil {return nil, 0, err}return driver, ranges, nil}-// countPartitionKeyRanges reports how many physical partitions the fixture+// countContainerRanges reports how many physical partitions a fixture// container spans. It reads the REST endpoint because the SDK keeps the range// list to itself, inside the query path under test.-func countPartitionKeyRanges(endpoint string) (int, error) {+func countContainerRanges(endpoint, container string) (int, error) {client, err := newEmulatorRESTClient(endpoint)if err != nil {return 0, errors.Wrap(err, "build the emulator REST client")}- link := fmt.Sprintf("dbs/%s/colls/%s", crossPartitionDatabase, crossPartitionContainer)+ link := fmt.Sprintf("dbs/%s/colls/%s", crossPartitionDatabase, container)body, err := client.get(link+"/pkranges", "pkranges", link)if err != nil {return 0, errors.Wrap(err, "read the container's partition key ranges")@@ -573,11 +574,291 @@ func countPartitionKeyRanges(endpoint string) (int, error) {return len(resp.PartitionKeyRanges), nil}+// seedItem writes one fixture item, retrying what a loaded emulator does to a+// write it cannot serve in time: a 408, a 429, a 503, or a dropped connection+// that surfaces as an EOF. The emulator is slow enough under this repo's own+// test load that an unretried seeder fails the whole suite on one dropped+// write, with an error that reads like a query-engine bug. An error that is+// not transient costs the attempts and then surfaces unchanged.+func seedItem(ctx context.Context, container *azcosmos.ContainerClient, partitionKey string, item []byte) error {+ var err error+ for attempt := range 6 {+ if attempt > 0 {+ select {+ case <-ctx.Done():+ return ctx.Err()+ case <-time.After(time.Duration(attempt) * 500 * time.Millisecond):+ }+ }+ if _, err = container.CreateItem(ctx, azcosmos.NewPartitionKeyString(partitionKey), item, nil); err == nil || alreadyExists(err) {+ return nil+ }+ }+ return err+}+func alreadyExists(err error) bool {var responseErr *azcore.ResponseErrorreturn errors.As(err, &responseErr) && responseErr.StatusCode == http.StatusConflict}+// ------------------------------------------ multi-page fixture, local emulator++const (+ // pagedContainer is a second fixture whose ranges answer over several+ // pages. The gateway caps a page at pagedPageSize items when the request+ // names no page size, which is what the SDK's engine requests do: it+ // forwards a continuation token and the range's partition key range id,+ // and nothing else. A query engine that stops at the first page therefore+ // loses every row past the cap, which is what this fixture catches.+ pagedContainer = "paged"+ // The emulator hands a container one physical partition per 6k RU or so,+ // and the cities fixture already spends most of its budget, so this one+ // asks for the least that still spans more than one.+ pagedThroughput = 12000+ // pagedPageSize is the gateway's own per-page item cap, measured both on+ // the emulator and on a real Cosmos account.+ pagedPageSize = 1000+ // pagedBigRows puts one partition key value past the cap, so the range+ // holding it must be read over several pages.+ pagedBigRows = pagedPageSize + 50+ // pagedSmallRows keeps the other partition key values short, so a merge+ // has ranges that drain while the big ones still have pages to come.+ pagedSmallRows = 5+)++// pagedBuckets are the fixture's partition key values: a partition key value+// lives in exactly one physical partition, so the row count per value is what+// decides which ranges have to page.+var (+ pagedBigBuckets = []string{"big-1", "big-2"}+ pagedSmallBuckets = []string{"small-1", "small-2", "small-3", "small-4", "small-5", "small-6"}+)++// pagedRows is the fixture's row count. Every row carries a distinct seq, from+// 0 to pagedRows-1, so an ordered result has exactly one correct answer and+// DISTINCT and GROUP BY over seq have exactly pagedRows outputs.+func pagedRows() int {+ return len(pagedBigBuckets)*pagedBigRows + len(pagedSmallBuckets)*pagedSmallRows+}++var (+ pagedOnce sync.Once+ pagedContainerClient *azcosmos.ContainerClient+ pagedRanges int+ pagedErr error+)++// pagedFixture returns the seeded multi-page container, building it on first+// use. It refuses a fixture confined to one physical partition for the same+// reason emulatorFixture does: the gateway serves those queries itself.+func pagedFixture(t *testing.T) *azcosmos.ContainerClient {+ t.Helper()+ driver := emulatorFixture(t)+ pagedOnce.Do(func() {+ pagedContainerClient, pagedRanges, pagedErr = seedPaged(driver)+ })+ require.NoError(t, pagedErr)+ require.Greater(t, pagedRanges, 1,+ "fixture spans %d physical partition(s); cross-partition queries need more than one", pagedRanges)+ return pagedContainerClient+}++func seedPaged(driver *Driver) (*azcosmos.ContainerClient, int, error) {+ ctx, cancel := context.WithTimeout(context.Background(), 10*time.Minute)+ defer cancel()++ database, err := driver.client.NewDatabase(crossPartitionDatabase)+ if err != nil {+ return nil, 0, errors.Wrap(err, "open the fixture database")+ }+ throughput := azcosmos.NewManualThroughputProperties(pagedThroughput)+ if _, err := database.CreateContainer(ctx, azcosmos.ContainerProperties{+ ID: pagedContainer,+ PartitionKeyDefinition: azcosmos.PartitionKeyDefinition{Paths: []string{"/bucket"}},+ }, &azcosmos.CreateContainerOptions{ThroughputProperties: &throughput}); err != nil && !alreadyExists(err) {+ return nil, 0, errors.Wrap(err, "create the multi-page container")+ }+ container, err := database.NewContainer(pagedContainer)+ if err != nil {+ return nil, 0, errors.Wrap(err, "open the multi-page container")+ }++ // A few thousand single writes is most of this suite's runtime, so they go+ // out concurrently. The worker count is what the emulator answered without+ // timing out under the load of the rest of this machine.+ type row struct {+ bucket string+ seq int+ }+ rows := make(chan row, pagedRows())+ seq := 0+ for _, bucket := range pagedBigBuckets {+ for range pagedBigRows {+ rows <- row{bucket: bucket, seq: seq}+ seq+++ }+ }+ for _, bucket := range pagedSmallBuckets {+ for range pagedSmallRows {+ rows <- row{bucket: bucket, seq: seq}+ seq+++ }+ }+ close(rows)++ var wg sync.WaitGroup+ errs := make(chan error, 1)+ for range 12 {+ wg.Go(func() {+ for r := range rows {+ item, err := json.Marshal(pagedRow{+ ID: fmt.Sprintf("row-%d", r.seq),+ Bucket: r.bucket,+ Seq: r.seq,+ })+ if err == nil {+ err = seedItem(ctx, container, r.bucket, item)+ }+ if err != nil {+ select {+ case errs <- errors.Wrapf(err, "seed row %d", r.seq):+ default:+ }+ return+ }+ }+ })+ }+ wg.Wait()+ select {+ case err := <-errs:+ return nil, 0, err+ default:+ }++ ranges, err := countContainerRanges(driver.connCfg.DataSource.GetHost(), pagedContainer)+ if err != nil {+ return nil, 0, err+ }+ return container, ranges, nil+}++type pagedRow struct {+ ID string `json:"id"`+ Bucket string `json:"bucket"`+ Seq int `json:"seq"`+}++// pagedSeqs runs a query against the multi-page fixture and returns the seq of+// every row it emitted, in the order the engine emitted them.+func pagedSeqs(t *testing.T, container *azcosmos.ContainerClient, sql string) []int {+ t.Helper()+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)+ defer cancel()+ items, err := QueryEveryPartition(ctx, container, sql, nil, 0)+ require.NoError(t, err, "QueryEveryPartition: %s", sql)+ seqs := make([]int, 0, len(items))+ for _, item := range items {+ var row struct {+ Seq *int `json:"seq"`+ }+ require.NoError(t, json.Unmarshal(item, &row), "row: %s", item)+ require.NotNil(t, row.Seq, "row missing seq: %s", item)+ seqs = append(seqs, *row.Seq)+ }+ return seqs+}++// ascendingSeqs is the fixture's seq values in order: every query below either+// returns this sequence or a slice of it.+func ascendingSeqs(from, to int) []int {+ seqs := make([]int, 0, to-from)+ for seq := from; seq < to; seq++ {+ seqs = append(seqs, seq)+ }+ return seqs+}++// TestCrossPartitionMultiPage covers the query classes whose results a range+// can only deliver over several pages. Each one reads past the gateway's+// per-page cap, which an engine that treats a continuation token as the end of+// a range cannot do: before the engine followed them, an unbounded ORDER BY+// failed outright on any container holding more than pagedPageSize rows in one+// range, and so did DISTINCT and GROUP BY over that many values and a TOP+// above the cap.+func TestCrossPartitionMultiPage(t *testing.T) {+ container := pagedFixture(t)+ rows := pagedRows()++ t.Run("order_by_unbounded", func(t *testing.T) {+ assert.Equal(t, ascendingSeqs(0, rows),+ pagedSeqs(t, container, `SELECT c.seq FROM c ORDER BY c.seq ASC`))+ })++ t.Run("order_by_descending", func(t *testing.T) {+ want := ascendingSeqs(0, rows)+ slices.Reverse(want)+ assert.Equal(t, want, pagedSeqs(t, container, `SELECT c.seq FROM c ORDER BY c.seq DESC`))+ })++ // A page of a range ends mid-result, so the rows either side of the cap+ // are the ones a resumed range can misplace.+ t.Run("offset_limit_across_a_page_boundary", func(t *testing.T) {+ assert.Equal(t, ascendingSeqs(pagedPageSize-5, pagedPageSize+5),+ pagedSeqs(t, container, fmt.Sprintf(+ `SELECT c.seq FROM c ORDER BY c.seq ASC OFFSET %d LIMIT 10`, pagedPageSize-5)))+ })++ t.Run("distinct_high_cardinality", func(t *testing.T) {+ seqs := pagedSeqs(t, container, `SELECT DISTINCT c.seq FROM c`)+ slices.Sort(seqs)+ assert.Equal(t, ascendingSeqs(0, rows), seqs)+ })++ t.Run("group_by_many_groups", func(t *testing.T) {+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)+ defer cancel()+ items, err := QueryEveryPartition(ctx, container,+ `SELECT c.seq, COUNT(1) AS n FROM c GROUP BY c.seq`, nil, 0)+ require.NoError(t, err)+ seqs := make([]int, 0, len(items))+ for _, item := range items {+ var group struct {+ Seq int `json:"seq"`+ N int `json:"n"`+ }+ require.NoError(t, json.Unmarshal(item, &group))+ assert.Equal(t, 1, group.N, "seq %d", group.Seq)+ seqs = append(seqs, group.Seq)+ }+ slices.Sort(seqs)+ assert.Equal(t, ascendingSeqs(0, rows), seqs)+ })++ t.Run("top_above_the_page_cap", func(t *testing.T) {+ assert.Len(t, pagedSeqs(t, container,+ fmt.Sprintf(`SELECT TOP %d c.seq FROM c`, pagedPageSize+25)), pagedPageSize+25)+ })++ // An aggregate answers with one partial document per range however many+ // rows that range holds, which is why aggregates were the one class this+ // fixture's size never broke. Kept as the control case.+ t.Run("aggregate_over_the_whole_fixture", func(t *testing.T) {+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)+ defer cancel()+ items, err := QueryEveryPartition(ctx, container,+ `SELECT COUNT(1) AS n, SUM(c.seq) AS total FROM c`, nil, 0)+ require.NoError(t, err)+ require.Len(t, items, 1)+ want := 0+ for _, seq := range ascendingSeqs(0, rows) {+ want += seq+ }+ assert.JSONEq(t, fmt.Sprintf(`{"n":%d,"total":%d}`, rows, want), string(items[0]))+ })+}+func TestCrossPartitionAggregates(t *testing.T) {driver := emulatorFixture(t)items := crossPartitionItems()diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/distinct.go b/backend/plugin/db/cosmosdb/queryengine/gonative/distinct.goindex cd2ebb6ca5..330eb408ae 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/distinct.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/distinct.go@@ -53,11 +53,9 @@ func canonicalJSON(raw json.RawMessage) ([]byte, error) {// The OS is the memory ceiling. Queries whose DISTINCT cardinality could// exhaust memory should scope themselves with a WHERE clause.type distinctPipeline struct {- query string- pkRangeIDs []string- partitionsDone map[string]bool- issued bool- closed bool+ query string+ fanout rangeFanout+ closed bool// Pending items not yet returned to the caller. Populated during// ProvideData as each partition's response is de-duplicated against the@@ -82,9 +80,8 @@ func newDistinctPipeline(plan *planDoc, pkRangeIDs []string) (*distinctPipeline,// against each partition. The pipeline needs the original query text to// populate QueryRequest.Query; the caller passes it via CreateQueryPipeline.return &distinctPipeline{- pkRangeIDs: append([]string(nil), pkRangeIDs...),- partitionsDone: make(map[string]bool, len(pkRangeIDs)),- seen: make(map[string]struct{}),+ fanout: newRangeFanout(pkRangeIDs),+ seen: make(map[string]struct{}),}, nil}@@ -92,44 +89,25 @@ func newDistinctPipeline(plan *planDoc, pkRangeIDs []string) (*distinctPipeline,func (p *distinctPipeline) Query() string { return p.query }// IsComplete implements queryengine.QueryPipeline. A DISTINCT pipeline is-// complete once every partition has delivered and every deduped item has been-// flushed to the caller.+// complete once every range has delivered its last page and every deduped+// item has been flushed to the caller.func (p *distinctPipeline) IsComplete() bool {- if !p.issued {- return false- }if len(p.pending) > 0 {return false}- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }- }- return true+ return p.fanout.allDrained()}// Close implements queryengine.QueryPipeline.func (p *distinctPipeline) Close() { p.closed = true }-// Run drives one pipeline turn:-// 1. First call — emit one QueryRequest per pk-range carrying the original query.-// 2. Subsequent calls — flush any pending deduplicated items; otherwise wait-// for the SDK to deliver more partition responses via ProvideData.+// Run drives one pipeline turn. Deduplicated items go out as soon as they are+// known, so a DISTINCT over many pages does not hold the whole result before+// the caller sees its first row:+// 1. Flush any pending deduplicated items.+// 2. Otherwise ask for the next page of every range that has one — the+// initial fan-out on the first call.func (p *distinctPipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- reqs := make([]queryengine.QueryRequest, len(p.pkRangeIDs))- for i, id := range p.pkRangeIDs {- reqs[i] = queryengine.QueryRequest{- PartitionKeyRangeID: id,- Id: uint64(i),- Query: p.query,- IncludeParameters: true,- }- }- p.issued = true- return &queryengine.PipelineResult{Requests: reqs}, nil- }if len(p.pending) > 0 {batch := p.pendingp.pending = nil@@ -138,6 +116,9 @@ func (p *distinctPipeline) Run() (*queryengine.PipelineResult, error) {IsCompleted: p.IsComplete(),}, nil}+ if reqs := p.fanout.requests(p.query); len(reqs) > 0 {+ return &queryengine.PipelineResult{Requests: reqs}, nil+ }return &queryengine.PipelineResult{IsCompleted: p.IsComplete()}, nil}@@ -166,10 +147,9 @@ func (p *distinctPipeline) ProvideData(results []queryengine.QueryResult) error// buffer, which the SDK may reuse for later pages.p.pending = append(p.pending, append([]byte(nil), doc...))}- if r.NextContinuation != "" {- return errors.New("gonative: distinct partition returned a continuation token (multi-page not supported in Stage 2)")+ if err := p.fanout.note(r); err != nil {+ return err}- p.partitionsDone[r.PartitionKeyRangeID] = true}return nil}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/distinct_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/distinct_test.goindex 332bf9b50f..3e0be9e63f 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/distinct_test.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/distinct_test.go@@ -173,19 +173,34 @@ func TestDistinctPipeline_RejectsOrderedDistinctType(t *testing.T) {require.ErrorIs(t, err, ErrUnsupportedPlanFeature)}-func TestDistinctPipeline_RejectsContinuationToken(t *testing.T) {+// A value already emitted from an earlier page must not be emitted again when+// a later page of the same range repeats it.+func TestDistinctPipeline_DedupesAcrossPages(t *testing.T) {plan := &planDoc{}plan.QueryInfo.DistinctType = "Unordered"p, err := newDistinctPipeline(plan, []string{"0"})require.NoError(t, err)- _, _ = p.Run()- body, _ := json.Marshal(map[string]any{"Documents": rawMsgs(`"AE"`)})- err = p.ProvideData([]queryengine.QueryResult{- {PartitionKeyRangeID: "0", Data: body, NextContinuation: "deadbeef"},+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkDistinctBody(t, `"AE"`, `"BR"`), continuation: "0-page-2"},+ {body: mkDistinctBody(t, `"BR"`, `"CN"`)},+ },})- require.Error(t, err)- assert.Contains(t, err.Error(), "continuation token")+ got := make([]string, 0, len(rows))+ for _, r := range rows {+ got = append(got, string(r))+ }+ assert.Equal(t, []string{`"AE"`, `"BR"`, `"CN"`}, got)+ assert.Equal(t, map[string]int{"0": 2}, read)+}++// mkDistinctBody wraps raw JSON values into a DISTINCT partition response.+func mkDistinctBody(t *testing.T, values ...string) []byte {+ t.Helper()+ body, err := json.Marshal(map[string]any{"Documents": rawMsgs(values...)})+ require.NoError(t, err)+ return body}// Verifies the pipeline accepts high-cardinality inputs unchanged — the seen-setdiff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/fanout.go b/backend/plugin/db/cosmosdb/queryengine/gonative/fanout.gonew file mode 100644index 0000000000..a090fba640--- /dev/null+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/fanout.go@@ -0,0 +1,123 @@+package gonative++import (+ "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos/queryengine"+ "github.com/pkg/errors"+)++// fanoutRange is one partition key range's paging state.+type fanoutRange struct {+ id string+ // started is false until the range's first request goes out.+ started bool+ // next is the continuation token the range's next request must carry.+ // Empty on a started range means there is nothing to ask for: either a+ // response is still owed for it, or it has drained.+ next string+ // sent is the token the range's last request carried. It guards against a+ // token that never advances, which would otherwise page forever.+ sent string+ drained bool+}++// rangeFanout tracks the per-range request state of a pipeline that runs one+// query against every partition key range the container reports.+//+// A range's result can span several response pages: the gateway caps a page by+// item count and by size, and signals the rest with a continuation token. The+// fanout hands that token back on the range's next request and treats the+// range as drained only once a response for it carries no token.+//+// The SDK's QueryRequest.Drain flag looks like it would do this, but its+// drain loop reuses the original request for every page without feeding the+// continuation back, so a drained request re-reads page one forever.+type rangeFanout struct {+ ranges []*fanoutRange+ byID map[string]*fanoutRange+ nextID uint64+}++func newRangeFanout(rangeIDs []string) rangeFanout {+ f := rangeFanout{+ ranges: make([]*fanoutRange, 0, len(rangeIDs)),+ byID: make(map[string]*fanoutRange, len(rangeIDs)),+ }+ for _, id := range rangeIDs {+ r := &fanoutRange{id: id}+ f.ranges = append(f.ranges, r)+ f.byID[id] = r+ }+ return f+}++// requests returns the work the caller should issue next: the initial fan-out+// on the first call, then one follow-up request per range holding a+// continuation token. It returns nil when every range has either drained or+// has a response outstanding.+func (f *rangeFanout) requests(query string) []queryengine.QueryRequest {+ return f.requestsWhere(query, nil)+}++// requestsWhere is requests narrowed to the ranges want reports true for. An+// operator that consumes its ranges unevenly uses it to leave a range's next+// page unread until it can use it: fetching a page early costs request charge+// and holds the rows in memory, and under a LIMIT the query may never need it+// at all. A range the predicate skips keeps its token and is offered again on+// the next turn.+func (f *rangeFanout) requestsWhere(query string, want func(id string) bool) []queryengine.QueryRequest {+ var reqs []queryengine.QueryRequest+ for _, r := range f.ranges {+ if r.drained || (r.started && r.next == "") {+ continue+ }+ if want != nil && !want(r.id) {+ continue+ }+ r.started = true+ r.sent = r.next+ r.next = ""+ reqs = append(reqs, queryengine.QueryRequest{+ PartitionKeyRangeID: r.id,+ Id: f.nextID,+ Query: query,+ Continuation: r.sent,+ IncludeParameters: true,+ })+ f.nextID+++ }+ return reqs+}++// note records what a response says about its range's remaining pages.+func (f *rangeFanout) note(result queryengine.QueryResult) error {+ r, ok := f.byID[result.PartitionKeyRangeID]+ if !ok {+ return errors.Errorf("gonative: response for unknown partition key range %q", result.PartitionKeyRangeID)+ }+ if result.NextContinuation == "" {+ r.next = ""+ r.drained = true+ return nil+ }+ if result.NextContinuation == r.sent {+ return errors.Errorf("gonative: partition key range %q returned the same continuation token twice", r.id)+ }+ r.next = result.NextContinuation+ return nil+}++// drained reports whether the named range has delivered its last page.+func (f *rangeFanout) drained(id string) bool {+ r, ok := f.byID[id]+ return ok && r.drained+}++// allDrained reports whether every range has delivered its last page.+func (f *rangeFanout) allDrained() bool {+ for _, r := range f.ranges {+ if !r.drained {+ return false+ }+ }+ return true+}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/fanout_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/fanout_test.gonew file mode 100644index 0000000000..c26903db01--- /dev/null+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/fanout_test.go@@ -0,0 +1,127 @@+package gonative++import (+ "testing"++ "github.com/Azure/azure-sdk-for-go/sdk/data/azcosmos/queryengine"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestRangeFanout_InitialFanOutCoversEveryRange(t *testing.T) {+ f := newRangeFanout([]string{"0", "1", "2"})+ reqs := f.requests("SELECT 1")++ require.Len(t, reqs, 3)+ ids := make(map[string]bool)+ seen := make(map[uint64]bool)+ for _, req := range reqs {+ assert.Empty(t, req.Continuation, "the first page of a range carries no token")+ assert.Equal(t, "SELECT 1", req.Query)+ assert.True(t, req.IncludeParameters)+ assert.False(t, seen[req.Id], "request ids must be distinct")+ seen[req.Id] = true+ ids[req.PartitionKeyRangeID] = true+ }+ assert.Equal(t, map[string]bool{"0": true, "1": true, "2": true}, ids)+ assert.False(t, f.allDrained())+}++func TestRangeFanout_AsksNothingWhileResponsesAreOutstanding(t *testing.T) {+ f := newRangeFanout([]string{"0", "1"})+ require.Len(t, f.requests("q"), 2)+ assert.Empty(t, f.requests("q"),+ "a range with a response outstanding must not be asked again")+}++func TestRangeFanout_FollowsAContinuationToken(t *testing.T) {+ f := newRangeFanout([]string{"0", "1"})+ require.Len(t, f.requests("q"), 2)+ require.NoError(t, f.note(queryengine.NewQueryResultString("0", `{}`, "token-0")))+ require.NoError(t, f.note(queryengine.NewQueryResultString("1", `{}`, "")))++ reqs := f.requests("q")+ require.Len(t, reqs, 1, "only the range that reported a token has another page")+ assert.Equal(t, "0", reqs[0].PartitionKeyRangeID)+ assert.Equal(t, "token-0", reqs[0].Continuation)++ assert.True(t, f.drained("1"))+ assert.False(t, f.drained("0"))+ assert.False(t, f.allDrained())++ require.NoError(t, f.note(queryengine.NewQueryResultString("0", `{}`, "")))+ assert.True(t, f.allDrained())+ assert.Empty(t, f.requests("q"))+}++func TestRangeFanout_RejectsATokenThatDoesNotAdvance(t *testing.T) {+ f := newRangeFanout([]string{"0"})+ require.Len(t, f.requests("q"), 1)+ require.NoError(t, f.note(queryengine.NewQueryResultString("0", `{}`, "token")))+ require.Len(t, f.requests("q"), 1)++ err := f.note(queryengine.NewQueryResultString("0", `{}`, "token"))+ require.Error(t, err, "a token that repeats itself would page forever")+ assert.Contains(t, err.Error(), "same continuation token twice")+}++func TestRangeFanout_RejectsAnUnknownRange(t *testing.T) {+ f := newRangeFanout([]string{"0"})+ err := f.note(queryengine.NewQueryResultString("9", `{}`, ""))+ require.Error(t, err)+ assert.Contains(t, err.Error(), "unknown partition key range")+}++// ------------------------------------------------------- multi-page test driver++// page is one response the gateway returns for a range: a body, and the+// continuation token that says whether another page follows.+type page struct {+ body []byte+ continuation string+}++// drivePages runs a pipeline to completion against a per-range script of+// pages, answering each request with that range's next page and asserting that+// a follow-up request carries the token the previous page handed out. It+// returns every emitted row in order, and how many pages of each range the+// pipeline read — a pipeline that stops early must not have read them all.+func drivePages(t *testing.T, p queryengine.QueryPipeline, feed map[string][]page) (rows [][]byte, read map[string]int) {+ t.Helper()+ next := make(map[string]int, len(feed))+ read = make(map[string]int, len(feed))+ // A pipeline that asks for the same page forever would otherwise hang the+ // test; the bound is well above the longest script here.+ for range 200 {+ if p.IsComplete() {+ return rows, read+ }+ res, err := p.Run()+ require.NoError(t, err)+ rows = append(rows, res.Items...)+ if len(res.Items) > 0 {+ continue+ }+ require.NotEmpty(t, res.Requests, "pipeline neither emitted a row nor asked for a page")++ results := make([]queryengine.QueryResult, 0, len(res.Requests))+ for _, req := range res.Requests {+ script, ok := feed[req.PartitionKeyRangeID]+ require.True(t, ok, "missing fixture for %s", req.PartitionKeyRangeID)+ i := next[req.PartitionKeyRangeID]+ require.Less(t, i, len(script), "range %s was asked for a page past its script", req.PartitionKeyRangeID)+ if i == 0 {+ assert.Empty(t, req.Continuation, "the first page of range %s carries no token", req.PartitionKeyRangeID)+ } else {+ assert.Equal(t, script[i-1].continuation, req.Continuation,+ "range %s must resume from the token its previous page returned", req.PartitionKeyRangeID)+ }+ next[req.PartitionKeyRangeID] = i + 1+ read[req.PartitionKeyRangeID] = i + 1+ results = append(results, queryengine.NewQueryResult(req.PartitionKeyRangeID, script[i].body, script[i].continuation))+ }+ require.NoError(t, p.ProvideData(results))+ }+ t.Fatal("pipeline did not complete")+ return rows, read+}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/group.go b/backend/plugin/db/cosmosdb/queryengine/gonative/group.goindex fd67741acd..42b070155e 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/group.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/group.go@@ -55,14 +55,13 @@ type groupState struct {// partition has delivered.//// GROUP BY is non-streaming — all partitions must arrive before any row is-// emitted. Memory is bounded by the cardinality of distinct group keys, not+// emitted, and a partition that answers over several pages must be read to its+// last page. Memory is bounded by the cardinality of distinct group keys, not// by the total row count across partitions.type groupPipeline struct {- query string- pkRangeIDs []string- partitionsDone map[string]bool- issued bool- closed bool+ query string+ fanout rangeFanout+ closed bool// aliases preserves the order of groupByAliases; kinds[i] is the// aggregate kind for aliases[i] ("" when the alias is a group-key column).@@ -126,59 +125,41 @@ func newGroupPipeline(plan *planDoc, pkRangeIDs []string) (*groupPipeline, error// GROUP BY plans always carry a non-empty rewrittenQuery that wraps the// user's projection into {groupByItems, payload}; running the original// query instead would return raw rows with no groupByItems field.- query: qi.RewrittenQuery,- pkRangeIDs: append([]string(nil), pkRangeIDs...),- partitionsDone: make(map[string]bool, len(pkRangeIDs)),- aliases: aliases,- kinds: kinds,- groups: make(map[string]*groupState),+ query: qi.RewrittenQuery,+ fanout: newRangeFanout(pkRangeIDs),+ aliases: aliases,+ kinds: kinds,+ groups: make(map[string]*groupState),}, nil}// Query implements queryengine.QueryPipeline.func (p *groupPipeline) Query() string { return p.query }-// IsComplete returns true once every partition has delivered and every-// finalized row has been flushed to the caller.+// IsComplete returns true once every range has delivered its last page and+// every finalized row has been flushed to the caller.func (p *groupPipeline) IsComplete() bool {- if !p.issued {- return false- }if len(p.pending) > 0 {return false}- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }- }- return p.finalized+ return p.fanout.allDrained() && p.finalized}// Close implements queryengine.QueryPipeline.func (p *groupPipeline) Close() { p.closed = true }// Run drives one pipeline turn:-// 1. First call — fan out one request per pk-range.-// 2. After every partition has provided data, build the output rows by-// finalizing each group's aggregators and emitting in alias order.+// 1. Ask for the next page of every range that has one — the initial fan-out+// across all ranges on the first call.+// 2. Once every range has drained, build the output rows by finalizing each+// group's aggregators and emitting in alias order.// 3. Flush pending rows on subsequent calls until drained.func (p *groupPipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- reqs := make([]queryengine.QueryRequest, len(p.pkRangeIDs))- for i, id := range p.pkRangeIDs {- reqs[i] = queryengine.QueryRequest{- PartitionKeyRangeID: id,- Id: uint64(i),- Query: p.query,- IncludeParameters: true,- }- }- p.issued = true+ if reqs := p.fanout.requests(p.query); len(reqs) > 0 {return &queryengine.PipelineResult{Requests: reqs}, nil}- if !p.finalized && p.allPartitionsDone() {+ if !p.finalized && p.fanout.allDrained() {if err := p.finalize(); err != nil {return nil, err}@@ -196,6 +177,9 @@ func (p *groupPipeline) Run() (*queryengine.PipelineResult, error) {// appropriate group's state.func (p *groupPipeline) ProvideData(results []queryengine.QueryResult) error {for _, r := range results {+ if err := p.fanout.note(r); err != nil {+ return err+ }resp, err := parseGroupPartitionResponse(r.Data)if err != nil {return err@@ -234,10 +218,6 @@ func (p *groupPipeline) ProvideData(results []queryengine.QueryResult) error {}}}- if r.NextContinuation != "" {- return errors.New("gonative: group partition returned a continuation token (multi-page not supported in Stage 6)")- }- p.partitionsDone[r.PartitionKeyRangeID] = true}return nil}@@ -264,16 +244,6 @@ func (p *groupPipeline) initGroupState(doc groupDoc) *groupState {return s}-// allPartitionsDone returns true when every pk-range has reported.-func (p *groupPipeline) allPartitionsDone() bool {- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }- }- return true-}-// finalize walks the group map and produces one output row per group.// Emission order is unspecified (follows Go's map iteration randomization);// callers that need deterministic order should add an ORDER BY clause, whichdiff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/group_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/group_test.goindex 340910c24c..e60dd2614c 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/group_test.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/group_test.go@@ -252,20 +252,31 @@ func TestGroupPipeline_GroupKeysBeforeAggregatesInAliasOrder(t *testing.T) {assert.Equal(t, `{"cityCount":5,"country":"AE"}`, string(rows[0]))}-func TestGroupPipeline_RejectsContinuationToken(t *testing.T) {+// A group whose rows straddle a page boundary gets one output row, with the+// partials from every page folded into it.+func TestGroupPipeline_FoldsAGroupsPartialsAcrossPages(t *testing.T) {plan := newGroupPlan("c.a",[]string{"a", "n"},map[string]string{"a": "", "n": "Count"})p, err := newGroupPipeline(plan, []string{"0"})require.NoError(t, err)- _, _ = p.Run()- body := mkGroupBody(t, groupEntry{key: `"x"`, payload: `{"a":"x","n":{"item":1}}`})- err = p.ProvideData([]queryengine.QueryResult{- {PartitionKeyRangeID: "0", Data: body, NextContinuation: "cont"},+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkGroupBody(t, groupEntry{key: `"x"`, payload: `{"a":"x","n":{"item":2}}`}),+ continuation: "0-page-2"},+ {body: mkGroupBody(t,+ groupEntry{key: `"x"`, payload: `{"a":"x","n":{"item":3}}`},+ groupEntry{key: `"y"`, payload: `{"a":"y","n":{"item":1}}`},+ )},+ },})- require.Error(t, err)- assert.Contains(t, err.Error(), "continuation token")+ got := make([]string, 0, len(rows))+ for _, r := range rows {+ got = append(got, string(r))+ }+ assert.ElementsMatch(t, []string{`{"a":"x","n":5}`, `{"a":"y","n":1}`}, got)+ assert.Equal(t, map[string]int{"0": 2}, read)}func TestGroupPipeline_RejectsMissingPayloadAlias(t *testing.T) {diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/merge.go b/backend/plugin/db/cosmosdb/queryengine/gonative/merge.goindex b692450ddb..1ac99cd4cf 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/merge.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/merge.go@@ -11,9 +11,11 @@ import (// orderByQueryFilterPlaceholder is the token the gateway embeds into ORDER BY// rewritten queries. The client-side engine must substitute it before firing-// per-partition requests — with "true" on the initial page, and with a-// continuation filter comparing the last emitted order-by key on subsequent-// pages. Stage 3 handles the single-page case only; continuation is deferred.+// per-partition requests. The engine substitutes "true" and leaves it there:+// a range's later pages are fetched with the gateway's own continuation token,+// which resumes that range's enumeration, so the filter never has to encode+// where the range left off. The placeholder exists for engines that resume a+// range from a client-side continuation token instead.const orderByQueryFilterPlaceholder = "{documentdb-formattableorderbyquery-filter}"// orderByItem is each element of the per-document orderByItems array. The@@ -43,10 +45,13 @@ func parseOrderByPartitionResponse(raw []byte) (*orderByPartitionResponse, errorreturn &r, nil}-// partitionStream holds one partition's ORDER BY documents, in gateway-sorted-// order. The pipeline pops from the head as the heap selects from this-// partition; emptying the slice means the partition is drained.+// partitionStream buffers one partition's ORDER BY documents, in+// gateway-sorted order. The pipeline pops from the head as the heap selects+// from this partition; an empty buffer means the partition has delivered+// everything it has so far, which is the end of its stream only once the+// fanout reports the range drained.type partitionStream struct {+ id string // the partition key range that feeds this streamdocs []orderByDochead int // index of next doc to emit; len(docs)-head is the remaining count}@@ -119,17 +124,19 @@ func (h *mergeHeap) Pop() any {// the per-partition query to `OFFSET 0 LIMIT (offset+limit)` so every// partition delivers enough rows to satisfy any interleaving, and this// pipeline handles the global skip + take after merging.+//+// A range answers over as many pages as its share of the result needs. The+// merge therefore runs only while every range that still has pages has a row+// buffered: the first range to run dry ends the turn, because its next page+// may sort ahead of every other range's head.type orderByPipeline struct {rewrittenQuery string- pkRangeIDs []string+ fanout rangeFanoutdescending bool- partitionsDone map[string]bool- partitionByID map[string]int- partitions []*partitionStream+ partitionByID map[string]int+ partitions []*partitionStream- heap *mergeHeap- issued boolclosed bool// offset and limit implement plan.QueryInfo.Offset/Limit. A negative limit@@ -155,9 +162,9 @@ func newOrderByPipeline(plan *planDoc, pkRangeIDs []string) (*orderByPipeline, eif plan.QueryInfo.OrderBy[0] != "Ascending" && plan.QueryInfo.OrderBy[0] != "Descending" {return nil, ErrUnsupportedPlanFeature}- // Substitute the formattable-order-by-query-filter placeholder with "true"- // for the initial request per partition. Multi-page continuation (which- // would substitute with a tail-comparison filter) is out of scope here.+ // Substitute the formattable-order-by-query-filter placeholder with+ // "true": every request this pipeline makes, first page or later, selects+ // the whole range and relies on the continuation token to resume it.query := strings.ReplaceAll(plan.QueryInfo.RewrittenQuery, orderByQueryFilterPlaceholder, "true")// OFFSET/LIMIT always composes with ORDER BY per Cosmos syntax; defaults@@ -181,13 +188,12 @@ func newOrderByPipeline(plan *planDoc, pkRangeIDs []string) (*orderByPipeline, epartitions := make([]*partitionStream, len(pkRangeIDs))for i, id := range pkRangeIDs {partByID[id] = i- partitions[i] = &partitionStream{}+ partitions[i] = &partitionStream{id: id}}return &orderByPipeline{rewrittenQuery: query,- pkRangeIDs: append([]string(nil), pkRangeIDs...),+ fanout: newRangeFanout(pkRangeIDs),descending: plan.QueryInfo.OrderBy[0] == "Descending",- partitionsDone: make(map[string]bool, len(pkRangeIDs)),partitionByID: partByID,partitions: partitions,offset: offset,@@ -198,14 +204,11 @@ func newOrderByPipeline(plan *planDoc, pkRangeIDs []string) (*orderByPipeline, efunc (p *orderByPipeline) Query() string { return p.rewrittenQuery }func (p *orderByPipeline) Close() { p.closed = true }-// IsComplete returns true once every partition's gateway response has been-// merged and the last pending row has been handed to the caller, or once a-// LIMIT has been satisfied (in which case unprocessed partition rows are-// intentionally discarded).+// IsComplete returns true once every range has delivered its last page, the+// merge has consumed every buffered row and the last pending row has been+// handed to the caller, or once a LIMIT has been satisfied (in which case+// unprocessed partition rows are intentionally discarded).func (p *orderByPipeline) IsComplete() bool {- if !p.issued {- return false- }if len(p.pending) > 0 {return false}@@ -216,16 +219,11 @@ func (p *orderByPipeline) IsComplete() bool {if p.limit >= 0 && p.emitted >= p.limit {return true}- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }- }- if p.heap != nil && p.heap.Len() > 0 {+ if !p.fanout.allDrained() {return false}for _, s := range p.partitions {- if s.head < len(s.docs) {+ if _, ok := s.peek(); ok {return false}}@@ -233,40 +231,41 @@ func (p *orderByPipeline) IsComplete() bool {}// Run drives one pipeline turn.-// 1. First call: fan out one request per pk-range carrying the (substituted)-// rewritten query.-// 2. After every partition has provided data, drain the heap into `pending`,-// then emit.+// 1. Merge whatever the buffered pages make certain, and emit it.+// 2. Otherwise ask for the next page of every range the merge is waiting on+// — the initial fan-out across all ranges on the first call.func (p *orderByPipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- reqs := make([]queryengine.QueryRequest, len(p.pkRangeIDs))- for i, id := range p.pkRangeIDs {- reqs[i] = queryengine.QueryRequest{- PartitionKeyRangeID: id,- Id: uint64(i),- Query: p.rewrittenQuery,- IncludeParameters: true,- }- }- p.issued = true- return &queryengine.PipelineResult{Requests: reqs}, nil- }-- if p.heap == nil && p.allPartitionsReady() {- p.initHeap()- p.drain()- }+ p.merge()if len(p.pending) > 0 {batch := p.pendingp.pending = nilreturn &queryengine.PipelineResult{Items: batch, IsCompleted: p.IsComplete()}, nil}- return &queryengine.PipelineResult{IsCompleted: p.IsComplete()}, nil+ if p.IsComplete() {+ return &queryengine.PipelineResult{IsCompleted: true}, nil+ }+ return &queryengine.PipelineResult{Requests: p.fanout.requestsWhere(p.rewrittenQuery, p.needsPage)}, nil+}++// needsPage reports whether the merge can use another page of the named range+// yet. Only a range whose buffered rows are all consumed can: the merge pops+// in sort order, so a range that still has a row is never what blocks it, and+// fetching that range's next page early would buy a page the merge cannot use+// — a whole range's worth of them, for a query whose ORDER BY puts that+// range's rows last and whose LIMIT may stop before reaching them.+func (p *orderByPipeline) needsPage(id string) bool {+ idx, ok := p.partitionByID[id]+ if !ok {+ return false+ }+ _, buffered := p.partitions[idx].peek()+ return !buffered}-// ProvideData parses and stores each partition's response. Validates that-// every document has at least one orderByItems entry and a payload.+// ProvideData parses each response and buffers its documents against the+// range that produced them. Validates that every document has at least one+// orderByItems entry and a payload.func (p *orderByPipeline) ProvideData(results []queryengine.QueryResult) error {for _, r := range results {resp, err := parseOrderByPartitionResponse(r.Data)@@ -281,30 +280,40 @@ func (p *orderByPipeline) ProvideData(results []queryengine.QueryResult) error {return errors.Errorf("gonative: order-by doc %d missing payload", i)}}- if r.NextContinuation != "" {- return errors.New("gonative: order-by partition returned a continuation token (multi-page not supported in Stage 3)")- }idx, ok := p.partitionByID[r.PartitionKeyRangeID]if !ok {return errors.Errorf("gonative: unexpected partition id %q", r.PartitionKeyRangeID)}- p.partitions[idx].docs = append(p.partitions[idx].docs, resp.Documents...)- p.partitionsDone[r.PartitionKeyRangeID] = true+ if err := p.fanout.note(r); err != nil {+ return err+ }+ s := p.partitions[idx]+ // Drop the rows the merge has already emitted before buffering the new+ // page, so a range's buffer stays the size of its unread rows rather+ // than of everything it has ever returned.+ if s.head > 0 {+ s.docs = s.docs[s.head:]+ s.head = 0+ }+ s.docs = append(s.docs, resp.Documents...)}return nil}-func (p *orderByPipeline) allPartitionsReady() bool {- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }+// merge flushes as much of the k-way merge into p.pending as the buffered+// pages make certain. Popping the heap's top, advancing that range and+// re-pushing it emits the globally-next row; a range that runs dry while it+// still has pages ends the turn instead, because its next page may sort ahead+// of every other range's head.+//+// OFFSET/LIMIT (Stage 5) apply here: the first `offset` rows are discarded,+// and emission stops once `limit` rows have been collected (when limit >= 0).+// Both are tracked on the pipeline so the next turn resumes where this one+// stopped.+func (p *orderByPipeline) merge() {+ if p.waitingForPage() {+ return}- return true-}--// initHeap seeds the merge heap with every non-empty partition's head.-func (p *orderByPipeline) initHeap() {h := &mergeHeap{partitions: p.partitions, descending: p.descending}for i, s := range p.partitions {if _, ok := s.peek(); ok {@@ -312,30 +321,15 @@ func (p *orderByPipeline) initHeap() {}}heap.Init(h)- p.heap = h-}-// drain flushes the k-way merge into p.pending. After the single-page-// guarantee the heap holds at most one row per partition; popping the top,-// advancing that partition, and re-pushing (if not drained) emits the-// globally-next row. Runs to completion in one Run() turn.-//-// OFFSET/LIMIT (Stage 5) apply here: the first `offset` rows are discarded,-// and emission stops once `limit` rows have been collected (when limit >= 0).-// Both are tracked on the pipeline across calls so a partial drain would-// resume correctly — though in practice drain runs to completion.-func (p *orderByPipeline) drain() {- for p.heap.Len() > 0 {+ for h.Len() > 0 {if p.limit >= 0 && p.emitted >= p.limit {- // LIMIT reached — stop popping and drop the remaining heap state- // so IsComplete trips on the next turn.- p.heap.idx = p.heap.idx[:0]+ // LIMIT reached — the caller has everything it asked for.return}- top, ok := heap.Pop(p.heap).(int)+ top, ok := heap.Pop(h).(int)if !ok {// Unreachable: the heap is seeded with partition indexes only.- p.heap.idx = p.heap.idx[:0]return}s := p.partitions[top]@@ -348,7 +342,22 @@ func (p *orderByPipeline) drain() {p.emitted++}if _, ok := s.peek(); ok {- heap.Push(p.heap, top)+ heap.Push(h, top)+ continue+ }+ if !p.fanout.drained(s.id) {+ return+ }+ }+}++// waitingForPage reports whether a range has nothing buffered and pages still+// to come, which is what makes the merge's next pop uncertain.+func (p *orderByPipeline) waitingForPage() bool {+ for _, s := range p.partitions {+ if _, buffered := s.peek(); !buffered && !p.fanout.drained(s.id) {+ return true}}+ return false}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/merge_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/merge_test.goindex 4217df6a40..7a3d3cb69e 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/merge_test.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/merge_test.go@@ -344,15 +344,14 @@ func TestOrderByPipeline_OffsetBeyondAvailableRows(t *testing.T) {assert.True(t, p.IsComplete())}+// LIMIT 0 needs no row from any range, so the pipeline completes without+// asking for a page at all.func TestOrderByPipeline_LimitZero_EmitsNothing(t *testing.T) {p := newAscOffsetLimit(t, 0, 0, "0")- rows := runOnePass(t, p, map[string][]byte{- "0": mkOrderByBody(t,- ordered{ob: `1`, payload: `{"x":1}`},- ordered{ob: `2`, payload: `{"x":2}`},- ),- })- assert.Empty(t, rows)+ res, err := p.Run()+ require.NoError(t, err)+ assert.Empty(t, res.Items)+ assert.Empty(t, res.Requests)assert.True(t, p.IsComplete())}@@ -378,13 +377,127 @@ func TestNewOrderByPipeline_RejectsNegativeLimit(t *testing.T) {assert.Contains(t, err.Error(), "negative LIMIT")}-func TestOrderByPipeline_RejectsContinuationToken(t *testing.T) {- p := newAscPipeline(t, "0")- _, _ = p.Run()- body := mkOrderByBody(t, ordered{ob: `1`, payload: `{}`})- err := p.ProvideData([]queryengine.QueryResult{- {PartitionKeyRangeID: "0", Data: body, NextContinuation: "cont"},+// ------------------------------------------------------------- several pages++func TestOrderByPipeline_ResumesARangeAcrossPages(t *testing.T) {+ p := newAscPipeline(t, "0", "1")+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t,+ ordered{ob: `1`, payload: `{"x":1}`},+ ordered{ob: `5`, payload: `{"x":5}`},+ ), continuation: "0-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `9`, payload: `{"x":9}`})},+ },+ "1": {+ {body: mkOrderByBody(t, ordered{ob: `2`, payload: `{"x":2}`})},+ },})- require.Error(t, err)- assert.Contains(t, err.Error(), "continuation token")+ assert.Equal(t, []string{`{"x":1}`, `{"x":2}`, `{"x":5}`, `{"x":9}`}, asStrings(rows))+ assert.Equal(t, map[string]int{"0": 2, "1": 1}, read)+}++// A range that runs dry mid-merge must not be overtaken: its next page can+// hold a row that sorts ahead of every other range's head. Merging everything+// buffered before fetching that page would emit 1, 2, 4, 3 here.+func TestOrderByPipeline_WaitsForANextPageRatherThanOvertakeIt(t *testing.T) {+ p := newAscPipeline(t, "0", "1")+ rows, _ := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t, ordered{ob: `1`, payload: `{"x":1}`}), continuation: "0-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `3`, payload: `{"x":3}`})},+ },+ "1": {+ {body: mkOrderByBody(t,+ ordered{ob: `2`, payload: `{"x":2}`},+ ordered{ob: `4`, payload: `{"x":4}`},+ )},+ },+ })+ assert.Equal(t, []string{`{"x":1}`, `{"x":2}`, `{"x":3}`, `{"x":4}`}, asStrings(rows))+}++func TestOrderByPipeline_DescendingResumesARangeAcrossPages(t *testing.T) {+ p := newDescPipeline(t, "0", "1")+ rows, _ := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t, ordered{ob: `9`, payload: `{"x":9}`}), continuation: "0-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `5`, payload: `{"x":5}`})},+ },+ "1": {+ {body: mkOrderByBody(t,+ ordered{ob: `7`, payload: `{"x":7}`},+ ordered{ob: `1`, payload: `{"x":1}`},+ )},+ },+ })+ assert.Equal(t, []string{`{"x":9}`, `{"x":7}`, `{"x":5}`, `{"x":1}`}, asStrings(rows))+}++// A LIMIT the first page already satisfies ends the query there: the rows a+// range still holds were fetched speculatively, and its later pages are never+// asked for.+func TestOrderByPipeline_LimitStopsBeforeTheNextPage(t *testing.T) {+ p := newAscOffsetLimit(t, 0, 2, "0")+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t,+ ordered{ob: `1`, payload: `{"x":1}`},+ ordered{ob: `2`, payload: `{"x":2}`},+ ), continuation: "0-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `3`, payload: `{"x":3}`})},+ },+ })+ assert.Equal(t, []string{`{"x":1}`, `{"x":2}`}, asStrings(rows))+ assert.Equal(t, map[string]int{"0": 1}, read)+}++// An OFFSET past the first page has to read the next one to answer at all.+func TestOrderByPipeline_OffsetReachesIntoTheNextPage(t *testing.T) {+ p := newAscOffsetLimit(t, 2, 2, "0")+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t,+ ordered{ob: `1`, payload: `{"x":1}`},+ ordered{ob: `2`, payload: `{"x":2}`},+ ), continuation: "0-page-2"},+ {body: mkOrderByBody(t,+ ordered{ob: `3`, payload: `{"x":3}`},+ ordered{ob: `4`, payload: `{"x":4}`},+ )},+ },+ })+ assert.Equal(t, []string{`{"x":3}`, `{"x":4}`}, asStrings(rows))+ assert.Equal(t, map[string]int{"0": 2}, read)+}++// Ranges whose sort values do not overlap are consumed one after the other, so+// the merge must leave the later range's pages unread while it works through+// the earlier one. Asking every range with a token for its next page every+// turn buys pages the merge cannot use — here it reads range 1 twice for a+// LIMIT that never returns one of its rows.+func TestOrderByPipeline_LeavesAnUnconsumedRangesPagesUnread(t *testing.T) {+ p := newAscOffsetLimit(t, 0, 2, "0", "1")+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkOrderByBody(t, ordered{ob: `1`, payload: `{"x":1}`}), continuation: "0-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `2`, payload: `{"x":2}`})},+ },+ "1": {+ {body: mkOrderByBody(t, ordered{ob: `10`, payload: `{"x":10}`}), continuation: "1-page-2"},+ {body: mkOrderByBody(t, ordered{ob: `11`, payload: `{"x":11}`})},+ },+ })+ assert.Equal(t, []string{`{"x":1}`, `{"x":2}`}, asStrings(rows))+ assert.Equal(t, map[string]int{"0": 2, "1": 1}, read,+ "range 1 still had a buffered row, so its second page was never needed")+}++// asStrings renders emitted rows for comparison against literal fixtures.+func asStrings(rows [][]byte) []string {+ out := make([]string, 0, len(rows))+ for _, r := range rows {+ out = append(out, string(r))+ }+ return out}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline.go b/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline.goindex c0607b373e..372cef18c5 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline.go@@ -12,43 +12,22 @@ import (// aggregate pipelines. Aggregators execute in a fixed positional order — the// pipeline knows how many slots it needs before the first partition response// arrives, and which slot each partial lands in.+//+// A range that answers over several pages contributes one partial per page;+// the aggregators fold them in as they arrive, so the final row is the same+// whether a range answered in one page or in twenty.type aggPipelineBase struct {rewrittenQuery string- pkRangeIDs []string+ fanout rangeFanoutaggregators []aggregator // len == number of aggregates to emit- partitionsDone map[string]bool- issued boolemitted boolclosed bool}-// issueRequests constructs the initial fan-out: one QueryRequest per-// partition-key-range, all carrying the rewritten query the gateway produced.-func (b *aggPipelineBase) issueRequests() []queryengine.QueryRequest {- reqs := make([]queryengine.QueryRequest, len(b.pkRangeIDs))- for i, id := range b.pkRangeIDs {- reqs[i] = queryengine.QueryRequest{- PartitionKeyRangeID: id,- Id: uint64(i),- Query: b.rewrittenQuery,- IncludeParameters: true,- }- }- b.issued = true- return reqs-}--// allPartitionsDone reports whether every pk-range has finished streaming.-func (b *aggPipelineBase) allPartitionsDone() bool {- if len(b.pkRangeIDs) == 0 {- return true- }- for _, id := range b.pkRangeIDs {- if !b.partitionsDone[id] {- return false- }- }- return true+// requests returns the work to issue next: the initial fan-out across every+// range, then a follow-up for each range that still has pages to deliver.+func (b *aggPipelineBase) requests() []queryengine.QueryRequest {+ return b.fanout.requests(b.rewrittenQuery)}// -----------------------------------------------------------------------------@@ -74,9 +53,8 @@ func newValuePipeline(plan *planDoc, pkRangeIDs []string) (*valuePipeline, errorreturn &valuePipeline{aggPipelineBase: aggPipelineBase{rewrittenQuery: plan.QueryInfo.RewrittenQuery,- pkRangeIDs: pkRangeIDs,+ fanout: newRangeFanout(pkRangeIDs),aggregators: aggs,- partitionsDone: make(map[string]bool, len(pkRangeIDs)),},}, nil}@@ -91,18 +69,20 @@ func (p *valuePipeline) IsComplete() bool { return p.emitted }func (p *valuePipeline) Close() { p.closed = true }// Run drives one pipeline turn. Must be called in the order:-// 1. Run() — returns per-partition Requests on first call.+// 1. Run() — returns per-partition Requests on first call, and a follow-up+// request for every range whose last response carried a continuation.// 2. Caller invokes ProvideData for each Request's partition response.-// 3. Run() — finalizes aggregators and returns the single result row.+// 3. Run() — once every range has drained, finalizes aggregators and returns+// the single result row.func (p *valuePipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- return &queryengine.PipelineResult{Requests: p.issueRequests()}, nil- }if p.emitted {return &queryengine.PipelineResult{IsCompleted: true}, nil}- if !p.allPartitionsDone() {- // Caller has not yet fed every partition — no new work to surface.+ if reqs := p.requests(); len(reqs) > 0 {+ return &queryengine.PipelineResult{Requests: reqs}, nil+ }+ if !p.fanout.allDrained() {+ // Caller has not yet fed every range — no new work to surface.return &queryengine.PipelineResult{}, nil}item, err := p.finalRow()@@ -130,12 +110,9 @@ func (p *valuePipeline) ProvideData(results []queryengine.QueryResult) error {}}}- // Stage 1 assumes one page per partition for aggregates; NextContinuation- // should be empty. Flag explicitly if the assumption breaks.- if r.NextContinuation != "" {- return errors.New("gonative: aggregate partition returned a continuation token (multi-page not supported in Stage 1)")+ if err := p.fanout.note(r); err != nil {+ return err}- p.partitionsDone[r.PartitionKeyRangeID] = true}return nil}@@ -191,9 +168,8 @@ func newAliasedPipeline(plan *planDoc, pkRangeIDs []string) (*aliasedPipeline, ereturn &aliasedPipeline{aggPipelineBase: aggPipelineBase{rewrittenQuery: plan.QueryInfo.RewrittenQuery,- pkRangeIDs: pkRangeIDs,+ fanout: newRangeFanout(pkRangeIDs),aggregators: aggs,- partitionsDone: make(map[string]bool, len(pkRangeIDs)),},aliases: aliases,kinds: kinds,@@ -205,13 +181,13 @@ func (p *aliasedPipeline) IsComplete() bool { return p.emitted }func (p *aliasedPipeline) Close() { p.closed = true }func (p *aliasedPipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- return &queryengine.PipelineResult{Requests: p.issueRequests()}, nil- }if p.emitted {return &queryengine.PipelineResult{IsCompleted: true}, nil}- if !p.allPartitionsDone() {+ if reqs := p.requests(); len(reqs) > 0 {+ return &queryengine.PipelineResult{Requests: reqs}, nil+ }+ if !p.fanout.allDrained() {return &queryengine.PipelineResult{}, nil}item, err := p.finalRow()@@ -239,10 +215,9 @@ func (p *aliasedPipeline) ProvideData(results []queryengine.QueryResult) error {}}}- if r.NextContinuation != "" {- return errors.New("gonative: aggregate partition returned a continuation token (multi-page not supported in Stage 1)")+ if err := p.fanout.note(r); err != nil {+ return err}- p.partitionsDone[r.PartitionKeyRangeID] = true}return nil}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline_test.goindex fff9433b88..203fc34984 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline_test.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/pipeline_test.go@@ -2,6 +2,7 @@ package gonative_testimport ("encoding/json"+ "fmt""os""path/filepath""testing"@@ -150,6 +151,72 @@ func TestAggPipeline_5_5_MultiAggMinMax(t *testing.T) {assert.LessOrEqual(t, minV, maxV)}+// driveAggPagedPipeline is driveAggPipeline for a range that answers over+// several pages: it replays each captured partition body `pages` times, every+// page but the last carrying a continuation token, and returns the single+// emitted row. An aggregate folds one partial per page, so the result is the+// captured partial counted `pages` times over.+func driveAggPagedPipeline(t *testing.T, queryID, originalQuery string, pages int) json.RawMessage {+ t.Helper()+ base := filepath.Join("testdata", "query_"+queryID)+ plan := mustReadFile(t, base+"_plan.json")+ pkranges := mustReadFile(t, base+"_pkranges.json")+ bodies := partitionBodies(t, base+"_partitions")++ engine := gonative.Default()+ pipe, err := engine.CreateQueryPipeline(originalQuery, string(plan), string(pkranges))+ require.NoError(t, err, "CreateQueryPipeline")+ defer pipe.Close()++ served := make(map[string]int, len(bodies))+ var emitted json.RawMessage+ for i := 0; i < 10*pages && !pipe.IsComplete(); i++ {+ res, err := pipe.Run()+ require.NoError(t, err, "Run turn %d", i)+ if len(res.Requests) > 0 {+ results := make([]queryengine.QueryResult, 0, len(res.Requests))+ for _, req := range res.Requests {+ body, ok := bodies[req.PartitionKeyRangeID]+ require.True(t, ok, "missing fixture for pk-range %s", req.PartitionKeyRangeID)+ served[req.PartitionKeyRangeID]+++ continuation := ""+ if served[req.PartitionKeyRangeID] < pages {+ continuation = fmt.Sprintf("%s-page-%d", req.PartitionKeyRangeID, served[req.PartitionKeyRangeID])+ } else {+ require.Equal(t, pages, served[req.PartitionKeyRangeID],+ "pk-range %s was asked for a page past the script", req.PartitionKeyRangeID)+ }+ results = append(results, queryengine.NewQueryResult(req.PartitionKeyRangeID, body, continuation))+ }+ require.NoError(t, pipe.ProvideData(results))+ }+ if len(res.Items) > 0 {+ require.Len(t, res.Items, 1, "aggregate query emits exactly one row")+ emitted = append(json.RawMessage(nil), res.Items[0]...)+ }+ }+ require.True(t, pipe.IsComplete(), "pipeline did not converge")+ require.NotNil(t, emitted, "no row emitted")+ for id, pagesServed := range served {+ assert.Equal(t, pages, pagesServed, "pk-range %s must be read to its last page", id)+ }+ return emitted+}++func TestAggPipeline_ValueCountFoldsPartialsAcrossPages(t *testing.T) {+ row := driveAggPagedPipeline(t, "5_1b", `SELECT VALUE COUNT(1) FROM c`, 3)+ var n float64+ require.NoError(t, json.Unmarshal(row, &n))+ assert.EqualValues(t, 54, n, "three pages of the 18-row partial")+}++func TestAggPipeline_AliasedCountFoldsPartialsAcrossPages(t *testing.T) {+ row := driveAggPagedPipeline(t, "5_1", `SELECT COUNT(1) AS totalRecords FROM c`, 2)+ var obj map[string]any+ require.NoError(t, json.Unmarshal(row, &obj))+ assert.EqualValues(t, 36, obj["totalRecords"], "two pages of the 18-row partial")+}+// drivePipelineAll runs a pipeline end-to-end against captured fixtures and// returns every emitted row. Used for operators that emit more than one row// (DISTINCT, later Stage 3+ ORDER BY/TOP/LIMIT/GROUP BY).diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake.go b/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake.goindex c7dcf44eca..bf5fba17e1 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake.go@@ -28,16 +28,17 @@ func parseTopPartitionResponse(raw []byte) (*topPartitionResponse, error) {// Rows from each partition are concatenated and the first N are emitted.//// TOP composed with ORDER BY/DISTINCT/aggregates/GROUP BY is out of Stage 4's-// scope; the dispatch rejects those plans with ErrUnsupportedPlanFeature. The-// gateway itself already caps each partition's response size when TOP is-// requested, so concatenation + cap at N is always bounded.+// scope; the dispatch rejects those plans with ErrUnsupportedPlanFeature.+//+// A TOP larger than a response page needs several pages from a range. The+// pipeline keeps asking for them until it holds N rows, at which point it+// stops: IsComplete trips on the emitted count and no further page is+// requested, however many rows the ranges still hold.type topPipeline struct {- query string- n int- pkRangeIDs []string- partitionsDone map[string]bool- issued bool- closed bool+ query string+ n int+ fanout rangeFanout+ closed bool// pending items ready to flush to the caller, already capped at N total.pending [][]byte@@ -71,75 +72,55 @@ func newTopPipeline(plan *planDoc, pkRangeIDs []string) (*topPipeline, error) {return nil, errors.Errorf("gonative: negative TOP N=%d", n)}return &topPipeline{- n: n,- pkRangeIDs: append([]string(nil), pkRangeIDs...),- partitionsDone: make(map[string]bool, len(pkRangeIDs)),+ n: n,+ fanout: newRangeFanout(pkRangeIDs),}, nil}// Query implements queryengine.QueryPipeline.func (p *topPipeline) Query() string { return p.query }-// IsComplete returns true once either (a) we've emitted N rows or (b) every-// partition has delivered and all pending rows have been flushed.+// IsComplete returns true once either (a) we've emitted N rows — which covers+// TOP 0, so the pipeline never fires a request for it — or (b) every range has+// delivered its last page and all pending rows have been flushed.func (p *topPipeline) IsComplete() bool {if p.emitted >= p.n {return true}- if !p.issued {- return false- }if len(p.pending) > 0 {return false}- for _, id := range p.pkRangeIDs {- if !p.partitionsDone[id] {- return false- }- }- return true+ return p.fanout.allDrained()}// Close implements queryengine.QueryPipeline.func (p *topPipeline) Close() { p.closed = true }-// Run drives one pipeline turn.+// Run drives one pipeline turn: flush the rows already in hand, then ask for+// the next page of every range that has one — the initial fan-out on the first+// call.func (p *topPipeline) Run() (*queryengine.PipelineResult, error) {- if !p.issued {- // Edge case: TOP 0 — emit zero rows without firing any partition work.- if p.n == 0 {- p.issued = true- return &queryengine.PipelineResult{IsCompleted: true}, nil- }- reqs := make([]queryengine.QueryRequest, len(p.pkRangeIDs))- for i, id := range p.pkRangeIDs {- reqs[i] = queryengine.QueryRequest{- PartitionKeyRangeID: id,- Id: uint64(i),- Query: p.query,- IncludeParameters: true,- }- }- p.issued = true- return &queryengine.PipelineResult{Requests: reqs}, nil- }if len(p.pending) > 0 {batch := p.pendingp.pending = nilp.emitted += len(batch)return &queryengine.PipelineResult{Items: batch, IsCompleted: p.IsComplete()}, nil}- return &queryengine.PipelineResult{IsCompleted: p.IsComplete()}, nil+ if p.IsComplete() {+ return &queryengine.PipelineResult{IsCompleted: true}, nil+ }+ return &queryengine.PipelineResult{Requests: p.fanout.requests(p.query)}, nil}// ProvideData consumes each partition's response and appends rows to `pending`// up to the overall TOP N limit. Anything beyond N is dropped.func (p *topPipeline) ProvideData(results []queryengine.QueryResult) error {for _, r := range results {+ if err := p.fanout.note(r); err != nil {+ return err+ }if p.accumulated >= p.n {- // Already have enough rows; just mark remaining partitions done- // so IsComplete can trip.- p.partitionsDone[r.PartitionKeyRangeID] = true+ // Already have enough rows — leave this response unread.continue}resp, err := parseTopPartitionResponse(r.Data)@@ -154,10 +135,6 @@ func (p *topPipeline) ProvideData(results []queryengine.QueryResult) error {p.pending = append(p.pending, append([]byte(nil), doc...))p.accumulated++}- if r.NextContinuation != "" {- return errors.New("gonative: top partition returned a continuation token (multi-page not supported in Stage 4)")- }- p.partitionsDone[r.PartitionKeyRangeID] = true}return nil}diff --git a/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake_test.go b/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake_test.goindex 8348ef3aca..55bce60cb0 100644--- a/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake_test.go+++ b/backend/plugin/db/cosmosdb/queryengine/gonative/topskiptake_test.go@@ -160,15 +160,35 @@ func TestTopPipeline_EmptyPartitions(t *testing.T) {assert.True(t, p.IsComplete())}-func TestTopPipeline_RejectsContinuationToken(t *testing.T) {- plan := newTopPlan(5)- p, err := newTopPipeline(plan, []string{"0"})+// A TOP larger than a page reads as many pages as it takes to collect N rows.+func TestTopPipeline_ReadsPagesUntilNRowsAreInHand(t *testing.T) {+ p, err := newTopPipeline(newTopPlan(5), []string{"0"})require.NoError(t, err)- _, _ = p.Run()- err = p.ProvideData([]queryengine.QueryResult{- {PartitionKeyRangeID: "0", Data: mkTopBody(t, `{"x":1}`), NextContinuation: "cont"},+ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkTopBody(t, `{"x":1}`, `{"x":2}`), continuation: "0-page-2"},+ {body: mkTopBody(t, `{"x":3}`, `{"x":4}`), continuation: "0-page-3"},+ {body: mkTopBody(t, `{"x":5}`, `{"x":6}`)},+ },})- require.Error(t, err)- assert.Contains(t, err.Error(), "continuation token")+ assert.Len(t, rows, 5)+ assert.Equal(t, map[string]int{"0": 3}, read)+}++// Once N rows are in hand the pipeline stops, however many pages the ranges+// still hold.+func TestTopPipeline_StopsAtNWithoutReadingTheNextPage(t *testing.T) {+ p, err := newTopPipeline(newTopPlan(4), []string{"0"})+ require.NoError(t, err)++ rows, read := drivePages(t, p, map[string][]page{+ "0": {+ {body: mkTopBody(t, `{"x":1}`, `{"x":2}`), continuation: "0-page-2"},+ {body: mkTopBody(t, `{"x":3}`, `{"x":4}`), continuation: "0-page-3"},+ {body: mkTopBody(t, `{"x":5}`, `{"x":6}`)},+ },+ })+ assert.Len(t, rows, 4)+ assert.Equal(t, map[string]int{"0": 2}, read)}