snapshot of https://github.com/blevesearch/bleve.git (master, 2026-09-15; blobs > 131072B omitted)

geov2/cells.go

@@ -0,0 +1,49 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import "github.com/blevesearch/geo/s2"
+
+// getCellSearchBounds takes a raw uint64 S2 cell ID and returns the
+// minimum and maximum uint64 values defining its absolute spatial range.
+func getCellSearchBounds(cellUint uint64) (min uint64, max uint64) {
+	cellID := s2.CellID(cellUint)
+
+	rangeMin := cellID.RangeMin()
+	rangeMax := cellID.RangeMax()
+
+	return uint64(rangeMin), uint64(rangeMax)
+}
+
+// Returns the level of the given S2 cell ID
+func getCellLevel(cell uint64) uint64 {
+	return uint64(s2.CellID(cell).Level())
+}
+
+// Returns the parent cell ID of the given S2 cell ID at the specified level
+func getParentCell(cell uint64, level int) uint64 {
+	return uint64(s2.CellID(cell).Parent(level))
+}
+
+// CalcCellsScore returns the total area of the given S2 cells
+// in level 16 cell units (maxCellLevel in the geo repo's region coverer
+// configuration - see geo/geojson/geojson_v2.go)
+func CalcCellsScore(cells []uint64) uint64 {
+	var score uint64
+	for _, cell := range cells {
+		score += calcScore(0, getCellLevel(cell))
+	}
+	return score
+}

geov2/evaluator.go

@@ -0,0 +1,122 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import segment "github.com/blevesearch/scorch_segment_api/v2"
+
+type queryEvaluator struct {
+	queryInnerCells []uint64
+	queryCrossCells []uint64
+
+	innerCells  []uint64
+	innerDocIDs []uint32
+
+	crossCells  []uint64
+	crossDocIDs []uint32
+}
+
+func NewQueryEvaluator(query Query, geoData segment.GeoShapeV2Data) *queryEvaluator {
+	return &queryEvaluator{
+		queryInnerCells: query.InnerCells(),
+		queryCrossCells: query.CrossCells(),
+		innerCells:      geoData.InnerCells(),
+		innerDocIDs:     geoData.InnerDocIDs(),
+		crossCells:      geoData.CrossCells(),
+		crossDocIDs:     geoData.CrossDocIDs(),
+	}
+}
+
+// find the leftmost index in arr where arr[i] >= target, or
+// len(arr) if no such index exists
+func binarySearchLeftmostGreaterOrEqual(arr []uint64, target uint64) int {
+	lo, hi := 0, len(arr)
+	for lo < hi {
+		mid := int(uint(lo+hi) >> 1) // bitshift avoids the addition overflow risk
+		if arr[mid] < target {
+			lo = mid + 1
+		} else {
+			hi = mid
+		}
+	}
+	return lo
+}
+
+// forEachScoredDoc invokes fn exactly once for every docID present in either
+// score map, passing that doc's inner and cross scores (0 when the doc is
+// absent from the corresponding map).
+func forEachScoredDoc(innerScores, crossScores map[uint32]uint64,
+	fn func(id uint32, inner, cross uint64)) {
+	for id, inner := range innerScores {
+		fn(id, inner, crossScores[id])
+	}
+	for id, cross := range crossScores {
+		if _, ok := innerScores[id]; !ok {
+			fn(id, 0, cross)
+		}
+	}
+}
+
+// scan and score the overlap of query inner cells with all index cells
+func (qe *queryEvaluator) rangeScanInner(innerScores, crossScores map[uint32]uint64) {
+	for _, cell := range qe.queryInnerCells {
+		minVal, maxVal := getCellSearchBounds(cell)
+		cellLevel := getCellLevel(cell)
+		rangeScanOne(cell, minVal, maxVal, cellLevel, qe.innerCells, qe.innerDocIDs, innerScores)
+		rangeScanOne(cell, minVal, maxVal, cellLevel, qe.crossCells, qe.crossDocIDs, crossScores)
+	}
+}
+
+// scan and score the overlap of query cross cells with all index cells
+func (qe *queryEvaluator) rangeScanCross(innerScores, crossScores map[uint32]uint64) {
+	for _, cell := range qe.queryCrossCells {
+		minVal, maxVal := getCellSearchBounds(cell)
+		cellLevel := getCellLevel(cell)
+		rangeScanOne(cell, minVal, maxVal, cellLevel, qe.innerCells, qe.innerDocIDs, innerScores)
+		rangeScanOne(cell, minVal, maxVal, cellLevel, qe.crossCells, qe.crossDocIDs, crossScores)
+	}
+}
+
+// scan and score the overlap of a single query cell with the given index cells
+func rangeScanOne(queryCell uint64, minVal, maxVal, cellLevel uint64,
+	indexCells []uint64, docIds []uint32, scores map[uint32]uint64) {
+	// find the range of index cells within the min/max bounds of the query cell
+	// end will be < start if there are no index cells within the bounds
+	start := binarySearchLeftmostGreaterOrEqual(indexCells, minVal)
+	end := binarySearchLeftmostGreaterOrEqual(indexCells, maxVal+1) - 1
+
+	// score all index cells within the bounds of the query cell
+	for i := start; i <= end; i++ {
+		id := docIds[i]
+		val := indexCells[i]
+
+		valLevel := getCellLevel(val)
+		scores[id] += calcScore(cellLevel, valLevel)
+	}
+
+	// score all parent cells of the query cell that are present in the index
+	// since parent cells are not within the min/max bounds
+	for level := int(cellLevel) - 1; level >= 0; level-- {
+		// get the parent cell of the query cell at this level
+		parentCell := getParentCell(queryCell, level)
+		// search for the leftmost index of this parent cell in the index cells
+		parentStart := binarySearchLeftmostGreaterOrEqual(indexCells, parentCell)
+
+		// score all index cells that match this parent cell exactly
+		for i := parentStart; i < len(indexCells) && indexCells[i] == parentCell; i++ {
+			id := docIds[i]
+			scores[id] += calcScore(cellLevel, uint64(level))
+		}
+	}
+}

