DataFrameOperations 类

pandas 数据帧 CRUD 操作的命名空间。

通过 client.dataframe 访问。围绕记录级 CRUD 操作提供面向 DataFrame 的包装器。

示例：


   import pandas as pd

   client = DataverseClient(base_url, credential)

   # Query records as a DataFrame
   df = client.dataframe.get("account", select=["name"], top=100)

   # Create records from a DataFrame
   new_df = pd.DataFrame([{"name": "Contoso"}, {"name": "Fabrikam"}])
   new_df["accountid"] = client.dataframe.create("account", new_df)

   # Update records
   new_df["telephone1"] = ["555-0100", "555-0200"]
   client.dataframe.update("account", new_df, id_column="accountid")

   # Delete records
   client.dataframe.delete("account", new_df["accountid"])

构造函数

DataFrameOperations(client: DataverseClient)

参数

名称	说明
client 必需	DataverseClient 父 DataverseClient 实例。

方法

create	从 pandas 数据帧创建记录。 Tip 所有行都在单个 CreateMultiple 请求中发送。对于非常大型数据帧，请考虑拆分为较小的批处理以避免请求超时。
delete	通过传递 pandas 系列 GUID 来删除记录。
get	提取记录并作为单个 pandas 数据帧返回。提供时 `record_id` ，返回单行数据帧。如果 `record_id` 为 None，则内部循环访问所有页面并返回一个合并的数据帧。 Tip 对于大型表，请使用顶部或筛选器来限制结果集。
sql	执行 SQL 查询，并将结果作为 pandas 数据帧返回。委托 sql 并将记录列表转换为单个数据帧。
update	从 pandas 数据帧更新记录。 DataFrame 中的每个行都表示更新。指定 `id_column` 包含记录 GUID 的列。 Tip 所有行都在单个 UpdateMultiple 请求中发送（或一行的单个 PATCH。对于非常大的数据帧，请考虑拆分为较小的批处理以避免请求超时。

create

从 pandas 数据帧创建记录。

Tip

所有行都在单个 CreateMultiple 请求中发送。对于非常

大型数据帧，请考虑拆分为较小的批处理以避免

请求超时。

create(table: str, records: DataFrame) -> Series

参数

名称	说明
table 必需	str 表的架构名称（例如 `"account"` 或 `"new_MyTestTable"`）。
records 必需	Dataframe 数据帧，其中每一行都是要创建的记录。

类型	说明
Series	一系列创建的记录 GUID，与输入数据帧索引保持一致。

例外

类型	说明
TypeError	如果 `records` 不是 pandas 数据帧，则为。
ValueError	如果 `records` 为空或返回的 ID 数与输入行数不匹配。

示例

从数据帧创建记录：


   import pandas as pd

   df = pd.DataFrame([
       {"name": "Contoso", "telephone1": "555-0100"},
       {"name": "Fabrikam", "telephone1": "555-0200"},
   ])
   df["accountid"] = client.dataframe.create("account", df)

delete

通过传递 pandas 系列 GUID 来删除记录。

delete(table: str, ids: Series, use_bulk_delete: bool = True) -> str | None

参数

名称	说明
table 必需	str 表的架构名称（例如 `"account"` 或 `"new_MyTestTable"`）。
ids 必需	Series 要删除的一系列记录 GUID。
use_bulk_delete	bool 如果 `True` （默认值）并 `ids` 包含多个值，请执行 BulkDelete 操作并返回其异步作业标识符。按顺序删除每个记录时 `False` 。默认值: True

类型	说明
str, None	通过 BulkDelete 删除多个记录时 BulkDelete 作业 ID; `None` 删除单个记录、使用顺序删除或为空时 `ids` 。

例外

类型	说明
TypeError	如果 `ids` 不是 pandas 系列。
ValueError	如果 `ids` 包含无效（非字符串、空或仅空格）值。

示例

使用序列删除记录：


   import pandas as pd

   ids = pd.Series(["guid-1", "guid-2", "guid-3"])
   client.dataframe.delete("account", ids)

get

提取记录并作为单个 pandas 数据帧返回。

提供时 record_id ，返回单行数据帧。如果 record_id 为 None，则内部循环访问所有页面并返回一个合并的数据帧。

Tip

对于大型表，请使用顶部或筛选器来限制结果集。

get(table: str, record_id: str | None = None, select: List[str] | None = None, filter: str | None = None, orderby: List[str] | None = None, top: int | None = None, expand: List[str] | None = None, page_size: int | None = None, count: bool = False, include_annotations: str | None = None) -> DataFrame

参数

