iris-pgwire 1.5.2__tar.gz → 1.5.3__tar.gz

{iris_pgwire-1.5.2 → iris_pgwire-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-pgwire
-Version: 1.5.2
+Version: 1.5.3
 Summary: PostgreSQL Wire Protocol Server for InterSystems IRIS - Connect BI tools, Python frameworks, and PostgreSQL clients to IRIS databases
 Project-URL: Homepage, https://github.com/intersystems-community/iris-pgwire
 Project-URL: Documentation, https://github.com/intersystems-community/iris-pgwire#readme

{iris_pgwire-1.5.2 → iris_pgwire-1.5.3}/src/iris_pgwire/__init__.py

@@ -6,7 +6,7 @@ Based on the specification from docs/iris_pgwire_plan.md and proven patterns fro
 caretdev/sqlalchemy-iris.
 """
 
-__version__ = "1.5.2"
+__version__ = "1.5.3"
 __author__ = "Thomas Dyar <thomas.dyar@intersystems.com>"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

{iris_pgwire-1.5.2 → iris_pgwire-1.5.3}/src/iris_pgwire/models/vector_query_request.py

@@ -22,8 +22,10 @@ class VectorQueryRequest(BaseModel):
     Vector similarity query after translation from pgvector to IRIS syntax.
 
     Lifecycle:
-    1. Client sends pgvector query: SELECT * FROM docs ORDER BY embedding <-> '[0.1,0.2]' LIMIT 5
-    2. PGWire translates to IRIS: SELECT TOP 5 * FROM docs ORDER BY VECTOR_COSINE(embedding, TO_VECTOR('[0.1,0.2]', 'DECIMAL'))
+    1. Client sends pgvector query: SELECT * FROM docs ORDER BY embedding <=> '[0.1,0.2]' LIMIT 5
+    2. PGWire translates to IRIS: SELECT TOP 5 * FROM docs ORDER BY (1 - VECTOR_COSINE(embedding, TO_VECTOR('[0.1,0.2]', DOUBLE)))
+       Note: <=> is cosine *distance* (0=identical); IRIS VECTOR_COSINE is cosine *similarity* (1=identical).
+       The (1 - ...) wrapper converts similarity → distance so ORDER BY ASC returns most-similar rows first.
     3. VectorQueryRequest captures both original and translated SQL + telemetry
     4. DBAPI executor uses translated_sql for execution
     5. Response includes translation_time_ms for SLA validation
@@ -98,15 +100,19 @@ class VectorQueryRequest(BaseModel):
 
     def operator_to_iris_function(self) -> str:
         """
-        Map pgvector operator to IRIS vector function.
+        Map pgvector operator to IRIS vector function name (for telemetry only).
+
+        Note: <=> maps to VECTOR_COSINE but the actual SQL rewrite wraps it as
+        (1 - VECTOR_COSINE(...)) to convert similarity → distance. This method
+        returns only the base function name for display/telemetry purposes.
 
         Returns:
             IRIS function name (VECTOR_L2, VECTOR_COSINE, VECTOR_DOT_PRODUCT)
         """
         operator_map = {
-            "<->": "VECTOR_L2",  # L2 distance (Euclidean)
-            "<=>": "VECTOR_COSINE",  # Cosine distance
-            "<#>": "VECTOR_DOT_PRODUCT",  # Inner product (max)
+            "<->": "VECTOR_L2",  # L2 distance (Euclidean) — unsupported, raises error
+            "<=>": "VECTOR_COSINE",  # Cosine distance → emitted as (1 - VECTOR_COSINE(...))
+            "<#>": "VECTOR_DOT_PRODUCT",  # Inner product (max) → emitted as (-VECTOR_DOT_PRODUCT(...))
         }
         return operator_map[self.vector_operator]
 
@@ -145,9 +151,9 @@ class VectorQueryRequest(BaseModel):
         json_schema_extra = {
             "example": {
                 "request_id": "req-f47ac10b-58cc-4372-a567-0e02b2c3d479",
-                "original_sql": "SELECT * FROM documents ORDER BY embedding <-> '[0.1,0.2,0.3]' LIMIT 5",
-                "translated_sql": "SELECT TOP 5 * FROM documents ORDER BY VECTOR_COSINE(embedding, TO_VECTOR('[0.1,0.2,0.3]', 'DECIMAL'))",
-                "vector_operator": "<->",
+                "original_sql": "SELECT * FROM documents ORDER BY embedding <=> '[0.1,0.2,0.3]' LIMIT 5",
+                "translated_sql": "SELECT TOP 5 * FROM documents ORDER BY (1 - VECTOR_COSINE(embedding, TO_VECTOR('[0.1,0.2,0.3]', DOUBLE)))",
+                "vector_operator": "<=>",
                 "vector_column": "embedding",
                 "query_vector": [0.1, 0.2, 0.3],
                 "vector_dimensions": 3,

{iris_pgwire-1.5.2 → iris_pgwire-1.5.3}/src/iris_pgwire/sql_translator/normalizer.py

@@ -330,20 +330,38 @@ class SQLTranslator:
         return result, count
 
     def _translate_vector_functions(self, sql: str) -> tuple[str, int]:
-        """Translate pgvector function names to IRIS equivalents"""
+        """Translate pgvector function names to IRIS equivalents.
+
+        cosine_distance / vector_cosine_distance are pgvector distance functions
+        (0.0 = identical). IRIS VECTOR_COSINE is a *similarity* function (1.0 =
+        identical), so we wrap the call as (1 - VECTOR_COSINE(...)) to preserve
+        correct distance semantics.
+        """
         count = 0
-        vector_functions = {
-            "vector_cosine_distance": "VECTOR_COSINE",
-            "cosine_distance": "VECTOR_COSINE",
+
+        # Cosine distance functions: wrap as (1 - VECTOR_COSINE(...)) so that
+        # ORDER BY ASC still returns most-similar rows first.
+        for pg_func in ("vector_cosine_distance", "cosine_distance"):
+            pattern = rf"\b{pg_func}\b"
+            if re.search(pattern, sql, re.IGNORECASE):
+                sql = re.sub(pattern, "VECTOR_COSINE", sql, flags=re.IGNORECASE)
+                # Wrap each full VECTOR_COSINE(...) call produced by this substitution.
+                sql = re.sub(
+                    r"VECTOR_COSINE(\s*\([^)]*\))",
+                    r"(1 - VECTOR_COSINE\1)",
+                    sql,
+                )
+                count += 1
+
+        # Simple renames — no semantic adjustment needed.
+        simple_renames = {
             "vector_l2_distance": "VECTOR_L2_DISTANCE",  # Error handled later if not supported
             "l2_distance": "VECTOR_L2_DISTANCE",
             "inner_product": "VECTOR_DOT_PRODUCT",
             "vector_dims": "VECTOR_DIM",
             "vector_norm": "VECTOR_NORM",
         }
-
-        # Case-insensitive replacement
-        for pg_func, iris_func in vector_functions.items():
+        for pg_func, iris_func in simple_renames.items():
             pattern = rf"\b{pg_func}\b"
             if re.search(pattern, sql, re.IGNORECASE):
                 sql = re.sub(pattern, iris_func, sql, flags=re.IGNORECASE)