package cursors

import "github.com/datastax/astra-db-go/v2/astra/cursors"

Index

Variables

var ErrCursorClosed = errors.New("cursor is closed")

ErrCursorClosed is returned when operations are attempted on a closed cursor. 

var ErrNoCurrentDocument = errors.New("no current document available")

ErrNoCurrentDocument is returned when Decode is called without a current document.

Functions

func All

func All[T any](ctx context.Context, c AbstractCursor) iter.Seq2[*T, error]

All is a helper function that returns an iterator over all remaining items in the cursor, decoding each item into type T.

This is a convenience function that combines the iteration and decoding steps into a single operation.

The iterator stops when the cursor is exhausted or an error is encountered during pagination or decoding. Err() does not need to be called separately when using this function, as any errors will be returned through the iterator. 

for item, err := range cursors.All[MyType](ctx, cursor) {
  if err != nil {
    // handle error
  }
  // use item
}

func Decode

func Decode[T any](c AbstractCursor) (T, error)

Decode is a helper function that decodes the current item from the cursor into a new value of type T.

This is a convenience function that combines the creation of the result value and the call to AbstractCursor.Decode.

The zero value of T is returned in case of a decoding error.

item, err := cursors.Decode[MyType](cursor) 

if err != nil {
  // handle error
}

func DecodeAll

func DecodeAll[T any](ctx context.Context, c AbstractCursor) ([]T, error)

DecodeAll is a helper function that exhausts the cursor, decoding all remaining items into a new slice of type T.

This is a convenience function that combines the creation of the results slice and the call to AbstractCursor.DecodeAll.

A nil slice is returned in case of a decoding error. 

items, err := cursors.DecodeAll[MyType](ctx, cursor)
if err != nil {
  // handle error
}

Types

type AbstractCursor

type AbstractCursor interface {
	// State returns the current state of the cursor.
	//
	// See CursorState for more details on the possible states.
	//
	//  cursor := ...
	//  fmt.Println(cursor.State()) // "idle"
	//
	//  cursor.Next(ctx)
	//  fmt.Println(cursor.State()) // "started"
	//
	//  cursor.Close()
	//  fmt.Println(cursor.State()) // "closed"
	State() CursorState
	// Buffered returns the number of items currently buffered in the cursor.
	//
	// This is the number of items that can be consumed without triggering
	// a fetch of the next page.
	Buffered() int
	// Next advances the cursor to the next item, returning true if there are no
	// errors and is another item available.
	//
	// If Next returns false, the loop has either reached the end of the data
	// or an error occurred during pagination; use Err() to distinguish between
	// the two. Subsequent calls will return false unless the cursor is rewound.
	//
	//  for cursor.Next(ctx) {
	//    var item MyType
	//    if err := cursor.Decode(&item); err != nil {
	//      // handle decode error
	//    }
	//  }
	//
	//  if err := cursor.Err(); err != nil {
	//    // handle cursor error
	//  }
	Next(ctx context.Context) bool
	// Decode decodes the current item into result without advancing the cursor.
	// result must be a pointer to the appropriate type.
	//
	// Multiple calls to Decode will return the same item until Next is called.
	// If the buffer is empty or the cursor has not been started, it returns an error.
	// Errors during decoding do not affect the cursor's state or the result pointer.
	//
	//  for cursor.Next(ctx) {
	//    var item MyType
	//    err := cursor.Decode(&item)
	//  }
	//
	// See cursors.Decode for a helper function that creates the result value and decodes into it in one step.
	Decode(result any) error
	// DecodeAll exhausts the cursor, decoding all remaining items into results.
	// results must be a pointer to a slice of the appropriate type.
	//
	// This is a terminal operation; except for parameter validation errors, the cursor
	// is closed upon return. If the cursor is already closed, it returns ErrCursorClosed.
	// The results slice will not be modified in the case of an error.
	//
	//  var items []MyType
	//  err := cursor.DecodeAll(ctx, &items)
	//
	// See cursors.DecodeAll for a helper function that creates the results slice and decodes into it in one step.
	DecodeAll(ctx context.Context, results any) error
	// DecodeBuffered decodes up to max items from the current buffer into results and advances the cursor.
	// The results argument must be a pointer to a slice of the appropriate type.
	//
	// If max is 0, all buffered items are decoded. If the buffer is
	// empty, results is set to an empty slice and no error is returned.
	//
	// DecodeBuffered never fetches the next page from the server. If an error occurs during decoding,
	// the cursor state remains unchanged/unadvanced, and the results slice is not modified.
	//
	//  var items []MyType
	//  err := cursor.DecodeBuffered(&items, 0)
	DecodeBuffered(results any, max int) error
	// Err returns the error, if any, that was encountered during iteration.
	//
	// If Err returns a non-nil error, it implies that the cursor is closed,
	// and no further operations can be performed on it until it is rewound.
	//
	// This method primarily reports errors encountered during pagination (e.g., network errors, server errors).
	// Errors encountered during decoding (e.g., malformed data) are returned directly by the Decode and DecodeAll
	// methods and do not affect the cursor's state.
	Err() error
	// Rewind resets the cursor to its initial state, allowing iteration to start over.
	//
	// All initial options and parameters are preserved, but any buffered data is cleared
	// and the cursor state is reset to idle, and the cursor may be used afresh.
	Rewind()
	// Close explicitly closes the cursor, clearing the buffer and preventing any further operations until it is rewound.
	//
	// The cursor is automatically closed when it is exhausted or encounters an error during pagination,
	// but Close can be used to proactively release resources.
	Close()
}

