package results

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

Index

Variables

var ErrNoDocuments error = errors.New("no documents found")
var ErrTooManyDocumentsToCount error = errors.New("too many documents")

ErrTooManyDocumentsToCount is returned when a Count command exceeds the upper bounds.

Types

type CollectionDefaultIdDefinition

type CollectionDefaultIdDefinition struct {
	// Type is the type of the default ID that the API should generate if no ID is provided in the inserted document.
	// Valid values: "uuid", "uuidv6", "uuidv7", "objectId".
	// If not specified, the default ID will be a string UUID.
	Type *CollectionIdType `json:"type,omitempty"`
}

CollectionDefaultIdDefinition represents the definition for a collection's default ID.

If `type` is not specified, the default ID will be a string UUID.

type CollectionDefinition

type CollectionDefinition struct {
	// Settings for generating ids
	DefaultId *CollectionDefaultIdDefinition `json:"defaultId,omitempty"`

	// Vector specifications for the collection
	Vector *VectorDefinition `json:"vector,omitempty"`

	// Overrides for document indexing
	Indexing *IndexingDefinition `json:"indexing,omitempty"`

	// Lexical analysis definition for the collection
	Lexical *LexicalDefinition `json:"lexical,omitempty"`

	// Reranking definition for the collection
	Rerank *RerankDefinition `json:"rerank,omitempty"`
}

CollectionDefinition represents the definition of a collection.

type CollectionDescriptor

type CollectionDescriptor struct {
	// Name of the collection.
	Name string `json:"name"`

	// Definition of the collection.
	Definition CollectionDefinition `json:"options"`
}

CollectionDescriptor represents the descriptor for a collection, including its name and definition.

type CollectionIdType

type CollectionIdType string

CollectionIdType specifies the type of auto-generated document ID when no _id is provided in an inserted document. If not set, the default is a string UUID v4. 

const (
	// CollectionIdTypeUUID uses a [UUID v4] as the default document ID.
	//
	// [UUID v4]: https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html#name-uuid-version-4
	CollectionIdTypeUUID CollectionIdType = CollectionIdType(constants.CollectionIdTypeUUID)
	// CollectionIdTypeUUIDv6 uses a UUID v6 as the default document ID.
	// UUID v6 is field-compatible with UUID v1 and supports lexicographic sorting.
	//
	// [UUID v6]: https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html#name-uuid-version-6
	CollectionIdTypeUUIDv6 CollectionIdType = CollectionIdType(constants.CollectionIdTypeUUIDv6)
	// CollectionIdTypeUUIDv7 uses a [UUID v7] as the default document ID.
	// UUID v7 is recommended for new systems as a replacement for UUID v1.
	//
	// [UUID v7]: https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html#name-uuid-version-7
	CollectionIdTypeUUIDv7 CollectionIdType = CollectionIdType(constants.CollectionIdTypeUUIDv7)
	// CollectionIdTypeObjectId uses an ObjectID as the default document ID.
	CollectionIdTypeObjectId CollectionIdType = CollectionIdType(constants.CollectionIdTypeObjectId)
)

type DataAPIError

type DataAPIError struct {
	Message        string `json:"message"`
	ErrorCode      string `json:"errorCode"`
	ExceptionClass string `json:"exceptionClass"`
	Family         string `json:"family"`
	Scope          string `json:"scope"`
	Title          string `json:"title"`
	ID             string `json:"id"`
}

DataAPIError represents errors as they are returned from the API. Example error: 

{
	"message":"Document already exists with the given _id",
	"errorCode":"DOCUMENT_ALREADY_EXISTS",
	"id":"4055f085-68d8-4c2d-8d91-90a0722b5fef",
	"title":"Document already exists with the given _id",
	"family":"REQUEST",
	"scope":"DOCUMENT"
}
func (*DataAPIError) Error
func (a *DataAPIError) Error() string

Error implements the error interface.

type DataAPIErrors

type DataAPIErrors []DataAPIError

DataAPIErrors is a slice of errors that implements error interface.

func (DataAPIErrors) Error
func (e DataAPIErrors) Error() string

Error implements the error interface for a pointer to the slice

func (DataAPIErrors) Unwrap
func (e DataAPIErrors) Unwrap() []error

Unwrap allows errors.As to look inside the slice

type DeleteResult

type DeleteResult struct {
	DeletedCount int
}

DeleteResult represents the result of a delete operation.

type EmbeddingProviderAuthInfo

