DataFrameOperations Kelas

Namespace untuk operasi CRUD DataFrame pandas.

Diakses melalui client.dataframe. Menyediakan pembungkus berorientasi DataFrame di sekitar operasi CRUD tingkat rekor.

Example:


   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"])

Konstruktor

DataFrameOperations(client: DataverseClient)

Parameter

Nama	Deskripsi
client Diperlukan	DataverseClient Instans induk DataverseClient .

Metode

create	Membuat rekaman dari Pandas DataFrame. Tip Semua baris dikirim dalam satu permintaan CreateMultiple. Untuk sangat DataFrame besar, pertimbangkan untuk memisahkan menjadi batch yang lebih kecil untuk dihindari meminta batas waktu.
delete	Menghapus rekaman dengan meneruskan Seri GUID panda.
get	Ambil rekaman dan kembalikan sebagai satu panda DataFrame. Saat `record_id` disediakan, mengembalikan DataFrame satu baris. Ketika `record_id` Tidak Ada, secara internal mengulangi semua halaman dan mengembalikan satu DataFrame terkonsolidasi. Tip Untuk tabel besar, gunakan atas atau filter untuk membatasi tataan hasil.
sql	Jalankan kueri SQL dan kembalikan hasilnya sebagai DataFrame pandas. Mendelegasikan ke sql dan mengonversi daftar rekaman menjadi satu DataFrame.
update	Memperbarui rekaman dari DataFrame pandas. Setiap baris dalam DataFrame mewakili pembaruan. Menentukan `id_column` kolom mana yang berisi GUID rekaman. Tip Semua baris dikirim dalam satu permintaan UpdateMultiple (atau patch tunggal untuk satu baris). Untuk DataFrame yang sangat besar, pertimbangkan memisahkan menjadi batch yang lebih kecil untuk menghindari batas waktu permintaan.

create

Membuat rekaman dari Pandas DataFrame.

Tip

Semua baris dikirim dalam satu permintaan CreateMultiple. Untuk sangat

DataFrame besar, pertimbangkan untuk memisahkan menjadi batch yang lebih kecil untuk dihindari

meminta batas waktu.

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

Parameter

Nama	Deskripsi
table Diperlukan	str Nama skema tabel (misalnya `"account"` atau `"new_MyTestTable"`).
records Diperlukan	Dataframe DataFrame tempat setiap baris adalah rekaman yang akan dibuat.

Mengembalikan

Jenis	Deskripsi
Series	Rangkaian GUID rekaman yang dibuat, diselaraskan dengan indeks DataFrame input.

Pengecualian

Jenis	Deskripsi
TypeError	Jika `records` bukan Pandas DataFrame.
ValueError	Jika `records` kosong atau jumlah ID yang dikembalikan tidak cocok dengan jumlah baris input.

Contoh

Membuat rekaman dari 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

Menghapus rekaman dengan meneruskan Seri GUID panda.

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

Parameter

Nama	Deskripsi
table Diperlukan	str Nama skema tabel (misalnya `"account"` atau `"new_MyTestTable"`).
ids Diperlukan	Series Serangkaian GUID rekaman yang akan dihapus.
use_bulk_delete	bool Ketika `True` (default) dan `ids` berisi beberapa nilai, jalankan tindakan BulkDelete dan kembalikan pengidentifikasi pekerjaan asinkronnya. Saat `False` setiap rekaman dihapus secara berurutan. Nilai default: True

Mengembalikan

Jenis	Deskripsi
str, None	ID pekerjaan BulkDelete saat menghapus beberapa rekaman melalui BulkDelete; `None` saat menghapus satu rekaman, menggunakan penghapusan berurutan, atau saat `ids` kosong.

Pengecualian

Jenis	Deskripsi
TypeError	Jika `ids` bukan Seri panda.
ValueError	Jika `ids` berisi nilai yang tidak valid (non-string, kosong, atau spasi kosong).

Contoh

Menghapus rekaman menggunakan Seri:


   import pandas as pd

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

get

Ambil rekaman dan kembalikan sebagai satu panda DataFrame.

Saat record_id disediakan, mengembalikan DataFrame satu baris. Ketika record_id Tidak Ada, secara internal mengulangi semua halaman dan mengembalikan satu DataFrame terkonsolidasi.

Tip

Untuk tabel besar, gunakan atas atau filter untuk membatasi tataan hasil.

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

Parameter

