DataFrameOperations 類別

pandas DataFrame CRUD 操作的命名空間。

透過 client.dataframe 存取。提供以 DataFrame 為導向的封裝器，包覆記錄層級的 CRUD 操作。

範例：


   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)

參數

名稱	Description
client 必要	DataverseClient 父 DataverseClient 實例。

方法

create	從 pandas DataFrame 建立紀錄。 Tip 所有列都會在同一個 CreateMultiple 請求中傳送。非常對於大型資料幀，建議分成較小的批次以避免請求暫停。
delete	透過傳遞 PANDAS 一串 GUID 來刪除記錄。
get	擷取記錄並返回為單一 pandas DataFrame。當 `record_id` 提供時，回傳一個單列資料幀。當 `record_id` 為 None 時，內部會迭代所有頁面並回傳一個整合後的資料框架。 Tip 對於大型表格，請使用頂置或篩選器來限制結果集。
sql	執行 SQL 查詢，並將結果以 pandas DataFrame 回傳。將記錄清單委派並 sql 轉換成單一資料框架。
update	更新 pandas DataFrame 的紀錄。 DataFrame 中的每一列代表一次更新。該欄位 `id_column` 指定包含記錄 GUID。 Tip 所有資料列都會在單一 UpdateMultiple 請求中傳送（或單一 PATCH 顯示一列）。對於非常大的資料框架，考慮一下分成較小的批次以避免請求逾時。

create

從 pandas DataFrame 建立紀錄。

Tip

所有列都會在同一個 CreateMultiple 請求中傳送。非常

對於大型資料幀，建議分成較小的批次以避免

請求暫停。

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

參數

名稱	Description
table 必要	str 表的結構名稱（例如 `"account"` 或 `"new_MyTestTable"`）。
records 必要	Dataframe DataFrame 中每一列都是要建立的記錄。

傳回

類型	Description
Series	一系列已建立的記錄 GUID，與輸入 DataFrame 索引對齊。

例外狀況

類型	Description
TypeError	如果 `records` 不是 pandas DataFrame。
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

參數

名稱	Description
table 必要	str 表的結構名稱（例如 `"account"` 或 `"new_MyTestTable"`）。
ids 必要	Series 一系列記錄 GUID 可刪除。
use_bulk_delete	bool 當（預設值）和`ids`包含多個值時`True`，執行 BulkDelete 動作並回傳其非同步工作識別碼。每 `False` 筆紀錄依序刪除。預設值: True

傳回

類型	Description
str, None	透過 BulkDelete 刪除多筆紀錄時的 BulkDelete 工作 ID; `None` 當刪除單一記錄、使用序列刪除，或是 `ids` 空時。

例外狀況

類型	Description
TypeError	如果 `ids` 不是熊貓系列。
ValueError	如果 `ids` 包含無效值（非字串、空或僅留白）。

範例

使用系列刪除紀錄：


   import pandas as pd

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

get

擷取記錄並返回為單一 pandas DataFrame。

當 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

參數

名稱	Description
table 必要	str 表的結構名稱（例如 `"account"` 或 `"new_MyTestTable"`）。
record_id	str 可選的 GUID 用來擷取特定紀錄。若無，則查詢多筆紀錄。預設值: 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

傳回

類型	Description
Dataframe	包含所有匹配紀錄的資料框架。當沒有紀錄相符時，會回傳一個空的資料框架。

例外狀況

類型	Description
ValueError	如果 `record_id` 不是非空字串，或查詢參數（ `filterorderbytopexpandpage_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 DataFrame 回傳。

將記錄清單委派並 sql 轉換成單一資料框架。

sql(sql: str) -> DataFrame

參數

名稱	Description
sql 必要	str 支援 SQL SELECT 陳述式。

傳回

類型	Description
Dataframe	包含所有結果列的資料框架。當沒有任何資料列相符時，會回傳一個空的資料框架。

例外狀況

類型	Description
ValidationError	如果 `sql` 不是字串或是空的。

範例

SQL 查詢至 DataFrame：


   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())

向 DataFrame 進行彙總查詢：


   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 的紀錄。

DataFrame 中的每一列代表一次更新。該欄位 id_column 指定包含記錄 GUID。

Tip

所有資料列都會在單一 UpdateMultiple 請求中傳送（或

單一 PATCH 顯示一列）。對於非常大的資料框架，考慮一下

分成較小的批次以避免請求逾時。

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

參數

名稱	Description
table 必要	str 表的結構名稱（例如 `"account"` 或 `"new_MyTestTable"`）。
changes 必要	Dataframe DataFrame 中，每列包含一個記錄 GUID 及需更新的欄位。
id_column 必要	str 包含記錄 GUID 的資料框架欄位名稱。
clear_nulls	bool 當（預設）時 `False` ，遺漏值（NaN/None）會被跳過（該欄位在伺服器上保持不變）。當 `True`時，遺失值會傳送 `null` 到 Dataverse，清除該欄位。只有在你刻意想讓 NaN/None 值清空欄位時才使用 `True` 。預設值: False

例外狀況

類型	Description
TypeError	如果 `changes` 不是 pandas DataFrame。
ValueError	若`changes`為空、 `id_column` DataFrame `id_column` 中找不到、包含無效值（非字串、空或僅留白），或除了是 `Falseclear_nulls` 外無可更新欄位`id_columnclear_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)