DataFrameOperations Classe

Espace de noms pour les opérations CRUD de trame de données pandas.

Accessible via client.dataframe. Fournit des wrappers orientés DataFrame autour des opérations CRUD au niveau de l’enregistrement.

Exemple :


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

Constructeur

DataFrameOperations(client: DataverseClient)

Paramètres

Nom	Description
client Obligatoire	DataverseClient Instance parente DataverseClient .

Méthodes

create	Créez des enregistrements à partir d’un DataFrame pandas. Tip Toutes les lignes sont envoyées dans une seule requête CreateMultiple. Pour très Grands DataFrames, envisagez de fractionner en lots plus petits pour éviter délai d’expiration de la requête.
delete	Supprimez les enregistrements en passant une série pandas de GUID.
get	Récupérez des enregistrements et retournez en tant que DataFrame pandas unique. Quand `record_id` elle est fournie, retourne un DataFrame à une seule ligne. Lorsqu’il `record_id` s’agit de None, itère en interne toutes les pages et retourne un DataFrame consolidé. Tip Pour les tables volumineuses, utilisez le haut ou le filtre pour limiter le jeu de résultats.
sql	Exécutez une requête SQL et retournez les résultats sous forme de DataFrame pandas. Délégués vers sql et convertit la liste des enregistrements en un seul DataFrame.
update	Mettez à jour les enregistrements à partir d’un DataFrame pandas. Chaque ligne du DataFrame représente une mise à jour. Spécifie `id_column` quelle colonne contient les GUID d’enregistrement. Tip Toutes les lignes sont envoyées dans une seule requête UpdateMultiple (ou patch unique pour une ligne). Pour les dataFrames très volumineux, envisagez fractionnement en lots plus petits pour éviter les délais d’expiration des demandes.

create

Créez des enregistrements à partir d’un DataFrame pandas.

Tip

Toutes les lignes sont envoyées dans une seule requête CreateMultiple. Pour très

Grands DataFrames, envisagez de fractionner en lots plus petits pour éviter

délai d’expiration de la requête.

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

Paramètres

Nom	Description
table Obligatoire	str Nom du schéma de la table (par exemple `"account"` , ou `"new_MyTestTable"`).
records Obligatoire	Dataframe DataFrame où chaque ligne est un enregistrement à créer.

Retours

Type	Description
Series	Série de GUID d’enregistrement créés, alignés avec l’index DataFrame d’entrée.

Exceptions

Type	Description
TypeError	Si `records` ce n’est pas un DataFrame pandas.
ValueError	S’il `records` est vide ou si le nombre d’ID retournés ne correspond pas au nombre de lignes d’entrée.

Exemples

Créez des enregistrements à partir d’un 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

Supprimez les enregistrements en passant une série pandas de GUID.

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

Paramètres

Nom	Description
table Obligatoire	str Nom du schéma de la table (par exemple `"account"` , ou `"new_MyTestTable"`).
ids Obligatoire	Series Série de GUID d’enregistrement à supprimer.
use_bulk_delete	bool Quand `True` (valeur par défaut) et `ids` contient plusieurs valeurs, exécutez l’action BulkDelete et retournez son identificateur de travail asynchrone. Lorsque `False` chaque enregistrement est supprimé séquentiellement. Valeur par défaut: True

Retours

Type	Description
str, None	ID de travail BulkDelete lors de la suppression de plusieurs enregistrements via BulkDelete ; `None` lors de la suppression d’un enregistrement unique, à l’aide d’une suppression séquentielle ou lorsqu’il `ids` est vide.

Exceptions

Type	Description
TypeError	S’il `ids` ne s’agit pas d’une série pandas.
ValueError	Si `ids` elle contient des valeurs non valides (non string, vides ou espaces blancs uniquement).

Exemples

Supprimez les enregistrements à l’aide d’une série :


   import pandas as pd

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

get

Récupérez des enregistrements et retournez en tant que DataFrame pandas unique.

Quand record_id elle est fournie, retourne un DataFrame à une seule ligne. Lorsqu’il record_id s’agit de None, itère en interne toutes les pages et retourne un DataFrame consolidé.

Tip

Pour les tables volumineuses, utilisez le haut ou le filtre pour limiter le jeu de résultats.

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

Paramètres