geov2/evaluator_test.go

@@ -0,0 +1,128 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/blevesearch/geo/s2"
+)
+
+func TestBinarySearchLeftmostGreaterOrEqual(t *testing.T) {
+	tests := []struct {
+		name   string
+		arr    []uint64
+		target uint64
+		want   int
+	}{
+		{"empty", nil, 5, 0},
+		{"all less than target", []uint64{1, 2, 3}, 5, 3},
+		{"all greater than target", []uint64{5, 6, 7}, 1, 0},
+		{"exact match", []uint64{1, 3, 5, 7}, 5, 2},
+		{"target between elements", []uint64{1, 3, 5, 7}, 4, 2},
+		{"leftmost of duplicates", []uint64{1, 3, 3, 3, 5}, 3, 1},
+		{"target before all", []uint64{2, 4, 6}, 0, 0},
+		{"target equals last", []uint64{2, 4, 6}, 6, 2},
+		{"single element hit", []uint64{9}, 9, 0},
+		{"single element miss high", []uint64{9}, 10, 1},
+	}
+	for _, test := range tests {
+		if got := binarySearchLeftmostGreaterOrEqual(test.arr, test.target); got != test.want {
+			t.Errorf("%s: binarySearchLeftmostGreaterOrEqual(%v, %d) = %d, want %d",
+				test.name, test.arr, test.target, got, test.want)
+		}
+	}
+}
+
+// TestRangeScanOne verifies the two scoring paths of rangeScanOne: index
+// cells that fall within the query cell's range (the query cell itself and
+// its descendants), and ancestor cells found by walking the query cell's
+// parents (which lie outside the range).
+func TestRangeScanOne(t *testing.T) {
+	const queryLevel = 10
+
+	queryCell := uint64(s2.CellIDFromFace(2).ChildBeginAtLevel(queryLevel))
+	childCell := uint64(s2.CellID(queryCell).ChildBeginAtLevel(12)) // descendant, in range
+	parentCell := uint64(s2.CellID(queryCell).Parent(5))            // ancestor, out of range
+	unrelated := uint64(s2.CellIDFromFace(4).ChildBeginAtLevel(queryLevel))
+
+	// assign each cell a distinct doc ID
+	type entry struct {
+		cell  uint64
+		docID uint32
+	}
+	entries := []entry{
+		{queryCell, 0},
+		{childCell, 1},
+		{parentCell, 2},
+		{unrelated, 3},
+	}
+
+	// index cells must be sorted ascending, with docIds kept parallel
+	sort.Slice(entries, func(i, j int) bool {
+		return entries[i].cell < entries[j].cell
+	})
+	indexCells := make([]uint64, len(entries))
+	docIds := make([]uint32, len(entries))
+	for i, e := range entries {
+		indexCells[i] = e.cell
+		docIds[i] = e.docID
+	}
+
+	scores := make(map[uint32]uint64)
+	minVal, maxVal := getCellSearchBounds(queryCell)
+	rangeScanOne(queryCell, minVal, maxVal, queryLevel, indexCells, docIds, scores)
+
+	// docID 0 is the query cell itself: in range, equal levels
+	if want := calcScore(queryLevel, queryLevel); scores[0] != want {
+		t.Errorf("query cell score = %d, want %d", scores[0], want)
+	}
+	// docID 1 is a descendant at level 12: in range, index cell deeper
+	if want := calcScore(queryLevel, 12); scores[1] != want {
+		t.Errorf("descendant cell score = %d, want %d", scores[1], want)
+	}
+	// docID 2 is an ancestor at level 5: found via the parent walk
+	if want := calcScore(queryLevel, 5); scores[2] != want {
+		t.Errorf("ancestor cell score = %d, want %d", scores[2], want)
+	}
+	// docID 3 is unrelated (different face): must not be scored
+	if scores[3] != 0 {
+		t.Errorf("unrelated cell score = %d, want 0", scores[3])
+	}
+}
+
+// TestRangeScanOneNoMatches confirms that a query cell with no overlapping
+// index cells produces no scores, exercising the empty-range case where
+// end < start.
+func TestRangeScanOneNoMatches(t *testing.T) {
+	const queryLevel = 10
+	queryCell := uint64(s2.CellIDFromFace(0).ChildBeginAtLevel(queryLevel))
+
+	// index cells entirely on a different, non-ancestor part of the tree
+	indexCells := []uint64{
+		uint64(s2.CellIDFromFace(5).ChildBeginAtLevel(queryLevel)),
+		uint64(s2.CellIDFromFace(5).ChildBeginAtLevel(queryLevel).Next()),
+	}
+	docIds := []uint32{0, 1}
+	scores := make(map[uint32]uint64)
+
+	minVal, maxVal := getCellSearchBounds(queryCell)
+	rangeScanOne(queryCell, minVal, maxVal, queryLevel, indexCells, docIds, scores)
+
+	if len(scores) != 0 {
+		t.Errorf("expected no scores, got %d entries: %v", len(scores), scores)
+	}
+}