type EmbeddingProviderAuthInfo struct {
	// Enabled indicates whether this auth method is supported for the provider.
	Enabled bool `json:"enabled"`

	// Tokens contains additional info on how exactly this auth method is supposed to be used.
	// Will be empty if Enabled is false.
	Tokens []EmbeddingProviderTokenInfo `json:"tokens"`
}

EmbeddingProviderAuthInfo contains information about a specific auth method (such as "HEADER", "SHARED_SECRET", or "NONE") for a specific provider.

Example: 

// openai.SupportedAuthentication["HEADER"]:
EmbeddingProviderAuthInfo{
    Enabled: true,
    Tokens: []EmbeddingProviderTokenInfo{{
        Accepted:  "x-embedding-api-key",
        Forwarded: "Authorization",
    }},
}

type EmbeddingProviderInfo

type EmbeddingProviderInfo struct {
	// DisplayName is the prettified name of the provider (as shown in the Astra portal).
	//
	// Example: "OpenAI"
	DisplayName string `json:"displayName"`

	// URL is the embeddings endpoint used for the provider. May be nil for some providers.
	//
	// May use a Python f-string-style interpolation pattern for certain providers which take
	// in additional parameters (such as huggingfaceDedicated or azureOpenAI).
	//
	// Example:
	//
	//	// openai.URL:
	//	ptr.To("https://api.openai.com/v1/")
	//
	//	// huggingfaceDedicated.URL:
	//	ptr.To("https://{endpointName}.{regionName}.{cloudName}.endpoints.huggingface.cloud/embeddings")
	URL *string `json:"url"`

	// SupportedAuthentication maps auth method names to info about that auth method for this provider.
	//
	// Possible methods include "HEADER", "SHARED_SECRET", and "NONE".
	//
	//   - "HEADER": Authentication using direct API keys passed through headers on every Data API call.
	//
	//	    coll := db.Collection("my_coll",
	//	        options.API().SetHeaders(map[string]string{
	//	            // Not tied to the collection; can be different every time.
	//	            "x-embedding-api-key": "sk-...",
	//	        }),
	//	    )
	//
	//   - "SHARED_SECRET": Authentication tied to a collection at collection creation time using the Astra KMS.
	//
	//	    _, err = db.CreateCollection(ctx, "my_coll",
	//	        options.CreateCollection().UpdateVector(
	//	            options.Vector().UpdateService(
	//	                options.VectorService().
	//	                    SetProvider("openai").
	//	                    SetModelName("text-embedding-3-small").
	//	                    // Name of the key in Astra portal's OpenAI integration (KMS):
	//	                    SetAuthentication(map[string]any{"providerKey": "*KEY_NAME*"}),
	//	            ),
	//	        ),
	//	    )
	//
	//
	//   - "NONE": For providers that do not require authentication (e.g. nvidia).
	//     No key or credential is needed when creating or using the collection.
	//
	//	    _, err = db.CreateCollection(ctx, "my_coll",
	//	        options.CreateCollection().UpdateVector(
	//	            options.Vector().UpdateService(
	//	                options.VectorService().
	//	                    SetProvider("nvidia").
	//	                    SetModelName("NV-Embed-QA"),
	//	            ),
	//	        ),
	//	    )
	//
	// Example:
	//
	//	// openai.SupportedAuthentication["HEADER"]:
	//	EmbeddingProviderAuthInfo{
	//	    Enabled: true,
	//	    Tokens: []EmbeddingProviderTokenInfo{{
	//	        Accepted:  "x-embedding-api-key",
	//	        Forwarded: "Authorization",
	//	    }},
	//	}
	SupportedAuthentication map[string]EmbeddingProviderAuthInfo `json:"supportedAuthentication"`

	// Parameters are any additional, arbitrary parameters the provider may take in. May or may not be required.
	//
	// Passed into the parameters block when creating a vectorize-enabled collection or table
	// (except for vectorDimension, which belongs in the vector dimension field).
	//
	// Example:
	//
	//	// openai.Parameters[0]:
	//	EmbeddingProviderProviderParameterInfo{
	//	    EmbeddingProviderModelParameterInfo: EmbeddingProviderModelParameterInfo{
	//	        Name:         "organizationId",
	//	        Type:         "STRING",
	//	        Required:     false,
	//	        DefaultValue: "",
	//	        Validation:   nil,
	//	        Help:         "Organization ID will be passed as an OpenAI organization",
	//	    },
	//	    DisplayName: "Organization ID",
	//	    Hint:        "Add an (optional) organization ID",
	//	}
	Parameters []EmbeddingProviderProviderParameterInfo `json:"parameters"`

	// Models are the specific models that the provider supports.
	//
	// May include an "endpoint-defined-model" for some providers, such as huggingfaceDedicated,
	// where the model may be truly arbitrary.
	//
	// Example:
	//
	//	// nvidia.Models[0]:
	//	EmbeddingProviderModelInfo{
	//	    Name:            "NV-Embed-QA",
	//	    VectorDimension: ptr.To(1024),
	//	    Parameters:      nil,
	//	}
	//
	//	// huggingfaceDedicated.Models[0]:
	//	EmbeddingProviderModelInfo{
	//	    Name:            "endpoint-defined-model",
	//	    VectorDimension: nil,
	//	    Parameters: []EmbeddingProviderModelParameterInfo{{
	//	        Name:         "vectorDimension",
	//	        Type:         "number",
	//	        Required:     true,
	//	        DefaultValue: "",
	//	        Validation:   map[string]any{"numericRange": []int{2, 3072}},
	//	        Help:         "Vector dimension to use in the database, should be the same as ...",
	//	    }},
	//	}
	Models []EmbeddingProviderModelInfo `json:"models"`
}

