stash

Author: Max Wang

README.md

@@ -3,7 +3,7 @@
 A Python package allowing developers to connect to Dataverse environments for DDL / DML operations.
 
 - Read (SQL) — Execute constrained read-only SQL via the Dataverse Web API `?sql=` parameter. Returns `list[dict]`.
-- OData CRUD — Unified methods `create(logical_name, record|records)`, `update(logical_name, id|ids, patch|patches)`, `delete(logical_name, id|ids)` plus `get` with record id or filters.
+- OData CRUD — Unified methods `create(logical_name, record|records)`, `update(logical_name, id|ids, patch|patches)`, `delete(logical_name, id|ids)` plus `get` with record id or filters and `delete_async` for better multi-record delete performance.
 - Bulk create — Pass a list of records to `create(...)` to invoke the bound `CreateMultiple` action; returns `list[str]` of GUIDs. If any payload omits `@odata.type` the SDK resolves and stamps it (cached).
 - Bulk update — Provide a list of IDs with a single patch (broadcast) or a list of per‑record patches to `update(...)`; internally uses the bound `UpdateMultiple` action; returns nothing. Each record must include the primary key attribute when sent to UpdateMultiple.
 - Retrieve multiple (paging) — Generator-based `get(...)` that yields pages, supports `$top` and Prefer: `odata.maxpagesize` (`page_size`).
@@ -39,7 +39,9 @@ Auth:
 | `update` | `update(logical_name, list[id], patch)` | `None` | Broadcast; same patch applied to all IDs (UpdateMultiple). |
 | `update` | `update(logical_name, list[id], list[patch])` | `None` | 1:1 patches; lengths must match (UpdateMultiple). |
 | `delete` | `delete(logical_name, id)` | `None` | Delete one record. |
-| `delete` | `delete(logical_name, list[id], use_bulk_delete=True)` | `Optional[str]` | Delete many with async BulkDelete or sequential single-record delete. |
+| `delete` | `delete(logical_name, list[id])` | `None` | Sequential deletes (loops over single-record delete). |
+| `delete_async` | `delete_async(logical_name, id)` | `str` | Async single-record delete. |
+| `delete_async` | `delete_async(logical_name, list[id])` | `str` | Async multi-record delete. |
 | `query_sql` | `query_sql(sql)` | `list[dict]` | Constrained read-only SELECT via `?sql=`. |
 | `create_table` | `create_table(tablename, schema, solution_unique_name=None)` | `dict` | Creates custom table + columns. Friendly name (e.g. `SampleItem`) becomes schema `new_SampleItem`; explicit schema name (contains `_`) used as-is. Pass `solution_unique_name` to attach the table to a specific solution instead of the default solution. |
 | `create_column` | `create_column(tablename, columns)` | `list[str]` | Adds columns using a `{name: type}` mapping (same shape as `create_table` schema). Returns schema names for the created columns. |
@@ -54,10 +56,10 @@ Auth:
 
 Guidelines:
 - `create` always returns a list of GUIDs (1 for single, N for bulk).
-- `update` always returns `None`.
+- `update` and `delete` always returns `None`.
 - Bulk update chooses broadcast vs per-record by the type of `changes` (dict vs list).
-- `delete` returns `None` for single-record delete and sequential multi-record delete, and the BulkDelete async job ID for multi-record BulkDelete.
-- BulkDelete doesn't wait for the delete job to complete. It returns once the async delete job is scheduled.
+- `delete_async` returns the BulkDelete async job ID and doesn't wait for completion.
+- It's recommended to use delete_async for multi-record delete for better performance. 
 - Paging and SQL operations never mutate inputs.
 - Metadata lookups for logical name stamping cached per entity set (in-memory).
 
@@ -143,8 +145,11 @@ print({"multi_update": "ok"})
 # Delete (single)
 client.delete("account", account_id)
 
-# Bulk delete (schedules BulkDelete and returns job id)
-job_id = client.delete("account", ids)
+# Delete multiple sequentially
+client.delete("account", ids)
+
+# Or queue a async bulk delete job
+job_id = client.delete_async("account", ids)
 
 # SQL (read-only) via Web API `?sql=`
 rows = client.query_sql("SELECT TOP 3 accountid, name FROM account ORDER BY createdon DESC")