geov2/query.go

@@ -0,0 +1,42 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"github.com/blevesearch/bleve/v2/util"
+	index "github.com/blevesearch/bleve_index_api"
+	segment "github.com/blevesearch/scorch_segment_api/v2"
+)
+
+type Query interface {
+	Evaluate(geoData segment.GeoShapeV2Data) *util.Bitset
+	InnerCells() []uint64
+	CrossCells() []uint64
+}
+
+func NewQuery(shape index.GeoJSON, relation string) Query {
+	switch relation {
+	case "contains":
+		return NewContainsQuery(shape)
+	case "intersects":
+		return NewIntersectsQuery(shape)
+	case "within":
+		return NewWithinQuery(shape)
+	case "disjoint":
+		return NewDisjointQuery(shape)
+	default:
+		return nil
+	}
+}

geov2/query_contains.go

@@ -0,0 +1,141 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"bytes"
+
+	"github.com/blevesearch/bleve/v2/util"
+	index "github.com/blevesearch/bleve_index_api"
+	"github.com/blevesearch/geo/geojson"
+	segment "github.com/blevesearch/scorch_segment_api/v2"
+)
+
+type containsQuery struct {
+	innerCells []uint64
+	crossCells []uint64
+
+	shape index.GeoJSON
+	bBox  index.GeoJSON
+
+	score uint64
+}
+
+func NewContainsQuery(shape index.GeoJSON) Query {
+	inner, cross := shape.QueryCells()
+
+	score := CalcCellsScore(inner) + CalcCellsScore(cross)
+
+	return &containsQuery{
+		innerCells: inner,
+		crossCells: cross,
+		shape:      shape,
+		bBox:       shape.BoundingBox(),
+		score:      score,
+	}
+}
+
+func (cq *containsQuery) Evaluate(geoData segment.GeoShapeV2Data) *util.Bitset {
+	numDocs := int(geoData.NumDocs())
+	exclude := geoData.Excluded()
+
+	// create bitsets for hits and maybeHits providing exclude to the bitset
+	// which will make it impossible to set those bits
+	hits := util.NewBitset(numDocs, exclude)
+	maybeHits := util.NewBitset(numDocs, exclude)
+
+	// failsafe for a degenerate query shape that produced no cells
+	if cq.score == 0 {
+		return hits
+	}
+
+	// obtain zeroed score arrays from the segment-level pool and return
+	// them once the evaluation is done
+	innerScores := geoData.GetScoreMap()
+	crossScores := geoData.GetScoreMap()
+	defer geoData.PutScoreMap(innerScores)
+	defer geoData.PutScoreMap(crossScores)
+
+	// create an evaluator instance to scan the query cells against the index cells
+	evaluator := NewQueryEvaluator(cq, geoData)
+
+	// scan and score the overlap of all query cells with all index cells
+	evaluator.rangeScanInner(innerScores, crossScores)
+	evaluator.rangeScanCross(innerScores, crossScores)
+
+	// if all of the query cells are contained within the inner index cells
+	// then we have a guaranteed hit, if they are contained within both the inner
+	// and cross index cells then we have a maybe hit, otherwise we have no hit
+	forEachScoredDoc(innerScores, crossScores, func(id uint32, inner, cross uint64) {
+		docNum := int(id)
+		if inner == cq.score {
+			hits.Add(docNum)
+		} else if inner+cross == cq.score {
+			maybeHits.Add(docNum)
+		}
+	})
+
+	var reader *bytes.Reader
+
+	// filter out any maybeHits that do not have a bounding box that
+	// contains the query bounding box
+	boxFilter := func(docNum int) {
+		docBBoxBytes, err := geoData.BoundingBox(uint32(docNum))
+		if docBBoxBytes == nil || err != nil {
+			return
+		}
+
+		docBBox, err := geojson.ExtractShapesFromBytes(docBBoxBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := docBBox.Contains(cq.bBox); err == nil && !ok {
+			maybeHits.Remove(docNum)
+		}
+	}
+
+	maybeHits.Iterate(boxFilter)
+
+	// filter out any maybeHits that do not have a shape that
+	// contains the query shape
+	shapeFilter := func(docNum int) {
+		docShapeBytes, err := geoData.Shape(uint32(docNum))
+		if docShapeBytes == nil || err != nil {
+			return
+		}
+
+		docShape, err := geojson.ExtractShapesFromBytes(docShapeBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := docShape.Contains(cq.shape); err == nil && ok {
+			hits.Add(docNum)
+		}
+	}
+
+	maybeHits.Iterate(shapeFilter)
+
+	return hits
+}
+
+func (cq *containsQuery) InnerCells() []uint64 {
+	return cq.innerCells
+}
+
+func (cq *containsQuery) CrossCells() []uint64 {
+	return cq.crossCells
+}

geov2/query_disjoint.go

@@ -0,0 +1,66 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"github.com/blevesearch/bleve/v2/util"
+	index "github.com/blevesearch/bleve_index_api"
+	segment "github.com/blevesearch/scorch_segment_api/v2"
+)
+
+type disjointQuery struct {
+	innerCells []uint64
+	crossCells []uint64
+
+	shape index.GeoJSON
+	bBox  index.GeoJSON
+}
+
+func NewDisjointQuery(shape index.GeoJSON) Query {
+	inner, cross := shape.QueryCells()
+
+	return &disjointQuery{
+		innerCells: inner,
+		crossCells: cross,
+		shape:      shape,
+		bBox:       shape.BoundingBox(),
+	}
+}
+
+func (dq *disjointQuery) Evaluate(geoData segment.GeoShapeV2Data) *util.Bitset {
+	// evaluate the disjoint query by creating an intersects query and negating the results
+	intersectsQuery := &intersectsQuery{
+		innerCells: dq.innerCells,
+		crossCells: dq.crossCells,
+		shape:      dq.shape,
+		bBox:       dq.bBox,
+	}
+
+	// evaluate the intersects query to get the hits
+	hits := intersectsQuery.Evaluate(geoData)
+
+	// invert the hits to get the disjoint results
+	hits.Invert()
+
+	return hits
+}
+
+func (dq *disjointQuery) InnerCells() []uint64 {
+	return dq.innerCells
+}
+
+func (dq *disjointQuery) CrossCells() []uint64 {
+	return dq.crossCells
+}

geov2/query_intersects.go

@@ -0,0 +1,145 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"bytes"
+
+	"github.com/blevesearch/bleve/v2/util"
+	index "github.com/blevesearch/bleve_index_api"
+	"github.com/blevesearch/geo/geojson"
+	segment "github.com/blevesearch/scorch_segment_api/v2"
+)
+
+type intersectsQuery struct {
+	innerCells []uint64
+	crossCells []uint64
+
+	shape index.GeoJSON
+	bBox  index.GeoJSON
+}
+
+func NewIntersectsQuery(shape index.GeoJSON) Query {
+	inner, cross := shape.QueryCells()
+
+	return &intersectsQuery{
+		innerCells: inner,
+		crossCells: cross,
+		shape:      shape,
+		bBox:       shape.BoundingBox(),
+	}
+}
+
+func (iq *intersectsQuery) Evaluate(geoData segment.GeoShapeV2Data) *util.Bitset {
+	numDocs := int(geoData.NumDocs())
+	exclude := geoData.Excluded()
+
+	// create bitsets for hits and maybeHits providing exclude to the bitset
+	// which will make it impossible to set those bits
+	hits := util.NewBitset(numDocs, exclude)
+	maybeHits := util.NewBitset(numDocs, exclude)
+
+	// obtain zeroed score arrays from the segment-level pool and return
+	// them once the evaluation is done
+	innerScores := geoData.GetScoreMap()
+	crossScores := geoData.GetScoreMap()
+	defer geoData.PutScoreMap(innerScores)
+	defer geoData.PutScoreMap(crossScores)
+
+	// create an evaluator instance to scan the query cells against the index cells
+	evaluator := NewQueryEvaluator(iq, geoData)
+
+	// scan and score the overlap of query inner cells with all index cells
+	evaluator.rangeScanInner(innerScores, crossScores)
+
+	// if there is any overlap of query inner cells with any of the index cells
+	// then we have a guaranteed hit. Reset scores to reuse score maps for the
+	// next step
+	forEachScoredDoc(innerScores, crossScores, func(id uint32, inner, cross uint64) {
+		if inner > 0 || cross > 0 {
+			hits.Add(int(id))
+		}
+	})
+	clear(innerScores)
+	clear(crossScores)
+
+	// scan and score the overlap of query cross cells with all index cells
+	evaluator.rangeScanCross(innerScores, crossScores)
+
+	// if there is any overlap of query cross cells with any of the index inner
+	// cells then we have a guaranteed hit, if there is any overlap of query cross
+	// cells with any of the index cross cells then we have a maybe hit, otherwise
+	// we have no hit.
+	forEachScoredDoc(innerScores, crossScores, func(id uint32, inner, cross uint64) {
+		docNum := int(id)
+		if inner > 0 && !hits.Contains(docNum) {
+			hits.Add(docNum)
+		} else if cross > 0 && !hits.Contains(docNum) {
+			maybeHits.Add(docNum)
+		}
+	})
+
+	var reader *bytes.Reader
+
+	// filter out any maybeHits that do not have a bounding box that
+	// intersects the query bounding box
+	boxFilter := func(docNum int) {
+		docBBoxBytes, err := geoData.BoundingBox(uint32(docNum))
+		if docBBoxBytes == nil || err != nil {
+			return
+		}
+
+		docBBox, err := geojson.ExtractShapesFromBytes(docBBoxBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := docBBox.Intersects(iq.bBox); err == nil && !ok {
+			maybeHits.Remove(docNum)
+		}
+	}
+
+	maybeHits.Iterate(boxFilter)
+
+	// filter out any maybeHits that do not have a shape that
+	// intersects the query shape
+	shapeFilter := func(docNum int) {
+		docShapeBytes, err := geoData.Shape(uint32(docNum))
+		if docShapeBytes == nil || err != nil {
+			return
+		}
+
+		docShape, err := geojson.ExtractShapesFromBytes(docShapeBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := docShape.Intersects(iq.shape); err == nil && ok {
+			hits.Add(docNum)
+		}
+	}
+
+	maybeHits.Iterate(shapeFilter)
+
+	return hits
+}
+
+func (iq *intersectsQuery) InnerCells() []uint64 {
+	return iq.innerCells
+}
+
+func (iq *intersectsQuery) CrossCells() []uint64 {
+	return iq.crossCells
+}

geov2/query_within.go

@@ -0,0 +1,146 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"bytes"
+
+	"github.com/blevesearch/bleve/v2/util"
+	index "github.com/blevesearch/bleve_index_api"
+	"github.com/blevesearch/geo/geojson"
+	segment "github.com/blevesearch/scorch_segment_api/v2"
+)
+
+type withinQuery struct {
+	innerCells []uint64
+	crossCells []uint64
+
+	shape index.GeoJSON
+	bBox  index.GeoJSON
+}
+
+func NewWithinQuery(shape index.GeoJSON) Query {
+	inner, cross := shape.QueryCells()
+
+	return &withinQuery{
+		innerCells: inner,
+		crossCells: cross,
+		shape:      shape,
+		bBox:       shape.BoundingBox(),
+	}
+}
+
+func (wq *withinQuery) Evaluate(geoData segment.GeoShapeV2Data) *util.Bitset {
+	numDocs := int(geoData.NumDocs())
+	exclude := geoData.Excluded()
+
+	// create bitsets for hits and maybeHits providing exclude to the bitset
+	// which will make it impossible to set those bits
+	hits := util.NewBitset(numDocs, exclude)
+	maybeHits := util.NewBitset(numDocs, exclude)
+
+	// obtain zeroed score arrays from the segment-level pool and return
+	// them once the evaluation is done
+	innerScores := geoData.GetScoreMap()
+	crossScores := geoData.GetScoreMap()
+	defer geoData.PutScoreMap(innerScores)
+	defer geoData.PutScoreMap(crossScores)
+
+	docScoresInner, docScoresCross := geoData.DocScores()
+
+	// create an evaluator instance to scan the query cells against the index cells
+	evaluator := NewQueryEvaluator(wq, geoData)
+
+	// scan and score the overlap of query inner cells with all index cells
+	evaluator.rangeScanInner(innerScores, crossScores)
+
+	// if all of the index cells are contained within the query inner cells,
+	// then we have a guaranteed hit. Only consider documents with non zero
+	// total scores as hits
+	forEachScoredDoc(innerScores, crossScores, func(id uint32, inner, cross uint64) {
+		total := inner + cross
+		if total == docScoresInner[id]+docScoresCross[id] && total != 0 {
+			hits.Add(int(id))
+		}
+	})
+
+	// scan and score the overlap of query cross cells with all index cells
+	evaluator.rangeScanCross(innerScores, crossScores)
+
+	// A document is a maybe-hit once the accumulated score reaches at least
+	// its own inner-cell score. Complete overlap of index and cross scores
+	// may not always be possible due to the nature of region coverer being
+	// non exhaustive in the sense that the boundaries are not always only
+	// covered by the smallest possible cells.
+	forEachScoredDoc(innerScores, crossScores, func(id uint32, inner, cross uint64) {
+		docNum := int(id)
+		total := inner + cross
+		if !hits.Contains(docNum) && total >= docScoresInner[id] && total != 0 {
+			maybeHits.Add(docNum)
+		}
+	})
+
+	var reader *bytes.Reader
+
+	// filter out any maybeHits that do not have a bounding box that
+	// is within the query bounding box
+	boxFilter := func(docNum int) {
+		docBBoxBytes, err := geoData.BoundingBox(uint32(docNum))
+		if docBBoxBytes == nil || err != nil {
+			return
+		}
+
+		docBBox, err := geojson.ExtractShapesFromBytes(docBBoxBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := wq.bBox.Contains(docBBox); err == nil && !ok {
+			maybeHits.Remove(docNum)
+		}
+	}
+
+	maybeHits.Iterate(boxFilter)
+
+	// filter out any maybeHits that do not have a shape that
+	// is within the query shape
+	shapeFilter := func(docNum int) {
+		docShapeBytes, err := geoData.Shape(uint32(docNum))
+		if docShapeBytes == nil || err != nil {
+			return
+		}
+
+		docShape, err := geojson.ExtractShapesFromBytes(docShapeBytes, &reader, nil)
+		if err != nil {
+			return
+		}
+
+		if ok, err := wq.shape.Contains(docShape); err == nil && ok {
+			hits.Add(docNum)
+		}
+	}
+
+	maybeHits.Iterate(shapeFilter)
+
+	return hits
+}
+
+func (wq *withinQuery) InnerCells() []uint64 {
+	return wq.innerCells
+}
+
+func (wq *withinQuery) CrossCells() []uint64 {
+	return wq.crossCells
+}

geov2/score.go

@@ -0,0 +1,74 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+// pow4Table precomputes all valid powers of 4 for a uint64.
+// Array size 32 covers exp 0 through 31.
+var pow4Table = [32]uint64{
+	1,                   // 4^0
+	4,                   // 4^1
+	16,                  // 4^2
+	64,                  // 4^3
+	256,                 // 4^4
+	1024,                // 4^5
+	4096,                // 4^6
+	16384,               // 4^7
+	65536,               // 4^8
+	262144,              // 4^9
+	1048576,             // 4^10
+	4194304,             // 4^11
+	16777216,            // 4^12
+	67108864,            // 4^13
+	268435456,           // 4^14
+	1073741824,          // 4^15
+	4294967296,          // 4^16
+	17179869184,         // 4^17
+	68719476736,         // 4^18
+	274877906944,        // 4^19
+	1099511627776,       // 4^20
+	4398046511104,       // 4^21
+	17592186044416,      // 4^22
+	70368744177664,      // 4^23
+	281474976710656,     // 4^24
+	1125899906842624,    // 4^25
+	4503599627370496,    // 4^26
+	18014398509481984,   // 4^27
+	72057594037927936,   // 4^28
+	288230376151711744,  // 4^29
+	1152921504606846976, // 4^30
+	4611686018427387904, // 4^31
+}
+
+// pow4 returns 4^exp quickly using the lookup table.
+func pow4(exp uint64) uint64 {
+	if exp >= 32 {
+		// Handle overflow safely.
+		return 0
+	}
+	return pow4Table[exp]
+}
+
+// returns the overlap of query and index cells based on their levels.
+// Both levels are assumed to be at most 16 (maxCellLevel in the geo repo's
+// region coverer configuration - see geo/geojson/geojson_v2.go), the deepest
+// level used across the geoshape_v2 indexing and query cell coverings;
+// cells deeper than level 16 are outside this function's contract by design.
+func calcScore(queryCellLevel, indexCellLevel uint64) uint64 {
+	if indexCellLevel > queryCellLevel {
+		return pow4(16 - indexCellLevel)
+	} else {
+		return pow4(16 - queryCellLevel)
+	}
+}

geov2/score_test.go

@@ -0,0 +1,117 @@
+//  Copyright (c) 2026 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package geov2
+
+import (
+	"testing"
+
+	"github.com/blevesearch/geo/s2"
+)
+
+func TestPow4(t *testing.T) {
+	tests := []struct {
+		exp  uint64
+		want uint64
+	}{
+		{0, 1},
+		{1, 4},
+		{10, 1048576},
+		{15, 1073741824},
+		{31, 4611686018427387904}, // last representable power of 4 in a uint64
+		{32, 0},                   // out of range, guarded to 0
+		{100, 0},                  // well out of range, guarded to 0
+	}
+	for _, test := range tests {
+		if got := pow4(test.exp); got != test.want {
+			t.Errorf("pow4(%d) = %d, want %d", test.exp, got, test.want)
+		}
+	}
+}
+
+func TestCalcScore(t *testing.T) {
+	tests := []struct {
+		name           string
+		queryCellLevel uint64
+		indexCellLevel uint64
+		want           uint64
+	}{
+		{
+			// equal levels: the overlap is a single cell at that level
+			name: "equal levels", queryCellLevel: 16, indexCellLevel: 16, want: pow4(0),
+		},
+		{
+			name: "equal levels shallow", queryCellLevel: 6, indexCellLevel: 6, want: pow4(10),
+		},
+		{
+			// index cell is deeper (smaller): the overlap is the index cell
+			name: "index deeper", queryCellLevel: 6, indexCellLevel: 10, want: pow4(6),
+		},
+		{
+			// query cell is deeper (smaller): the overlap is the query cell
+			name: "query deeper", queryCellLevel: 11, indexCellLevel: 8, want: pow4(5),
+		},
+		{
+			name: "both at level 0", queryCellLevel: 0, indexCellLevel: 0, want: pow4(16),
+		},
+	}
+	for _, test := range tests {
+		if got := calcScore(test.queryCellLevel, test.indexCellLevel); got != test.want {
+			t.Errorf("%s: calcScore(%d, %d) = %d, want %d",
+				test.name, test.queryCellLevel, test.indexCellLevel, got, test.want)
+		}
+	}
+}
+
+// cellAtLevel returns a valid S2 cell ID at the requested level, derived
+// deterministically from a fixed face so tests do not depend on any RNG.
+func cellAtLevel(level int) uint64 {
+	return uint64(s2.CellIDFromFace(1).ChildBeginAtLevel(level))
+}
+
+func TestCalcCellsScore(t *testing.T) {
+	// build cells at known levels; each contributes calcScore(0, level)
+	// which equals pow4(16 - level)
+	cells := []uint64{
+		cellAtLevel(16), // contributes pow4(0) = 1
+		cellAtLevel(15), // contributes pow4(1) = 4
+		cellAtLevel(14), // contributes pow4(2) = 16
+	}
+	want := pow4(0) + pow4(1) + pow4(2)
+	if got := CalcCellsScore(cells); got != want {
+		t.Fatalf("CalcCellsScore = %d, want %d", got, want)
+	}
+
+	// an empty slice scores zero
+	if got := CalcCellsScore(nil); got != 0 {
+		t.Fatalf("CalcCellsScore(nil) = %d, want 0", got)
+	}
+}
+
+func TestCellLevelAndParent(t *testing.T) {
+	cell := cellAtLevel(12)
+	if got := getCellLevel(cell); got != 12 {
+		t.Fatalf("getCellLevel = %d, want 12", got)
+	}
+	parent := getParentCell(cell, 8)
+	if got := getCellLevel(parent); got != 8 {
+		t.Fatalf("getCellLevel(parent) = %d, want 8", got)
+	}
+	// the parent's range must contain the child cell
+	minVal, maxVal := getCellSearchBounds(parent)
+	if cell < minVal || cell > maxVal {
+		t.Fatalf("expected child cell %d to fall within parent bounds [%d, %d]",
+			cell, minVal, maxVal)
+	}
+}