DataverseClient Class

High-level client for Microsoft Dataverse operations.

This client provides a simple, stable interface for interacting with Dataverse environments through the Web API. It handles authentication via Azure Identity and delegates HTTP operations to an internal OData client.

Key capabilities:

OData CRUD operations: create, read, update, delete records
SQL queries: execute read-only SQL via Web API ?sql parameter
Table metadata: create, inspect, and delete custom tables; create and delete columns
File uploads: upload files to file columns with chunking support

Note

The client lazily initializes its internal OData client on first use, allowing lightweight construction without immediate network calls.

Note

All methods that communicate with the Dataverse Web API may raise

HttpError on non-successful

HTTP responses (e.g. 401, 403, 404, 429, 500). Individual method

docstrings document only domain-specific exceptions.

Operations are organized into namespaces:

client.records – create, update, delete, and get records (single or paginated queries)
client.query – query and search operations
client.tables – table and column metadata management
client.files – file upload operations
client.dataframe – pandas DataFrame wrappers for record CRUD
client.batch – batch multiple operations into a single HTTP request

v0 beta methods (client.create, client.query_sql, etc.) were removed in 1.0 GA. Calling one now raises AttributeError with a message naming the GA replacement and the codemod command – previously these calls raised a bare AttributeError with no migration hint, so debugging half-migrated code was painful. See _REMOVED_BETA_METHODS.

The client supports Python's context manager protocol for automatic resource cleanup and HTTP connection pooling:

Constructor

DataverseClient(base_url: str, credential: TokenCredential, config: DataverseConfig | None = None, *, context: OperationContext | None = None)

Parameters

Name	Description
base_url Required	str Your Dataverse environment URL, for example `"https://org.crm.dynamics.com"`. Trailing slash is automatically removed.
credential Required	TokenCredential Azure Identity credential for authentication.
config	DataverseConfig or None Optional configuration for language, timeouts, and retries. If not provided, defaults are loaded from from_env. Default value: None
context Required	OperationContext or None Optional caller-defined context object appended to the outbound `User-Agent` header for plugin/tool attribution. Cannot be used together with `config` – pass the context via DataverseConfig instead.

Keyword-Only Parameters

Name	Description
context	Default value: None

Examples

Recommended – context manager (enables HTTP connection pooling):


   from azure.identity import InteractiveBrowserCredential
   from PowerPlatform.Dataverse.client import DataverseClient

   credential = InteractiveBrowserCredential()

   with DataverseClient("https://org.crm.dynamics.com", credential) as client:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
       client.records.update("account", record_id, {"telephone1": "555-0100"})
   # Session closed, caches cleared automatically

Manual lifecycle:


   client = DataverseClient("https://org.crm.dynamics.com", credential)
   try:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
   finally:
       client.close()

Methods

Close the client and release resources.

Closes the HTTP session (if any), clears internal caches, and marks the client as closed. Safe to call multiple times. After closing, any operation will raise RuntimeError.

Called automatically when using the client as a context manager.

Example:


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()

flush_cache

Flush cached client metadata or state.

close