AbstractCursor represents some lazy, abstract iterable over any arbitrary data, which may or may not be paginated.

Example usages: 

if cursor.Next(ctx) {
  var item MyType
  err := cursor.Decode(&item)
}

items, err := cursors.DecodeAll[MyType](ctx, cursor)

This type is goroutine safe and may be used concurrently across multiple goroutines.

type CollectionFindAndRerankCursor

type CollectionFindAndRerankCursor struct {
	// contains filtered or unexported fields
}

CollectionFindAndRerankCursor is a cursor for iterating over documents returned by a collection findAndRerank operation.

Example usage: 

cursor := collection.FindAndRerank(ctx, filter, opts)
defer cursor.Close()

for cursor.Next(ctx) {
  var doc MyDocument
  if err := cursor.Decode(&doc); err != nil {
    // handle decode error
  }
  // use doc
}

if err := cursor.Err(); err != nil {
  // handle cursor error
}

This type is goroutine safe and may be used concurrently across multiple goroutines.

func NewCollectionFindAndRerankCursor
func NewCollectionFindAndRerankCursor(filter any, opts *options.CollectionFindAndRerankOptions, fetcher findLikeCursorFetcher, err error) *CollectionFindAndRerankCursor

NewCollectionFindAndRerankCursor creates a new collection findAndRerank cursor.

This method is not intended to be called directly by users. Instead, use Collection.FindAndRerank() which will create a CollectionFindAndRerankCursor for you.

Note that opts must not be nil, or it will panic.

func (*CollectionFindAndRerankCursor) Clone
func (c *CollectionFindAndRerankCursor) Clone() *CollectionFindAndRerankCursor

Clone creates a new CollectionFindAndRerankCursor with the same configuration.

func (CollectionFindAndRerankCursor) GetScores
func (c CollectionFindAndRerankCursor) GetScores() map[string]float32

GetScores returns the scores for the current document in the cursor.

type CollectionFindCursor

type CollectionFindCursor struct {
	// contains filtered or unexported fields
}

CollectionFindCursor is a cursor for iterating over documents returned by a collection find operation.

Example usage: 

cursor := collection.Find(ctx, filter, opts)
defer cursor.Close()

for cursor.Next(ctx) {
  var doc MyDocument
  if err := cursor.Decode(&doc); err != nil {
    // handle decode error
  }
  // use doc
}

if err := cursor.Err(); err != nil {
  // handle cursor error
}

This type is goroutine safe and may be used concurrently across multiple goroutines.

func NewCollectionFindCursor
func NewCollectionFindCursor(filter any, opts *options.CollectionFindOptions, fetcher findLikeCursorFetcher, err error) *CollectionFindCursor

NewCollectionFindCursor creates a new collection find cursor

This method is not intended to be called directly by users. Instead, use Collection.Find() which will create a CollectionFindCursor for you.

Note that opts must not be nil, or it will panic.

func (*CollectionFindCursor) Clone
func (c *CollectionFindCursor) Clone() *CollectionFindCursor

Clone creates a new CollectionFindCursor with the same filter, options, and fetcher.

This allows you to create multiple independent cursors that iterate over the same query results. 

cursor1 := collection.Find(ctx, filter, opts)
cursor2 := cursor1.Clone()

// cursor1 and cursor2 can be used independently

type CursorState

type CursorState int

CursorState represents the current state of a cursor. 

const (
	// CursorStateIdle means the cursor has not started iteration.
	//
	// A newly created or rewound cursor will be in this state.
	CursorStateIdle CursorState = iota
	// CursorStateStarted means the cursor is actively iterating.
	//
	// A cursor which has fetched an item will be in this state,
	// even if no items were consumed.
	CursorStateStarted
	// CursorStateClosed means the cursor has been explicitly closed.
	//
	// A cursor that has been closed, exhausted, or has encountered
	// an error, will be in this state.
	CursorStateClosed
)
func (CursorState) String
func (c CursorState) String() string

type FindAndRerankCursor

