DataFrameOperations Класс

Пространство имен для операций CRUD с кадрами данных Pandas.

Доступ к ней осуществляется через client.dataframe. Предоставляет оболочки, ориентированные на кадры данных, вокруг операций CRUD на уровне записей.

Пример:


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

Конструктор

DataFrameOperations(client: DataverseClient)

Параметры

Имя	Описание
client Обязательно	DataverseClient Родительский DataverseClient экземпляр.

Методы

create	Создайте записи из кадра данных Pandas. Tip Все строки отправляются в одном запросе CreateMultiple. Для очень крупные кадры данных, рассмотрите возможность разделения на небольшие пакеты, чтобы избежать время ожидания запроса.
delete	Удаление записей путем передачи pandas series of GUID.
get	Получение записей и возвращение в виде одного кадра данных Pandas. При `record_id` указании возвращает однострочные кадры данных. Если `record_id` значение None, внутренне выполняет итерацию всех страниц и возвращает один консолидированный кадр данных. Tip Для больших таблиц используйте верхний или фильтр, чтобы ограничить результирующий набор.
sql	Выполните SQL-запрос и верните результаты в виде кадра данных pandas. Делегирует sql и преобразует список записей в один кадр данных.
update	Обновление записей из кадра данных Pandas. Каждая строка в кадре данных представляет обновление. Указывает `id_column` , какой столбец содержит идентификаторы GUID записей. Tip Все строки отправляются в одном запросе UpdateMultiple (или одно исправление для одной строки). Для очень больших кадров данных рассмотрите возможность разделение на небольшие пакеты, чтобы избежать времени ожидания запроса.

create

Создайте записи из кадра данных Pandas.

Tip

Все строки отправляются в одном запросе CreateMultiple. Для очень

крупные кадры данных, рассмотрите возможность разделения на небольшие пакеты, чтобы избежать

время ожидания запроса.

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

Параметры

Имя	Описание
table Обязательно	str Имя схемы таблицы (например `"account"` , или `"new_MyTestTable"`).
records Обязательно	Dataframe Кадр данных, в котором каждая строка является записью для создания.

Возвращаемое значение

Тип	Описание
Series	Ряд созданных графических идентификаторов записей, выровненных с входным индексом DataFrame.

Исключения

Тип	Описание
TypeError	Если `records` это не кадр данных Pandas.
ValueError	Если `records` идентификаторы пусты или количество возвращаемых идентификаторов не соответствует количеству входных строк.

Примеры

Создание записей из кадра данных:


   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

Удаление записей путем передачи pandas series of GUID.

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

Параметры

Имя	Описание
table Обязательно	str Имя схемы таблицы (например `"account"` , или `"new_MyTestTable"`).
ids Обязательно	Series Ряд идентификаторов ИДЕНТИФИКАТОРов записей для удаления.
use_bulk_delete	bool Если `True` (по умолчанию) и `ids` содержит несколько значений, выполните действие BulkDelete и верните его асинхронный идентификатор задания. При `False` последовательном удалении каждой записи. Default value: True

Возвращаемое значение

Тип	Описание
str, None	Идентификатор задания BulkDelete при удалении нескольких записей с помощью BulkDelete; `None` при удалении одной записи с использованием последовательного удаления или при `ids` его удалении.

Исключения

Тип	Описание
TypeError	Если `ids` это не серия pandas.
ValueError	Если `ids` содержит недопустимые (нестроковые, пустые или только пробелы) значения.

Примеры

Удаление записей с помощью ряда:


   import pandas as pd

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

get

Получение записей и возвращение в виде одного кадра данных Pandas.

При record_id указании возвращает однострочные кадры данных. Если record_id значение None, внутренне выполняет итерацию всех страниц и возвращает один консолидированный кадр данных.

Tip

Для больших таблиц используйте верхний или фильтр, чтобы ограничить результирующий набор.

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

Параметры

Имя	Описание
table Обязательно	str Имя схемы таблицы (например `"account"` , или `"new_MyTestTable"`).
record_id	str Необязательный GUID для получения определенной записи. Если нет, запросит несколько записей. Default value: None
select	list[str] или None Необязательный список логических имен атрибутов для получения. Default value: None
filter	str Необязательная строка фильтра OData. Имена столбцов должны использовать точные логические имена строчных регистров. Default value: None
orderby	list[str] или None Необязательный список атрибутов для сортировки по. Default value: None
top	int Необязательное максимальное количество возвращаемых записей. Default value: None
expand	list[str] или None Необязательный список свойств навигации для расширения (учитывает регистр). Default value: None
page_size	int Необязательное число записей на страницу для разбиения на страницы. Default value: None
count	bool Если `True`, добавляется `$count=true` для включения общего количества записей в ответ. Default value: False
include_annotations	str Шаблон заметки OData для заголовка `Prefer: odata.include-annotations` (например `"*"` , или `"OData.Community.Display.V1.FormattedValue"`) или `None`. Default value: None

Возвращаемое значение

Тип	Описание
Dataframe	Кадр данных, содержащий все соответствующие записи. Возвращает пустой кадр данных, если записи не совпадают.

Исключения

Тип	Описание
ValueError	Если `record_id` строка не является пустой или если параметры запроса ( `filterorderbytopexpandpage_sizerecord_id`

Примеры

Получение одной записи в виде кадра данных:


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

Запрос с фильтрацией:


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

Ограничение размера результата:


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

sql

Выполните SQL-запрос и верните результаты в виде кадра данных pandas.

Делегирует sql и преобразует список записей в один кадр данных.

sql(sql: str) -> DataFrame

Параметры

Имя	Описание
sql Обязательно	str Поддерживаемая инструкция SQL SELECT.

Возвращаемое значение

Тип	Описание
Dataframe	Кадр данных, содержащий все строки результатов. Возвращает пустой кадр данных, если строки не совпадают.

Исключения

Тип	Описание
ValidationError	Если `sql` строка не является или пуста.

Примеры

SQL-запрос к Кадру данных:


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

Агрегированный запрос к Кадру данных:


   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

Обновление записей из кадра данных Pandas.

Каждая строка в кадре данных представляет обновление. Указывает id_column , какой столбец содержит идентификаторы GUID записей.

Tip

Все строки отправляются в одном запросе UpdateMultiple (или

одно исправление для одной строки). Для очень больших кадров данных рассмотрите возможность

разделение на небольшие пакеты, чтобы избежать времени ожидания запроса.

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

Параметры

Имя	Описание
table Обязательно	str Имя схемы таблицы (например `"account"` , или `"new_MyTestTable"`).
changes Обязательно	Dataframe Кадр данных, в котором каждая строка содержит GUID записи и поля для обновления.
id_column Обязательно	str Имя столбца DataFrame, содержащего идентификаторы GUID записей.
clear_nulls	bool Если `False` (по умолчанию) отсутствующие значения (NaN/None) пропускаются (поле остается неизменным на сервере). Когда `True`отсутствующие значения отправляются в `null` Dataverse, очищая поле. Используйте `True` только в том случае, если вы намеренно хотите, чтобы значения NaN/None очищали поля. Default value: False

Исключения

Тип	Описание
TypeError	Если `changes` это не кадр данных Pandas.
ValueError	Если `changes` он пуст, он не найден в кадре данных, `id_columnid_column` содержит недопустимые (нестроковые, пустые или только пробелы) значения, или кроме этого не существуют `Falseid_columnclear_nullsclear_nulls` обновляемые столбцы.`True`

Примеры

Обновите записи с разными значениями для каждой строки:


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

Транслировать одно и то же изменение для всех записей:


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

Снимите поле, задав параметр clear_nulls=True:


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