Documentation
¶
Overview ¶
Package mariadb exposes MariaDB's native VECTOR column type through the Core vector-store capability interfaces. Documents live in a regular MariaDB table (id / content / metadata JSON / embedding VECTOR) reached through `database/sql` + the go-sql-driver/mysql driver. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: MariaDB Community Server 11.7+, or Enterprise Server 11.4.5-3+ — "vectors are available from MariaDB Community Server 11.7 and from MariaDB Enterprise Server 11.4.5-3". 11.7 is a rolling release; 11.8 is the first LTS to include vectors. There is no 11.6 with vector support.
Distance metrics: DistanceCosine (uses `vec_distance_cosine`) / DistanceEuclidean (uses `vec_distance_euclidean`). A MariaDB vector index is built for one distance function and serves only queries that name that same function, so StoreConfig.InitializeSchema states the configured metric as the index's DISTANCE option. A table provisioned elsewhere must declare the matching DISTANCE, or searches fall back to a full table scan and still return correct rows — a degradation nothing surfaces.
Vector binding. MariaDB accepts vectors through the `VEC_FromText` function — the store renders `[v1,v2,...]` as a literal and lets MariaDB parse it. Typed binary binding isn't exposed by the Go driver yet, but the textual form is fully supported.
Filter visitor reaches into the JSON metadata column with `JSON_VALUE(metadata, '$.k')`, wrapping numeric comparisons in `CAST(... AS DECIMAL(65,30))` so range queries don't fall back to lexicographic ordering.
Partial writes. Index prepares one upsert and runs it per document without wrapping the batch in a transaction, so a failure leaves the rows already written in place. The returned error names the id that failed, and repeating the call is safe because the statement is idempotent per row.
Numeric comparisons cast to DECIMAL, not DOUBLE. DOUBLE is an approximate type whose 53-bit mantissa cannot hold every int64, so an id or timestamp past 2^53 would compare equal to its neighbor and match the wrong row. DECIMAL stores exact values up to the documented 65 digits, which covers every integer the filter AST can carry — and the AST compares as a rational precisely so an integer is never rounded to a float's precision.
See https://mariadb.com/kb/en/vector-overview/ for the official reference.
Index ¶
- Constants
- type DistanceMetric
- type Store
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const ( DefaultTableName = "vector_store" DefaultIDColumn = "id" DefaultContentColumn = "content" DefaultMetadataColumn = "metadata" DefaultEmbeddingColumn = "embedding" DefaultDistanceMetric = DistanceCosine )
Exported defaults keep constructor behavior visible and overridable.
const Provider = "MariaDB"
Provider is the stable backend name for host-side attribution.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric selects the vec_distance_<metric> function used at query time and the distance ordering MariaDB applies under the vector index.
const ( // DistanceCosine — cosine distance. Default. DistanceCosine DistanceMetric = "cosine" // DistanceEuclidean — Euclidean (L2) distance. DistanceEuclidean DistanceMetric = "euclidean" )
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vector-store capabilities with the VECTOR column type and vec_distance_* functions introduced in MariaDB Community Server 11.7.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore performs schema setup during construction, which is why it takes a context: a store returned before its table and vector index exist would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes rows by primary key. MariaDB has no array type, so it emits one `?` placeholder per id — `DELETE FROM <table> WHERE <id> IN (?, ?, ...)` — binding the ids as query args. An empty slice is a no-op; unknown ids are silently ignored (idempotent). Implements vectorstore.IDDeleter.
func (*Store) DeleteWhere ¶
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
Index embeds documents and upserts them into the vector table.
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
Search embeds the query, ranks rows by vec_distance, and returns matching documents above MinScore.
type StoreConfig ¶
type StoreConfig struct {
// DB is the database handle. Required. Use a *sql.DB built from
// the github.com/go-sql-driver/mysql driver pointed at a MariaDB
// 11.7+ instance (or Enterprise Server 11.4.5-3+) with vector support.
DB *sql.DB
// SchemaName is the optional schema (database) prefix. When
// empty the connection's default database is used.
SchemaName string
// TableName is the table that stores documents and their
// embeddings. Optional: defaults to [DefaultTableName].
TableName string
// IDColumn / ContentColumn / MetadataColumn / EmbeddingColumn
// override the column names of the generated schema. Each
// defaults to its respective Default* constant when empty.
IDColumn string
ContentColumn string
MetadataColumn string
EmbeddingColumn string
// EmbeddingModel produces vectors for the documents. Required.
EmbeddingModel embedding.Model
// DocumentBatcher batches documents before insertion. Required.
DocumentBatcher vectorstore.Batcher
// Dimensions sets the VECTOR column width, and is required when
// InitializeSchema is true: the width is part of the column type, and
// nothing here can read it off a table that does not exist yet.
Dimensions int
// DistanceMetric selects the distance function. Optional:
// defaults to [DistanceCosine].
DistanceMetric DistanceMetric
// InitializeSchema, when true, creates the table + vector index
// if they don't already exist.
InitializeSchema bool
}
StoreConfig contains configuration options for the MariaDB vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files