@@ -334,8 +339,8 @@ client.delete_table("SampleItem")       # delete table (friendly name or explici
 
 Notes:
 - `create` always returns a list of GUIDs (length 1 for single input).
-- `update` returns `None`.
-- `delete` returns `None` for single-record delete/sequential multi-record delete, and the BulkDelete async job ID for BulkDelete.
+- `update` and `delete` returns `None`.
+- `delete_async` returns the BulkDelete async job ID.
 - Passing a list of payloads to `create` triggers bulk create and returns `list[str]` of IDs.
 - `get` supports single record retrieval with record id or paging through result sets (prefer `select` to limit columns).
 - For CRUD methods that take a record id, pass the GUID string (36-char hyphenated). Parentheses around the GUID are accepted but not required.

examples/quickstart.py

@@ -33,6 +33,10 @@
 # Create a credential we can reuse (for DataverseClient)
 credential = InteractiveBrowserCredential()
 client = DataverseClient(base_url=base_url, credential=credential)
+elastic_table_schema = "new_ElasticDeleteDemo"
+elastic_table_created_this_run = False
+elastic_table_logical_name: Optional[str] = None
+elastic_table_metadata_id: Optional[str] = None
 
 # Small helpers: call logging and step pauses
 def log_call(call: str) -> None:
@@ -69,6 +73,129 @@ def backoff_retry(op, *, delays=(0, 2, 5, 10, 20), retry_http_statuses=(400, 403
 			break
 	if last_exc:
 		raise last_exc
+
+def run_elastic_delete_demo() -> None:
+	global elastic_table_created_this_run, elastic_table_logical_name, elastic_table_metadata_id
+	print("Elastic DeleteMultiple demo (elastic table setup):")
+	odata_client = client._get_odata()
+	schema_name = elastic_table_schema
+	publisher_prefix = schema_name.split("_", 1)[0] if "_" in schema_name else schema_name
+	primary_attr = f"{publisher_prefix}_Name"
+	count_attr = f"{publisher_prefix}_Count"
+	flag_attr = f"{publisher_prefix}_Flag"
+
+	def _fetch_metadata() -> Optional[dict]:
+		url = f"{odata_client.api}/EntityDefinitions"
+		params = {
+			"$select": "MetadataId,LogicalName,EntitySetName,SchemaName,TableType",
+			"$filter": f"SchemaName eq '{schema_name}'",
+		}
+		r = odata_client._request("get", url, params=params)
+		try:
+			body = r.json() if r.text else {}
+		except ValueError:
+			return None
+		items = body.get("value") if isinstance(body, dict) else None
+		if isinstance(items, list) and items:
+			md = items[0]
+			return md if isinstance(md, dict) else None
+		return None
+
+	try:
+		metadata = _fetch_metadata()
+		if metadata and str(metadata.get("TableType", "")).lower() != "elastic":
+			print({
+				"elastic_table": schema_name,
+				"skipped": True,
+				"reason": "Existing table is not elastic; DeleteMultiple demo not run",
+				"table_type": metadata.get("TableType"),
+			})
+			return
+		if not metadata:
+			log_call(f"POST EntityDefinitions (TableType=Elastic) for {schema_name}")
+			attributes = [
+				odata_client._attribute_payload(primary_attr, "string", is_primary_name=True),
+				odata_client._attribute_payload(count_attr, "int"),
+				odata_client._attribute_payload(flag_attr, "bool"),
+			]
+			attrs = [a for a in attributes if a]
+			payload = {
+				"@odata.type": "Microsoft.Dynamics.CRM.EntityMetadata",
+				"SchemaName": schema_name,
+				"DisplayName": odata_client._label("Elastic Delete Demo"),
+				"DisplayCollectionName": odata_client._label("Elastic Delete Demos"),
+				"Description": odata_client._label("Elastic table for DeleteMultiple quickstart validation"),
+				"OwnershipType": "UserOwned",
+				"HasActivities": False,
+				"HasNotes": True,
+				"IsEnabledForCharts": False,
+				"IsVirtualEntityReportingEnabled": False,
+				"IsActivity": False,
+				"TableType": "Elastic",
+				"Attributes": attrs,
+			}
+			def _create_elastic():
+				odata_client._request("post", f"{odata_client.api}/EntityDefinitions", json=payload)
+				return True
+			try:
+				backoff_retry(_create_elastic)
+			except Exception as create_exc:
+				print({
+					"elastic_table": schema_name,
+					"skipped": True,
+					"reason": "Elastic table creation failed",
+					"error": str(create_exc),
+				})
+				return
+			ready = backoff_retry(lambda: odata_client._wait_for_entity_ready(schema_name), retry_http_statuses=())
+			if not ready or not ready.get("MetadataId"):
+				raise RuntimeError("Elastic demo table metadata not ready")
+			metadata = _fetch_metadata()
+			elastic_table_created_this_run = True
+		if not metadata:
+			print({"elastic_table": schema_name, "skipped": True, "reason": "Metadata unavailable"})
+			return
+		elastic_table_logical_name = metadata.get("LogicalName")
+		elastic_table_metadata_id = metadata.get("MetadataId")
+		odata_client._elastic_table_cache.pop(elastic_table_logical_name, None)
+		odata_client._logical_to_entityset_cache.pop(elastic_table_logical_name, None)
+		odata_client._logical_primaryid_cache.pop(elastic_table_logical_name, None)
+		is_elastic = odata_client._is_elastic_table(elastic_table_logical_name) if elastic_table_logical_name else False
+		print({
+			"elastic_table": schema_name,
+			"logical_name": elastic_table_logical_name,
+			"table_type_reported": metadata.get("TableType"),
+			"is_elastic": bool(is_elastic),
+		})
+		logical = elastic_table_logical_name
+		if not logical:
+			print({"elastic_table": schema_name, "skipped": True, "reason": "Logical name missing"})
+			return
+		prefix = logical.split("_", 1)[0] if "_" in logical else logical
+		name_key = f"{prefix}_name"
+		count_key = f"{prefix}_count"
+		flag_key = f"{prefix}_flag"
+		records = [
+			{name_key: "Elastic Demo A", count_key: 10, flag_key: True},
+			{name_key: "Elastic Demo B", count_key: 11, flag_key: False},
+			{name_key: "Elastic Demo C", count_key: 12, flag_key: True},
+		]
+		log_call(f"client.create('{logical}', <{len(records)} elastic records>)")
+		created_ids = backoff_retry(lambda: client.create(logical, records))
+		valid_ids = [rid for rid in created_ids if isinstance(rid, str)] if isinstance(created_ids, list) else []
+		if not valid_ids:
+			raise RuntimeError("Elastic demo record creation returned no GUIDs")
+		print({"elastic_create_ids": valid_ids})
+		log_call(f"client.delete('{logical}', <{len(valid_ids)} elastic ids>)")
+		backoff_retry(lambda: client.delete(logical, valid_ids))
+		print({
+			"elastic_delete_multiple": {
+				"requested": len(valid_ids),
+				"succeeded": True,
+			}
+		})
+	except Exception as exc:
+		print({"elastic_demo_error": str(exc)})
 
 # Enum demonstrating local option set creation with multilingual labels (for French labels to work, enable French language in the environment first)
 class Status(IntEnum):
@@ -88,6 +215,10 @@ class Status(IntEnum):
 		}
 	}
 
