rename execute and execute_update

Author: leo-altertable

README.md

@@ -19,7 +19,7 @@ from altertable_flightsql import Client
 # Connect to Altertable
 with Client(username="your_username", password="your_password") as client:
     # Execute a query
-    reader = client.execute("SELECT * FROM users WHERE age > 18")
+    reader = client.query("SELECT * FROM users WHERE age > 18")
 
     # Process results
     for batch in reader:
@@ -46,12 +46,12 @@ client = Client(
 
 ```python
 # Execute SELECT query
-reader = client.execute("SELECT * FROM users")
+reader = client.query("SELECT * FROM users")
 for batch in reader:
     print(batch.to_pandas())
 
 # Execute INSERT/UPDATE/DELETE
-rows_affected = client.execute_update("INSERT INTO users (name) VALUES ('Alice')")
+rows_affected = client.execute("INSERT INTO users (name) VALUES ('Alice')")
 print(f"Affected {rows_affected} rows")
 ```
 
@@ -72,8 +72,8 @@ with client.prepare("SELECT * FROM users WHERE id = ?") as stmt:
 txn_id = client.begin_transaction()
 
 try:
-    client.execute_update("INSERT INTO users ...", transaction_id=txn_id)
-    client.execute_update("UPDATE accounts ...", transaction_id=txn_id)
+    client.execute("INSERT INTO users ...", transaction_id=txn_id)
+    client.execute("UPDATE accounts ...", transaction_id=txn_id)
     client.commit_transaction(txn_id)
 except Exception:
     client.rollback_transaction(txn_id)

examples/client_usage.py

@@ -41,7 +41,7 @@ def example_basic_query():
         **CONNECTION_SETTINGS,
     ) as client:
         # Execute query
-        reader = client.execute("SELECT * FROM users WHERE age > 18")
+        reader = client.query("SELECT * FROM users WHERE age > 18")
 
         # Read results
         for batch in reader:
@@ -62,16 +62,19 @@ def example_updates():
         password=ALTERTABLE_PASSWORD,
         **CONNECTION_SETTINGS,
     ) as client:
+        # Create table
+        client.execute("CREATE TABLE users (id INT, name VARCHAR, age INT)")
+
         # Insert
-        rows = client.execute_update("INSERT INTO users (name, age) VALUES ('Alice', 25)")
+        rows = client.execute("INSERT INTO users (name, age) VALUES ('Alice', 25)")
         print(f"Inserted {rows} rows")
 
         # Update
-        rows = client.execute_update("UPDATE users SET age = 26 WHERE name = 'Alice'")
+        rows = client.execute("UPDATE users SET age = 26 WHERE name = 'Alice'")
         print(f"Updated {rows} rows")
 
         # Delete
-        rows = client.execute_update("DELETE FROM users WHERE name = 'Alice'")
+        rows = client.execute("DELETE FROM users WHERE name = 'Alice'")
         print(f"Deleted {rows} rows")
 
     print()
@@ -114,11 +117,11 @@ def example_transactions():
         # Begin transaction
         with client.begin_transaction():
             # Execute queries in transaction
