feat: add execute_update example for python

Author: niebayes

python/client.py

@@ -102,6 +102,15 @@ def execute(self, sql: str) -> pandas.DataFrame:
         df = reader.read_pandas()
         return df
 
+    def execute_update(self, sql: str) -> int:
+        """
+        Executes the sql on Datalayers and returns the affected rows.
+        This method is meant to be used for executing DMLs, including Insert and Delete.
+        Note, Datalayers does not support Update and the development of Delete is in progress.
+        """
+
+        return self.inner.execute_update(sql, None)
+
     def prepare(self, sql: str) -> PreparedStatement:
         """
         Creates a prepared statement.
@@ -122,6 +131,15 @@ def execute_prepared(
         df = reader.read_pandas()
         return df
 
+    def close_prepared(self, prepared_stmt: PreparedStatement):
+        """
+        Closes the prepared statement.
+        Note, generally you should not call this method explicitly.
+        Use with clause to manage the life cycle of a prepared statement instead.
+        """
+
+        prepared_stmt.close()
+
     def close(self):
         """
         Closes the inner Arrow FlightSQL client.

python/main.py

@@ -105,6 +105,32 @@ def main():
         # 1 2024-09-02 10:05:00+08:00    2   15.3     1
         print(result)
 
+    # There provides a dedicated interface `execute_update` for executing DMLs, including Insert, Delete.
+    # This interface directly returns the affected rows which might be convenient for some use cases.
+    #
+    # Note, Datalayers does not support Update and the development for Delete is in progress.
+    sql = """
+        INSERT INTO python.demo (ts, sid, value, flag) VALUES
+            ('2024-09-03T10:00:00+08:00', 1, 4.5, 0),
+            ('2024-09-03T10:05:00+08:00', 2, 11.6, 1);
+        """
+    #! It's expected that the affected rows is 2.
+    #! However, the flightsql-dbapi library does not implement the `execute_update` correctly
+    #! and the returned affected rows is always 0.
+    affected_rows = client.execute_update(sql)
+    # The output should be:
+    # Affected rows: 2
+    # print("Affected rows: {}".format(affected_rows))
+
+    # Checks that the data are inserted successfully.
+    sql = "SELECT * FROM python.demo where ts >= '2024-09-03T10:00:00+08:00'"
+    result = client.execute(sql)
+    # The result should be:
+    #                          ts  sid  value  flag
+    # 0 2024-09-03 10:00:00+08:00    1    4.5     0
+    # 1 2024-09-03 10:05:00+08:00    2   11.6     1
+    print(result)
+
 
 if __name__ == "__main__":
     main()