EmbeddingProviderInfo contains info about a specific embedding provider.

type EmbeddingProviderModelApiSupportInfo

type EmbeddingProviderModelApiSupportInfo struct {
	// Status is the current lifecycle status of the model.
	//
	// Example: ModelLifecycleStatusSupported (openai.Models[0].ApiModelSupport.Status)
	Status ModelLifecycleStatus `json:"status"`
}

EmbeddingProviderModelApiSupportInfo describes the API support status and lifecycle of a model.

Example: 

// openai.Models[0].ApiModelSupport:
EmbeddingProviderModelApiSupportInfo{Status: ModelLifecycleStatusSupported}

type EmbeddingProviderModelInfo

type EmbeddingProviderModelInfo struct {
	// Name is the name of the model to use.
	// May be "endpoint-defined-model" for providers like huggingfaceDedicated.
	//
	// Example:
	//
	//	// openai.Models[0].Name
	//	"text-embedding-3-small"
	//
	//	// huggingfaceDedicated.Models[0].Name
	//	"endpoint-defined-model"
	Name string `json:"name"`

	// VectorDimension is the preset, exact vector dimension to be used (if applicable).
	// If nil, a vectorDimension parameter will be present in Parameters instead.
	//
	// Example:
	//
	//	// openai.Models[3].VectorDimension (text-embedding-ada-002)
	//	ptr.To(1536)
	//
	//	// huggingfaceDedicated.Models[0].VectorDimension (endpoint-defined-model)
	//	nil
	VectorDimension *int `json:"vectorDimension"`

	// Parameters are any additional, arbitrary parameters the model may take in.
	//
	// Example:
	//
	//	// openai.Models[0].Parameters[0] (text-embedding-3-small):
	//	EmbeddingProviderModelParameterInfo{
	//	    Name:         "vectorDimension",
	//	    Type:         "number",
	//	    Required:     true,
	//	    DefaultValue: "1536",
	//	    Validation:   map[string]any{"numericRange": []int{2, 1536}},
	//	    Help:         "Vector dimension to use in the database and when calling OpenAI.",
	//	}
	Parameters []EmbeddingProviderModelParameterInfo `json:"parameters"`

	// ApiModelSupport describes the API support status and lifecycle of the model.
	//
	// Example:
	//
	//	// openai.Models[0].ApiModelSupport
	//	EmbeddingProviderModelApiSupportInfo{Status: ModelLifecycleStatusSupported}
	ApiModelSupport EmbeddingProviderModelApiSupportInfo `json:"apiModelSupport"`
}

EmbeddingProviderModelInfo describes a specific model offered by an embedding provider.

May include an "endpoint-defined-model" for some providers, such as huggingfaceDedicated, where the model may be truly arbitrary.

Example: 

// nvidia.Models[0]:
EmbeddingProviderModelInfo{Name: "NV-Embed-QA", VectorDimension: ptr.To(1024), Parameters: nil}

// huggingfaceDedicated.Models[0]:
EmbeddingProviderModelInfo{Name: "endpoint-defined-model", VectorDimension: nil, Parameters: [...]}

type EmbeddingProviderModelParameterInfo