-            client.execute_update(
+            client.execute(
                 "INSERT INTO users (name, age) VALUES ('Bob', 30)",
             )
 
-            client.execute_update(
+            client.execute(
                 "INSERT INTO users (name, age) VALUES ('Carol', 28)",
             )
 
@@ -163,8 +166,8 @@ def example_metadata():
 
 
 if __name__ == "__main__":
-    example_basic_query()
     example_updates()
+    example_basic_query()
     example_prepared_statement()
     example_transactions()
     example_metadata()

src/altertable_flightsql/client.py

@@ -70,7 +70,7 @@ class Client:
 
     Example:
         >>> client = Client(username="user", password="pass")
-        >>> result = client.execute("SELECT * FROM users")
+        >>> result = client.query("SELECT * FROM users")
         >>> for batch in result:
         ...     print(batch.to_pandas())
     """
@@ -162,7 +162,7 @@ def set_catalog(self, catalog: str):
     def set_schema(self, schema: str):
         self._set_options({"schema": sql_pb2.SessionOptionValue(string_value=schema)})
 
-    def execute(
+    def query(
         self,
         query: str,
         *,
@@ -179,7 +179,7 @@ def execute(
             FlightStreamReader for reading query results.
 
         Example:
-            >>> reader = client.execute("SELECT * FROM users WHERE age > 18")
+            >>> reader = client.query("SELECT * FROM users WHERE age > 18")
             >>> for batch in reader:
             ...     print(batch.to_pandas())
         """
@@ -198,7 +198,7 @@ def execute(
 
         return self._client.do_get(endpoint.ticket)
 
-    def execute_update(
+    def execute(
         self,
         query: str,
         *,
@@ -215,7 +215,7 @@ def execute_update(
             Number of rows affected.
 
         Example:
-            >>> rows = client.execute_update("INSERT INTO users (name) VALUES ('Alice')")
+            >>> rows = client.execute("INSERT INTO users (name) VALUES ('Alice')")
             >>> print(f"Inserted {rows} rows")
         """
         # Create SQL update command

tests/conftest.py

@@ -140,13 +140,13 @@ def test_catalog(altertable_client: Client) -> Generator[str, None, None]:
     catalog_name = f"test_catalog_{uuid.uuid4().hex[:8]}"
 
     # Create catalog by attaching a memory database
-    altertable_client.execute_update(f"ATTACH ':memory:' AS {catalog_name}")
+    altertable_client.execute(f"ATTACH ':memory:' AS {catalog_name}")
 
     yield catalog_name
 
     # Cleanup: detach the catalog
     try:
-        altertable_client.execute_update(f"DETACH {catalog_name}")
+        altertable_client.execute(f"DETACH {catalog_name}")
     except Exception as e:
         # Ignore cleanup errors
         print(f"Warning: Failed to detach catalog {catalog_name}: {e}")
@@ -170,7 +170,7 @@ def test_schema(altertable_client: Client, test_catalog: str) -> Generator[Schem
     fully_qualified_schema = f"{test_catalog}.{schema_name}"
 
     # Create schema in the test catalog
-    altertable_client.execute_update(f"CREATE SCHEMA {fully_qualified_schema}")
+    altertable_client.execute(f"CREATE SCHEMA {fully_qualified_schema}")
 
     schema_info = SchemaInfo(
         catalog=test_catalog, schema=schema_name, full_name=fully_qualified_schema
@@ -180,7 +180,7 @@ def test_schema(altertable_client: Client, test_catalog: str) -> Generator[Schem
 
     # Cleanup: drop the schema
     try:
-        altertable_client.execute_update(f"DROP SCHEMA IF EXISTS {fully_qualified_schema} CASCADE")
+        altertable_client.execute(f"DROP SCHEMA IF EXISTS {fully_qualified_schema} CASCADE")
     except Exception as e:
         # Ignore cleanup errors
         print(f"Warning: Failed to drop schema {fully_qualified_schema}: {e}")
@@ -207,11 +207,11 @@ def test_table(
     table_name = f"test_table_{uuid.uuid4().hex[:8]}"
     fully_qualified_table = f"{test_schema.full_name}.{table_name}"
 
-    altertable_client.execute_update(
+    altertable_client.execute(
         f"CREATE TABLE {fully_qualified_table} (id INT, name VARCHAR, value INT)"
     )
 
-    altertable_client.execute_update(
+    altertable_client.execute(
         f"INSERT INTO {fully_qualified_table} (id, name, value) VALUES (1, 'Alice', 100), (2, 'Bob', 200), (3, 'Charlie', 300)"
     )
 
@@ -226,7 +226,7 @@ def test_table(
 
     # Cleanup: drop the table
     try:
-        altertable_client.execute_update(f"DROP TABLE IF EXISTS {fully_qualified_table}")
+        altertable_client.execute(f"DROP TABLE IF EXISTS {fully_qualified_table}")
     except Exception as e:
         # Ignore cleanup errors
         print(f"Warning: Failed to drop table {fully_qualified_table}: {e}")

tests/test_metadata.py

@@ -128,16 +128,16 @@ def test_set_catalog(self, altertable_client: Client):
         query = "SELECT current_catalog() AS current_catalog"
 
         current_catalog = (
-            altertable_client.execute(query).read_all().to_pandas()["current_catalog"][0]
+            altertable_client.query(query).read_all().to_pandas()["current_catalog"][0]
         )
         assert current_catalog != catalog_name
 
-        altertable_client.execute_update(f"ATTACH ':memory:' AS {catalog_name}")
+        altertable_client.execute(f"ATTACH ':memory:' AS {catalog_name}")
 
         altertable_client.set_catalog(catalog_name)
 
         current_catalog = (
-            altertable_client.execute(query).read_all().to_pandas()["current_catalog"][0]
+            altertable_client.query(query).read_all().to_pandas()["current_catalog"][0]
         )
         assert current_catalog == catalog_name
 
@@ -146,15 +146,15 @@ def test_set_schema(self, altertable_client: Client):
         schema_name = f"test_schema_{uuid.uuid4().hex[:8]}"
         query = "SELECT current_schema() AS current_schema"
 
-        altertable_client.execute_update(f"CREATE SCHEMA {schema_name}")
+        altertable_client.execute(f"CREATE SCHEMA {schema_name}")
 
         current_schema = (
-            altertable_client.execute(query).read_all().to_pandas()["current_schema"][0]
+            altertable_client.query(query).read_all().to_pandas()["current_schema"][0]
         )
         assert current_schema != schema_name
 
         altertable_client.set_schema(schema_name)
         current_schema = (
-            altertable_client.execute(query).read_all().to_pandas()["current_schema"][0]
+            altertable_client.query(query).read_all().to_pandas()["current_schema"][0]
         )
         assert current_schema == schema_name

tests/test_queries.py

@@ -15,7 +15,7 @@ class TestBasicQueries:
 
     def test_simple_select(self, altertable_client: Client):
         """Test executing a simple SELECT query."""
-        reader = altertable_client.execute("SELECT 1 AS value")
+        reader = altertable_client.query("SELECT 1 AS value")
 
         # Check the result
         df = reader.read_pandas()
@@ -25,7 +25,7 @@ def test_simple_select(self, altertable_client: Client):
     def test_select_multiple_columns(self, altertable_client: Client):
         """Test SELECT with multiple columns."""
         query = "SELECT 1 AS col1, 'test' AS col2, 3.14 AS col3"
-        reader = altertable_client.execute(query)
+        reader = altertable_client.query(query)
 
         df = reader.read_pandas()
         assert df["col1"].iloc[0] == 1
@@ -35,7 +35,7 @@ def test_select_multiple_columns(self, altertable_client: Client):
     def test_select_with_filter(self, altertable_client: Client, test_table: TableInfo):
         """Test SELECT with WHERE clause."""
         # Query with filter
-        reader = altertable_client.execute(
+        reader = altertable_client.query(
             f"SELECT * FROM {test_table.full_name} WHERE value >= 200"
         )
 
@@ -46,7 +46,7 @@ def test_select_with_filter(self, altertable_client: Client, test_table: TableIn
     def test_empty_result_set(self, altertable_client: Client, test_table: TableInfo):
         """Test query that returns no rows."""
         # Query empty table
-        reader = altertable_client.execute(
+        reader = altertable_client.query(
             f"SELECT * FROM {test_table.full_name} WHERE value > 1000"
         )
         table = reader.read_all()
@@ -78,20 +78,20 @@ class TestErrorHandling:
     def test_invalid_sql_syntax(self, altertable_client: Client):
         """Test handling of invalid SQL syntax."""
         with pytest.raises(Exception):
-            reader = altertable_client.execute("INVALID SQL SYNTAX")
+            reader = altertable_client.query("INVALID SQL SYNTAX")
             list(reader)
 
     def test_nonexistent_table(self, altertable_client: Client):
         """Test querying a non-existent table."""
         with pytest.raises(Exception):
-            reader = altertable_client.execute("SELECT * FROM nonexistent_table_12345")
+            reader = altertable_client.query("SELECT * FROM nonexistent_table_12345")
             list(reader)
 
     def test_invalid_column_name(self, altertable_client: Client, test_table: TableInfo):
         """Test querying with invalid column name."""
         # Query with invalid column
         with pytest.raises(Exception):
-            reader = altertable_client.execute(
+            reader = altertable_client.query(
                 f"SELECT nonexistent_column FROM {test_table.full_name}"
             )
             list(reader)

tests/test_transactions.py

@@ -14,12 +14,12 @@ class TestBasicTransactions:
     def test_commit_transaction(self, altertable_client: Client, test_table: TableInfo):
         """Test committing a transaction."""
         with altertable_client.begin_transaction():
-            altertable_client.execute_update(
+            altertable_client.execute(
                 f"INSERT INTO {test_table.full_name} (id, name, value) VALUES (999, 'Robert', 600)",
             )
 
         # Verify data was committed
-        reader = altertable_client.execute(
+        reader = altertable_client.query(
             f"SELECT name FROM {test_table.full_name} WHERE id = 999"
         )
         df = reader.read_pandas()
@@ -29,11 +29,11 @@ def test_commit_transaction(self, altertable_client: Client, test_table: TableIn
     def test_rollback_transaction(self, altertable_client: Client, test_table: TableInfo):
         """Test rolling back a transaction."""
         with altertable_client.begin_transaction() as txn:
-            altertable_client.execute_update(
+            altertable_client.execute(
                 f"INSERT INTO {test_table.full_name} (id, name, value) VALUES (999, 'Robert', 600)",
             )
 
-            reader = altertable_client.execute(
+            reader = altertable_client.query(
                 f"SELECT name FROM {test_table.full_name} WHERE id = 999"
             )
             df = reader.read_pandas()
@@ -43,6 +43,6 @@ def test_rollback_transaction(self, altertable_client: Client, test_table: Table
             txn.rollback()
 
         # Verify data was not committed
-        reader = altertable_client.execute(f"SELECT * FROM {test_table.full_name} WHERE id = 999")
+        reader = altertable_client.query(f"SELECT * FROM {test_table.full_name} WHERE id = 999")
         df = reader.read_pandas()
         assert len(df) == 0