+pause("Run elastic DeleteMultiple demo")
+run_elastic_delete_demo()
+sys.exit(0)
+
 print("Ensure custom table exists (Metadata):")
 table_info = None
 created_this_run = False
@@ -512,16 +643,16 @@ def run_paging_demo(label: str, *, top: Optional[int], page_size: Optional[int])
 
 		# Fire-and-forget bulk delete for the first portion
 		try:
-			log_call(f"client.delete('{logical}', <{len(bulk_targets)} ids>, use_bulk_delete=True)")
-			bulk_job_id = client.delete(logical, bulk_targets)
+			log_call(f"client.delete_async('{logical}', <{len(bulk_targets)} ids>)")
+			bulk_job_id = client.delete_async(logical, bulk_targets)
 		except Exception as ex:
 			bulk_error = str(ex)
 
 		# Sequential deletes for the remainder
 		try:
-			log_call(f"client.delete('{logical}', <{len(sequential_targets)} ids>, use_bulk_delete=False)")
+			log_call(f"client.delete('{logical}', <{len(sequential_targets)} ids>)")
 			for rid in sequential_targets:
-				backoff_retry(lambda rid=rid: client.delete(logical, rid, use_bulk_delete=False))
+				backoff_retry(lambda rid=rid: client.delete(logical, rid))
 		except Exception as ex:
 			sequential_error = str(ex)
 
