package sort

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

Package sort provides type-safe sort specifications for Astra DB queries.

Sort specifications control result ordering for find, update, and delete operations. They support ascending/descending field sorts, vector similarity search, vectorize text search, and lexical text search.

Use the fluent builder for type-safe, order-preserving sorts: 

sort.Asc("rating").Desc("title")
sort.Vector([]float32{0.1, 0.2, 0.3})
sort.Vectorize("find books about space")
sort.Hybrid("search query")

Use S as a raw map escape hatch when you need full control: 

sort.S{"$vector": myVec}

Index

Constants

const Ascending = 1

Ascending is the sort order value for ascending (1). 

const Descending = -1

Descending is the sort order value for descending (-1).

Types

type Clauses

type Clauses []S

Clauses represents multiple sort specifications. Use this when you need full control over the sort JSON, or when working with sort specifications that don't fit the fluent builder.

Example: 

sort.Clauses{sort.S{"title": -1}, sort.S{"rating": 1}}
func (Clauses) MarshalAstra
func (s Clauses) MarshalAstra(_ serdes.EncodeCtx) (any, error)

type CollSort

type CollSort struct{}

CollSort is a namespace for collection-specific sort operators. Access via Coll. The returned Sort values compose with the fluent Sort.Asc / Sort.Desc / Sort.By methods like any other sort clause.

Example: 

sort.Coll.Vector(myVec)

var Coll CollSort

Coll provides access to collection-specific sort operators such as CollSort.Vector, CollSort.Vectorize, and CollSort.Lexical.

func (CollSort) Lexical
func (CollSort) Lexical(text string) Sort

Lexical creates a Sort for lexical text search using the collection's reserved $lexical field. Collection-only.

func (CollSort) Vector
func (CollSort) Vector(v any) Sort

Vector creates a Sort for vector similarity search using the collection's reserved $vector field. Collection-only.

func (CollSort) Vectorize
func (CollSort) Vectorize(text string) Sort

Vectorize creates a Sort for vectorize text search using the collection's reserved $vectorize field. Collection-only.

type HybridSort

type HybridSort struct {
	Vectorize *string
	Lexical   *string
	Vector    any
}

HybridSort represents the complex object used with the $hybrid operator.

func (HybridSort) MarshalAstra
func (h HybridSort) MarshalAstra(_ serdes.EncodeCtx) (any, error)

type S

type S map[string]any

S represents a SINGLE sort specification as a raw map. Use this when you need full control over the sort JSON, or when working with sort specifications that don't fit the fluent builder.

Example: 

sort.S{"$vector": []float32{0.1, 0.2, 0.3}}
sort.S{"rating": 1}

Since maps do not preserve order, S should only be used for single-clause sorts: 

// Don't do this:
sort.S{"title": -1, "rating": 1}

Instead, use the fluent builder or Clauses for multi-field sorts:

type Sort

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

Sort is an ordered sort specification built with fluent constructors. Unlike maps, Sort preserves the insertion order of clauses, which matters for multi-field sorts.

Create a Sort with package-level constructors: 

sort.Asc("rating")                         // ascending field sort
sort.Desc("title")                         // descending field sort
sort.Vector([]float32{0.1, 0.2, 0.3})     // vector similarity search
sort.By("my_vec", myVec)          // custom sort with raw value
sort.Vectorize("find books about space")   // vectorize text search
sort.Lexical("search query")               // lexical text search

Chain additional clauses: 

sort.Asc("rating").Desc("title")
func Asc
func Asc(field string) Sort

Asc creates a Sort with an ascending clause on the given field.

func By
func By(field string, value any) Sort

By creates a Sort with a single key-value clause.

func Desc
func Desc(field string) Sort

Desc creates a Sort with a descending clause on the given field.

func Hybrid
func Hybrid(query string) Sort

Hybrid creates a Sort for hybrid search using a simple search query.

func HybridBy
func HybridBy(h HybridSort) Sort

HybridBy creates a Sort for hybrid search using a complex HybridSort configuration.

func Lexical
func Lexical(text string) Sort

Lexical creates a Sort for lexical text search.

func Vector
func Vector(v any) Sort

Vector creates a Sort for vector similarity search. The vector parameter should be a slice of float32 or float64 values.

func Vectorize
func Vectorize(text string) Sort

Vectorize creates a Sort for vectorize text search.

func (Sort) Asc
func (s Sort) Asc(field string) Sort

Asc appends an ascending clause and returns the extended Sort.

func (Sort) By
func (s Sort) By(field string, value any) Sort

By appends a key-value clause and returns the extended Sort.

func (Sort) Desc
func (s Sort) Desc(field string) Sort

Desc appends a descending clause and returns the extended Sort.

func (Sort) MarshalAstra
func (s Sort) MarshalAstra(_ serdes.EncodeCtx) (any, error)

type Sortable

type Sortable interface {
	// contains filtered or unexported methods
}

Sortable is implemented by types that can be used as sort specifications. It is satisfied by Sort (the fluent builder) and S (raw map).

type TableSort

type TableSort struct{}

TableSort is a namespace for table-specific sort operators. Access via Table. The returned Sort values compose with the fluent Sort.Asc / Sort.Desc / Sort.By methods like any other sort clause.

Example: 

sort.Table.Vector("embedding", myVec)

var Table TableSort

Table provides access to table-specific sort operators such as TableSort.Vector, TableSort.Vectorize, and TableSort.Lexical.

func (TableSort) Lexical
func (TableSort) Lexical(key string, text string) Sort

Lexical creates a Sort for lexical text search on the given column. Table-only.

func (TableSort) Vector
func (TableSort) Vector(key string, v any) Sort

Vector creates a Sort for vector similarity search on the given column. Table-only.

func (TableSort) Vectorize
func (TableSort) Vectorize(key string, text string) Sort

Vectorize creates a Sort for vectorize text search on the given column. Table-only.