DataFrameOperations クラス

pandas DataFrame 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 DataFrame からレコードを作成します。 Tip すべての行は、1 つの CreateMultiple 要求で送信されます。非常に大きな DataFrame を使用する場合は、回避するために小さなバッチに分割することを検討してください。要求タイムアウト。
delete	pandas シリーズの GUID を渡してレコードを削除します。
get	レコードをフェッチし、単一の pandas DataFrame として返します。 `record_id`が指定されている場合は、単一行の DataFrame を返します。 `record_id`が None の場合、内部的にすべてのページが反復処理され、1 つの統合 DataFrame が返されます。 Tip 大きなテーブルの場合は、top または filter を使用して結果セットを制限します。
sql	SQL クエリを実行し、結果を pandas DataFrame として返します。 sqlに委任し、レコードの一覧を 1 つの DataFrame に変換します。
update	pandas DataFrame からレコードを更新します。 DataFrame の各行は更新を表します。 `id_column`は、レコード GUID を含む列を指定します。 Tip すべての行は、単一の UpdateMultiple 要求 (または 1 行に対して 1 つの PATCH)。非常に大規模な DataFrame の場合は、次の点を考慮してください。要求タイムアウトを回避するために、より小さなバッチに分割します。

create

pandas DataFrame からレコードを作成します。

Tip

すべての行は、1 つの CreateMultiple 要求で送信されます。非常に

大きな DataFrame を使用する場合は、回避するために小さなバッチに分割することを検討してください。

要求タイムアウト。

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

パラメーター

名前	説明
table 必須	str テーブルのスキーマ名 ( `"account"` や `"new_MyTestTable"`など)。
records 必須	Dataframe 各行が作成するレコードである DataFrame。

返品

型	説明
Series	入力 DataFrame インデックスに合わせた一連の作成済みレコード GUID。

例外

型	説明
TypeError	`records`が pandas DataFrame でない場合。
ValueError	`records`が空であるか、返された ID の数が入力行数と一致しない場合。

例

DataFrame からレコードを作成する:


   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` 、1 つのレコードを削除する場合、順次削除を使用する場合、または `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 DataFrame として返します。

record_idが指定されている場合は、単一行の DataFrame を返します。 record_idが None の場合、内部的にすべてのページが反復処理され、1 つの統合 DataFrame が返されます。

Tip

大きなテーブルの場合は、top または filter を使用して結果セットを制限します。

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 ページ改ページの 1 ページあたりのレコード数 (省略可能)。規定値: None
count	bool `True`場合は、応答に合計レコード数を含める`$count=true`を追加します。規定値: False
include_annotations	str `Prefer: odata.include-annotations` ヘッダーの OData 注釈パターン (`"*"`や`"OData.Community.Display.V1.FormattedValue"`など)、または`None`。規定値: None

返品

型	説明
Dataframe	一致するすべてのレコードを含む DataFrame。レコードが一致しない場合は、空の DataFrame を返します。

例外

型	説明
ValueError	`record_id`が空でない文字列でない場合、またはクエリパラメーター (`filterorderbytopexpandpage_sizerecord_id`

例

1 つのレコードを DataFrame としてフェッチします。


   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に委任し、レコードの一覧を 1 つの DataFrame に変換します。

sql(sql: str) -> DataFrame

パラメーター

名前	説明
sql 必須	str サポートされている SQL SELECT ステートメント。

返品

型	説明
Dataframe	すべての結果行を含む 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())

クエリを 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 要求 (または

1 行に対して 1 つの PATCH)。非常に大規模な DataFrame の場合は、次の点を考慮してください。

要求タイムアウトを回避するために、より小さなバッチに分割します。

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

パラメーター

名前	説明
table 必須	str テーブルのスキーマ名 ( `"account"` や `"new_MyTestTable"`など)。
changes 必須	Dataframe 各行にレコード GUID と更新するフィールドが含まれている DataFrame。
id_column 必須	str レコード GUID を含む DataFrame 列の名前。
clear_nulls	bool `False` (既定値) の場合、欠損値 (NaN/None) はスキップされます (フィールドはサーバー上で変更されません)。 `True`すると、欠損値が Dataverse に`null`として送信され、フィールドがクリアされます。 `True`は、NaN/None 値を意図的にフィールドをクリアする場合にのみ使用します。規定値: False

例外

型	説明
TypeError	`changes`が pandas DataFrame でない場合。
ValueError	`changes`が空の場合、dataFrame に`id_column`が見つからない、`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)