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

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

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

iris_pgwire-1.5.5/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.3 → iris_pgwire-1.5.5}/src/iris_pgwire/protocol.py

@@ -2930,10 +2930,14 @@ class PGWireProtocol:
                 # For SELECT/SHOW statements, send RowDescription with column metadata
                 # For DDL/DML statements, send NoData
                 query = stmt.get("translated_query", stmt.get("query", ""))
+                # Use original_query for RETURNING detection: the translation pipeline
+                # strips RETURNING before storing translated_query (IRIS doesn't support it
+                # natively), so has_returning would always be False if we use translated_query.
+                original_query = stmt.get("original_query", query)
                 query_upper = query.strip().upper()
 
                 plan = ReturningPlan.from_sql(
-                    query,
+                    original_query,
                     metadata_cache=self.iris_executor.metadata_cache,
                     executor=self.iris_executor,
                 )
@@ -3081,10 +3085,13 @@ class PGWireProtocol:
 
                 stmt = self.prepared_statements[statement_name]
                 query = stmt.get("translated_query", stmt.get("query", ""))
+                # Use original_query for RETURNING detection: translated_query has the
+                # RETURNING clause stripped (IRIS doesn't support it natively).
+                original_query = stmt.get("original_query", query)
                 query_upper = query.strip().upper()
 
                 plan = ReturningPlan.from_sql(
-                    query,
+                    original_query,
                     metadata_cache=self.iris_executor.metadata_cache,
                     executor=self.iris_executor,
                 )

{iris_pgwire-1.5.3 → iris_pgwire-1.5.5}/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.3/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]