Nom	Description
table Obligatoire	str Nom du schéma de la table (par exemple `"account"` , ou `"new_MyTestTable"`).
record_id	str GUID facultatif pour extraire un enregistrement spécifique. Si ce n’est pas le cas, interroge plusieurs enregistrements. Valeur par défaut: None
select	list[str] ou None Liste facultative des noms logiques d’attribut à récupérer. Valeur par défaut: None
filter	str Chaîne de filtre OData facultative. Les noms de colonnes doivent utiliser des noms logiques minuscules exacts. Valeur par défaut: None
orderby	list[str] ou None Liste facultative d’attributs à trier. Valeur par défaut: None
top	int Nombre maximal facultatif d’enregistrements à retourner. Valeur par défaut: None
expand	list[str] ou None Liste facultative des propriétés de navigation à développer (respectant la casse). Valeur par défaut: None
page_size	int Nombre facultatif d’enregistrements par page pour la pagination. Valeur par défaut: None
count	bool Si `True`, ajoute `$count=true` pour inclure un nombre total d’enregistrements dans la réponse. Valeur par défaut: False
include_annotations	str Modèle d’annotation OData pour l’en-tête `Prefer: odata.include-annotations` (par exemple `"*"` , ou `"OData.Community.Display.V1.FormattedValue"`) ou `None`. Valeur par défaut: None

Retours

Type	Description
Dataframe	DataFrame contenant tous les enregistrements correspondants. Retourne un DataFrame vide lorsqu’aucun enregistrement ne correspond.

Exceptions

Type	Description
ValueError	S’il `record_id` ne s’agit pas d’une chaîne non vide ou si les paramètres de requête ( `filterorderbytopexpandpage_sizerecord_id`

Exemples

Récupérez un enregistrement unique en tant que DataFrame :


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

Requête avec filtrage :


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

Limitez la taille des résultats :


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

sql

Exécutez une requête SQL et retournez les résultats sous forme de DataFrame pandas.

Délégués vers sql et convertit la liste des enregistrements en un seul DataFrame.

sql(sql: str) -> DataFrame

Paramètres

Nom	Description
sql Obligatoire	str Instruction SQL SELECT prise en charge.

Retours

Type	Description
Dataframe	DataFrame contenant toutes les lignes de résultat. Retourne un DataFrame vide lorsqu’aucune ligne ne correspond.

Exceptions

Type	Description
ValidationError	S’il `sql` ne s’agit pas d’une chaîne ou est vide.

Exemples

Requête SQL vers 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())

Agréger la requête vers 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

Mettez à jour les enregistrements à partir d’un DataFrame pandas.

Chaque ligne du DataFrame représente une mise à jour. Spécifie id_column quelle colonne contient les GUID d’enregistrement.

Tip

Toutes les lignes sont envoyées dans une seule requête UpdateMultiple (ou

patch unique pour une ligne). Pour les dataFrames très volumineux, envisagez

fractionnement en lots plus petits pour éviter les délais d’expiration des demandes.

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

Paramètres

Nom	Description
table Obligatoire	str Nom du schéma de la table (par exemple `"account"` , ou `"new_MyTestTable"`).
changes Obligatoire	Dataframe DataFrame où chaque ligne contient un GUID d’enregistrement et les champs à mettre à jour.
id_column Obligatoire	str Nom de la colonne DataFrame contenant des GUID d’enregistrement.
clear_nulls	bool Lorsque `False` (valeur par défaut), les valeurs manquantes (NaN/None) sont ignorées (le champ est laissé inchangé sur le serveur). Lorsque `True`, les valeurs manquantes sont envoyées à `null` Dataverse, en désactivant le champ. Utilisez `True` uniquement lorsque vous souhaitez intentionnellement que les valeurs NaN/None effacent les champs. Valeur par défaut: False

Exceptions

Type	Description
TypeError	Si `changes` ce n’est pas un DataFrame pandas.
ValueError	S’il `changes` est vide, `id_column` n’est pas trouvé dans le DataFrame, `id_column` contient des valeurs non valides (non-chaîne, vides ou espaces blancs `Falseid_columnclear_nullsclear_nulls` uniquement), ou aucune colonne pouvant être mise à jour n’existe pas.`True`

Exemples

Mettez à jour les enregistrements avec différentes valeurs par ligne :


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

Diffusez la même modification sur tous les enregistrements :


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

Effacez un champ en définissant clear_nulls=True :


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