DataFrameOperations Classe

Namespace para operações dataFrame CRUD de pandas.

Acedido via client.dataframe. Fornece wrappers orientados a DataFrame para as operações CRUD ao nível de registo.

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

Construtor

DataFrameOperations(client: DataverseClient)

Parâmetros

Name	Description
client Necessário	DataverseClient A instância principal DataverseClient .

Métodos

create	Criar registos a partir de um DataFrame pandas. Gorjeta Todas as linhas são enviadas num único pedido CreateMultiplex. Por muito DataFrames grandes, considere dividir em lotes mais pequenos para evitar Peça tempos mortos.
delete	Apague registos passando uma série de GUIDs pandas.
get	Obtém registos e retornam como um único DataFrame pandas. Quando `record_id` é fornecido, devolve um DataFrame de uma única linha. Quando `record_id` é Nenhum, itera internamente todas as páginas e retorna um DataFrame consolidado. Gorjeta Para tabelas grandes, use topo ou filtro para limitar o conjunto de resultados.
sql	Execute uma consulta SQL e devolve os resultados como um DataFrame pandas. Delega para sql e converte a lista de registos num único DataFrame.
update	Atualizar registos a partir de um DataFrame pandas. Cada linha no DataFrame representa uma atualização. Especifica `id_column` qual coluna contém os GUIDs dos registos. Gorjeta Todas as linhas são enviadas num único pedido UpdateMultiple (ou num um único PATCH para uma linha). Para DataFrames muito grandes, considere Dividir em lotes mais pequenos para evitar tempos de espera dos pedidos.

create

Criar registos a partir de um DataFrame pandas.

Gorjeta

Todas as linhas são enviadas num único pedido CreateMultiplex. Por muito

DataFrames grandes, considere dividir em lotes mais pequenos para evitar

Peça tempos mortos.

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

Parâmetros

Name	Description
table Necessário	str Nome do esquema da tabela (por exemplo, `"account"` ou `"new_MyTestTable"`).
records Necessário	Dataframe DataFrame onde cada linha é um registo a criar.

Devoluções

Tipo	Description
Series	Série de GUIDs de registo criados, alinhados com o índice DataFrame de entrada.

Exceções

Tipo	Description
TypeError	Se `records` não for um DataFrame pandas.
ValueError	Se `records` estiver vazio ou o número de IDs devolvidos não corresponder ao número de linhas de entrada.

Exemplos

Criar registos a partir de um 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

Apague registos passando uma série de GUIDs pandas.

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

Parâmetros

Name	Description
table Necessário	str Nome do esquema da tabela (por exemplo, `"account"` ou `"new_MyTestTable"`).
ids Necessário	Series Série de GUIDs de registo para eliminar.
use_bulk_delete	bool Quando `True` (por defeito) e `ids` contiver múltiplos valores, execute a ação BulkDelete e devolve o seu identificador de trabalho assíncrono. Quando `False` cada registo é eliminado sequencialmente. Default value: True

Devoluções

Tipo	Description
str, None	ID de trabalho BulkDelete ao eliminar múltiplos registos via BulkDelete; `None` ao eliminar um único registo, usando eliminação sequencial, ou quando `ids` está vazio.

Exceções

Tipo	Description
TypeError	Se `ids` não é uma série pandas.
ValueError	Se `ids` contiver valores inválidos (sem cadeia, vazios ou apenas em espaços em branco).

Exemplos

Apagar registos usando uma Série:


   import pandas as pd

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

get

Obtém registos e retornam como um único DataFrame pandas.

Quando record_id é fornecido, devolve um DataFrame de uma única linha. Quando record_id é Nenhum, itera internamente todas as páginas e retorna um DataFrame consolidado.

Gorjeta

Para tabelas grandes, use topo ou filtro para limitar o conjunto de resultados.

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

Parâmetros

