DataFrameOperations Classe

Spazio dei nomi per le operazioni CRUD del dataframe pandas.

Accesso tramite client.dataframe. Fornisce wrapper orientati ai dataframe per le operazioni CRUD a livello di record.

Esempio:


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

Costruttore

DataFrameOperations(client: DataverseClient)

Parametri

Nome	Descrizione
client Necessario	DataverseClient Istanza padre DataverseClient .

Metodi

create	Creare record da un dataframe pandas. Tip Tutte le righe vengono inviate in una singola richiesta CreateMultiple. Per molto dataframe di grandi dimensioni, prendere in considerazione la suddivisione in batch più piccoli per evitare timeout della richiesta.
delete	Eliminare i record passando una serie pandas di GUID.
get	Recuperare i record e restituire come singolo dataframe pandas. Quando `record_id` viene specificato, restituisce un dataframe a riga singola. Quando `record_id` è Nessuno, esegue internamente l'iterazione di tutte le pagine e restituisce un dataframe consolidato. Tip Per le tabelle di grandi dimensioni, usare top o filter per limitare il set di risultati.
sql	Eseguire una query SQL e restituire i risultati come dataframe pandas. Delegati in sql e converte l'elenco di record in un singolo dataframe.
update	Aggiornare i record da un dataframe pandas. Ogni riga nel dataframe rappresenta un aggiornamento. `id_column` Specifica la colonna contenente i GUID del record. Tip Tutte le righe vengono inviate in una singola richiesta UpdateMultiple (o patch singola per una riga. Per i dataframe molto grandi, prendere in considerazione suddivisione in batch più piccoli per evitare timeout delle richieste.

create

Creare record da un dataframe pandas.

Tip

Tutte le righe vengono inviate in una singola richiesta CreateMultiple. Per molto

dataframe di grandi dimensioni, prendere in considerazione la suddivisione in batch più piccoli per evitare

timeout della richiesta.

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

Parametri

Nome	Descrizione
table Necessario	str Nome dello schema della tabella ,ad esempio `"account"` o `"new_MyTestTable"`.
records Necessario	Dataframe DataFrame in cui ogni riga è un record da creare.

Valori restituiti

Tipo	Descrizione
Series	Serie di GUID di record creati, allineati all'indice dataframe di input.

Eccezioni

Tipo	Descrizione
TypeError	Se `records` non è un dataframe pandas.
ValueError	Se `records` è vuoto o il numero di ID restituiti non corrisponde al numero di righe di input.

Esempio

Creare record da 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

Eliminare i record passando una serie pandas di GUID.

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

Parametri

Nome	Descrizione
table Necessario	str Nome dello schema della tabella ,ad esempio `"account"` o `"new_MyTestTable"`.
ids Necessario	Series Serie di GUID di record da eliminare.
use_bulk_delete	bool Quando `True` (impostazione predefinita) e `ids` contiene più valori, eseguire l'azione BulkDelete e restituire l'identificatore del processo asincrono. Quando `False` ogni record viene eliminato in sequenza. Valore predefinito: True

Valori restituiti

Tipo	Descrizione
str, None	BulkDelete JOB ID quando si eliminano più record tramite BulkDelete; `None` quando si elimina un singolo record, usando l'eliminazione sequenziale o quando `ids` è vuoto.

Eccezioni

Tipo	Descrizione
TypeError	Se `ids` non è una serie pandas.
ValueError	Se `ids` contiene valori non validi (solo stringhe, vuote o spazi vuoti).

Esempio

Eliminare record usando una serie:


   import pandas as pd

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

get

Recuperare i record e restituire come singolo dataframe pandas.

Quando record_id viene specificato, restituisce un dataframe a riga singola. Quando record_id è Nessuno, esegue internamente l'iterazione di tutte le pagine e restituisce un dataframe consolidato.

Tip

Per le tabelle di grandi dimensioni, usare top o filter per limitare il set di risultati.

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

Parametri

Nome	Descrizione
table Necessario	str Nome dello schema della tabella ,ad esempio `"account"` o `"new_MyTestTable"`.
record_id	str GUID facoltativo per recuperare un record specifico. Se Nessuno, esegue una query su più record. Valore predefinito: None
select	list[str] oppure None Elenco facoltativo di nomi logici degli attributi da recuperare. Valore predefinito: None
filter	str Stringa di filtro OData facoltativa. I nomi delle colonne devono usare nomi logici minuscoli esatti. Valore predefinito: None
orderby	list[str] oppure None Elenco facoltativo di attributi per cui eseguire l'ordinamento. Valore predefinito: None
top	int Numero massimo facoltativo di record da restituire. Valore predefinito: None
expand	list[str] oppure None Elenco facoltativo delle proprietà di navigazione da espandere (con distinzione tra maiuscole e minuscole). Valore predefinito: None
page_size	int Numero facoltativo di record per paginazione. Valore predefinito: None
count	bool Se `True`, aggiunge `$count=true` per includere un conteggio totale dei record nella risposta. Valore predefinito: False
include_annotations	str Modello di annotazione OData per l'intestazione `Prefer: odata.include-annotations` (ad esempio `"*"` , o `"OData.Community.Display.V1.FormattedValue"`) o `None`. Valore predefinito: None

Valori restituiti

Tipo	Descrizione
Dataframe	DataFrame contenente tutti i record corrispondenti. Restituisce un dataframe vuoto quando nessun record corrisponde.

Eccezioni

Tipo	Descrizione
ValueError	Se `record_id` non è una stringa non vuota o se i parametri di query ( `filterorderbytopexpandpage_sizerecord_id`

Esempio

Recuperare un singolo record come dataframe:


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

Query con filtro:


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

Limitare le dimensioni dei risultati:


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

sql

Eseguire una query SQL e restituire i risultati come dataframe pandas.

Delegati in sql e converte l'elenco di record in un singolo dataframe.

sql(sql: str) -> DataFrame

Parametri

Nome	Descrizione
sql Necessario	str Istruzione SQL SELECT supportata.

Valori restituiti

Tipo	Descrizione
Dataframe	DataFrame contenente tutte le righe dei risultati. Restituisce un dataframe vuoto quando non corrispondono righe.

Eccezioni

Tipo	Descrizione
ValidationError	Se `sql` non è una stringa o è vuota.

Esempio

Query SQL nel 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())

Query di aggregazione nel 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

Aggiornare i record da un dataframe pandas.

Ogni riga nel dataframe rappresenta un aggiornamento. id_column Specifica la colonna contenente i GUID del record.

Tip

Tutte le righe vengono inviate in una singola richiesta UpdateMultiple (o

patch singola per una riga. Per i dataframe molto grandi, prendere in considerazione

suddivisione in batch più piccoli per evitare timeout delle richieste.

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

Parametri

Nome	Descrizione
table Necessario	str Nome dello schema della tabella ,ad esempio `"account"` o `"new_MyTestTable"`.
changes Necessario	Dataframe DataFrame in cui ogni riga contiene un GUID di record e i campi da aggiornare.
id_column Necessario	str Nome della colonna DataFrame contenente GUID di record.
clear_nulls	bool Quando `False` (impostazione predefinita), i valori mancanti (NaN/None) vengono ignorati (il campo rimane invariato nel server). Quando `True`, i valori mancanti vengono inviati a `null` Dataverse, cancellando il campo. Usare `True` solo quando si desidera intenzionalmente che i valori NaN/None cancellano i campi. Valore predefinito: False

Eccezioni

Tipo	Descrizione
TypeError	Se `changes` non è un dataframe pandas.
ValueError	Se `changes` è vuoto, `id_column` non viene trovato nel dataframe, `id_column` contiene valori non validi (non stringa, vuota o solo spazi vuoti) oppure non esiste alcuna colonna aggiornabile oltre `id_columnclear_nulls` a è `Falseclear_nullsTrue`

Esempio

Aggiornare i record con valori diversi per riga:


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

Trasmettere la stessa modifica a tutti i record:


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

Cancellare un campo impostando clear_nulls=True:


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