Completed implementation

Author: mpak123

pandas/core/generic.py

@@ -2798,6 +2798,7 @@ def to_sql(
         chunksize: int | None = None,
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
+        hints: dict[str, str | list[str]] | None = None,
     ) -> int | None:
         """
         Write records stored in a DataFrame to a SQL database.
@@ -3044,6 +3045,7 @@ def to_sql(
             chunksize=chunksize,
             dtype=dtype,
             method=method,
+            hints=hints,
         )
 
     @final

pandas/io/sql.py

@@ -18,7 +18,6 @@
     datetime,
     time,
 )
-from functools import partial
 import re
 from typing import (
     TYPE_CHECKING,
@@ -232,6 +231,41 @@ def _wrap_result_adbc(
     return df
 
 
+def _process_sql_hints(
+    hints: dict[str, str | list[str]] | None, dialect_name: str
+) -> str | None:
+    if hints is None or not hints:
+        return None
+
+    dialect_name = dialect_name.lower()
+
+    hint_value = None
+    for key, value in hints.items():
+        if key.lower() == dialect_name:
+            hint_value = value
+            break
+
+    if hint_value is None:
+        return None
+
+    if isinstance(hint_value, list):
+        hint_str = " ".join(hint_value)
+    else:
+        hint_str = str(hint_value)
+
+    if hint_str.strip().startswith("/*+") and hint_str.strip().endswith("*/"):
+        return hint_str.strip()
+
+    if dialect_name == "oracle":
+        return f"/*+ {hint_str} */"
+    elif dialect_name == "mysql":
+        return hint_str
+    elif dialect_name == "mssql":
+        return hint_str
+    else:
+        return f"/*+ {hint_str} */"
+
+
 # -----------------------------------------------------------------------------
 # -- Read and write to DataFrames
 
@@ -750,6 +784,7 @@ def to_sql(
     dtype: DtypeArg | None = None,
     method: Literal["multi"] | Callable | None = None,
     engine: str = "auto",
+    hints: dict[str, str | list[str]] | None = None,
     **engine_kwargs,
 ) -> int | None:
     """
@@ -852,6 +887,7 @@ def to_sql(
             dtype=dtype,
             method=method,
             engine=engine,
+            hints=hints,
             **engine_kwargs,
         )
 
@@ -998,7 +1034,13 @@ def create(self) -> None:
         else:
             self._execute_create()
 
-    def _execute_insert(self, conn, keys: list[str], data_iter) -> int:
+    def _execute_insert(
+        self,
+        conn,
+        keys: list[str],
+        data_iter,
+        hint_str: str | None = None,
+    ) -> int:
         """
         Execute SQL statement inserting data
 
@@ -1010,11 +1052,23 @@ def _execute_insert(self, conn, keys: list[str], data_iter) -> int:
         data_iter : generator of list
            Each item contains a list of values to be inserted
         """
-        data = [dict(zip(keys, row, strict=True)) for row in data_iter]
-        result = self.pd_sql.execute(self.table.insert(), data)
+        data = [dict(zip(keys, row, strict=False)) for row in data_iter]
+
+        if hint_str:
+            stmt = self.table.insert().prefix_with(hint_str)
+        else:
+            stmt = self.table.insert()
+
+        result = self.pd_sql.execute(stmt, data)
         return result.rowcount
 
-    def _execute_insert_multi(self, conn, keys: list[str], data_iter) -> int:
+    def _execute_insert_multi(
+        self,
+        conn,
+        keys: list[str],
+        data_iter,
+        hint_str: str | None = None,
+    ) -> int:
         """
         Alternative to _execute_insert for DBs support multi-value INSERT.
 
@@ -1023,11 +1077,15 @@ def _execute_insert_multi(self, conn, keys: list[str], data_iter) -> int:
         but performance degrades quickly with increase of columns.
 
         """
-
         from sqlalchemy import insert
 
-        data = [dict(zip(keys, row, strict=True)) for row in data_iter]
-        stmt = insert(self.table).values(data)
+        data = [dict(zip(keys, row, strict=False)) for row in data_iter]
+
+        if hint_str:
+            stmt = insert(self.table).values(data).prefix_with(hint_str)
+        else:
+            stmt = insert(self.table).values(data)
+
         result = self.pd_sql.execute(stmt)
         return result.rowcount
 
