DataFrameOperations Klasa

Przestrzeń nazw dla operacji CRUD ramki danych pandas.

Dostęp jest uzyskiwany za pośrednictwem client.dataframe. Udostępnia otoki zorientowane na ramki danych wokół operacji CRUD na poziomie rekordu.

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)

Parametry

Nazwa	Opis
client Wymagane	DataverseClient Wystąpienie nadrzędne DataverseClient .

Metody

create	Tworzenie rekordów na podstawie ramki danych biblioteki pandas. Wskazówka Wszystkie wiersze są wysyłane w jednym żądaniu CreateMultiple. Dla bardzo duże ramki danych, rozważ podzielenie na mniejsze partie, aby uniknąć limity czasu żądania.
delete	Usuń rekordy, przekazując serię identyfikatorów GUID biblioteki pandas.
get	Pobieranie rekordów i zwracanie ich jako pojedynczej ramki danych biblioteki pandas. Gdy `record_id` zostanie podana, zwraca ramkę danych z jednym wierszem. Gdy `record_id` ma wartość None, wewnętrznie iteruje wszystkie strony i zwraca jedną skonsolidowaną ramkę danych. Wskazówka W przypadku dużych tabel użyj górnej lub filtru, aby ograniczyć zestaw wyników.
sql	Wykonaj zapytanie SQL i zwróć wyniki jako ramkę danych biblioteki pandas. Delegaci do sql i konwertują listę rekordów na jedną ramkę danych.
update	Aktualizowanie rekordów z ramki danych biblioteki pandas. Każdy wiersz w ramce danych reprezentuje aktualizację. Określa, która kolumna `id_column` zawiera identyfikatory GUID rekordu. Wskazówka Wszystkie wiersze są wysyłane w jednym żądaniu UpdateMultiple (lub pojedyncza poprawka dla jednego wiersza). W przypadku bardzo dużych ramek danych należy wziąć pod uwagę dzielenie na mniejsze partie, aby uniknąć przekroczenia limitu czasu żądania.

create

Tworzenie rekordów na podstawie ramki danych biblioteki pandas.

Wskazówka

Wszystkie wiersze są wysyłane w jednym żądaniu CreateMultiple. Dla bardzo

duże ramki danych, rozważ podzielenie na mniejsze partie, aby uniknąć

limity czasu żądania.

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

Parametry

Nazwa	Opis
table Wymagane	str Nazwa schematu tabeli (np. `"account"` lub `"new_MyTestTable"`).
records Wymagane	Dataframe Ramka danych, w której każdy wiersz jest rekordem do utworzenia.

Zwraca

Typ	Opis
Series	Seria utworzonych identyfikatorów GUID rekordów dopasowanych do wejściowego indeksu ramki danych.

Wyjątki

Typ	Opis
TypeError	Jeśli `records` nie jest to ramka danych biblioteki pandas.
ValueError	Jeśli `records` jest pusty lub liczba zwróconych identyfikatorów nie jest zgodna z liczbą wierszy wejściowych.

Przykłady

Tworzenie rekordów na podstawie ramki danych:


   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

Usuń rekordy, przekazując serię identyfikatorów GUID biblioteki pandas.

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

Parametry

Nazwa	Opis
table Wymagane	str Nazwa schematu tabeli (np. `"account"` lub `"new_MyTestTable"`).
ids Wymagane	Series Seria identyfikatorów GUID rekordów do usunięcia.
use_bulk_delete	bool Gdy `True` (ustawienie domyślne) i `ids` zawiera wiele wartości, wykonaj akcję BulkDelete i zwróć identyfikator zadania asynchronicznego. Gdy `False` każdy rekord zostanie usunięty sekwencyjnie. Domyślna wartość: True

Zwraca

Typ	Opis
str, None	Identyfikator zadania BulkDelete podczas usuwania wielu rekordów za pośrednictwem metody BulkDelete; `None` podczas usuwania pojedynczego rekordu przy użyciu usuwania sekwencyjnego lub gdy `ids` jest pusty.

Wyjątki

Typ	Opis
TypeError	Jeśli `ids` nie jest serią pandas.
ValueError	Jeśli `ids` zawiera nieprawidłowe wartości (bez ciągów, pustych lub tylko odstępów).

Przykłady

Usuwanie rekordów przy użyciu serii:


   import pandas as pd

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

get

Pobieranie rekordów i zwracanie ich jako pojedynczej ramki danych biblioteki pandas.

Gdy record_id zostanie podana, zwraca ramkę danych z jednym wierszem. Gdy record_id ma wartość None, wewnętrznie iteruje wszystkie strony i zwraca jedną skonsolidowaną ramkę danych.

Wskazówka

W przypadku dużych tabel użyj górnej lub filtru, aby ograniczyć zestaw wyników.

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

Parametry

