@an5/adapters 0.2.11 → 0.2.14

package/golang/an5_adapter.go

@@ -68,6 +68,9 @@ func GetRelationsForModel(modelName string) map[string]RelationDef {
 type An5Adapter struct {
 	DB      *sql.DB
 	Dialect Dialect
+	// VectorSupport carries the SQLite vector settings. Set it before the first
+	// search to load sqlite-vec or to pin a strategy.
+	VectorSupport sqlite.VectorSupport
 }
 
 // NewAn5Adapter constructs an An5Adapter instance.
@@ -167,14 +170,47 @@ func (a *An5Adapter) VectorSearch(ctx context.Context, tableName string, targetV
 	vecBytes, _ := json.Marshal(targetVector)
 	vecStr := string(vecBytes)
 
-	// 1. Primary path: Native database SQL vector query execution via dialect provider (mssql / postgres / sqlite)
+	// 1. SQLite ranks through sqlite-vec, a driver function or json_each,
+	//    whichever this connection supports, so the table never has to leave the
+	//    database. `database/sql` cannot register a user function, so the UDF
+	//    strategy needs the driver to install them; see sqlite.RegisterVectorFunctions.
+	if a.Dialect == base.DialectSqlite {
+		tail := ""
+		if strings.TrimSpace(whereClause) != "" {
+			tail = " WHERE " + whereClause
+		}
+		support := a.VectorSupport
+		ranked, ran, err := sqlite.RunVectorSearch(
+			ctx,
+			a.DB,
+			a.QueryRaw,
+			base.QuoteTable(tableName, a.Dialect),
+			sqlite.NormalizeTableName(tableName),
+			base.QuoteIdentifier(vectorField, a.Dialect),
+			vectorField,
+			targetVector,
+			distanceMetric,
+			take,
+			tail,
+			args,
+			support,
+		)
+		if err != nil {
+			return nil, err
+		}
+		if ran {
+			return DecodeVectorRows(ranked, vectorField), nil
+		}
+		// No in-database strategy: score the column in Go instead.
+		return a.vectorSearchInMemory(ctx, tableName, targetVector, take, whereClause, vectorField, distanceMetric, args)
+	}
+
+	// 2. Primary path: Native database SQL vector query execution via dialect provider (mssql / postgres)
 	var sqlQuery string
 	if a.Dialect == base.DialectPostgres {
 		sqlQuery = postgres.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
 	} else if a.Dialect == base.DialectMssql {
 		sqlQuery = mssql.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
-	} else if a.Dialect == base.DialectSqlite {
-		sqlQuery = sqlite.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
 	}
 
 	if sqlQuery != "" {
@@ -185,7 +221,7 @@ func (a *An5Adapter) VectorSearch(ctx context.Context, tableName string, targetV
 		}
 	}
 
-	// 2. Secondary fallback: Fetch rows and compute vector distance in-memory if DB lacks native vector extensions
+	// 3. Secondary fallback: Fetch rows and compute vector distance in-memory if DB lacks native vector extensions
 	fallbackQuery := "SELECT * FROM " + base.QuoteTable(tableName, a.Dialect)
 	if strings.TrimSpace(whereClause) != "" {
 		fallbackQuery += " WHERE " + whereClause
@@ -199,6 +235,45 @@ func (a *An5Adapter) VectorSearch(ctx context.Context, tableName string, targetV
 	return VectorSearchFallback(rows, targetVector, take, vectorField, distanceMetric), nil
 }
 
+// vectorSearchInMemory loads the table and scores the vector column in Go.
+//
+// The last resort for every provider, and the only option on a SQLite connection
+// that offers neither sqlite-vec, a driver function nor JSON1. The whole table is
+// loaded, so it is only reasonable for a table small enough to fit in memory.
+func (a *An5Adapter) vectorSearchInMemory(ctx context.Context, tableName string, targetVector []float64, take int, whereClause string, vectorField string, distanceMetric string, args []interface{}) ([]map[string]interface{}, error) {
+	query := "SELECT * FROM " + base.QuoteTable(tableName, a.Dialect)
+	if strings.TrimSpace(whereClause) != "" {
+		query += " WHERE " + whereClause
+	}
+	rows, err := a.QueryRaw(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	return VectorSearchFallback(rows, targetVector, take, vectorField, distanceMetric), nil
+}
+
+// DecodeVectorRows replaces every stored `VECTOR(n)` column with a decoded
+// float64 slice, so a caller reads numbers rather than float32 bytes or JSON text.
+func DecodeVectorRows(rows []map[string]interface{}, vectorField string) []map[string]interface{} {
+	for _, row := range rows {
+		for key, value := range row {
+			if key != vectorField {
+				continue
+			}
+			decoded := base.DecodeVector(value)
+			if decoded == nil {
+				continue
+			}
+			// A `distance` column is a real number, not a stored vector.
+			if key == "distance" {
+				continue
+			}
+			row[key] = decoded
+		}
+	}
+	return rows
+}
+
 // VectorSearchFallback ranks rows in-memory.
 func VectorSearchFallback(rows []map[string]interface{}, targetVector []float64, take int, vectorField string, distanceMetric string) []map[string]interface{} {
 	type scored struct {
@@ -213,36 +288,14 @@ func VectorSearchFallback(rows []map[string]interface{}, targetVector []float64,
 			continue
 		}
 
-		var rowVec []float64
-		switch v := raw.(type) {
-		case string:
-			_ = json.Unmarshal([]byte(v), &rowVec)
-		case []byte:
-			_ = json.Unmarshal(v, &rowVec)
-		case []float64:
-			rowVec = v
-		case []interface{}:
-			for _, item := range v {
-				if f, ok := item.(float64); ok {
-					rowVec = append(rowVec, f)
-				}
-			}
-		}
-
-		if len(rowVec) != len(targetVector) {
+		// A float32 BLOB, a legacy JSON text column and an already-decoded slice
+		// all read the same way.
+		rowVec := base.DecodeVector(raw)
+		dist, ok := base.VectorDistance(targetVector, rowVec, distanceMetric)
+		if !ok {
 			continue
 		}
 
-		var dist float64
-		switch strings.ToLower(distanceMetric) {
-		case "euclidean":
-			dist = base.EuclideanDistance(targetVector, rowVec)
-		case "dot":
-			dist = -base.DotProduct(targetVector, rowVec)
-		default: // cosine
-			dist = 1.0 - base.CosineSimilarity(targetVector, rowVec)
-		}
-
 		rCopy := make(map[string]interface{})
 		for k, val := range r {
 			rCopy[k] = val
@@ -311,4 +364,3 @@ func (a *An5Adapter) ExecuteProc(ctx context.Context, procName string, args ...i
 	}
 	return a.ExecuteRaw(ctx, sql, args...)
 }
-

package/golang/base/vectors.go

@@ -0,0 +1,263 @@
+package base
+
+import (
+	"encoding/binary"
+	"encoding/json"
+	"math"
+	"strings"
+)
+
+// ─── SQLite vector codec ──────────────────────────────────────────────────────────
+//
+// SQLite has no vector type, so a `VECTOR(n)` column stores a BLOB of little-endian
+// float32 values. These helpers are shared by the adapter (which reads and writes
+// the column) and by the `sqlite` package (which builds the ranking SQL).
+//
+// BytesPerVectorFloat is the size of one stored value; the column length in bytes
+// is the dimension times this, which is what the sqlite-vec strategy filters on.
+const BytesPerVectorFloat = 4
+
+// Vector field kinds the generated clients can describe.
+const (
+	VectorStrategySqliteVec = "sqlite-vec"
+	VectorStrategyUdf       = "udf"
+	VectorStrategySQL       = "sql"
+	VectorStrategyMemory    = "memory"
+)
+
+// An5VectorFunctions are the scalar functions the driver may register so SQLite
+// itself ranks the column.
+var An5VectorFunctions = map[string]string{
+	"cosine":    "an5_vec_cosine",
+	"euclidean": "an5_vec_l2",
+	"dot":       "an5_vec_ip",
+}
+
+// SqliteVecFunctions are the scalar functions the sqlite-vec extension provides.
+var SqliteVecFunctions = map[string]string{
+	"cosine":    "vec_distance_cosine",
+	"euclidean": "vec_distance_l2",
+	"dot":       "vec_distance_ip",
+}
+
+// EncodeVector encodes a vector as the little-endian float32 BLOB the column stores.
+func EncodeVector(values []float64) []byte {
+	bytes := make([]byte, len(values)*BytesPerVectorFloat)
+	for i, v := range values {
+		binary.LittleEndian.PutUint32(bytes[i*BytesPerVectorFloat:], math.Float32bits(float32(v)))
+	}
+	return bytes
+}
+
+// ParseVector reads a numeric sequence, or JSON text holding one.
+func ParseVector(value interface{}) []float64 {
+	switch v := value.(type) {
+	case nil:
+		return nil
+	case []float64:
+		return v
+	case float32:
+		return []float64{float64(v)}
+	case float64:
+		return []float64{v}
+	case []float32:
+		out := make([]float64, len(v))
+		for i, f := range v {
+			out[i] = float64(f)
+		}
+		return out
+	case string:
+		trimmed := strings.TrimSpace(v)
+		if !strings.HasPrefix(trimmed, "[") {
+			return nil
+		}
+		var parsed []float64
+		if err := json.Unmarshal([]byte(trimmed), &parsed); err != nil {
+			return nil
+		}
+		return ParseVector(parsed)
+	case []byte:
+		// `database/sql` hands a BLOB column over as bytes; whether that is
+		// float32 storage or JSON text is decided by its length and first byte.
+		if len(v) > 0 && v[0] == '[' {
+			var parsed []float64
+			if err := json.Unmarshal(v, &parsed); err != nil {
+				return nil
+			}
+			return ParseVector(parsed)
+		}
+		return DecodeVector(v)
+	case []interface{}:
+		out := make([]float64, 0, len(v))
+		for _, item := range v {
+			f, ok := item.(float64)
+			if !ok {
+				return nil
+			}
+			out = append(out, f)
+		}
+		return out
+	default:
+		return nil
+	}
+}
+
+// DecodeVector decodes a stored vector: a float32 BLOB, a legacy JSON text
+// column, or a sequence the driver already decoded.
+func DecodeVector(value interface{}) []float64 {
+	if bytes, ok := value.([]byte); ok {
+		if len(bytes) == 0 || len(bytes)%BytesPerVectorFloat != 0 {
+			// Not float32 storage; it may still be JSON text in the same column.
+			return ParseVector(string(bytes))
+		}
+		if len(bytes) > 0 && bytes[0] == '[' {
+			var parsed []float64
+			if json.Unmarshal(bytes, &parsed) == nil { return parsed }
+		}
+		out := make([]float64, len(bytes)/BytesPerVectorFloat)
+		for i := range out {
+			out[i] = float64(math.Float32frombits(binary.LittleEndian.Uint32(bytes[i*BytesPerVectorFloat:])))
+		}
+		return out
+	}
+	return ParseVector(value)
+}
+
+// NeedsVectorEncoding reports whether a value still has to become bytes on its
+// way into a `VECTOR(n)` column. `[]float64` and `[]interface{}` are the shapes
+// a caller writes; text and bytes are already stored forms and pass through.
+func NeedsVectorEncoding(value interface{}) bool {
+	switch value.(type) {
+	case nil, string, []byte:
+		return false
+	case []float64, []float32:
+		return true
+	case []interface{}:
+		return len(value.([]interface{})) > 0
+	default:
+		return false
+	}
+}
+
+// IsVectorField reports whether generated metadata describes a `VECTOR(n)` column.
+// The metadata value is a map of field name to a small record, so both a typed
+// struct and a plain map are accepted.
+func IsVectorField(definition interface{}) bool {
+	switch def := definition.(type) {
+	case nil:
+		return false
+	case string:
+		return strings.Contains(def, "[]") || strings.HasPrefix(strings.ToUpper(strings.TrimSpace(def)), "VECTOR")
+	case map[string]interface{}:
+		if kind, _ := def["kind"].(string); kind == "vector" {
+			return true
+		}
+		for _, key := range []string{"sql", "type"} {
+			if sql, ok := def[key].(string); ok && sqlLooksVector(sql) {
+				return true
+			}
+		}
+		ts, _ := def["ts"].(string)
+		return strings.Contains(ts, "[]")
+	default:
+		return false
+	}
+}
+
+// sqlLooksVector reports whether a declared SQL type names a vector column.
+func sqlLooksVector(sql string) bool {
+	trimmed := strings.ToUpper(strings.TrimSpace(sql))
+	if !strings.HasPrefix(trimmed, "VECTOR") {
+		return false
+	}
+	rest := trimmed[len("VECTOR"):]
+	return rest == "" || strings.HasPrefix(rest, "(") || strings.HasPrefix(rest, " ")
+}
+
+// PlanVectorStrategies returns the ordered strategies to try for a connection.
+//
+// capabilities reports what the connection supports; declaredType is the
+// column's DDL type, because the JSON strategy only reaches rows stored as text
+// and so a BLOB column drops it from the order. preference pins one strategy.
+func PlanVectorStrategies(capabilities map[string]bool, declaredType, preference string) []string {
+	if preference != "" && preference != "auto" {
+		if preference == VectorStrategyMemory {
+			return nil
+		}
+		return []string{preference}
+	}
+
+	var available []string
+	if capabilities["vec"] {
+		available = append(available, VectorStrategySqliteVec)
+	}
+	if capabilities["udf"] {
+		available = append(available, VectorStrategyUdf)
+	}
+	if capabilities["json1"] {
+		available = append(available, VectorStrategySQL)
+	}
+
+	declared := strings.ToUpper(strings.TrimSpace(declaredType))
+	if declared != "" && !strings.Contains(declared, "TEXT") && !strings.Contains(declared, "CHAR") &&
+		!strings.Contains(declared, "CLOB") && !strings.Contains(declared, "STRING") &&
+		!strings.Contains(declared, "JSON") {
+		return without(available, VectorStrategySQL)
+	}
+	return available
+}
+
+func without(list []string, item string) []string {
+	out := make([]string, 0, len(list))
+	for _, entry := range list {
+		if entry != item {
+			out = append(out, entry)
+		}
+	}
+	return out
+}
+
+// NormalizeMetric returns a known metric name, defaulting to cosine.
+func NormalizeMetric(metric string) string {
+	switch strings.ToLower(strings.TrimSpace(metric)) {
+	case "euclidean", "dot":
+		return strings.ToLower(strings.TrimSpace(metric))
+	default:
+		return "cosine"
+	}
+}
+
+// VectorDistance returns the distance between two equal-length vectors, lower is
+// closer. It mirrors the SQL functions so a search ranks the same way whichever
+// strategy ran. The second result is false when the pair cannot be scored, which
+// is how a stored vector of another dimension is kept out of the ranking.
+func VectorDistance(a, b []float64, metric string) (float64, bool) {
+	if len(a) == 0 || len(a) != len(b) {
+		return 0, false
+	}
+	switch NormalizeMetric(metric) {
+	case "euclidean":
+		return EuclideanDistance(a, b), true
+	case "dot":
+		return -DotProduct(a, b), true
+	default:
+		m1 := math.Sqrt(sumOfSquares(a))
+		m2 := math.Sqrt(sumOfSquares(b))
+		if m1 == 0 || m2 == 0 {
+			return 1.0, true
+		}
+		var dot float64
+		for i := range a {
+			dot += a[i] * b[i]
+		}
+		return 1.0 - dot/(m1*m2), true
+	}
+}
+
+func sumOfSquares(values []float64) float64 {
+	var sum float64
+	for _, v := range values {
+		sum += v * v
+	}
+	return sum
+}

package/golang/sqlite/vector.go

@@ -0,0 +1,248 @@
+// Package sqlite provides SQLite specific dialect execution and query generation for AN5 Go Adapters.
+//
+// SQLite has no vector type, so a `VECTOR(n)` column stores a BLOB of little-endian
+// float32 values and is ranked in one of four ways, in this order:
+//
+//  1. sqlite-vec  native scalar distances, when the driver loaded the extension.
+//  2. udf         an5_vec_cosine / an5_vec_l2 / an5_vec_ip registered with the
+//     driver. Reads the BLOB and the legacy JSON text.
+//  3. sql         json_each brute force in plain SQL. Needs no user function, so it
+//     works with any driver, but only reaches rows stored as JSON text.
+//  4. memory      the column is loaded and scored in Go.
+//
+// Strategies 1-3 rank inside the database and transfer only the matching rows,
+// which is why they are preferred over the in-memory path.
+package sqlite
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"an5adapters/base"
+)
+
+// BuildVectorSearchQuery returns empty string as SQLite ranks through its own
+// strategies; see RunVectorSearch for the statements it builds.
+func BuildVectorSearchQuery(table, field, metric string, dim, take int, where string) string {
+	_ = base.QuoteTable(table, base.DialectSqlite)
+	_ = base.QuoteIdentifier(field, base.DialectSqlite)
+	// Native vector extension not present in standard sqlite; in-memory fallback is used.
+	return ""
+}
+
+// VectorSupport carries what a SQLite connection needs for in-database vector
+// search: the path to the sqlite-vec extension to load and a strategy to pin
+// instead of probing.
+type VectorSupport struct {
+	// SqliteVecPath names the sqlite-vec extension binary. It is only used to
+	// report what the caller asked for; loading the extension is the driver's
+	// job (mattn/go-sqlite3 takes it in the DSN as `_loc`/`_x` style options, and
+	// modernc.org/sqlite through its own LoadExtension API).
+	SqliteVecPath string
+	// VectorStrategy pins "sqlite-vec", "udf", "sql" or "memory". Empty probes.
+	VectorStrategy string
+}
+
+// ScalarFuncRegistrar installs a scalar function with a driver. `database/sql`
+// has no API for this, so a driver has to hand one over:
+//
+//	sql.Register("an5-sqlite3", &sqlite3.SQLiteDriver{
+//	    ConnectHook: func(c *sqlite3.SQLiteConn) error {
+//	        return sqlite.RegisterVectorFunctions(c.RegisterFunc)
+//	    },
+//	})
+func RegisterVectorFunctions(register func(name string, impl interface{}, pure bool) error) error {
+	for metric, name := range base.An5VectorFunctions {
+		captured := metric
+		if err := register(name, func(a, b interface{}) interface{} {
+			distance, ok := base.VectorDistance(base.DecodeVector(a), base.DecodeVector(b), captured)
+			if !ok { return nil }
+			return distance
+		}, true); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Capabilities probes what this connection can do, once per call. Both probes are
+// cheap `SELECT`s; the sqlite-vec one fails on a connection without the extension,
+// and the user-function one on a driver that never registered them.
+func Capabilities(ctx context.Context, db *sql.DB) map[string]bool {
+	caps := map[string]bool{"vec": false, "udf": false, "json1": false}
+	if db == nil {
+		return caps
+	}
+
+	row := db.QueryRowContext(ctx, "SELECT vec_version()")
+	var version interface{}
+	if err := row.Scan(&version); err == nil {
+		caps["vec"] = true
+	}
+
+	// The probe has to reach a real distance: a driver that resolved the name
+	// would still fail on the arguments otherwise.
+	row = db.QueryRowContext(ctx, "SELECT an5_vec_cosine(zeroblob(4), zeroblob(4))")
+	var distance interface{}
+	if err := row.Scan(&distance); err == nil {
+		caps["udf"] = true
+	}
+
+	row = db.QueryRowContext(ctx, "SELECT json_valid('[1]')")
+	var jsonOK interface{}
+	if err := row.Scan(&jsonOK); err == nil {
+		caps["json1"] = true
+	}
+
+	return caps
+}
+
+// ReadColumnType returns a vector column's declared DDL type, or "" when the
+// table or column is not there.
+func ReadColumnType(ctx context.Context, db *sql.DB, table, column string) string {
+	row := db.QueryRowContext(ctx, "SELECT type FROM pragma_table_info(?) WHERE name = ?", table, column)
+	var declared sql.NullString
+	if err := row.Scan(&declared); err != nil || !declared.Valid {
+		return ""
+	}
+	return declared.String
+}
+
+// jsonText guards the JSON path: `json_valid` fails on a float32 BLOB.
+func jsonText(column string) string {
+	return fmt.Sprintf("CASE WHEN json_valid(%s) THEN %s ELSE '[]' END", column, column)
+}
+
+func jsonDistanceExpr(metric, column string) string {
+	row := jsonText(column)
+	sameLength := fmt.Sprintf("(SELECT COUNT(*) FROM json_each(%s)) = (SELECT COUNT(*) FROM q)", row)
+
+	var terms string
+	switch metric {
+	case "euclidean":
+		terms = fmt.Sprintf("sqrt((SELECT SUM((je.value - q.v) * (je.value - q.v)) FROM json_each(%s) je JOIN q ON q.k = je.key))", row)
+	case "dot":
+		terms = fmt.Sprintf("-(SELECT SUM(je.value * q.v) FROM json_each(%s) je JOIN q ON q.k = je.key)", row)
+	default:
+		terms = fmt.Sprintf("1.0 - (SELECT SUM(je.value * q.v) FROM json_each(%s) je JOIN q ON q.k = je.key)"+
+			" / NULLIF(sqrt((SELECT SUM(q.v * q.v) FROM q)) * sqrt((SELECT SUM(je.value * je.value) FROM json_each(%s) je)), 0)", row, row)
+	}
+	return fmt.Sprintf("CASE WHEN %s THEN %s END", sameLength, terms)
+}
+
+// BuildRankingQuery returns the ranking SQL for one strategy, with the arguments
+// the query vector needs appended to `args`.
+//
+// sqlite-vec and udf bind the query vector as a float32 BLOB; sql binds it as
+// JSON text because json_each reads text.
+//
+// A row whose stored vector cannot be scored (a NULL, a text column, another
+// dimension) yields a NULL distance; those rows are dropped rather than reported,
+// so a caller never has to sort them out of the result.
+func BuildRankingQuery(strategy, metric, table, column string, vector []float64, take int, tail string, args []interface{}) (string, []interface{}) {
+	rank := func(inner string) string {
+		return fmt.Sprintf("SELECT * FROM (%s) AS an5_ranked WHERE distance IS NOT NULL ORDER BY distance ASC LIMIT %d", inner, take)
+	}
+
+	switch metric {
+	case "euclidean", "dot":
+	default:
+		metric = "cosine"
+	}
+
+	if strategy == base.VectorStrategySqliteVec {
+		fn, ok := base.SqliteVecFunctions[metric]
+		if !ok {
+			return "", args
+		}
+		// sqlite-vec only understands float32 BLOB operands, so rows stored any
+		// other way are excluded instead of aborting the query. The guard joins the
+		// caller's WHERE with AND, since the ranking query is where both apply.
+		guard := fmt.Sprintf("%s IS NOT NULL", column)
+		// `tail` carries its own leading " WHERE", so it is appended after AND.
+		if tail != "" {
+			guard += " AND" + strings.Replace(tail, " WHERE ", " ", 1)
+		}
+		inner := fmt.Sprintf("SELECT *, CASE WHEN vec_length(vec_f32(%s)) = %d THEN %s(vec_f32(%s), ?) END AS distance FROM %s WHERE %s",
+			column, len(vector), fn, column, table, guard)
+		return rank(inner), append([]interface{}{base.EncodeVector(vector)}, args...)
+	}
+
+	if strategy == base.VectorStrategyUdf {
+		fn, ok := base.An5VectorFunctions[metric]
+		if !ok {
+			return "", args
+		}
+		inner := fmt.Sprintf("SELECT *, %s(%s, ?) AS distance FROM %s%s", fn, column, table, tail)
+		return rank(inner), append([]interface{}{base.EncodeVector(vector)}, args...)
+	}
+
+	payload, err := json.Marshal(vector)
+	if err != nil {
+		return "", args
+	}
+	inner := fmt.Sprintf("SELECT *, %s AS distance FROM %s%s", jsonDistanceExpr(metric, column), table, tail)
+	prefix := "WITH q AS (SELECT je.key AS k, CAST(je.value AS REAL) AS v FROM json_each(?) je) "
+	return prefix + rank(inner), append([]interface{}{string(payload)}, args...)
+}
+
+// RunVectorSearch ranks a SQLite table inside the database, trying each available
+// strategy in order. It reports whether a strategy ran: when none does, the
+// caller falls back to scoring in memory.
+func RunVectorSearch(
+	ctx context.Context,
+	db *sql.DB,
+	exec func(ctx context.Context, query string, args ...interface{}) ([]map[string]interface{}, error),
+	table, rawTable, column, rawColumn string,
+	vector []float64,
+	metric string,
+	take int,
+	tail string,
+	args []interface{},
+	support VectorSupport,
+) ([]map[string]interface{}, bool, error) {
+	if len(vector) == 0 {
+		return nil, false, nil
+	}
+
+	caps := Capabilities(ctx, db)
+	if db == nil {
+		return nil, false, nil
+	}
+	declared := ReadColumnType(ctx, db, rawTable, rawColumn)
+
+	for _, strategy := range base.PlanVectorStrategies(caps, declared, support.VectorStrategy) {
+		if strategy == base.VectorStrategySQL {
+			clause := " WHERE "
+			if tail != "" { clause = tail + " AND " }
+			binary, err := exec(ctx, "SELECT 1 FROM " + table + clause + "typeof(" + column + ") = 'blob' LIMIT 1", args...)
+			if err != nil || len(binary) > 0 { continue }
+		}
+		query, queryArgs := BuildRankingQuery(strategy, metric, table, column, vector, take, tail, args)
+		if query == "" {
+			continue
+		}
+		rows, err := exec(ctx, query, queryArgs...)
+		if err == nil {
+			return rows, true, nil
+		}
+		// The connection advertised the capability but the query failed, e.g. an
+		// extension that did not really load. The next strategy is cheaper than
+		// reporting the failure, and memory is the last resort.
+	}
+	return nil, false, nil
+}
+
+// NormalizeTableName reduces a mapped table name to the bare name
+// `pragma_table_info` takes as a plain string: the last segment of a qualified
+// name, with the quoting a generated client may have left around it removed.
+func NormalizeTableName(name string) string {
+	trimmed := strings.TrimSpace(name)
+	if index := strings.LastIndex(trimmed, "."); index >= 0 {
+		trimmed = trimmed[index+1:]
+	}
+	return strings.Trim(trimmed, "[]`\"")
+}