DataFrameOperations Classe

Namespace para operações CRUD do DataFrame do Pandas.

Acessado por meio de client.dataframe. Fornece wrappers orientados a DataFrame em torno das operações CRUD no nível do registro.

Exemplo:

   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

Nome	Description
client Obrigatório	DataverseClient A instância pai DataverseClient .

Métodos

create	Crie registros de um DataFrame do Pandas. Dica Todas as linhas são enviadas em uma única solicitação CreateMultiple. Para muito DataFrames grandes, considere dividir em lotes menores para evitar tempos limite de solicitação.
delete	Exclua registros passando uma série pandas de GUIDs.
get	Buscar registros e retornar como um único DataFrame pandas. Quando record_id for fornecido, retornará um DataFrame de linha única. Quando record_id é None, itera internamente todas as páginas e retorna um DataFrame consolidado. Dica Para tabelas grandes, use a parte superior ou o filtro para limitar o conjunto de resultados.
sql	Execute uma consulta SQL e retorne os resultados como um DataFrame pandas. sql Delega e converte a lista de registros em um único DataFrame.
update	Atualize os registros de um DataFrame do Pandas. Cada linha no DataFrame representa uma atualização. A id_column coluna especifica qual coluna contém os GUIDs de registro. Dica Todas as linhas são enviadas em uma única solicitação UpdateMultiple (ou uma patch único para uma linha). Para DataFrames muito grandes, considere dividindo em lotes menores para evitar tempos limite de solicitação.

create

Crie registros de um DataFrame do Pandas.

Dica

Todas as linhas são enviadas em uma única solicitação CreateMultiple. Para muito

DataFrames grandes, considere dividir em lotes menores para evitar

tempos limite de solicitação.

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

Parâmetros

Nome	Description
table Obrigatório	str Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
records Obrigatório	Dataframe DataFrame em que cada linha é um registro a ser criado.

Retornos

Tipo	Description
Series	Série de GUIDs de registro criados, alinhadas 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 retornadas não corresponder ao número de linhas de entrada.

Exemplos

Criar registros 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

Exclua registros passando uma série pandas de GUIDs.

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

Parâmetros

Nome	Description
table Obrigatório	str Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
ids Obrigatório	Series Série de GUIDs de registro a serem excluídos.
use_bulk_delete	bool Quando True (padrão) e ids contiver vários valores, execute a ação BulkDelete e retorne seu identificador de trabalho assíncrono. Quando False cada registro é excluído sequencialmente. Valor padrão: True

Retornos

Tipo	Description
str, None	ID do trabalho BulkDelete ao excluir vários registros via BulkDelete; None ao excluir um único registro, usando exclusão sequencial ou quando ids estiver vazio.

Exceções

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

Exemplos

Excluir registros usando uma série:

   import pandas as pd

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

get

Buscar registros e retornar como um único DataFrame pandas.

Quando record_id for fornecido, retornará um DataFrame de linha única. Quando record_id é None, itera internamente todas as páginas e retorna um DataFrame consolidado.

Dica

Para tabelas grandes, use a parte superior ou o 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

Nome	Description
table Obrigatório	str Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
record_id	str GUID opcional para buscar um registro específico. Se Nenhum, consulta vários registros. Valor padrão: None
select	list[str] ou None Lista opcional de nomes lógicos de atributo a serem recuperados. Valor padrão: None
filter	str Cadeia de caracteres de filtro OData opcional. Os nomes de coluna devem usar nomes lógicos minúsculos exatos. Valor padrão: None
orderby	list[str] ou None Lista opcional de atributos a serem classificados. Valor padrão: None
top	int Número máximo opcional de registros a serem retornados. Valor padrão: None
expand	list[str] ou None Lista opcional de propriedades de navegação a serem expandidas (diferencia maiúsculas de minúsculas). Valor padrão: None
page_size	int Número opcional de registros por página para paginação. Valor padrão: None
count	bool Se True, adiciona $count=true para incluir uma contagem total de registros na resposta. Valor padrão: 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. Valor padrão: None

Retornos

Tipo	Description
Dataframe	DataFrame que contém todos os registros correspondentes. Retorna um DataFrame vazio quando nenhum registro corresponde.

Exceções

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

Exemplos

Buscar um único registro como um 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")

Limitar o tamanho do resultado:

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

sql

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

sql Delega e converte a lista de registros em um único DataFrame.

sql(sql: str) -> DataFrame

Parâmetros

Nome	Description
sql Obrigatório	str Instrução SQL SELECT com suporte.

Retornos

Tipo	Description
Dataframe	DataFrame que contém todas as linhas de resultado. Retorna um DataFrame vazio quando nenhuma linha corresponde.

Exceções

Tipo	Description
ValidationError	Se sql não for uma cadeia de caracteres 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())

Agregar consulta ao 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

Atualize os registros de um DataFrame do Pandas.

Cada linha no DataFrame representa uma atualização. A id_column coluna especifica qual coluna contém os GUIDs de registro.

Dica

Todas as linhas são enviadas em uma única solicitação UpdateMultiple (ou uma

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

dividindo em lotes menores para evitar tempos limite de solicitação.

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

Parâmetros

Nome	Description
table Obrigatório	str Nome do esquema da tabela (por exemplo, "account" ou "new_MyTestTable").
changes Obrigatório	Dataframe DataFrame em que cada linha contém um GUID de registro e os campos a serem atualizados.
id_column Obrigatório	str Nome da coluna DataFrame que contém GUIDs de registro.
clear_nulls	bool Quando False (padrão), os valores ausentes (NaN/None) são ignorados (o campo é deixado inalterado no servidor). Quando True, os valores ausentes são enviados como null para o Dataverse, desmarcando o campo. Use True somente quando desejar intencionalmente que os valores NaN/None desmarquem campos. Valor padrão: False

Exceções

Tipo	Description
TypeError	Se changes não for um DataFrame pandas.
ValueError	Se changes estiver vazio, id_column não for encontrado no DataFrame, id_column contiver valores inválidos (sem cadeia de caracteres, vazias ou somente espaço em branco) ou nenhuma coluna atualizável existir além id_columnclear_nulls de is Falseclear_nullsTrue

Exemplos

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

Transmita a mesma alteração para todos os registros:

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

Desmarque um campo definindo clear_nulls=True:

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