名称	说明
table 必需	str 表的架构名称（例如 `"account"` 或 `"new_MyTestTable"`）。
record_id	str 用于提取特定记录的可选 GUID。如果为 None，则查询多个记录。默认值: None
select	list[str] 或 None 要检索的属性逻辑名称的可选列表。默认值: None
filter	str 可选的 OData 筛选器字符串。列名必须使用确切的小写逻辑名称。默认值: None
orderby	list[str] 或 None 要排序的属性的可选列表。默认值: None
top	int 要返回的最大记录数可选。默认值: None
expand	list[str] 或 None 要展开的导航属性的可选列表（区分大小写）。默认值: None
page_size	int 每个页面的可选记录数，用于分页。默认值: None
count	bool 如果 `True`，则添加 `$count=true` 以在响应中包含总记录计数。默认值: False
include_annotations	str 标头的 OData 注释模式 `Prefer: odata.include-annotations` （例如 `"*"` 或 `"OData.Community.Display.V1.FormattedValue"`），或 `None`。默认值: None

类型	说明
Dataframe	包含所有匹配记录的数据帧。如果没有记录匹配，则返回空的 DataFrame。

例外

类型	说明
ValueError	如果不是非空字符串，或者查询参数（）`record_idfilterorderbytopexpandpage_sizerecord_id`

示例

以数据帧的形式提取单个记录：


   df = client.dataframe.get("account", record_id=account_id, select=["name", "telephone1"])
   print(df)

使用筛选进行查询：


   df = client.dataframe.get("account", filter="statecode eq 0", select=["name"])
   print(f"Got {len(df)} active accounts")

限制结果大小：


   df = client.dataframe.get("account", select=["name"], top=100)

sql

执行 SQL 查询，并将结果作为 pandas 数据帧返回。

委托 sql 并将记录列表转换为单个数据帧。

sql(sql: str) -> DataFrame

参数

名称	说明
sql 必需	str 支持的 SQL SELECT 语句。

类型	说明
Dataframe	包含所有结果行的数据帧。如果没有行匹配，则返回空的 DataFrame。

例外

类型	说明
ValidationError	如果 `sql` 不是字符串或为空。

示例

对 DataFrame 的 SQL 查询：


   df = client.dataframe.sql(
       "SELECT TOP 100 name, revenue FROM account "
       "WHERE statecode = 0 ORDER BY revenue"
   )
   print(f"Got {len(df)} rows")
   print(df.head())

聚合数据帧查询：


   df = client.dataframe.sql(
       "SELECT a.name, COUNT(c.contactid) as cnt "
       "FROM account a "
       "JOIN contact c ON a.accountid = c.parentcustomerid "
       "GROUP BY a.name"
   )

update

从 pandas 数据帧更新记录。

DataFrame 中的每个行都表示更新。指定 id_column 包含记录 GUID 的列。

Tip

所有行都在单个 UpdateMultiple 请求中发送（或

一行的单个 PATCH。对于非常大的数据帧，请考虑

拆分为较小的批处理以避免请求超时。

update(table: str, changes: DataFrame, id_column: str, clear_nulls: bool = False) -> None

参数

名称	说明
table 必需	str 表的架构名称（例如 `"account"` 或 `"new_MyTestTable"`）。
changes 必需	Dataframe 数据帧，其中每行都包含记录 GUID 和要更新的字段。
id_column 必需	str 包含记录 GUID 的 DataFrame 列的名称。
clear_nulls	bool 如果 `False` （默认值），将跳过缺失值（NaN/None）（字段在服务器上保持不变）。当 `True`缺失值发送到 `null` Dataverse 时，清除字段。仅当有意希望 NaN/None 值清除字段时才使用 `True` 。默认值: False

例外

类型	说明
TypeError	如果 `changes` 不是 pandas 数据帧，则为。
ValueError	如果`changes`为空，`id_column`则在 DataFrame `id_column` 中找不到，则包含无效（非字符串、空或仅空格）值，或者不存在任何`id_columnclear_nulls`可更新的列是`Falseclear_nullsTrue`

示例

更新每行具有不同值的记录：


   import pandas as pd

   df = pd.DataFrame([
       {"accountid": "guid-1", "telephone1": "555-0100"},
       {"accountid": "guid-2", "telephone1": "555-0200"},
   ])
   client.dataframe.update("account", df, id_column="accountid")

将相同的更改广播到所有记录：


   df = pd.DataFrame({"accountid": ["guid-1", "guid-2", "guid-3"]})
   df["websiteurl"] = "https://example.com"
   client.dataframe.update("account", df, id_column="accountid")

通过设置 clear_nulls=True 清除字段：


   df = pd.DataFrame([{"accountid": "guid-1", "websiteurl": None}])
   client.dataframe.update("account", df, id_column="accountid", clear_nulls=True)