@@ -1084,14 +1142,20 @@ def insert(
         self,
         chunksize: int | None = None,
         method: Literal["multi"] | Callable | None = None,
+        hints: dict[str, str | list[str]] | None = None,
+        dialect_name: str | None = None,
     ) -> int | None:
         # set insert method
         if method is None:
             exec_insert = self._execute_insert
         elif method == "multi":
             exec_insert = self._execute_insert_multi
         elif callable(method):
-            exec_insert = partial(method, self)
+
+            def callable_wrapper(conn, keys, data_iter, hint_str=None):
+                return method(self, conn, keys, data_iter)
+
+            exec_insert = callable_wrapper
         else:
             raise ValueError(f"Invalid parameter `method`: {method}")
 
@@ -1108,6 +1172,9 @@ def insert(
             raise ValueError("chunksize argument should be non-zero")
 
         chunks = (nrows // chunksize) + 1
+
+        hint_str = _process_sql_hints(hints, dialect_name) if dialect_name else None
+
         total_inserted = None
         with self.pd_sql.run_transaction() as conn:
             for i in range(chunks):
@@ -1119,7 +1186,7 @@ def insert(
                 chunk_iter = zip(
                     *(arr[start_i:end_i] for arr in data_list), strict=True
                 )
-                num_inserted = exec_insert(conn, keys, chunk_iter)
+                num_inserted = exec_insert(conn, keys, chunk_iter, hint_str)
                 # GH 46891
                 if num_inserted is not None:
                     if total_inserted is None:
@@ -1503,6 +1570,7 @@ def to_sql(
         chunksize: int | None = None,
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
+        hints: dict[str, str | list[str]] | None = None,
         engine: str = "auto",
         **engine_kwargs,
     ) -> int | None:
@@ -1539,6 +1607,8 @@ def insert_records(
         schema=None,
         chunksize: int | None = None,
         method=None,
+        hints: dict[str, str | list[str]] | None = None,
+        dialect_name: str | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -1563,6 +1633,8 @@ def insert_records(
         schema=None,
         chunksize: int | None = None,
         method=None,
+        hints: dict[str, str | list[str]] | None = None,
+        dialect_name: str | None = None,
         **engine_kwargs,
     ) -> int | None:
         from sqlalchemy import exc
@@ -1975,6 +2047,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
+        hints: dict[str, str | list[str]] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -2047,6 +2120,8 @@ def to_sql(
             schema=schema,
             chunksize=chunksize,
             method=method,
+            hints=hints,
+            dialect_name=self.con.dialect.name,
             **engine_kwargs,
         )
 
@@ -2339,6 +2414,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
+        hints: dict[str, str | list[str]] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -2388,6 +2464,8 @@ def to_sql(
             raise NotImplementedError(
                 "engine != 'auto' not implemented for ADBC drivers"
             )
+        if hints:
+            raise NotImplementedError("'hints' is not implemented for ADBC drivers")
 
         if schema:
             table_name = f"{schema}.{name}"
@@ -2569,7 +2647,7 @@ def insert_statement(self, *, num_rows: int) -> str:
         )
         return insert_statement
 
-    def _execute_insert(self, conn, keys, data_iter) -> int:
+    def _execute_insert(self, conn, keys, data_iter, hints) -> int:
         from sqlite3 import Error
 
         data_list = list(data_iter)
@@ -2579,7 +2657,7 @@ def _execute_insert(self, conn, keys, data_iter) -> int:
             raise DatabaseError("Execution failed") from exc
         return conn.rowcount
 
-    def _execute_insert_multi(self, conn, keys, data_iter) -> int:
+    def _execute_insert_multi(self, conn, keys, data_iter, hints) -> int:
         data_list = list(data_iter)
         flattened_data = [x for row in data_list for x in row]
         conn.execute(self.insert_statement(num_rows=len(data_list)), flattened_data)
@@ -2816,6 +2894,7 @@ def to_sql(
         dtype: DtypeArg | None = None,
         method: Literal["multi"] | Callable | None = None,
         engine: str = "auto",
+        hints: dict[str, str | list[str]] | None = None,
         **engine_kwargs,
     ) -> int | None:
         """
@@ -2857,6 +2936,13 @@ def to_sql(
             Details and a sample callable implementation can be found in the
             section :ref:`insert method <io.sql.method>`.
         """
+        if hints:
+            warnings.warn(
+                "SQL hints are not supported for SQLite and will be ignored.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+
         if dtype:
             if not is_dict_like(dtype):
                 # error: Value expression in dictionary comprehension has incompatible