feat(types): add L1 distance operator and corresponding tests for Vector type

Author: cofin

advanced_alchemy/types/vector.py

@@ -21,6 +21,7 @@
 from sqlalchemy.engine import Dialect
 from sqlalchemy.ext.compiler import compiles
 from sqlalchemy.sql.expression import ColumnElement
+from sqlalchemy.sql.visitors import InternalTraversal
 from sqlalchemy.types import JSON, TypeDecorator, TypeEngine
 
 if TYPE_CHECKING:
@@ -30,8 +31,8 @@
 
 __all__ = ("Vector",)
 
-_PGVECTOR_OPERATORS = {"cosine": "<=>", "l2": "<->", "inner_product": "<#>"}
-_ORACLE_METRICS = {"cosine": "COSINE", "l2": "EUCLIDEAN", "inner_product": "DOT"}
+_PGVECTOR_OPERATORS = {"cosine": "<=>", "l2": "<->", "l1": "<+>", "inner_product": "<#>"}
+_ORACLE_METRICS = {"cosine": "COSINE", "l2": "EUCLIDEAN", "l1": "MANHATTAN", "inner_product": "DOT"}
 
 
 class Vector(TypeDecorator[list[float]]):
@@ -94,6 +95,9 @@ def cosine_distance(self, other: "Sequence[float]") -> "_VectorDistance":
         def l2_distance(self, other: "Sequence[float]") -> "_VectorDistance":
             return self._distance(other, "l2")
 
+        def l1_distance(self, other: "Sequence[float]") -> "_VectorDistance":
+            return self._distance(other, "l1")
+
         def max_inner_product(self, other: "Sequence[float]") -> "_VectorDistance":
             return self._distance(other, "inner_product")
 
@@ -106,12 +110,23 @@ class _VectorDistance(ColumnElement[float]):
     The SQL is chosen at compile time so the same expression compiles to native
     operators on each backend:
 
-    - PostgreSQL / CockroachDB → ``<=>`` / ``<->`` / ``<#>`` (pgvector)
-    - Oracle 23ai → ``VECTOR_DISTANCE(col, :vec, COSINE | EUCLIDEAN | DOT)``
+    - PostgreSQL / CockroachDB → ``<=>`` / ``<->`` / ``<+>`` / ``<#>`` (pgvector)
+    - Oracle 23ai → ``VECTOR_DISTANCE(col, :vec, COSINE | EUCLIDEAN | MANHATTAN | DOT)``
     - other dialects → :exc:`NotImplementedError` (no native vector backend)
+
+    ``max_inner_product`` (pgvector ``<#>``, Oracle ``DOT``) returns the *negated*
+    inner product on both backends, so ascending order yields the nearest match.
+
+    ``_traverse_internals`` makes the expression cache-safe: statements containing
+    a vector distance participate in SQLAlchemy's compiled-statement cache keyed on
+    the operands and metric.
     """
 
-    inherit_cache = False
+    _traverse_internals = [
+        ("left", InternalTraversal.dp_clauseelement),
+        ("right", InternalTraversal.dp_clauseelement),
+        ("metric", InternalTraversal.dp_string),
+    ]
 
     def __init__(self, left: "ColumnElement[Any]", right: "ColumnElement[Any]", metric: str) -> None:
         self.left = left

tests/unit/test_types/test_vector.py

@@ -164,6 +164,7 @@ def test_vector_distance_methods_exist_on_column() -> None:
     column: Column[list[float]] = Column("embedding", Vector(3))
     assert hasattr(column, "cosine_distance")
     assert hasattr(column, "l2_distance")
+    assert hasattr(column, "l1_distance")
     assert hasattr(column, "max_inner_product")
 
 
@@ -183,6 +184,14 @@ def test_vector_l2_distance_postgresql_emits_operator() -> None:
     assert "<->" in sql
 
 
+def test_vector_l1_distance_postgresql_emits_operator() -> None:
+    """L1 distance compiles to the pgvector ``<+>`` operator on PostgreSQL."""
+    column: Column[list[float]] = Column("embedding", Vector(3))
+    statement = column.l1_distance([1.0, 2.0, 3.0])
+    sql = str(statement.compile(dialect=postgresql_dialect_mod.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
+    assert "<+>" in sql
+
+
 def test_vector_max_inner_product_postgresql_emits_operator() -> None:
     """Negative inner product compiles to the pgvector ``<#>`` operator on PostgreSQL."""
     column: Column[list[float]] = Column("embedding", Vector(3))
@@ -209,6 +218,15 @@ def test_vector_l2_distance_oracle_uses_euclidean_metric() -> None:
     assert "EUCLIDEAN" in sql
 
 
+def test_vector_l1_distance_oracle_uses_manhattan_metric() -> None:
+    """L1 distance maps to the Oracle ``MANHATTAN`` metric."""
+    column: Column[list[float]] = Column("embedding", Vector(3))
+    statement = column.l1_distance([1.0, 2.0, 3.0])
+    sql = str(statement.compile(dialect=oracle_dialect_mod.dialect()))  # type: ignore[no-untyped-call,unused-ignore]
+    assert "VECTOR_DISTANCE" in sql
+    assert "MANHATTAN" in sql
+
+
 def test_vector_max_inner_product_oracle_uses_dot_metric() -> None:
     """Negative inner product maps to the Oracle ``DOT`` metric."""
     column: Column[list[float]] = Column("embedding", Vector(3))
@@ -218,6 +236,16 @@ def test_vector_max_inner_product_oracle_uses_dot_metric() -> None:
     assert "DOT" in sql
 
 
+def test_vector_distance_is_cacheable() -> None:
+    """Distance expressions generate a SQLAlchemy cache key keyed on operands and metric."""
+    column: Column[list[float]] = Column("embedding", Vector(3))
+    cosine = column.cosine_distance([1.0, 2.0, 3.0])
+    l2 = column.l2_distance([1.0, 2.0, 3.0])
+    assert cosine._generate_cache_key() is not None  # pyright: ignore[reportPrivateUsage]
+    assert cosine._generate_cache_key() == column.cosine_distance([1.0, 2.0, 3.0])._generate_cache_key()  # pyright: ignore[reportPrivateUsage]
+    assert cosine._generate_cache_key() != l2._generate_cache_key()  # pyright: ignore[reportPrivateUsage]
+
+
 def test_vector_distance_unsupported_dialect_raises() -> None:
     """Distance operations require a native vector backend; JSON fallback raises clearly."""
     column: Column[list[float]] = Column("embedding", Vector(3))