models Package

Alternate key metadata for a Dataverse table.

Response from a single operation within a batch request.

Responses are returned in submission order. For operations added to a changeset, responses appear in the changeset's position in that order.

Example:

   for item in result.responses:
       if item.is_success:
           print(f"[OK] {item.status_code} entity_id={item.entity_id}")
       else:
           print(f"[ERR] {item.status_code}: {item.error_message}")

Result of executing a batch request.

Contains one BatchItemResponse per HTTP operation submitted. Operations that expand to multiple HTTP requests (e.g. add_columns with three columns) contribute three entries.

Example:

   result = client.batch.new().execute()
   print(f"Succeeded: {len(result.succeeded)}, Failed: {len(result.failed)}")
   for guid in result.entity_ids:
       print(f"[OK] entity_id: {guid}")

Defines cascade behavior for relationship operations.

Valid values for each parameter:

• "Cascade": Perform the operation on all related records

• "NoCascade": Do not perform the operation on related records

• "RemoveLink": Remove the relationship link but keep the records

• "Restrict": Prevent the operation if related records exist

Column metadata from a Dataverse table definition.

Fluent proxy for building OData filter expressions from a column name.

Returned by col. Operator overloads and methods produce FilterExpression instances that can be passed to QueryBuilder.where().

Example:

   from PowerPlatform.Dataverse.models.filters import col

   expr = col("statecode") == 0               # equality
   expr = col("revenue") > 1_000_000          # comparison
   expr = col("name").like("Contoso%")        # startswith
   expr = col("name").is_null()               # null check
   expr = col("statecode").in_([0, 1])        # in

Structural Protocol enabling typed entity instances to be passed to records.create() and records.update().

Implement this Protocol on any entity class (dataclass, Pydantic model, hand-rolled) to enable it to be passed directly to CRUD operations without specifying the table name or converting to dict manually.

Required class variables:

• __entity_logical_name__ — Dataverse logical entity name (e.g. "account")

• __entity_set_name__ — OData entity set name (e.g. "accounts")

Required instance methods:

• to_dict() — return record payload as dict

• from_dict(data) — classmethod to reconstruct from a response dict

Example:

   from dataclasses import dataclass
   from PowerPlatform.Dataverse import DataverseModel

   @dataclass
   class Account:
       __entity_logical_name__ = "account"
       __entity_set_name__ = "accounts"
       name: str = ""
       telephone1: str = ""

       def to_dict(self) -> dict:
           return {"name": self.name, "telephone1": self.telephone1}

       @classmethod
       def from_dict(cls, data: dict) -> "Account":
           return cls(
               name=data.get("name", ""),
               telephone1=data.get("telephone1", ""),
           )

   # isinstance() works today — Protocol is runtime_checkable:
   assert isinstance(Account(), DataverseModel)

   # Type your own helpers against the Protocol now:
   def save(entity: DataverseModel) -> None:
       data = entity.to_dict()
       client.records.create(entity.__entity_logical_name__, data)

Structured options for an $expand navigation property.

Allows specifying nested $select, $filter, $orderby, and $top options for a single navigation property expansion, following the OData $expand syntax.

Example:

   # Expand Account_Tasks with nested options
   opt = (ExpandOption("Account_Tasks")
          .select("subject", "createdon")
          .filter("contains(subject,'Task')")
          .order_by("createdon", descending=True)
          .top(5))

   query = (client.query.builder("account")
            .select("name")
            .expand(opt)
            .execute())

Inert FetchXML query object. No HTTP request is made until execute or execute_pages is called.

Obtained via client.query.fetchxml(xml).

Base class for composable OData filter expressions.

Supports Python operator overloads for logical composition:

• expr1 & expr2 produces (expr1 and expr2)

• expr1 | expr2 produces (expr1 or expr2)

• ~expr produces not (expr)

Represents a label that can have multiple localized versions.

Represents a localized label with a language code.

Metadata for a lookup attribute.

Valid required_level values:

• "None": The attribute is optional

• "Recommended": The attribute is recommended

• "ApplicationRequired": The attribute is required

Metadata for a many-to-many entity relationship.

Metadata for a one-to-many entity relationship.

Fluent interface for building and executing OData queries against a sync client.

Provides method chaining for constructing complex queries with composable filter expressions. Can be used standalone (via build()) or bound to a client (via execute).

Typed dictionary returned by QueryBuilder.build().

Provides IDE autocomplete when passing build results to client.records.list() manually.

Iterable wrapper around a list of Record objects.

Returned by execute (flat mode) and list.

Backward-compatible: for r in result continues to work without change.

Typed return model for relationship metadata.

Returned by create_one_to_many_relationship, create_many_to_many_relationship, get_relationship, and create_lookup_field.

Example:

   result = client.tables.create_one_to_many_relationship(lookup, relationship)
   print(result.relationship_schema_name)
   print(result.lookup_schema_name)

Table metadata with dict-like backward compatibility.

Supports both new attribute access (info.schema_name) and legacy dict-key access (info["table_schema_name"]) for backward compatibility with code written against the raw dict API.

Example:

   info = client.tables.create("new_Product", {"new_Price": "decimal"})
   print(info.schema_name)              # new attribute access
   print(info["table_schema_name"])     # legacy dict-key access

Represents a single upsert operation targeting a record by its alternate key.

Used with upsert to upsert one or more records identified by alternate keys rather than primary GUIDs.

Example:

   item = UpsertItem(
       alternate_key={"accountnumber": "ACC-001", "address1_postalcode": "98052"},
       record={"name": "Contoso Ltd", "telephone1": "555-0100"},
   )