DataFrameOperations Klasse

Namespace für Pandas DataFrame CRUD-Vorgänge.

Zugriff über client.dataframe. Stellt DataFrame-orientierte Wrapper um die CRUD-Vorgänge auf Datensatzebene bereit.

Beispiel:


   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

Name	Beschreibung
client Erforderlich	DataverseClient Die übergeordnete DataverseClient Instanz.

Methoden

create	Erstellen von Datensätzen aus einem Pandas DataFrame. Tip Alle Zeilen werden in einer einzigen CreateMultiple-Anforderung gesendet. Für sehr große DataFrames, erwägen Sie, in kleinere Batches aufzuteilen, um zu vermeiden Anforderungstimeouts.
delete	Löschen Sie Datensätze, indem Sie eine Pandas-Reihe von GUIDs übergeben.
get	Abrufen von Datensätzen und Zurückgeben als einzelner Pandas DataFrame. Gibt einen DataFrame mit einer Zeile zurück, wenn `record_id` dieser angegeben wird. Wenn `record_id` "None" ist, durchläuft intern alle Seiten und gibt einen konsolidierten DataFrame zurück. Tip Verwenden Sie für große Tabellen oben oder filter, um das Resultset einzuschränken.
sql	Führen Sie eine SQL-Abfrage aus, und geben Sie die Ergebnisse als Pandas DataFrame zurück. Delegiert an sql und konvertiert die Liste der Datensätze in einen einzelnen DataFrame.
update	Aktualisieren von Datensätzen aus einem Pandas DataFrame. Jede Zeile im DataFrame stellt eine Aktualisierung dar. Gibt `id_column` an, welche Spalte die Datensatz-GUIDs enthält. Tip Alle Zeilen werden in einer einzelnen UpdateMultiple-Anforderung (oder einer einzelner PATCH für eine Zeile). Berücksichtigen Sie bei sehr großen DataFrames Aufteilen in kleinere Batches, um Anforderungstimeouts zu vermeiden.

create

Erstellen von Datensätzen aus einem Pandas DataFrame.

Tip

Alle Zeilen werden in einer einzigen CreateMultiple-Anforderung gesendet. Für sehr

große DataFrames, erwägen Sie, in kleinere Batches aufzuteilen, um zu vermeiden

Anforderungstimeouts.

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

Parameter

Name	Beschreibung
table Erforderlich	str Schemaname der Tabelle (z. B. `"account"` oder `"new_MyTestTable"`).
records Erforderlich	Dataframe DataFrame, wobei jede Zeile ein zu erstellenden Datensatz ist.

Gibt zurück

Typ	Beschreibung
Series	Reihe erstellter Datensatz-GUIDs, die am Eingabedatenframeindex ausgerichtet sind.

Ausnahmen

Typ	Beschreibung
TypeError	If `records` is not a pandas DataFrame.
ValueError	Wenn `records` die Anzahl der zurückgegebenen IDs leer ist oder die Anzahl der zurückgegebenen IDs nicht mit der Anzahl der Eingabezeilen übereinstimmt.

Beispiele

Erstellen von Datensätzen aus einem 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

Löschen Sie Datensätze, indem Sie eine Pandas-Reihe von GUIDs übergeben.

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

Parameter

Name	Beschreibung
table Erforderlich	str Schemaname der Tabelle (z. B. `"account"` oder `"new_MyTestTable"`).
ids Erforderlich	Series Datensatz-GUIDs, die gelöscht werden sollen.
use_bulk_delete	bool Wenn `True` (Standard) und `ids` mehrere Werte enthalten sind, führen Sie die BulkDelete-Aktion aus, und geben Sie den asynchronen Auftragsbezeichner zurück. Wenn `False` jeder Datensatz sequenziell gelöscht wird. Standardwert: True

Gibt zurück

Typ	Beschreibung
str, None	BulkDelete-Auftrags-ID beim Löschen mehrerer Datensätze über BulkDelete; `None` beim Löschen eines einzelnen Datensatzes mit sequenziellem Löschen oder leer `ids` .

Ausnahmen

Typ	Beschreibung
TypeError	Wenn `ids` es sich nicht um eine Pandaserie handelt.
ValueError	Wenn `ids` ungültige Werte (nicht Zeichenfolge, leer oder nur Leerzeichen) enthalten sind.

Beispiele

Löschen von Datensätzen mithilfe einer Datenreihe:


   import pandas as pd

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

get

Abrufen von Datensätzen und Zurückgeben als einzelner Pandas DataFrame.

Gibt einen DataFrame mit einer Zeile zurück, wenn record_id dieser angegeben wird. Wenn record_id "None" ist, durchläuft intern alle Seiten und gibt einen konsolidierten DataFrame zurück.

Tip

Verwenden Sie für große Tabellen oben oder filter, um das Resultset einzuschränken.

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