Nama	Deskripsi
table Diperlukan	str Nama skema tabel (misalnya `"account"` atau `"new_MyTestTable"`).
record_id	str GUID opsional untuk mengambil rekaman tertentu. Jika Tidak Ada, kueri beberapa rekaman. Nilai default: None
select	list[str] atau None Daftar opsional nama logika atribut yang akan diambil. Nilai default: None
filter	str String filter OData opsional. Nama kolom harus menggunakan nama logika huruf kecil yang tepat. Nilai default: None
orderby	list[str] atau None Daftar atribut opsional untuk diurutkan. Nilai default: None
top	int Jumlah maksimum opsional rekaman yang akan dikembalikan. Nilai default: None
expand	list[str] atau None Daftar opsional properti navigasi untuk diperluas (peka huruf besar/kecil). Nilai default: None
page_size	int Jumlah catatan opsional per halaman untuk penomoran halaman. Nilai default: None
count	bool Jika `True`, tambahkan `$count=true` untuk menyertakan jumlah rekaman total dalam respons. Nilai default: False
include_annotations	str Pola anotasi OData untuk `Prefer: odata.include-annotations` header (misalnya `"*"` atau `"OData.Community.Display.V1.FormattedValue"`), atau `None`. Nilai default: None

Mengembalikan

Jenis	Deskripsi
Dataframe	DataFrame berisi semua rekaman yang cocok. Mengembalikan DataFrame kosong jika tidak ada rekaman yang cocok.

Pengecualian

Jenis	Deskripsi
ValueError	Jika `record_id` bukan string yang tidak kosong, atau jika parameter kueri ( `filterorderbytopexpandpage_sizerecord_id`

Contoh

Ambil satu rekaman sebagai DataFrame:


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

Kueri dengan pemfilteran:


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

Batasi ukuran hasil:


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

sql

Jalankan kueri SQL dan kembalikan hasilnya sebagai DataFrame pandas.

Mendelegasikan ke sql dan mengonversi daftar rekaman menjadi satu DataFrame.

sql(sql: str) -> DataFrame

Parameter

Nama	Deskripsi
sql Diperlukan	str Pernyataan SQL SELECT yang didukung.

Mengembalikan

Jenis	Deskripsi
Dataframe	DataFrame berisi semua baris hasil. Mengembalikan DataFrame kosong jika tidak ada baris yang cocok.

Pengecualian

Jenis	Deskripsi
ValidationError	Jika `sql` bukan string atau kosong.

Contoh

Kueri SQL ke 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())

Kueri agregat ke 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

Memperbarui rekaman dari DataFrame pandas.

Setiap baris dalam DataFrame mewakili pembaruan. Menentukan id_column kolom mana yang berisi GUID rekaman.

Tip

Semua baris dikirim dalam satu permintaan UpdateMultiple (atau

patch tunggal untuk satu baris). Untuk DataFrame yang sangat besar, pertimbangkan

memisahkan menjadi batch yang lebih kecil untuk menghindari batas waktu permintaan.

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

Parameter

Nama	Deskripsi
table Diperlukan	str Nama skema tabel (misalnya `"account"` atau `"new_MyTestTable"`).
changes Diperlukan	Dataframe DataFrame di mana setiap baris berisi GUID rekaman dan bidang yang akan diperbarui.
id_column Diperlukan	str Nama kolom DataFrame yang berisi GUID rekaman.
clear_nulls	bool Ketika `False` (default), nilai yang hilang (NaN/Tidak Ada) dilewati (bidang dibiarkan tidak berubah di server). Ketika `True`, nilai yang hilang dikirim ke `null` Dataverse, menghapus bidang . Gunakan `True` hanya saat Anda sengaja ingin nilai NaN/None menghapus bidang. Nilai default: False

Pengecualian

Jenis	Deskripsi
TypeError	Jika `changes` bukan Pandas DataFrame.
ValueError	Jika `changes` kosong, `id_column` tidak ditemukan di DataFrame, `id_column` berisi nilai yang tidak valid (non-string, kosong, atau khusus spasi kosong), atau tidak ada kolom yang dapat diperbarui selain `id_columnclear_nulls` itu adalah `Falseclear_nullsTrue`

Contoh

Perbarui rekaman dengan nilai yang berbeda per baris:


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

Siarkan perubahan yang sama ke semua rekaman:


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

Hapus bidang dengan mengatur clear_nulls=True:


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