[v17] MB-27666: Nested Fields (#70)

- Adds a `NestedDocument` interface which extends the `Document`
interface, allowing users to visit any sub-documents that may be nested
within the parent document.
- Adds a new `NewIndexInternalID` method to create an `IndexInternalID`
and also extends the API to enable getting the integer value of the
`IndexInternalID` from it.
- Extends the `IndexReader` interface to support the `Ancestors` method,
which allows the user to fetch the ancestry chain of any document ID
given. If the document does not have any ancestors (it is a root
document), an ancestry chain containing only the input document is
returned.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Abhinav Dangeti <abhinav@couchbase.com>

Author: 3 people

document.go

@@ -124,3 +124,11 @@ type SynonymDocument interface {
 	// The provided visitor function is called for each synonym field.
 	VisitSynonymFields(visitor SynonymFieldVisitor)
 }
+
+// NestedDocument is a document that contains other documents inside it.
+type NestedDocument interface {
+	Document
+	// VisitNestedDocuments allows iteration over all nested documents in the document.
+	// The provided visitor function is called for each nested document.
+	VisitNestedDocuments(visitor func(doc Document))
+}

index.go

@@ -17,6 +17,8 @@ package index
 import (
 	"bytes"
 	"context"
+	"encoding/binary"
+	"fmt"
 	"reflect"
 )
 
@@ -185,17 +187,46 @@ func (tfv *TermFieldVector) Size() int {
 		len(tfv.Field) + len(tfv.ArrayPositions)*sizeOfUint64
 }
 
-// IndexInternalID is an opaque document identifier interal to the index impl
+// IndexInternalID is an opaque document identifier internal to the index impl
 type IndexInternalID []byte
 
+// NewIndexInternalID encodes a uint64 into an 8-byte big-endian ID, reusing `buf` when possible.
+func NewIndexInternalID(buf []byte, in uint64) IndexInternalID {
+	if len(buf) != 8 {
+		if cap(buf) >= 8 {
+			buf = buf[0:8]
+		} else {
+			buf = make([]byte, 8)
+		}
+	}
+	binary.BigEndian.PutUint64(buf, in)
+	return buf
+}
+
+// NewIndexInternalIDFrom creates a new IndexInternalID by copying from `other`, reusing `buf` when possible.
+func NewIndexInternalIDFrom(buf IndexInternalID, other IndexInternalID) IndexInternalID {
+	buf = buf[:0]
+	return append(buf, other...)
+}
+
+// Equals checks if two IndexInternalID values are equal.
 func (id IndexInternalID) Equals(other IndexInternalID) bool {
 	return id.Compare(other) == 0
 }
 
+// Compare compares two IndexInternalID values, inherently comparing the encoded uint64 values.
 func (id IndexInternalID) Compare(other IndexInternalID) int {
 	return bytes.Compare(id, other)
 }
 
+// Value returns the uint64 value encoded in the IndexInternalID.
+func (id IndexInternalID) Value() (uint64, error) {
+	if len(id) != 8 {
+		return 0, fmt.Errorf("wrong len for IndexInternalID: %q", id)
+	}
+	return binary.BigEndian.Uint64(id), nil
+}
+
 type TermFieldDoc struct {
 	Term    string
 	ID      IndexInternalID
@@ -405,3 +436,48 @@ type IndexInsightsReader interface {
 	// cluster densities (or cardinalities)
 	CentroidCardinalities(field string, limit int, descending bool) (cenCards []CentroidCardinality, err error)
 }
+
+// -----------------------------------------------------------------------------
+// NestedReader is an extended index reader that supports hierarchical document structures.
+type NestedReader interface {
+	IndexReader
+	// Ancestors returns the ancestral chain for a given document ID in the index.
+	// For nested documents, this method retrieves all parent documents in the hierarchy
+	// leading up to the root document ID.
+	Ancestors(id IndexInternalID, prealloc []AncestorID) ([]AncestorID, error)
+}
+
+// AncestorID represents the identifier of an ancestor document in an ancestor chain.
+type AncestorID uint64
+
+// NewAncestorID creates a new AncestorID from the given uint64 value.
+func NewAncestorID(val uint64) AncestorID {
+	return AncestorID(val)
+}
+
+// Compare compares two AncestorID values.
+func (a AncestorID) Compare(b AncestorID) int {
+	switch {
+	case a < b:
+		return -1
+	case a > b:
+		return 1
+	default:
+		return 0
+	}
+}
+
+// Equals checks if two AncestorID values are equal.
+func (a AncestorID) Equals(b AncestorID) bool {
+	return a == b
+}
+
+// Add returns a new AncestorID by adding the given uint64 value to the current AncestorID.
+func (a AncestorID) Add(n uint64) AncestorID {
+	return AncestorID(uint64(a) + n)
+}
+
+// ToIndexInternalID converts the AncestorID to an IndexInternalID.
+func (a AncestorID) ToIndexInternalID(prealloc IndexInternalID) IndexInternalID {
+	return NewIndexInternalID(prealloc, uint64(a))
+}