Name	Beschreibung
table Erforderlich	str Schemaname der Tabelle (z. B. `"account"` oder `"new_MyTestTable"`).
record_id	str Optionale GUID zum Abrufen eines bestimmten Datensatzes. If None, queries multiple records. Standardwert: None
select	list[str] oder None Optionale Liste der abzurufenden attributlogischen Namen. Standardwert: None
filter	str Optionale OData-Filterzeichenfolge. Spaltennamen müssen genaue logische Namen in Kleinbuchstaben verwenden. Standardwert: None
orderby	list[str] oder None Optionale Liste der Attribute, nach der sortiert werden soll. Standardwert: None
top	int Optionale maximale Anzahl von Datensätzen, die zurückgegeben werden sollen. Standardwert: None
expand	list[str] oder None Optionale Liste der zu erweiternden Navigationseigenschaften (Groß-/Kleinschreibung beachten). Standardwert: None
page_size	int Optionale Anzahl von Datensätzen pro Seite für die Paginierung. Standardwert: None
count	bool Wenn `True`, wird hinzugefügt `$count=true` , um eine Gesamtanzahl von Datensätzen in die Antwort einzuschließen. Standardwert: False
include_annotations	str OData-Anmerkungsmuster für die `Prefer: odata.include-annotations` Kopfzeile (z. B. `"*"` oder ) oder `"OData.Community.Display.V1.FormattedValue"None`. Standardwert: None

Gibt zurück

Typ	Beschreibung
Dataframe	DataFrame mit allen übereinstimmenden Datensätzen. Gibt einen leeren DataFrame zurück, wenn keine Datensätze übereinstimmen.

Ausnahmen

Typ	Beschreibung
ValueError	If `record_id` is not a non-empty string, or if query parameters ( `filterorderbytopexpandpage_sizerecord_id`

Beispiele

Abrufen eines einzelnen Datensatzes als DataFrame:


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

Abfrage mit Filterung:


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

Beschränken Sie die Ergebnisgröße:


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

sql

Führen Sie eine SQL-Abfrage aus, und geben Sie die Ergebnisse als Pandas DataFrame zurück.

Delegiert an sql und konvertiert die Liste der Datensätze in einen einzelnen DataFrame.

sql(sql: str) -> DataFrame

Parameter

Name	Beschreibung
sql Erforderlich	str Unterstützte SQL SELECT-Anweisung.

Gibt zurück

Typ	Beschreibung
Dataframe	DataFrame mit allen Ergebniszeilen. Gibt einen leeren DataFrame zurück, wenn keine Zeilen übereinstimmen.

Ausnahmen

Typ	Beschreibung
ValidationError	Wenn `sql` es sich nicht um eine Zeichenfolge handelt oder leer ist.

Beispiele

SQL-Abfrage zu 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())

Aggregatabfrage zu 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

Aktualisieren von Datensätzen aus einem Pandas DataFrame.

Jede Zeile im DataFrame stellt eine Aktualisierung dar. Gibt id_column an, welche Spalte die Datensatz-GUIDs enthält.

Tip

Alle Zeilen werden in einer einzelnen UpdateMultiple-Anforderung (oder einer

einzelner PATCH für eine Zeile). Berücksichtigen Sie bei sehr großen DataFrames

Aufteilen in kleinere Batches, um Anforderungstimeouts zu vermeiden.

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

Parameter

Name	Beschreibung
table Erforderlich	str Schemaname der Tabelle (z. B. `"account"` oder `"new_MyTestTable"`).
changes Erforderlich	Dataframe DataFrame, in dem jede Zeile eine Datensatz-GUID und die zu aktualisierenden Felder enthält.
id_column Erforderlich	str Name der DataFrame-Spalte, die Datensatz-GUIDs enthält.
clear_nulls	bool Wenn `False` (Standardeinstellung) fehlende Werte (NaN/None) übersprungen werden (das Feld bleibt unverändert auf dem Server). Wenn `True`fehlende Werte an `null` Dataverse gesendet werden, wird das Feld gelöscht. Verwenden Sie `True` diesen Wert nur, wenn Sie beabsichtigt möchten, dass NaN/None-Werte Felder löschen. Standardwert: False

Ausnahmen

Typ	Beschreibung
TypeError	If `changes` is not a pandas DataFrame.
ValueError	Wenn `changes` sie leer ist, `id_column` wird im DataFrame nicht gefunden, `id_column` enthält ungültige (nicht Zeichenfolgen-, leere oder Leerzeichen)-Werte, oder es sind keine aktualisierbaren Spalten vorhanden`id_column`.`Falseclear_nullsclear_nullsTrue`

Beispiele

Aktualisieren von Datensätzen mit unterschiedlichen Werten pro Zeile:


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

Übertragen Sie dieselbe Änderung an alle Datensätze:


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

Löschen Sie ein Feld, indem Sie clear_nulls=True festlegen:


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