Name	Description
table Necessário	str Nome do esquema da tabela (por exemplo, `"account"` ou `"new_MyTestTable"`).
record_id	str GUID opcional para obter um registo específico. Se não houver, consulta múltiplos registos. Default value: None
select	list[str] ou None Lista opcional de nomes lógicos de atributos a recuperar. Default value: None
filter	str Cadeia opcional de filtro OData. Os nomes das colunas devem usar nomes lógicos minúsculos exatos. Default value: None
orderby	list[str] ou None Lista opcional de atributos para ordenar. Default value: None
top	int Número máximo opcional de registos a devolver. Default value: None
expand	list[str] ou None Lista opcional de propriedades de navegação a expandir (distinção de maiúsculas e minúsculas). Default value: None
page_size	int Número opcional de registos por página para paginação. Default value: None
count	bool Se `True`, soma `$count=true` para incluir uma contagem total de registos na resposta. Default value: False
include_annotations	str Padrão de anotação OData para o `Prefer: odata.include-annotations` cabeçalho (por exemplo, `"*"` ou `"OData.Community.Display.V1.FormattedValue"`), ou `None`. Default value: None

Devoluções

Tipo	Description
Dataframe	DataFrame contendo todos os registos correspondentes. Devolve um DataFrame vazio quando nenhum registo corresponde.

Exceções

Tipo	Description
ValueError	Se `record_id` não for uma cadeia não vazia, ou se parâmetros de consulta ( `filterorderbytopexpandpage_sizerecord_id`

Exemplos

Buscar um único registo como DataFrame:


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

Consulta com filtragem:


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

Tamanho limite do resultado:


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

sql

Execute uma consulta SQL e devolve os resultados como um DataFrame pandas.

Delega para sql e converte a lista de registos num único DataFrame.

sql(sql: str) -> DataFrame

Parâmetros

Name	Description
sql Necessário	str Instrução SQL SELECT suportada.

Devoluções

Tipo	Description
Dataframe	DataFrame contendo todas as linhas de resultados. Devolve um DataFrame vazio quando nenhuma linha corresponde.

Exceções

Tipo	Description
ValidationError	Se `sql` não for uma cadeia ou estiver vazia.

Exemplos

Consulta SQL para 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())

Consulta agregada para 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

Atualizar registos a partir de um DataFrame pandas.

Cada linha no DataFrame representa uma atualização. Especifica id_column qual coluna contém os GUIDs dos registos.

Gorjeta

Todas as linhas são enviadas num único pedido UpdateMultiple (ou num

um único PATCH para uma linha). Para DataFrames muito grandes, considere

Dividir em lotes mais pequenos para evitar tempos de espera dos pedidos.

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

Parâmetros

Name	Description
table Necessário	str Nome do esquema da tabela (por exemplo, `"account"` ou `"new_MyTestTable"`).
changes Necessário	Dataframe DataFrame onde cada linha contém um registo GUID e os campos a atualizar.
id_column Necessário	str Nome da coluna DataFrame que contém os GUIDs de registo.
clear_nulls	bool Quando `False` (por defeito), os valores em falta (NaN/Nenhum) são ignorados (o campo permanece inalterado no servidor). Quando `True`, os valores em falta são enviados como `null` para o Dataverse, limpando o campo. Use `True` apenas quando quiser intencionalmente que os valores de NaN/None limpem campos. Default value: False

Exceções

Tipo	Description
TypeError	Se `changes` não for um DataFrame pandas.
ValueError	Se for vazio, `id_column` não for encontrado no DataFrame, `id_column` contiver valores inválidos (não de string, vazio ou apenas de espaço em branco), ou não `changes` existirem colunas atualizáveis além `id_columnclear_nulls` de is `Falseclear_nulls` é`True`

Exemplos

Atualizar registos com valores diferentes por linha:


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

Transmitir a mesma alteração para todos os discos:


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

Limpar um campo definindo clear_nulls=Verdadeiro:


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