type EmbeddingProviderModelParameterInfo struct {
	// Name is the name of the parameter to be passed in.
	//
	// The one exception is the vectorDimension parameter, which should be passed into the
	// dimension field of the vector block instead.
	//
	// Example: "endpointName" (huggingface.Parameters[0].Name)
	Name string `json:"name"`

	// Type is the datatype of the parameter. Commonly "number" or "STRING".
	//
	// Example: "STRING" (huggingface.Parameters[0].Type)
	Type string `json:"type"`

	// Required indicates whether the parameter is required to be passed in.
	//
	// Example: true (huggingface.Parameters[0].Required)
	Required bool `json:"required"`

	// DefaultValue is the default value of the parameter, or an empty string if there is none.
	// Will always be in string form even if Type is "number".
	//
	// Example: "" (huggingface.Parameters[0].DefaultValue)
	DefaultValue string `json:"defaultValue"`

	// Validation holds validations that may be done on the inputted value.
	// Commonly either nil, or contains a "numericRange" key with [min, max].
	//
	// Example: nil (huggingface.Parameters[0].Validation — no validation)
	Validation map[string]any `json:"validation"`

	// Help is any additional help text/information about the parameter.
	//
	// Example: "The name of your Hugging Face dedicated endpoint, the first part of the Endpoint URL."
	//   (huggingface.Parameters[0].Help)
	Help string `json:"help"`
}

EmbeddingProviderModelParameterInfo contains info about any additional, arbitrary parameter a model may take in. May or may not be required.

Passed into the parameters block when creating a vectorize-enabled collection or table (except for vectorDimension, which should be set in the vector dimension field instead).

Example: 

// openai.Models[0].Parameters[0] (text-embedding-3-small):
EmbeddingProviderModelParameterInfo{
    Name:         "vectorDimension",
    Type:         "number",
    Required:     true,
    DefaultValue: "1536",
    Validation:   []map[string]any{{"numericRange": []int{2, 1536}}},
    Help:         "Vector dimension to use in the database and when calling OpenAI.",
}

type EmbeddingProviderProviderParameterInfo

type EmbeddingProviderProviderParameterInfo struct {
	EmbeddingProviderModelParameterInfo

	// DisplayName is the UI display name for the parameter.
	//
	// Example: "Organization ID" (openai.Parameters[0].DisplayName)
	DisplayName string `json:"displayName"`

	// Hint is a short usage hint for the parameter.
	//
	// Example: "Add an (optional) organization ID" (openai.Parameters[0].Hint)
	Hint string `json:"hint"`
}

EmbeddingProviderProviderParameterInfo contains info about any additional, arbitrary parameter a provider may take in. May or may not be required. Extends EmbeddingProviderModelParameterInfo with display metadata.

Example: 

// openai.Parameters[0]:
EmbeddingProviderProviderParameterInfo{
    EmbeddingProviderModelParameterInfo: EmbeddingProviderModelParameterInfo{
        Name:         "organizationId",
        Type:         "STRING",
        Required:     false,
        DefaultValue: "",
        Validation:   nil,
        Help:         "Organization ID will be passed as an OpenAI organization",
    },
    DisplayName: "Organization ID",
    Hint:        "Add an (optional) organization ID",
}

type EmbeddingProviderTokenInfo

type EmbeddingProviderTokenInfo struct {
	// Accepted is the accepted token.
	// Most often "providerKey" for SHARED_SECRET, or "x-embedding-api-key" for HEADER.
	Accepted string `json:"accepted"`

	// Forwarded is how the token is forwarded to the embedding provider.
	Forwarded string `json:"forwarded"`
}

EmbeddingProviderTokenInfo contains info on how exactly a method of auth may be used.

Example: 

// openai.SupportedAuthentication["HEADER"].Tokens[0]:
EmbeddingProviderTokenInfo{
    Accepted:  "x-embedding-api-key",
    Forwarded: "Authorization",
}

type FindEmbeddingProvidersResult

type FindEmbeddingProvidersResult struct {
	// EmbeddingProviders is a map of embedding provider names (e.g. "openai") to information
	// about said provider (e.g. models/auth).
	//
	// Example:
	//
	//	result.EmbeddingProviders["openai"] // => EmbeddingProviderInfo{ DisplayName: "OpenAI", ... }
	EmbeddingProviders map[string]EmbeddingProviderInfo `json:"embeddingProviders"`
}

FindEmbeddingProvidersResult is the overarching result containing the EmbeddingProviders map.

Example: 

result, err := dbAdmin.FindEmbeddingProviders(ctx)
if err != nil {
    return err
}
// ["text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002"]
for _, model := range result.EmbeddingProviders["openai"].Models {
    fmt.Println(model.Name)
}

