DataFrameOperations Clase

Espacio de nombres para las operaciones CRUD de DataFrame de Pandas.

Acceso a través de client.dataframe. Proporciona contenedores orientados a DataFrame en torno a las operaciones CRUD de nivel de registro.

Ejemplo:


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

Constructor

DataFrameOperations(client: DataverseClient)

Parámetros

Nombre	Description
client Requerido	DataverseClient Instancia primaria DataverseClient .

Métodos

create	Cree registros a partir de un dataFrame de Pandas. Sugerencia Todas las filas se envían en una única solicitud CreateMultiple. Para muy Tramas de datos grandes, considere la posibilidad de dividir en lotes más pequeños para evitar tiempos de espera de solicitud.
delete	Elimine registros pasando una serie pandas de GUID.
get	Capturar registros y devolver como un único DataFrame de Pandas. Cuando `record_id` se proporciona, devuelve un DataFrame de una sola fila. Cuando `record_id` es None, itera internamente todas las páginas y devuelve un dataframe consolidado. Sugerencia Para tablas grandes, use top o filter para limitar el conjunto de resultados.
sql	Ejecute una consulta SQL y devuelva los resultados como dataFrame de Pandas. Los delegados a sql y convierten la lista de registros en un solo DataFrame.
update	Actualice los registros de un DataFrame de Pandas. Cada fila del DataFrame representa una actualización. `id_column` Especifica qué columna contiene los GUID de registro. Sugerencia Todas las filas se envían en una única solicitud UpdateMultiple (o una patch único para una fila). Para tramas de datos muy grandes, considere la posibilidad de dividir en lotes más pequeños para evitar tiempos de espera de solicitud.

create

Cree registros a partir de un dataFrame de Pandas.

Sugerencia

Todas las filas se envían en una única solicitud CreateMultiple. Para muy

Tramas de datos grandes, considere la posibilidad de dividir en lotes más pequeños para evitar

tiempos de espera de solicitud.

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

Parámetros

Nombre	Description
table Requerido	str Nombre de esquema de la tabla (por ejemplo `"account"` , o `"new_MyTestTable"`).
records Requerido	Dataframe DataFrame donde cada fila es un registro que se va a crear.

Devoluciones

Tipo	Description
Series	Serie de GUID de registro creados, alineados con el índice de dataframe de entrada.

Excepciones

Tipo	Description
TypeError	Si `records` no es un DataFrame de Pandas.
ValueError	Si `records` está vacío o el número de identificadores devueltos no coincide con el número de filas de entrada.

Ejemplos

Cree registros a partir de 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

Elimine registros pasando una serie pandas de GUID.

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

Parámetros

Nombre	Description
table Requerido	str Nombre de esquema de la tabla (por ejemplo `"account"` , o `"new_MyTestTable"`).
ids Requerido	Series Serie de GUID de registro que se van a eliminar.
use_bulk_delete	bool Cuando `True` (valor predeterminado) y `ids` contiene varios valores, ejecute la acción BulkDelete y devuelva su identificador de trabajo asincrónico. Cuando `False` cada registro se elimina secuencialmente. Valor predeterminado: True

Devoluciones

Tipo	Description
str, None	BulkDelete job ID al eliminar varios registros a través de BulkDelete; `None` al eliminar un único registro, mediante la eliminación secuencial o cuando `ids` está vacío.

Excepciones

Tipo	Description
TypeError	Si `ids` no es una serie pandas.
ValueError	Si `ids` contiene valores no válidos (sin cadena, vacíos o solo espacios en blanco).

Ejemplos

Eliminar registros mediante una serie:


   import pandas as pd

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

get

Capturar registros y devolver como un único DataFrame de Pandas.

Cuando record_id se proporciona, devuelve un DataFrame de una sola fila. Cuando record_id es None, itera internamente todas las páginas y devuelve un dataframe consolidado.

Sugerencia

Para tablas grandes, use top o filter para limitar el 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

