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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-pgwire
-Version: 1.5.2
+Version: 1.5.4
 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.4}/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.4"
 __author__ = "Thomas Dyar <thomas.dyar@intersystems.com>"
 
 # Don't import server/protocol in __init__ to avoid sys.modules conflicts

iris_pgwire-1.5.4/src/iris_pgwire/conversions/vector_syntax.py

@@ -0,0 +1,156 @@
+"""
+Utilities for translating PostgreSQL vector syntax (pgvector) to IRIS vector syntax.
+
+IRIS HNSW index syntax (confirmed against live IRIS instance):
+    CREATE INDEX name ON [TABLE] schema.table (col)
+        AS HNSW(Distance='Cosine'[, M=16, efConstruction=64])
+
+Distance values: 'Cosine' | 'DotProduct'
+M and efConstruction are optional (IRIS defaults: M=16, efConstruction=64).
+Distance is required for correct query-time behaviour.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+
+@dataclass
+class HnswIndexSpec:
+    """Parsed HNSW index specification."""
+
+    index_name: str
+    table_name: str  # may include schema, e.g. "SQLUser.MyTable"
+    column_name: str
+    distance_metric: Literal["Cosine", "DotProduct"]
+    m: Optional[int] = None
+    ef_construction: Optional[int] = None
+    if_not_exists: bool = False
+
+    # Ignored PostgreSQL options (logged as warnings)
+    ignored_options: dict[str, Any] = field(default_factory=dict)
+
+    def to_iris_sql(self) -> str:
+        """Convert to IRIS SQL.
+
+        IRIS syntax:
+            CREATE INDEX name ON table (col) AS HNSW(Distance='Cosine'[, M=N, efConstruction=N])
+
+        Distance is always emitted so IRIS uses the right index structure at
+        query time (VECTOR_COSINE → Cosine, VECTOR_DOT_PRODUCT → DotProduct).
+        """
+        params = [f"Distance='{self.distance_metric}'"]
+        if self.m is not None:
+            params.append(f"M={self.m}")
+        if self.ef_construction is not None:
+            params.append(f"efConstruction={self.ef_construction}")
+        return (
+            f"CREATE INDEX {self.index_name} ON {self.table_name} "
+            f"({self.column_name}) AS HNSW({', '.join(params)})"
+        )
+
+    @classmethod
+    def from_postgres_sql(cls, sql: str) -> Optional["HnswIndexSpec"]:
+        """Parse an HNSW index statement in either pgvector or hybrid form.
+
+        Form 1 — pgvector standard (USING hnsw before column list):
+            CREATE [UNIQUE] INDEX [IF NOT EXISTS] name ON [schema.]table
+                USING hnsw (col vector_cosine_ops) [WITH (m=16, ef_construction=64)]
+
+        Form 2 — hybrid / user-written (column list before USING):
+            CREATE INDEX name ON [schema.]table (col)
+                USING HNSW [WITH (M=16, efConstruction=64, Distance='COSINE')]
+
+        Returns HnswIndexSpec if matched, None if not an HNSW statement.
+        Raises ValueError for unsupported operators (e.g. vector_l2_ops).
+        """
+        # Form 1: USING hnsw (col ops) [WITH (...)]
+        form1 = re.search(
+            r"CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?P<ine>IF\s+NOT\s+EXISTS\s+)?"
+            r"(?P<name>\w+)\s+ON\s+(?P<table>[\w.]+)\s+"
+            r"USING\s+hnsw\s*\(\s*(?P<col>\w+)\s+(?P<op>\w+)\s*\)"
+            r"(?:\s+WITH\s*\((?P<with>[^)]*)\))?",
+            sql,
+            re.IGNORECASE,
+        )
+        if form1:
+            op = form1.group("op").lower()
+            if op == "vector_l2_ops":
+                raise ValueError(
+                    "IRIS does not support L2/Euclidean distance for HNSW indexes. "
+                    "Use vector_cosine_ops or vector_ip_ops."
+                )
+            if op == "vector_cosine_ops":
+                distance: Literal["Cosine", "DotProduct"] = "Cosine"
+            elif op == "vector_ip_ops":
+                distance = "DotProduct"
+            else:
+                raise ValueError(f"Unsupported vector operator for HNSW: {op}")
+            m, ef = _parse_with_options(form1.group("with") or "")
+            return cls(
+                index_name=form1.group("name"),
+                table_name=form1.group("table"),
+                column_name=form1.group("col"),
+                distance_metric=distance,
+                m=m,
+                ef_construction=ef,
+                if_not_exists=bool(form1.group("ine")),
+            )
+
+        # Form 2: (col) USING HNSW [WITH (...)]
+        form2 = re.search(
+            r"CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?P<ine>IF\s+NOT\s+EXISTS\s+)?"
+            r"(?P<name>\w+)\s+ON\s+(?P<table>[\w.]+)\s*"
+            r"\(\s*(?P<col>\w+)\s*\)\s+"
+            r"USING\s+HNSW"
+            r"(?:\s+WITH\s*\((?P<with>[^)]*)\))?",
+            sql,
+            re.IGNORECASE,
+        )
+        if form2:
+            with_str = form2.group("with") or ""
+            m, ef = _parse_with_options(with_str)
+            distance = _parse_distance_from_with(with_str)
+            return cls(
+                index_name=form2.group("name"),
+                table_name=form2.group("table"),
+                column_name=form2.group("col"),
+                distance_metric=distance,
+                m=m,
+                ef_construction=ef,
+                if_not_exists=bool(form2.group("ine")),
+            )
+
+        return None
+
+
+def _parse_with_options(with_str: str) -> tuple[Optional[int], Optional[int]]:
+    """Extract M and efConstruction / ef_construction from a WITH clause body."""
+    m: Optional[int] = None
+    ef: Optional[int] = None
+    for part in with_str.split(","):
+        kv = re.match(r"\s*(\w+)\s*=\s*(\d+)", part.strip())
+        if not kv:
+            continue
+        key, val = kv.group(1).lower(), int(kv.group(2))
+        if key == "m":
+            m = val
+        elif key in ("efconstruction", "ef_construction"):
+            ef = val
+    return m, ef
+
+
+def _parse_distance_from_with(with_str: str) -> Literal["Cosine", "DotProduct"]:
+    """Extract Distance= value from a WITH clause body, defaulting to Cosine."""
+    dist = re.search(r"Distance\s*=\s*['\"]?(\w+)['\"]?", with_str, re.IGNORECASE)
+    if not dist:
+        return "Cosine"
+    val = dist.group(1).lower()
+    if val in ("dotproduct", "dot_product", "innerproduct", "inner_product"):
+        return "DotProduct"
+    return "Cosine"
+
+
+def normalize_vector(vector: list[float]) -> list[float]:
+    """Ensure vector is in a format IRIS can handle (list of floats)."""
+    return [float(x) for x in vector]

{iris_pgwire-1.5.2 → iris_pgwire-1.5.4}/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.4}/src/iris_pgwire/sql_translator/mappings/constructs.py

@@ -253,15 +253,27 @@ class IRISSQLConstructRegistry:
             notes="Strip IF NOT EXISTS from CREATE INDEX for IRIS compatibility",
         )
 
-        # HNSW Index Support (PostgreSQL USING hnsw -> IRIS AS HNSW)
+        # HNSW Index — Form 1: pgvector USING hnsw (col ops) [WITH (...)]
+        # Handles schema-qualified table names (schema.table)
         self.add_construct(
             name="HNSW_INDEX",
-            pattern=r"CREATE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?(\w+)\s+ON\s+(\w+)\s+USING\s+hnsw\s*\([^)]+\)",
-            replacement=None,  # Handled by post_process
+            pattern=r"CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?\w+\s+ON\s+[\w.]+\s+USING\s+hnsw\s*\([^)]+\)(?:\s+WITH\s*\([^)]*\))?",
+            replacement=None,
             post_process=self._translate_hnsw_index,
             confidence=0.95,
             construct_type=ConstructType.SYNTAX,
-            notes="Translate PostgreSQL HNSW index to IRIS syntax",
+            notes="Translate pgvector USING hnsw (col ops) to IRIS AS HNSW(Distance=...)",
+        )
+        # HNSW Index — Form 2: col-first (col) USING HNSW [WITH (...)]
+        # e.g. CREATE INDEX i ON t (emb) USING HNSW WITH (M=16, Distance='COSINE')
+        self.add_construct(
+            name="HNSW_INDEX_COL_FIRST",
+            pattern=r"CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?\w+\s+ON\s+[\w.]+\s*\([^)]+\)\s+USING\s+HNSW(?:\s+WITH\s*\([^)]*\))?",
+            replacement=None,
+            post_process=self._translate_hnsw_index,
+            confidence=0.95,
+            construct_type=ConstructType.SYNTAX,
+            notes="Translate col-first (col) USING HNSW WITH (...) to IRIS AS HNSW(Distance=...)",
         )
 
     def _translate_hnsw_index(self, match: re.Match, full_sql: str) -> str:

{iris_pgwire-1.5.2 → iris_pgwire-1.5.4}/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)

iris_pgwire-1.5.2/src/iris_pgwire/conversions/vector_syntax.py

@@ -1,94 +0,0 @@
-"""
-Utilities for translating PostgreSQL vector syntax (pgvector) to IRIS vector syntax.
-"""
-
-import re
-from dataclasses import dataclass, field
-from typing import Any, Literal, Optional
-
-
-@dataclass
-class HnswIndexSpec:
-    """Parsed HNSW index specification."""
-
-    index_name: str
-    table_name: str
-    column_name: str
-    distance_metric: Literal["COSINE", "DOT_PRODUCT"]
-    if_not_exists: bool = False
-
-    # Ignored PostgreSQL options (logged as warnings)
-    ignored_options: dict[str, Any] = field(default_factory=dict)
-
-    def to_iris_sql(self) -> str:
-        """
-        Convert to IRIS SQL index creation syntax.
-
-        Returns:
-            IRIS SQL string (e.g., "CREATE INDEX idx ON table (col) AS HNSW")
-        """
-        # Note: IRIS doesn't specify distance metric in the CREATE INDEX statement
-        # It's inferred from usage, but we validate support here.
-        # Actually, IRIS HNSW index syntax is simply:
-        # CREATE INDEX idxname ON table (col) AS HNSW
-        return f"CREATE INDEX {self.index_name} ON {self.table_name} ({self.column_name}) AS HNSW"
-
-    @classmethod
-    def from_postgres_sql(cls, sql: str) -> Optional["HnswIndexSpec"]:
-        """
-        Parse a PostgreSQL HNSW index creation statement.
-
-        Example: CREATE INDEX IF NOT EXISTS idx ON documents USING hnsw (embedding vector_cosine_ops)
-
-        Args:
-            sql: PostgreSQL CREATE INDEX statement
-
-        Returns:
-            HnswIndexSpec if matched, else None
-        """
-        # Regex to capture parts
-        pattern = (
-            r"CREATE\s+INDEX\s+(?P<if_not_exists>IF\s+NOT\s+EXISTS\s+)?(?P<index_name>\w+)\s+ON\s+"
-            r"(?P<table_name>\w+)\s+USING\s+hnsw\s*\((?P<column_name>\w+)\s+(?P<operator>\w+)\)"
-        )
-
-        match = re.search(pattern, sql, re.IGNORECASE)
-        if not match:
-            return None
-
-        operator = match.group("operator").lower()
-
-        if operator == "vector_l2_ops":
-            raise ValueError(
-                "IRIS does not support L2/Euclidean distance for HNSW indexes. "
-                "Use vector_cosine_ops or vector_ip_ops."
-            )
-
-        distance_metric: Literal["COSINE", "DOT_PRODUCT"]
-        if operator == "vector_cosine_ops":
-            distance_metric = "COSINE"
-        elif operator == "vector_ip_ops":
-            distance_metric = "DOT_PRODUCT"
-        else:
-            raise ValueError(f"Unsupported vector operator for HNSW: {operator}")
-
-        return cls(
-            index_name=match.group("index_name"),
-            table_name=match.group("table_name"),
-            column_name=match.group("column_name"),
-            distance_metric=distance_metric,
-            if_not_exists=bool(match.group("if_not_exists")),
-        )
-
-
-def normalize_vector(vector: list[float]) -> list[float]:
-    """
-    Ensure vector is in a format IRIS can handle (list of floats).
-
-    Args:
-        vector: List of floats
-
-    Returns:
-        Normalized vector
-    """
-    return [float(x) for x in vector]