type FindRerankingProvidersResult

type FindRerankingProvidersResult struct {
	// EmbeddingProviders is a map of embedding provider names (e.g. "openai") to information
	// about said provider (e.g. models/auth).
	//
	// Example:
	//
	//	result.EmbeddingProviders["openai"] // => EmbeddingProviderInfo{ DisplayName: "OpenAI", ... }
	RerankingProviders map[string]RerankingProviderInfo `json:"rerankingProviders"`
}

FindRerankingProvidersResult is the overarching result containing the rerankingProviders map.

Example: 

result, err := dbAdmin.FindRerankingProviders(ctx)
if err != nil {
    return err
}
// ["nvidia/llama-3.2-nv-rerankqa-1b-v2"]
for _, model := range result.rerankingProviders["nvidia"].Models {
    fmt.Println(model.Name)
}

type IndexColumn

type IndexColumn struct {
	Name string
	Func string
}
func (*IndexColumn) UnmarshalAstraRaw
func (m *IndexColumn) UnmarshalAstraRaw(ctx serdes.DecodeCtx, value []byte) error

type IndexDefinition

type IndexDefinition struct {
	// Column is the name of the indexed column.
	Column IndexColumn `json:"column"`
	// Options contains index-specific configuration.
	Options *IndexDefinitionOptions `json:"options,omitempty"`
}

IndexDefinition describes which column is indexed and its options.

type IndexDefinitionOptions

type IndexDefinitionOptions struct {
	// Metric is the similarity metric for vector indexes (cosine, dot_product, euclidean).
	Metric string `json:"metric,omitempty"`
	// SourceModel is the embedding model identifier for vector indexes.
	SourceModel string `json:"sourceModel,omitempty"`
	// Ascii if true, converts non-ASCII characters to US-ASCII before indexing.
	Ascii *bool `json:"ascii,omitempty"`
	// Normalize if true, applies Unicode character normalization before indexing.
	Normalize *bool `json:"normalize,omitempty"`
	// CaseSensitive if true, enforces case-sensitive matching.
	CaseSensitive *bool `json:"caseSensitive,omitempty"`
	// Analyzer is the name of the analyzer used for the index.
	Analyzer any `json:"analyzer,omitempty"`
}

IndexDefinitionOptions contains configuration for an index.

type IndexDescriptor

type IndexDescriptor struct {
	// Name is the index identifier.
	Name string `json:"name"`
	// Definition contains the column and options for the index.
	// Only populated when explain=true.
	Definition *IndexDefinition `json:"definition,omitempty"`
	// IndexType is either "regular" or "vector".
	// Only populated when explain=true.
	IndexType string `json:"indexType,omitempty"`
}

IndexDescriptor describes an index on a table. When listing indexes with explain=true, all fields are populated. When explain=false, only Name is populated.

func (*IndexDescriptor) UnmarshalAstraRaw
func (d *IndexDescriptor) UnmarshalAstraRaw(ctx serdes.DecodeCtx, value []byte) error

UnmarshalAstraRaw implements custom unmarshaling for IndexDescriptor. The API returns either a string (name only) or an object (full metadata) depending on the explain option.

type IndexingDefinition

type IndexingDefinition struct {
	// Allow is a list of field paths to index, or ["*"] to index all fields.
	// Mutually exclusive with Deny.
	Allow []string `json:"allow,omitempty"`

	// Deny is a list of field paths to exclude from indexing, or ["*"] to disable indexing entirely.
	// Mutually exclusive with Allow.
	Deny []string `json:"deny,omitempty"`
}

IndexingDefinition holds definition for collection indexing. Only one of `Allow` or `Deny` can be specified.

type InsertManyError

type InsertManyError struct {
	// Errors contains all DataAPIErrors that occurred during the operation
	Errors DataAPIErrors

	// Result contains the partial results of the operation
	Result *InsertManyResult
}

InsertManyError represents an error that occurred during an insertMany operation. It contains the partial results (successfully inserted IDs) along with the underlying errors.

func (*InsertManyError) DecodeIDs
func (e *InsertManyError) DecodeIDs(v any) error

DecodeIDs unmarshalls the inserted IDs into v. v should be a pointer to a slice of the appropriate ID type.

func (InsertManyError) Error
func (e InsertManyError) Error() string

Error implements the error interface for InsertManyError.

func (*InsertManyError) InsertedCount
func (e *InsertManyError) InsertedCount() int

