Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
101 changes: 101 additions & 0 deletions mysql-test/r/hnsw_vector_cache_metrics.result
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
SET PERSIST vsql_allow_preview_extensions = ON;
INSTALL EXTENSION vsql_vector;
SET @saved_cache_mode = @@GLOBAL.vsql_vector.cache_mode;
SET GLOBAL vsql_vector.cache_mode = 1;
CREATE TABLE tc (
id INT PRIMARY KEY,
v SVECTOR(4) NOT NULL,
INDEX idx_v (v hnsw_cosine) USING EXTENDED(hnsw) WITH (M = 8, ef_construction = 64)
) ENGINE=InnoDB;
CREATE TABLE ti (
id INT PRIMARY KEY,
v SVECTOR(4) NOT NULL,
INDEX idx_v (v hnsw_inner_product) USING EXTENDED(hnsw) WITH (M = 8, ef_construction = 64)
) ENGINE=InnoDB;
#
# 1. Cosine.
#
EXPLAIN FORMAT=TREE SELECT id FROM tc ORDER BY COSINE_DISTANCE(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
EXPLAIN
-> Limit: 10 row(s) (cost=20.2 rows=10)
-> Custom index distance scan on idx_v (cost=20.2 rows=200)

SELECT VARIABLE_VALUE INTO @hits0 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
# Through the index:
SELECT id, ROUND(COSINE_DISTANCE(v, '[1, 0.5, -0.3, 0.2]'), 4) AS d FROM tc ORDER BY COSINE_DISTANCE(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
id d
166 0.0125
33 0.0228
96 0.028
178 0.0383
82 0.0397
103 0.0402
52 0.0547
159 0.0579
115 0.0747
34 0.0789
SELECT VARIABLE_VALUE INTO @hits1 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
SELECT @hits1 - @hits0 > 0 AS served_from_cache;
served_from_cache
1
# Brute force (primary key scan and sort):
SELECT id, ROUND(COSINE_DISTANCE(v, '[1, 0.5, -0.3, 0.2]'), 4) AS d FROM tc FORCE INDEX (PRIMARY) ORDER BY COSINE_DISTANCE(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
id d
166 0.0125
33 0.0228
96 0.028
178 0.0383
82 0.0397
103 0.0402
52 0.0547
159 0.0579
115 0.0747
34 0.0789
#
# 2. Inner product.
#
EXPLAIN FORMAT=TREE SELECT id FROM ti ORDER BY NEGATIVE_INNER_PRODUCT(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
EXPLAIN
-> Limit: 10 row(s) (cost=20.2 rows=10)
-> Custom index distance scan on idx_v (cost=20.2 rows=200)

SELECT VARIABLE_VALUE INTO @hits0 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
# Through the index:
SELECT id, ROUND(INNER_PRODUCT(v, '[1, 0.5, -0.3, 0.2]'), 4) AS ip FROM ti ORDER BY NEGATIVE_INNER_PRODUCT(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
id ip
159 8.3399
33 8.1141
96 7.1649
89 6.2742
20 6.1313
27 6.0424
146 5.9507
90 5.8636
59 5.6381
152 5.6303
SELECT VARIABLE_VALUE INTO @hits1 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
SELECT @hits1 - @hits0 > 0 AS served_from_cache;
served_from_cache
1
# Brute force (primary key scan and sort):
SELECT id, ROUND(INNER_PRODUCT(v, '[1, 0.5, -0.3, 0.2]'), 4) AS ip FROM ti FORCE INDEX (PRIMARY) ORDER BY NEGATIVE_INNER_PRODUCT(v, '[1, 0.5, -0.3, 0.2]') LIMIT 10;
id ip
159 8.3399
33 8.1141
96 7.1649
89 6.2742
20 6.1313
27 6.0424
146 5.9507
90 5.8636
59 5.6381
152 5.6303
DROP TABLE tc, ti;
SET GLOBAL vsql_vector.cache_mode = @saved_cache_mode;
UNINSTALL EXTENSION vsql_vector;
SET PERSIST vsql_allow_preview_extensions = OFF;
RESET PERSIST vsql_allow_preview_extensions;
81 changes: 81 additions & 0 deletions mysql-test/t/hnsw_vector_cache_metrics.test
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
# The vector cache on cosine and inner-product indexes.
#
# The cache holds vectors in int16 form, so it attaches only to an index whose
# metric has an int16 kernel. Each check below runs a KNN query with the cache
# on and confirms that:
# - the query was served from the cache (cache_hits rose), and
# - its top 10 matches brute force in f32.
#
# The vectors vary in magnitude as well as direction, since magnitude is what
# separates inner product from cosine.

SET PERSIST vsql_allow_preview_extensions = ON;
INSTALL EXTENSION vsql_vector;

SET @saved_cache_mode = @@GLOBAL.vsql_vector.cache_mode;
SET GLOBAL vsql_vector.cache_mode = 1;

CREATE TABLE tc (
id INT PRIMARY KEY,
v SVECTOR(4) NOT NULL,
INDEX idx_v (v hnsw_cosine) USING EXTENDED(hnsw) WITH (M = 8, ef_construction = 64)
) ENGINE=InnoDB;

CREATE TABLE ti (
id INT PRIMARY KEY,
v SVECTOR(4) NOT NULL,
INDEX idx_v (v hnsw_inner_product) USING EXTENDED(hnsw) WITH (M = 8, ef_construction = 64)
) ENGINE=InnoDB;

# Each vector is passed to FROM_STRING as a literal: a computed string argument
# leaves the dimension unknown and the insert into SVECTOR(4) fails to decode.
--disable_query_log
--let $i = 1
while ($i <= 200)
{
--let $vec = `SELECT CONCAT('[', ROUND(SIN($i) * (1 + $i % 7), 4), ', ', ROUND(COS($i * 1.7) * (1 + $i % 5), 4), ', ', ROUND(SIN($i * 0.3) * (1 + $i % 3), 4), ', ', ROUND(COS($i * 2.3), 4), ']')`
--eval INSERT INTO tc VALUES ($i, SVECTOR::FROM_STRING('$vec'))
--eval INSERT INTO ti VALUES ($i, SVECTOR::FROM_STRING('$vec'))
--inc $i
}
--enable_query_log

--let $q = '[1, 0.5, -0.3, 0.2]'

--echo #
--echo # 1. Cosine.
--echo #
--eval EXPLAIN FORMAT=TREE SELECT id FROM tc ORDER BY COSINE_DISTANCE(v, $q) LIMIT 10

SELECT VARIABLE_VALUE INTO @hits0 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
--echo # Through the index:
--eval SELECT id, ROUND(COSINE_DISTANCE(v, $q), 4) AS d FROM tc ORDER BY COSINE_DISTANCE(v, $q) LIMIT 10
SELECT VARIABLE_VALUE INTO @hits1 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
SELECT @hits1 - @hits0 > 0 AS served_from_cache;

--echo # Brute force (primary key scan and sort):
--eval SELECT id, ROUND(COSINE_DISTANCE(v, $q), 4) AS d FROM tc FORCE INDEX (PRIMARY) ORDER BY COSINE_DISTANCE(v, $q) LIMIT 10

--echo #
--echo # 2. Inner product.
--echo #
--eval EXPLAIN FORMAT=TREE SELECT id FROM ti ORDER BY NEGATIVE_INNER_PRODUCT(v, $q) LIMIT 10

SELECT VARIABLE_VALUE INTO @hits0 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
--echo # Through the index:
--eval SELECT id, ROUND(INNER_PRODUCT(v, $q), 4) AS ip FROM ti ORDER BY NEGATIVE_INNER_PRODUCT(v, $q) LIMIT 10
SELECT VARIABLE_VALUE INTO @hits1 FROM performance_schema.global_status
WHERE VARIABLE_NAME = 'vsql_vector.cache_hits';
SELECT @hits1 - @hits0 > 0 AS served_from_cache;

--echo # Brute force (primary key scan and sort):
--eval SELECT id, ROUND(INNER_PRODUCT(v, $q), 4) AS ip FROM ti FORCE INDEX (PRIMARY) ORDER BY NEGATIVE_INNER_PRODUCT(v, $q) LIMIT 10

DROP TABLE tc, ti;
SET GLOBAL vsql_vector.cache_mode = @saved_cache_mode;
UNINSTALL EXTENSION vsql_vector;
SET PERSIST vsql_allow_preview_extensions = OFF;
RESET PERSIST vsql_allow_preview_extensions;
28 changes: 21 additions & 7 deletions src/distance_registry.h
Original file line number Diff line number Diff line change
Expand Up @@ -67,14 +67,28 @@ inline DistFn dist_for_name(const char *name) {
return nullptr;
}

// Whether this metric has a quantized (int16) kernel, and so whether an index
// on it can attach a vector cache. Only squared L2 today: quantize.h has
// dist_squared_l2_q and nothing else. Cosine is next and needs normalization
// at cache-fill time plus its own kernel; inner product needs a kernel; L1 has
// no precomputable per-vector reduction. The list lives here, next to the
// names, so adding a metric means touching one place.
// The metrics with a quantized (int16) kernel in quantize.h. An enum rather
// than a function pointer so the evaluator's switch inlines the kernel, as
// it did when squared L2 was the only one.
enum class QuantizedMetric { NONE, L2_SQUARED, COSINE, NEGATIVE_INNER_PRODUCT };

// Map a metric name to its quantized kernel; NONE if it has none. L1 has no
// precomputable per-vector reduction, so it never gets one. The list lives
// here, next to the names, so adding a metric means touching one place.
inline QuantizedMetric quantized_metric_for_name(const char *name) {
if (name == nullptr) return QuantizedMetric::NONE;
if (std::strcmp(name, kDistL2Squared) == 0)
return QuantizedMetric::L2_SQUARED;
if (std::strcmp(name, kDistCosine) == 0) return QuantizedMetric::COSINE;
if (std::strcmp(name, kDistNegativeInnerProduct) == 0)
return QuantizedMetric::NEGATIVE_INNER_PRODUCT;
return QuantizedMetric::NONE;
}

// Whether this metric has a quantized kernel, and so whether an index on it
// can attach a vector cache.
inline bool has_quantized_kernel(const char *name) {
return name != nullptr && std::strcmp(name, kDistL2Squared) == 0;
return quantized_metric_for_name(name) != QuantizedMetric::NONE;
}

} // namespace svector::native
Expand Down
38 changes: 29 additions & 9 deletions src/index/hnsw/distance_evaluator.h
Original file line number Diff line number Diff line change
Expand Up @@ -82,12 +82,15 @@ class DistanceEvaluator {
// (>= the decoded float length). prefix is the storage-ref header stripped
// off each value before its floats.
DistanceEvaluator(const char *helper_name, size_t buf_size, uint32_t prefix)
: m_fn(native::dist_for_name(helper_name)), m_prefix(prefix),
: m_fn(native::dist_for_name(helper_name)),
m_qmetric(native::quantized_metric_for_name(helper_name)),
m_prefix(prefix),
m_scratch_a(buf_size), m_scratch_b(buf_size),
m_qbuf_a(max_qdata_length(buf_size, prefix)),
m_qbuf_b(max_qdata_length(buf_size, prefix)) {
if (m_fn == nullptr && helper_name != nullptr) {
// Keep the name for eval()'s error; the buffer is small and fixed.
if ((m_fn == nullptr || m_qmetric == native::QuantizedMetric::NONE) &&
helper_name != nullptr) {
// Keep the name for eval()'s errors; the buffer is small and fixed.
std::strncpy(m_helper_name, helper_name, sizeof(m_helper_name) - 1);
}
}
Expand All @@ -99,8 +102,8 @@ class DistanceEvaluator {
// operand quantized: a vector the cache refused stays in its stored form,
// and eval() picks the kernel per comparison.
//
// L2 only for now: quantize.h has dist_squared_l2_q and nothing else, and
// IndexGraph::set_vector_cache() refuses a cache on other metrics.
// Only for a metric with a quantized kernel (native::has_quantized_kernel);
// IndexGraph::set_vector_cache() refuses a cache on any other.
void set_quantized(uint32_t padded_dim) {
m_quantized = true;
m_padded_dim = padded_dim;
Expand Down Expand Up @@ -264,8 +267,23 @@ class DistanceEvaluator {
if (m_fn == nullptr) {
return unresolved(err);
}
out = quant::dist_squared_l2_q(a, b, m_padded_dim);
return false;
switch (m_qmetric) {
case native::QuantizedMetric::L2_SQUARED:
out = quant::dist_squared_l2_q(a, b, m_padded_dim);
return false;
case native::QuantizedMetric::COSINE:
out = quant::dist_cosine_q(a, b, m_padded_dim);
return false;
case native::QuantizedMetric::NEGATIVE_INNER_PRODUCT:
out = quant::dist_negative_inner_product_q(a, b, m_padded_dim);
return false;
case native::QuantizedMetric::NONE:
break;
}
snprintf(err.data(), err.size(),
"HNSW: distance: no quantized kernel for helper '%s'",
m_helper_name);
return true;
}

// Decodes the raw stored value v into buf, which must be buf_len bytes
Expand Down Expand Up @@ -346,6 +364,8 @@ class DistanceEvaluator {
}

NativeDistFn m_fn;
// The int16 kernel for the same metric, NONE if it has none.
native::QuantizedMetric m_qmetric;
uint32_t m_prefix;
// Scratch for each operand when it cannot be read in place. Two buffers so
// both are live at once for the kernel call.
Expand All @@ -367,8 +387,8 @@ class DistanceEvaluator {
// set_quantized_fixed_operand().
const quant::QData *m_qa = nullptr;
const unsigned char *m_fixed_f32_src = nullptr;
// The bound helper name, kept only when it did not resolve, for eval()'s
// error message. Same 64-byte cap the server name lookup uses.
// The bound helper name, kept only when it did not resolve to both kernels,
// for eval()'s error messages. Same 64-byte cap the server name lookup uses.
char m_helper_name[64] = {};
};

Expand Down
6 changes: 3 additions & 3 deletions src/index/hnsw/graph.h
Original file line number Diff line number Diff line change
Expand Up @@ -519,9 +519,9 @@ class IndexGraph {
public:
// Attach a vector cache to sit behind resolve_node_data(), or nullptr for
// the uncached paged path. Refused when this index's metric has no
// quantized kernel -- the cache stores a quantized form, so attaching one
// on, say, a cosine index would be a correctness bug rather than a slow
// path. Such an index simply runs as it does today. Not owned: the cache
// quantized kernel (L1) -- the cache stores a quantized form, so attaching
// one there would be a correctness bug rather than a slow path. Such an
// index simply runs as it does today. Not owned: the cache
// lives on the IndexStore and outlives any one IndexGraph, which is what
// lets it persist across queries.
void set_vector_cache(VectorCache *cache) {
Expand Down
38 changes: 32 additions & 6 deletions src/quantize.h
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,16 @@
// along with this program; if not, write to the Free Software
// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

// Scalar int16 quantization for vectors, plus the SIMD squared-L2 kernel over
// the quantized form. Self-contained: no dependency on the HNSW storage layer.
// Intended for an in-memory resident quantized vector -- quantize a float
// vector once when it is materialized, then compare with dist_squared_l2_q.
// Scalar int16 quantization for vectors, plus SIMD kernels over the quantized
// form: squared L2, cosine and negated inner product. Self-contained: no
// dependency on the HNSW storage layer. Intended for an in-memory resident
// quantized vector -- quantize a float vector once when it is materialized,
// then compare with one of the dist_*_q kernels.
//
// Recipe mirrors MariaDB MHNSW's FVector: per-vector scale = max|v| / 32767,
// components rounded to int16, and abs2 = 0.5 * ||v||^2 precomputed so squared
// L2 reduces to a single int16 dot product plus a constant-time combine.
// components rounded to int16, and abs2 = 0.5 * ||v||^2 precomputed so each
// metric reduces to a single int16 dot product plus a constant-time combine.
// L1 has no such form: it needs every per-component difference.

#ifndef VILLAGESQL_VSQL_VECTOR_SRC_QUANTIZE_H
#define VILLAGESQL_VSQL_VECTOR_SRC_QUANTIZE_H
Expand Down Expand Up @@ -158,6 +160,30 @@ static SVECTOR_Q_ALWAYS_INLINE double dist_squared_l2_q(const QData *a,
b->dims, padded_dim);
}

// Cosine distance, 1 - cos(a, b), between two quantized vectors. The norms
// come from the precomputed abs2 = 0.5 * ||v||^2, so ||a|| * ||b|| =
// 2 * sqrt(abs2a * abs2b) and the kernel is still a single int16 dot product.
// Both norms are of the quantized vectors, the same ones the dot product is
// taken over, so the cosine stays within [-1, 1]. As native::dist_cosine, a
// zero or overflowed norm gives the maximum distance 1.
static SVECTOR_Q_ALWAYS_INLINE double dist_cosine_q(const QData *a,
const QData *b,
uint32_t padded_dim) {
const double dot = double(a->scale) * double(b->scale) *
double(qdot(a->dims, b->dims, padded_dim));
const double denom = 2.0 * std::sqrt(double(a->abs2) * double(b->abs2));
if (denom > 0.0 && std::isfinite(denom)) return 1.0 - dot / denom;
return 1.0;
}

// Negated inner product between two quantized vectors, as
// native::dist_negative_inner_product: smaller means more similar.
static SVECTOR_Q_ALWAYS_INLINE double dist_negative_inner_product_q(
const QData *a, const QData *b, uint32_t padded_dim) {
return -(double(a->scale) * double(b->scale) *
double(qdot(a->dims, b->dims, padded_dim)));
}

} // namespace svector::quant

#endif // VILLAGESQL_VSQL_VECTOR_SRC_QUANTIZE_H
Loading
Loading