@@ -655,5 +786,16 @@ def _ensure_removed():
 			print({"table_deleted": False, "reason": "not found"})
 	except Exception as e:
 		print(f"Delete table failed: {e}")
+	if elastic_table_created_this_run:
+		try:
+			log_call(f"client.delete_table('{elastic_table_schema}')")
+			client.delete_table(elastic_table_schema)
+			print({"elastic_table_deleted": True})
+		except Exception as e:
+			print({"elastic_table_delete_error": str(e)})
+	elif elastic_table_logical_name:
+		print({"elastic_table_deleted": False, "reason": "skipped (table existed before run)"})
 else:
 	print({"table_deleted": False, "reason": "user opted to keep table"})
+	if elastic_table_created_this_run:
+		print({"elastic_table_deleted": False, "reason": "user opted to keep table"})

src/dataverse_sdk/client.py

@@ -11,7 +11,6 @@
 from .config import DataverseConfig
 from .odata import ODataClient
 
-
 class DataverseClient:
     """
     High-level client for Microsoft Dataverse operations.
@@ -208,24 +207,20 @@ def delete(
         self,
         logical_name: str,
         ids: Union[str, List[str]],
-        use_bulk_delete: bool = True,
-    ) -> Optional[str]:
+    ) -> None:
         """
         Delete one or more records by GUID.
 
         :param logical_name: Logical (singular) entity name, e.g. ``"account"``.
         :type logical_name: str
         :param ids: Single GUID string or list of GUID strings to delete.
         :type ids: str or list[str]
-        :param use_bulk_delete: When ``True`` (default) and ``ids`` is a list, execute the BulkDelete action and
-            return its async job identifier. When ``False`` each record is deleted sequentially.
-        :type use_bulk_delete: bool
 
         :raises TypeError: If ``ids`` is not str or list[str].
         :raises HttpError: If the underlying Web API delete request fails.
-        
-        :return: BulkDelete job ID when deleting multiple records via BulkDelete; otherwise ``None``.
-        :rtype: str or None
+
+        :return: ``None`` once the requested records have been deleted sequentially.
+        :rtype: None
 
         Example:
             Delete a single record::
@@ -234,7 +229,7 @@ def delete(
 
             Delete multiple records::
 
-                job_id = client.delete("account", [id1, id2, id3])
+                client.delete("account", [id1, id2, id3])
         """
         od = self._get_odata()
         if isinstance(ids, str):
@@ -246,12 +241,50 @@ def delete(
             return None
         if not all(isinstance(rid, str) for rid in ids):
             raise TypeError("ids must contain string GUIDs")
-        if use_bulk_delete:
-            return od._delete_multiple(logical_name, ids)
+        if od._is_elastic_table(logical_name):
+            od._delete_multiple(logical_name, ids)
+            return None
         for rid in ids:
             od._delete(logical_name, rid)
         return None
 
+    def delete_async(
+        self,
+        logical_name: str,
+        ids: Union[str, List[str]],
+    ) -> str:
+        """
+        Issue an asynchronous BulkDelete job for one or more records.
+
+        :param logical_name: Logical (singular) entity name, e.g. ``"account"``.
+        :type logical_name: str
+        :param ids: Single GUID string or list of GUID strings to delete.
+        :type ids: str or list[str]
+
+        :raises TypeError: If ``ids`` is not str or list[str].
+        :raises HttpError: If the BulkDelete request fails.
+
+        :return: BulkDelete job identifier, a dummy if ids is empty.
+        :rtype: str
+
+        Example:
+            Queue a bulk delete::
+
+                job_id = client.delete_async("account", [id1, id2, id3])
+        """
+        od = self._get_odata()
+        if isinstance(ids, str):
+            return od._delete_async(logical_name, [ids])
+        elif isinstance(ids, list):
+            if not ids:
+                noop_bulkdelete_job_id = "00000000-0000-0000-0000-000000000000"
+                return noop_bulkdelete_job_id
+            if not all(isinstance(rid, str) for rid in ids):
+                raise TypeError("ids must contain string GUIDs")
+            return od._delete_async(logical_name, ids)
+        else:
+            raise TypeError("ids must be str or list[str]")
+
     def get(
         self,
         logical_name: str,