InsertedCount returns the number of documents that were successfully inserted before the error occurred.

func (*InsertManyError) RawIDs
func (e *InsertManyError) RawIDs() ([]json.RawMessage, error)

RawIDs returns the raw inserted IDs as a slice of any.

func (*InsertManyError) Unwrap
func (e *InsertManyError) Unwrap() error

Unwrap allows errors.As and errors.Is to work with the underlying errors.

type InsertManyResult

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

InsertManyResult represents the result of an insertMany operation.

func NewInsertManyResult
func NewInsertManyResult(batches []InternalInsertManyBatch, count int, warnings Warnings, target serdes.Target, desFlags serdes.DesFlags, idMapper InternalIDMapper) *InsertManyResult

NewInsertManyResult creates a new InsertManyResult.

func (*InsertManyResult) DecodeIDs
func (r *InsertManyResult) DecodeIDs(v any) error

DecodeIDs unmarshalls the inserted IDs into v. v should be a pointer to a slice of the appropriate ID type.

func (*InsertManyResult) InsertedCount
func (r *InsertManyResult) InsertedCount() int

InsertedCount returns the number of documents successfully inserted.

func (*InsertManyResult) RawIDs
func (r *InsertManyResult) RawIDs() ([]json.RawMessage, error)

RawIDs returns the raw inserted IDs as a slice of any.

func (*InsertManyResult) Warnings
func (r *InsertManyResult) Warnings() Warnings

Warnings returns any warnings from the API response.

type InsertOneResult

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

InsertOneResult represents the result of an insertOne operation.

func NewInsertOneResult
func NewInsertOneResult(insertedId json.RawMessage, warnings Warnings, targetCtx serdes.TargetDecodeCtx, target serdes.Target, desFlags serdes.DesFlags, idMapper InternalIDMapper) *InsertOneResult

NewInsertOneResult creates a new InsertOneResult.

func (*InsertOneResult) DecodeID
func (r *InsertOneResult) DecodeID(v any) error

DecodeID unmarshalls the inserted ID into v. v should be a pointer to the appropriate ID type (string, int, ObjectId, UUID, etc.)

func (*InsertOneResult) RawID
func (r *InsertOneResult) RawID() (json.RawMessage, error)

RawID returns the raw inserted ID as any.

func (*InsertOneResult) Warnings
func (r *InsertOneResult) Warnings() Warnings

Warnings returns any warnings from the API response.

type InternalIDMapper

type InternalIDMapper func(json.RawMessage, serdes.TargetDecodeCtx) json.RawMessage

type InternalInsertManyBatch

type InternalInsertManyBatch struct {
	InsertedIds []json.RawMessage
	TargetCtx   serdes.TargetDecodeCtx
}

type LexicalDefinition

type LexicalDefinition struct{}

type ModelLifecycleStatus

type ModelLifecycleStatus string

ModelLifecycleStatus is the lifecycle status of an embedding provider model. 

const (
	// ModelLifecycleStatusSupported indicates the model is actively supported and recommended for use.
	ModelLifecycleStatusSupported ModelLifecycleStatus = ModelLifecycleStatus(constants.ModelLifecycleStatusSupported)
	// ModelLifecycleStatusDeprecated indicates the model is still functional but deprecated and may be removed in the future.
	ModelLifecycleStatusDeprecated ModelLifecycleStatus = ModelLifecycleStatus(constants.ModelLifecycleStatusDeprecated)
	// ModelLifecycleStatusEndOfLife indicates the model is no longer supported and should not be used.
	ModelLifecycleStatusEndOfLife ModelLifecycleStatus = ModelLifecycleStatus(constants.ModelLifecycleStatusEndOfLife)
)

type RerankDefinition

type RerankDefinition struct{}

type RerankingProviderAuthInfo

type RerankingProviderAuthInfo struct {
	// Enabled indicates whether this auth method is supported for the provider.
	Enabled bool `json:"enabled"`

	// Tokens contains additional info on how exactly this auth method is supposed to be used.
	// Will be empty if Enabled is false.
	Tokens []RerankingProviderTokenInfo `json:"tokens"`
}

type RerankingProviderInfo