Nazwa	Opis
table Wymagane	str Nazwa schematu tabeli (np. `"account"` lub `"new_MyTestTable"`).
record_id	str Opcjonalny identyfikator GUID do pobrania określonego rekordu. Jeśli brak, wysyła zapytania o wiele rekordów. Domyślna wartość: None
select	list[str] lub None Opcjonalna lista nazw logicznych atrybutów do pobrania. Domyślna wartość: None
filter	str Opcjonalny ciąg filtru OData. Nazwy kolumn muszą używać dokładnych małych liter logicznych. Domyślna wartość: None
orderby	list[str] lub None Opcjonalna lista atrybutów do sortowania według. Domyślna wartość: None
top	int Opcjonalna maksymalna liczba rekordów do zwrócenia. Domyślna wartość: None
expand	list[str] lub None Opcjonalna lista właściwości nawigacji do rozwinięcia (uwzględniana wielkość liter). Domyślna wartość: None
page_size	int Opcjonalna liczba rekordów na stronę na potrzeby stronicowania. Domyślna wartość: None
count	bool Jeśli `True`element doda wartość `$count=true` , aby uwzględnić łączną liczbę rekordów w odpowiedzi. Domyślna wartość: False
include_annotations	str Wzorzec adnotacji OData dla nagłówka `Prefer: odata.include-annotations` (np. `"*"` lub `"OData.Community.Display.V1.FormattedValue"`) lub `None`. Domyślna wartość: None

Zwraca

Typ	Opis
Dataframe	Ramka danych zawierająca wszystkie pasujące rekordy. Zwraca pustą ramkę danych, gdy rekordy nie są zgodne.

Wyjątki

Typ	Opis
ValueError	Jeśli `record_id` nie jest ciągiem innym niż pusty lub jeśli parametry zapytania ( `filterorderbytopexpandpage_sizerecord_id`

Przykłady

Pobieranie pojedynczego rekordu jako ramki danych:


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

Zapytanie z filtrowaniem:


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

Ogranicz rozmiar wyniku:


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

sql

Wykonaj zapytanie SQL i zwróć wyniki jako ramkę danych biblioteki pandas.

Delegaci do sql i konwertują listę rekordów na jedną ramkę danych.

sql(sql: str) -> DataFrame

Parametry

Nazwa	Opis
sql Wymagane	str Obsługiwana instrukcja SQL SELECT.

Zwraca

Typ	Opis
Dataframe	Ramka danych zawierająca wszystkie wiersze wyników. Zwraca pustą ramkę danych, gdy wiersze nie są zgodne.

Wyjątki

Typ	Opis
ValidationError	Jeśli `sql` nie jest ciągiem lub jest pusty.

Przykłady

Zapytanie SQL do ramki danych:


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

Agregowanie zapytania do ramki danych:


   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

Aktualizowanie rekordów z ramki danych biblioteki pandas.

Każdy wiersz w ramce danych reprezentuje aktualizację. Określa, która kolumna id_column zawiera identyfikatory GUID rekordu.

Wskazówka

Wszystkie wiersze są wysyłane w jednym żądaniu UpdateMultiple (lub

pojedyncza poprawka dla jednego wiersza). W przypadku bardzo dużych ramek danych należy wziąć pod uwagę

dzielenie na mniejsze partie, aby uniknąć przekroczenia limitu czasu żądania.

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

Parametry

Nazwa	Opis
table Wymagane	str Nazwa schematu tabeli (np. `"account"` lub `"new_MyTestTable"`).
changes Wymagane	Dataframe Ramka danych, w której każdy wiersz zawiera identyfikator GUID rekordu i pola do zaktualizowania.
id_column Wymagane	str Nazwa kolumny DataFrame zawierającej identyfikatory GUID rekordów.
clear_nulls	bool Gdy `False` (ustawienie domyślne), brakujące wartości (NaN/None) są pomijane (pole pozostaje niezmienione na serwerze). W przypadku `True`, brakujące wartości są wysyłane jako `null` do usługi Dataverse, czyszcząc pole. Użyj `True` tylko wtedy, gdy celowo chcesz wyczyścić pola wartości NaN/None. Domyślna wartość: False

Wyjątki

Typ	Opis
TypeError	Jeśli `changes` nie jest to ramka danych biblioteki pandas.
ValueError	Jeśli `changes` wartość jest pusta, `id_column` nie zostanie znaleziona w ramce danych, `id_column` zawiera nieprawidłowe wartości (bez ciągów, pustych lub tylko odstępów) lub nie istnieją żadne kolumny, które można zaktualizować, poza `id_columnclear_nulls` tym jest `Falseclear_nullsTrue`

Przykłady

Aktualizuj rekordy przy użyciu różnych wartości w wierszu:


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

Rozgłaś tę samą zmianę dla wszystkich rekordów:


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

Wyczyść pole, ustawiając clear_nulls=True:


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