type FindAndRerankCursor interface {
	AbstractCursor

	// GetScores returns the reranking scores for the current document in the cursor.
	//
	// Scores are only available if IncludeScores was set to true in the options.
	// If scores are not available, this method returns nil.
	GetScores() map[string]float32

	// GetSortVector returns the sort vector used to perform the vector search, if applicable.
	//
	// This method will:
	// 1. Return `nil` if `IncludeSortVector` was not set to `true`
	// 2. Return the original vector if sort.Vector was used
	// 3. Return the generated vector if sort.Vectorize was used
	// 4. Return `nil` if vector search was not used
	//
	// If the sort vector is already in memory, it'll return that; otherwise it'll call the server.
	// If an error occurs while fetching a sort vector, cursor.Err() will be set.
	//
	//  vec := cursor.GetSortVector(ctx)
	//  if vec != nil {
	//    // use the sort vector
	//  }
	GetSortVector(ctx context.Context) *datatypes.Vector

	// Warnings returns all warnings accumulated during cursor operations.
	//
	// Warnings are collected from each page fetch and include any non-fatal issues
	// reported by the server during query execution.
	//
	//  if warnings := cursor.warnings(); len(warnings) > 0 {
	//    // handle warnings
	//  }
	Warnings() results.Warnings
}

FindAndRerankCursor is a lazy iterable over the results of a findAndRerank operation.

Example usage: 

cursor := collection.FindAndRerank(filter, options.CollectionFindAndRerank().
    SetSort(sort.Hybrid("search query")).
    SetLimit(10).
    SetIncludeScores(true))

for cursor.Next(ctx) {
    var doc MyDocument
    if err := cursor.Decode(&doc); err != nil {
        // handle error
    }

    // Access reranking scores
    scores := cursor.GetScores()
}

This type is goroutine safe and may be used concurrently across multiple goroutines.

type FindCursor

type FindCursor interface {
	AbstractCursor
	// GetSortVector returns the sort vector used to perform the vector search, if applicable.
	//
	// This method will:
	// 1. Return `nil` if `IncludeSortVector` was not set to `true`
	// 2. Return the original vector if sort.Vector was used
	// 3. Return the generated vector if sort.Vectorize was used
	// 4. Return `nil` if vector search was not used
	//
	// If the sort vector is already in memory, it'll return that; otherwise it'll call the server.
	// If an error occurs while fetching a sort vector, cursor.Err() will be set.
	//
	//  vec := cursor.GetSortVector(ctx)
	//  if vec != nil {
	//    // use the sort vector
	//  }
	GetSortVector(ctx context.Context) *datatypes.Vector
	// Warnings returns all warnings accumulated during cursor operations.
	//
	// Warnings are collected from each page fetch and include any non-fatal issues
	// reported by the server during query execution.
	//
	//  for cursor.Next(ctx) {
	//    // process items
	//  }
	//
	//  if warnings := cursor.warnings(); len(warnings) > 0 {
	//    // handle warnings
	//  }
	Warnings() results.Warnings
}

FindCursor is a lazy iterable over the results of a find operation on a collection or table.

Example usage: 

cursor := collection.Find(ctx, filter, opts)

for cursor.Next(ctx) {
  var doc MyType
  err := cursor.Decode(&doc)
}

This type is goroutine safe and may be used concurrently across multiple goroutines.

type RerankedResult

type RerankedResult[T any] struct {
	// Document is the decoded document.
	Document T

	// Scores contains the reranking scores for the document.
	Scores map[string]float32
}

RerankedResult is a wrapper for a document returned by a findAndRerank operation, which also includes the scores calculated during the reranking process.

Example usage with cursors.All: 

for res, err := range cursors.All[cursors.RerankedResult[MyDoc]](ctx, cursor) {
    if err != nil { /* ... */ }
    fmt.Println(res.Document)
    fmt.Println(res.Scores)
}

Alternatively, FindAndRerankCursor.GetScores may be used to access the scores for the current document without using a RerankedResult wrapper.

type TableFindCursor

type TableFindCursor struct {
	// contains filtered or unexported fields
}

TableFindCursor is a cursor for iterating over rows returned by a table find operation.

Example usage: 

cursor := table.Find(ctx, filter, opts)
defer cursor.Close()

for cursor.Next(ctx) {
  var row MyRow
  if err := cursor.Decode(&row); err != nil {
    // handle decode error
  }
  // use row
}

if err := cursor.Err(); err != nil {
  // handle cursor error
}

This type is goroutine safe and may be used concurrently across multiple goroutines.

func NewTableFindCursor
func NewTableFindCursor(filter any, opts *options.TableFindOptions, fetcher findLikeCursorFetcher, err error) *TableFindCursor

NewTableFindCursor creates a new table find cursor

This method is not intended to be called directly by users. Instead, use Table.Find() which will create a TableFindCursor for you.

Note that opts must not be nil, or it will panic.

func (*TableFindCursor) Clone
func (c *TableFindCursor) Clone() *TableFindCursor

Clone creates a new TableFindCursor with the same filter, options, and fetcher.

This allows you to create multiple independent cursors that iterate over the same query results. 

cursor1 := table.Find(ctx, filter, opts)
cursor2 := cursor1.Clone()

// cursor1 and cursor2 can be used independently