type RerankingProviderInfo struct {
	// IsDefault Shows if the reranking provider is the default one. The current default is Nvidia
	IsDefault bool `json:"isDefault"`

	// DisplayName is the prettified name of the provider (as shown in the Astra portal).
	//
	// Example: "OpenAI"
	DisplayName string `json:"displayName"`

	// SupportedAuthentication maps auth method names to info about that auth method for this provider.
	//
	// Possible methods include "HEADER", "SHARED_SECRET", and "NONE".
	//
	//   - "HEADER": Authentication using direct API keys passed through headers on every Data API call.
	//
	//	    coll := db.Collection("my_coll",
	//	        options.API().SetHeaders(map[string]string{
	//	            // Not tied to the collection; can be different every time.
	//	            "nvidia/llama-3.2-nv-rerankqa-1b-v2": "sk-...",
	//	        }),
	//	    )
	//
	//   - "SHARED_SECRET": Authentication tied to a collection at collection creation time using the Astra KMS.
	//
	//	    _, err = db.CreateCollection(ctx, "my_coll",
	//	        options.CreateCollection().UpdateVector(
	//	            options.Vector().UpdateService(
	//	                options.VectorService().
	//	                    SetProvider("nvidia").
	//	                    SetModelName("nvidia/llama-3.2-nv-rerankqa-1b-v2").
	//	                    // Name of the key in Astra portal's OpenAI integration (KMS):
	//	                    SetAuthentication(map[string]any{"providerKey": "*KEY_NAME*"}),
	//	            ),
	//	        ),
	//	    )
	//
	//
	//   - "NONE": For providers that do not require authentication (e.g. nvidia).
	//     No key or credential is needed when creating or using the collection.
	//
	//	    _, err = db.CreateCollection(ctx, "my_coll",
	//	        options.CreateCollection().UpdateVector(
	//	            options.Vector().UpdateService(
	//	                options.VectorService().
	//	                    SetProvider("nvidia").
	//	                    SetModelName("NV-Embed-QA"),
	//	            ),
	//	        ),
	//	    )
	SupportedAuthentication map[string]RerankingProviderAuthInfo `json:"supportedAuthentication"`

	// Models are the specific models that the provider supports.
	//
	// May include an "endpoint-defined-model" for some providers, such as huggingfaceDedicated,
	// where the model may be truly arbitrary.
	Models []RerankingProviderModelInfo `json:"models"`
}

RerankingProviderInfo contains info about a specific reranking provider.

type RerankingProviderModelApiSupportInfo

type RerankingProviderModelApiSupportInfo struct {
	// Status is the current lifecycle status of the model.
	Status ModelLifecycleStatus `json:"status"`
}

RerankingProviderModelApiSupportInfo describes the API support status and lifecycle of a model.

type RerankingProviderModelInfo

type RerankingProviderModelInfo struct {
	// Name is the name of the model to use.
	// May be "endpoint-defined-model" for providers like huggingfaceDedicated.
	Name string `json:"name"`

	// ApiModelSupport describes the API support status and lifecycle of the model.
	ApiModelSupport RerankingProviderModelApiSupportInfo `json:"apiModelSupport"`

	IsDefault bool `json:"isDefault"`

	// URL is the rerankings endpoint used for the provider. May be nil for some providers.
	//
	// May use a Python f-string-style interpolation pattern for certain providers which take
	// in additional parameters
	URL *string `json:"url"`

	// Properties is a free-form dictionary with string keys, describing the model.
	Properties map[string]any `json:"properties"`
}

RerankingProviderModelInfo describes a specific model offered by an reranking provider.

May include an "endpoint-defined-model" for some providers, such as huggingfaceDedicated, where the model may be truly arbitrary.

type RerankingProviderModelParameterInfo

type RerankingProviderModelParameterInfo struct {
	// Name is the name of the parameter to be passed in.
	//
	// The one exception is the vectorDimension parameter, which should be passed into the
	// dimension field of the vector block instead.
	Name string `json:"name"`

	// Type is the datatype of the parameter. Commonly "number" or "STRING".
	Type string `json:"type"`

	// Required indicates whether the parameter is required to be passed in.
	Required bool `json:"required"`

	// DefaultValue is the default value of the parameter, or an empty string if there is none.
	// Will always be in string form even if Type is "number".
	DefaultValue string `json:"defaultValue"`

	// Validation holds validations that may be done on the inputted value.
	// Commonly either nil, or contains a "numericRange" key with [min, max].
	Validation map[string]any `json:"validation"`

	// Help is any additional help text/information about the parameter.
	Help string `json:"help"`
}

type RerankingProviderProviderParameterInfo

type RerankingProviderProviderParameterInfo struct {
	RerankingProviderModelParameterInfo

	// DisplayName is the UI display name for the parameter.
	DisplayName string `json:"displayName"`

	// Hint is a short usage hint for the parameter.
	Hint string `json:"hint"`
}