Nombre	Description
table Requerido	str Nombre de esquema de la tabla (por ejemplo `"account"` , o `"new_MyTestTable"`).
record_id	str GUID opcional para capturar un registro específico. Si no, consulta varios registros. Valor predeterminado: None
select	list[str] o None Lista opcional de nombres lógicos de atributo que se van a recuperar. Valor predeterminado: None
filter	str Cadena de filtro OData opcional. Los nombres de columna deben usar nombres lógicos en minúsculas exactos. Valor predeterminado: None
orderby	list[str] o None Lista opcional de atributos por los que se va a ordenar. Valor predeterminado: None
top	int Número máximo opcional de registros que se van a devolver. Valor predeterminado: None
expand	list[str] o None Lista opcional de propiedades de navegación que se van a expandir (distingue mayúsculas de minúsculas). Valor predeterminado: None
page_size	int Número opcional de registros por página para la paginación. Valor predeterminado: None
count	bool Si `True`es , agrega `$count=true` para incluir un recuento total de registros en la respuesta. Valor predeterminado: False
include_annotations	str Patrón de anotación de OData para el `Prefer: odata.include-annotations` encabezado (por ejemplo `"*"` , o `"OData.Community.Display.V1.FormattedValue"`) o `None`. Valor predeterminado: None

Devoluciones

Tipo	Description
Dataframe	DataFrame que contiene todos los registros coincidentes. Devuelve un dataframe vacío cuando no coinciden registros.

Excepciones

Tipo	Description
ValueError	Si `record_id` no es una cadena no vacía o si los parámetros de consulta ( `filterorderbytopexpandpage_sizerecord_id`

Ejemplos

Capturar un único registro como dataframe:


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

Consulta con filtrado:


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

Limitar el tamaño del resultado:


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

sql

Ejecute una consulta SQL y devuelva los resultados como dataFrame de Pandas.

Los delegados a sql y convierten la lista de registros en un solo DataFrame.

sql(sql: str) -> DataFrame

Parámetros

Nombre	Description
sql Requerido	str Instrucción SELECT de SQL admitida.

Devoluciones

Tipo	Description
Dataframe	DataFrame que contiene todas las filas de resultados. Devuelve un dataframe vacío cuando no coinciden filas.

Excepciones

Tipo	Description
ValidationError	Si `sql` no es una cadena o está vacía.

Ejemplos

Consulta SQL a 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 de agregado a 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

Actualice los registros de un DataFrame de Pandas.

Cada fila del DataFrame representa una actualización. id_column Especifica qué columna contiene los GUID de registro.

Sugerencia

Todas las filas se envían en una única solicitud UpdateMultiple (o una

patch único para una fila). Para tramas de datos muy grandes, considere la posibilidad de

dividir en lotes más pequeños para evitar tiempos de espera de solicitud.

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

Parámetros

Nombre	Description
table Requerido	str Nombre de esquema de la tabla (por ejemplo `"account"` , o `"new_MyTestTable"`).
changes Requerido	Dataframe DataFrame donde cada fila contiene un GUID de registro y los campos que se van a actualizar.
id_column Requerido	str Nombre de la columna DataFrame que contiene GUID de registro.
clear_nulls	bool Cuando `False` (valor predeterminado), se omiten los valores que faltan (NaN/None) (el campo se deja sin cambios en el servidor). Cuando `True`, los valores que faltan se envían a `null` Dataverse, borrando el campo. Use `True` solo cuando desee intencionadamente valores NaN/None para borrar campos. Valor predeterminado: False

Excepciones

Tipo	Description
TypeError	Si `changes` no es un DataFrame de Pandas.
ValueError	Si `changes` está vacío, `id_column` no se encuentra en dataframe, `id_column` contiene valores no válidos (no string, vacíos o solo espacios en blanco), o no existe ninguna columna actualizable además `id_columnclear_nulls` de es .`Falseclear_nullsTrue`

Ejemplos

Actualice los registros con valores diferentes por fila:


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

Difunda el mismo cambio en todos los registros:


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

Desactive un campo estableciendo clear_nulls=True:


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