Vector distance and manipulation macros for TiDB Ecto queries.
This module provides Ecto query macro helpers that wrap TiDB's native vector SQL functions.
You can use these macros inside Ecto select, where, order_by, or having expressions
to perform k-Nearest Neighbors (k-NN), Approximate Nearest Neighbors (ANN), and distance calculations.
Importing
Import this module into your query context alongside Ecto.Query:
import Ecto.Query
import TiDB.Ecto.Vector.QueryExample: Nearest Neighbor Search
target_vector = TiDB.Vector.new([0.1, 0.2, 0.3])
# Find the top 10 most similar documents using Cosine Distance
query =
from d in MyApp.Document,
select: %{
id: d.id,
title: d.title,
distance: vec_cosine_distance(d.embedding, ^target_vector)
},
order_by: [asc: vec_cosine_distance(d.embedding, ^target_vector)],
limit: 10
MyApp.Repo.all(query)Summary
Functions
Converts a vector to its text / string representation using TiDB's VEC_AS_TEXT function.
Calculates the Cosine distance between two vectors using TiDB's VEC_COSINE_DISTANCE function.
Returns the number of dimensions of a vector using TiDB's VEC_DIMS function.
Parses and constructs a vector from its string representation using TiDB's VEC_FROM_TEXT function.
Calculates the Manhattan (L1) distance between two vectors using TiDB's VEC_L1_DISTANCE function.
Calculates the Euclidean (L2) distance between two vectors using TiDB's VEC_L2_DISTANCE function.
Calculates the Euclidean (L2) norm / magnitude of a vector using TiDB's VEC_L2_NORM function.
Calculates the negative inner product between two vectors using TiDB's VEC_NEGATIVE_INNER_PRODUCT function.
Functions
Converts a vector to its text / string representation using TiDB's VEC_AS_TEXT function.
Arguments
vector- A vector column or vector expression.
Examples
from d in Document,
select: vec_as_text(d.embedding)Calculates the Cosine distance between two vectors using TiDB's VEC_COSINE_DISTANCE function.
Formula: 1.0 - (dot_product(left, right) / (norm(left) * norm(right)))
Returns 0.0 for identical directions and 2.0 for opposing directions.
Arguments
left- A vector column or vector expression/parameter.right- A vector column or vector expression/parameter.
Examples
from d in Document,
select: %{document: d, score: 1.0 - vec_cosine_distance(d.embedding, ^query_vec)},
order_by: [asc: vec_cosine_distance(d.embedding, ^query_vec)]Returns the number of dimensions of a vector using TiDB's VEC_DIMS function.
Arguments
vector- A vector column or vector expression/parameter.
Examples
from d in Document,
where: vec_dims(d.embedding) == 384,
select: dParses and constructs a vector from its string representation using TiDB's VEC_FROM_TEXT function.
Arguments
vector- A string literal or text column containing a formatted vector (e.g."[1.0, 2.0, 3.0]").
Examples
from d in Document,
select: vec_from_text("[1.0, 2.0, 3.0]")Calculates the Manhattan (L1) distance between two vectors using TiDB's VEC_L1_DISTANCE function.
Formula: sum(|left[i] - right[i]|)
Arguments
left- A vector column or vector expression/parameter.right- A vector column or vector expression/parameter.
Examples
from d in Document,
order_by: [asc: vec_l1_distance(d.embedding, ^query_vec)]Calculates the Euclidean (L2) distance between two vectors using TiDB's VEC_L2_DISTANCE function.
Formula: sqrt(sum((left[i] - right[i])^2))
Arguments
left- A vector column or vector expression/parameter.right- A vector column or vector expression/parameter.
Examples
from d in Document,
select: vec_l2_distance(d.embedding, ^query_vec),
order_by: [asc: vec_l2_distance(d.embedding, ^query_vec)]Calculates the Euclidean (L2) norm / magnitude of a vector using TiDB's VEC_L2_NORM function.
Formula: sqrt(sum(vector[i]^2))
Arguments
vector- A vector column or vector expression/parameter.
Examples
from d in Document,
select: %{id: d.id, magnitude: vec_l2_norm(d.embedding)}Calculates the negative inner product between two vectors using TiDB's VEC_NEGATIVE_INNER_PRODUCT function.
Formula: -sum(left[i] * right[i])
Useful for Maximum Inner Product Search (MIPS) where ordering ascending by the negative inner product yields the highest dot product first.
Arguments
left- A vector column or vector expression/parameter.right- A vector column or vector expression/parameter.
Examples
from d in Document,
order_by: [asc: vec_negative_inner_product(d.embedding, ^query_vec)]