RerankingProviderProviderParameterInfo contains info about any additional, arbitrary parameter a provider may take in. May or may not be required. Extends RerankingProviderModelParameterInfo with display metadata.

type RerankingProviderTokenInfo

type RerankingProviderTokenInfo struct {
	// Accepted is the accepted token.
	// Most often "providerKey" for SHARED_SECRET, or "x-reranking-api-key" for HEADER.
	Accepted string `json:"accepted"`

	// Forwarded is how the token is forwarded to the reranking provider.
	Forwarded string `json:"forwarded"`
}

RerankingProviderAuthInfo contains information about a specific auth method (such as "HEADER", "SHARED_SECRET", or "NONE") for a specific provider.

Example: 

// openai.SupportedAuthentication["HEADER"]:
RerankingProviderAuthInfo{
    Enabled: true,
    Tokens: []RerankingProviderTokenInfo{{
        Accepted:  "x-embedding-api-key",
        Forwarded: "Authorization",
    }},
}

type SingleResult

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

SingleResult represents a document returned from an operation.

func NewSingleResult
func NewSingleResult(rawResp []byte, warnings Warnings, targetCtx serdes.TargetDecodeCtx, target serdes.Target, err error, desFlags serdes.DesFlags) *SingleResult

NewSingleResult creates a new SingleResult with the given response, warnings, and error.

func (*SingleResult) Decode
func (sr *SingleResult) Decode(v any) error

Decode will unmarshal the document represented by this SingleResult into `v`. If no documents are found, returns ErrNoDocuments.

func (*SingleResult) Err
func (sr *SingleResult) Err() error

Err returns any error that occurred during the operation that produced this SingleResult.

func (*SingleResult) Raw
func (sr *SingleResult) Raw() (json.RawMessage, error)

Raw returns the raw JSON document from the API response. If no documents are found, returns ErrNoDocuments.

func (*SingleResult) Warnings
func (sr *SingleResult) Warnings() Warnings

Warnings returns any warnings from the API response. Returns nil if there were no warnings.

type TableDescriptor

type TableDescriptor struct {
	// Name of the table.
	Name string `json:"name"`

	// Definition of the table (columns and primary key).
	// Only populated when listTables is called with explain=true.
	Definition table.Definition `json:"definition"`
}

TableDescriptor represents the descriptor for a table, including its name and definition.

type UDTDescriptor

type UDTDescriptor struct {
	// Name of the user-defined type.
	Name string `json:"udtName"`

	// Definition of the user-defined type.
	// Only populated when listTypes is called with explain=true.
	Definition table.UDTDefinition `json:"definition"`
}

UDTDescriptor represents the descriptor for a user-defined type, including its name and definition.

type UpdateResult

type UpdateResult struct {
	MatchedCount  int
	ModifiedCount int
	UpsertedCount int // 0 or 1 for updateOne; 0..N for updateMany
	UpsertedId    any // nil if no upsert occurred
}

UpdateResult represents the result of an update operation (updateOne, updateMany, replaceOne).

type VectorDefinition

type VectorDefinition struct {
	// Dimension specifies the dimension of vectors stored in this collection.
	// Required for vector-enabled collections.
	Dimension *int `json:"dimension,omitempty"`

	// Metric specifies the similarity metric used for vector search.
	// Valid values are "cosine", "euclidean", or "dot_product".
	// Default is "cosine".
	Metric *string `json:"metric,omitempty"`

	// Service configures automatic vector embedding generation (vectorize).
	Service *VectorServiceDefinition `json:"service,omitempty"`
}

VectorDefinition configures vector search for a collection.

type VectorServiceDefinition

type VectorServiceDefinition struct {
	// Provider is the embedding provider name (e.g., "openai", "huggingface").
	Provider *string `json:"provider,omitempty"`

	// ModelName is the name of the embedding model to use.
	ModelName *string `json:"modelName,omitempty"`
}

VectorServiceDefinition configures the embedding service for vectorize.

type Warning

type Warning DataAPIError

Warning represents a warning returned from the API. Warnings indicate non-fatal conditions that don't prevent the operation from completing, such as missing indexes.

func (Warning) Error
func (w Warning) Error() string

Error implements the error interface for Warning.

func (*Warning) String
func (w *Warning) String() string

String implements fmt.Stringer for logging convenience.

type Warnings

type Warnings []Warning

Warnings is a slice of warnings returned from API responses.