QueryOperations Класс

Создайте построитель текучих запросов для указанной таблицы.

Возвращает объект QueryBuilder , который можно связать с фильтром, выбором и порядком методов, а затем выполняться непосредственно с помощью .execute().

builder(table: str) -> QueryBuilder

Параметры

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

Примеры

Создайте и выполните запрос без изменений:

   from PowerPlatform.Dataverse.models.filters import col

   for record in (client.query.builder("account")
                  .select("name", "revenue")
                  .where(col("statecode") == 0)
                  .where(col("revenue") > 1_000_000)
                  .order_by("revenue", descending=True)
                  .top(100)
                  .page_size(50)
                  .execute()):
       print(record["name"])

С деревом компонуемых выражений:

   from PowerPlatform.Dataverse.models.filters import col

   for record in (client.query.builder("account")
                  .where((col("statecode") == 0) | (col("statecode") == 1))
                  .where(col("revenue") > 100_000)
                  .execute()):
       print(record["name"])

Возвращает инертный FetchXmlQuery объект.

Http-запрос не выполняется, пока execute или execute_pages не вызывается для возвращаемого объекта.

Используется для сценариев SQL-JOIN, агрегатных запросов или других операций, которые не могут выразить конечная точка конструктора OData.

Пример:

   query = client.query.fetchxml("""
     <fetch top="50">
       <entity name="account">
         <attribute name="name" />
         <link-entity name="contact" from="parentcustomerid"
                      to="accountid" alias="c" link-type="inner">
           <attribute name="fullname" />
         </link-entity>
       </entity>
     </fetch>
   """)

   # Eager — collect all pages:
   result = query.execute()
   df = result.to_dataframe()

   # Lazy — process one page at a time:
   for page in query.execute_pages():
       process(page.to_dataframe())

fetchxml(xml: str) -> FetchXmlQuery

Параметры

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

Исключения

@odata.bind Создайте запись для задания поля подстановки.

Автоматически обнаруживает имя свойства навигации и имя набора сущностей из метаданных. Возвращает единый дикт, который можно объединить в полезные данные создания или обновления.

Пример:

   # Instead of manually constructing:
   #   {"parentcustomerid_account@odata.bind": "/accounts(guid)"}
   # Just do:
   bind = client.query.odata_bind("contact", "account", acct_id)
   client.records.create("contact", {
       "firstname": "Jane",
       "lastname": "Doe",
       **bind,
   })

odata_bind(from_table: str, to_table: str, target_id: str) -> Dict[str, str]

Параметры

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

Исключения

Возвращает имя $expand свойства навигации из одной таблицы в другую.

Обнаруживается с помощью метаданных связи. Возвращает точную строку PascalCase для expand= параметра.

Пример:

   nav = client.query.odata_expand("contact", "account")
   # Returns e.g. "parentcustomerid_account"
   for page in client.records.get("contact",
                                  select=["fullname"],
                                  expand=[nav],
                                  top=5):
       for r in page:
           acct = r.get(nav) or {}
           print(f"{r['fullname']} -> {acct.get('name', 'N/A')}")

odata_expand(from_table: str, to_table: str) -> str

Параметры

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

Исключения

Обнаружение всех $expand свойств навигации из таблицы.

Возвращает записи для каждой исходящей подстановки (однозначное свойство навигации). Каждая запись содержит точное имя свойства навигации PascalCase, необходимое для $expand и @odata.bind, а также имя целевого набора сущностей.

Пример:

   expands = client.query.odata_expands("contact")
   for e in expands:
       print(f"expand={e['nav_property']}  -> {e['target_table']}")

   # Use in a query
   e = next(e for e in expands if e['target_table'] == 'account')
   for page in client.records.get("contact",
                                  select=["fullname"],
                                  expand=[e['nav_property']]):
       ...

odata_expands(table: str) -> List[Dict[str, Any]]

Параметры

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

Возвращает список логических имен столбцов, подходящих для $select.

Может передаваться напрямую client.records.get(table, select=...)в .

Пример:

   cols = client.query.odata_select("account")
   for page in client.records.get("account", select=cols, top=10):
       for r in page:
           print(r)

odata_select(table: str, *, include_system: bool = False) -> List[str]

Параметры

Параметры Keyword-Only

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

Выполните sql-запрос только для чтения с помощью веб-API Dataverse.

Конечная точка Dataverse SQL поддерживает широкий подмножество T-SQL:

   SELECT / SELECT DISTINCT / SELECT TOP N (0-5000)
   FROM table [alias]
   INNER JOIN / LEFT JOIN (multi-table, no depth limit)
   WHERE (=, !=, >, <, >=, <=, LIKE, IN, NOT IN, IS NULL,
          IS NOT NULL, BETWEEN, AND, OR, nested parentheses)
   GROUP BY column
   ORDER BY column [ASC|DESC]
   OFFSET n ROWS FETCH NEXT m ROWS ONLY
   COUNT(*), SUM(), AVG(), MIN(), MAX()

SELECT * не поддерживается— явно укажите имена столбцов. Используется sql_columns для обнаружения доступных имен столбцов для таблицы.

Не поддерживается: SELECT >>*<<, вложенные запросы, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, функции окна, строки/даты/математические функции, INSERT/UPDATE/DELETE. Для операций записи используйте client.records методы.

sql(sql: str) -> List[Record]

Параметры

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

Исключения

Примеры

Базовый запрос:

   rows = client.query.sql(
       "SELECT TOP 10 name FROM account ORDER BY name"
   )

JOIN с агрегированием:

   rows = client.query.sql(
       "SELECT a.name, COUNT(c.contactid) as cnt "
       "FROM account a "
       "JOIN contact c ON a.accountid = c.parentcustomerid "
       "GROUP BY a.name"
   )

Возвращает упрощенный список столбцов, доступных для использования SQL, для таблицы.

Каждый дикт содержит name (логическое имя для SQL), (тип атрибута Dataverse), is_pktype (флаг первичного ключа) и label (отображаемое имя). Виртуальные столбцы всегда исключаются, так как конечная точка SQL не может запрашивать их.

Пример:

   cols = client.query.sql_columns("account")
   for c in cols:
       print(f"{c['name']:30s} {c['type']:20s} PK={c['is_pk']}")

sql_columns(table: str, *, include_system: bool = False) -> List[Dict[str, Any]]

Параметры

Параметры Keyword-Only

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