QueryOperations Klasse

Namespace für Abfragevorgänge.

Zugriff über client.query. Stellt Abfrage- und Suchvorgänge für Dataverse-Tabellen bereit.

Beispiel:


   from PowerPlatform.Dataverse.models.filters import col

   client = DataverseClient(base_url, credential)

   # Fluent query builder (recommended)
   for record in (client.query.builder("account")
                  .select("name", "revenue")
                  .where(col("statecode") == 0)
                  .order_by("revenue", descending=True)
                  .top(100)
                  .execute()):
       print(record["name"])

   # SQL query
   rows = client.query.sql("SELECT TOP 10 name FROM account ORDER BY name")
   for row in rows:
       print(row["name"])

Konstruktor

QueryOperations(client: DataverseClient)

Parameter

Name Beschreibung
client
Erforderlich
DataverseClient

Die übergeordnete DataverseClient Instanz.

Methoden

builder

Erstellen Sie einen Fluent-Abfrage-Generator für die angegebene Tabelle.

Gibt einen QueryBuilder Wert zurück, der mit Filter-, Auswahl- und Bestellmethoden verkettet und dann direkt über .execute()ausgeführt werden kann.
fetchxml

Gibt ein inert-Objekt zurück FetchXmlQuery .

Es wird keine HTTP-Anforderung ausgeführt, bis execute das zurückgegebene Objekt aufgerufen oder execute_pages aufgerufen wird.

Wird für SQL-JOIN Szenarien, aggregierte Abfragen oder andere Vorgänge verwendet, die der OData-Generatorendpunkt nicht ausdrücken kann.

Beispiel:


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

Erstellen Sie einen @odata.bind Eintrag zum Festlegen eines Nachschlagefelds.

Ermittelt automatisch den Namen der Navigationseigenschaft und den Entitätssatznamen aus Metadaten. Gibt ein diktieren, das mit einer Erstellungs- oder Aktualisierungsnutzlast zusammengeführt werden kann.

Beispiel:


   # 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_expand

Gibt den Namen der Navigationseigenschaft $expand von einer Tabelle in eine andere zurück.

Ermittelt über Beziehungsmetadaten. Gibt die genaue PascalCase-Zeichenfolge für den expand= Parameter zurück.

Beispiel:


   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_expands

Entdecken Sie alle $expand Navigationseigenschaften aus einer Tabelle.

Gibt Einträge für jede ausgehende Suche (einzelwertige Navigationseigenschaft) zurück. Jeder Eintrag enthält den genauen Namen der PascalCase-Navigationseigenschaft, die für $expand und @odata.bindden Namen des Zielentitätssatzes benötigt wird.

Beispiel:


   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_select

Gibt eine Liste der logischen Spaltennamen zurück, die geeignet sind.$select

Kann direkt an client.records.get(table, select=...).

Beispiel:


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

Führen Sie eine schreibgeschützte SQL-Abfrage mit der Dataverse-Web-API aus.

Der Dataverse SQL-Endpunkt unterstützt eine breite Teilmenge von 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 * wird nicht unterstützt – Geben Sie Spaltennamen explizit an. Wird verwendet sql_columns , um verfügbare Spaltennamen für eine Tabelle zu ermitteln.

Nicht unterstützt: SELECT >>*<<, Unterabfragen, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, Window Functions, string/date/math functions, INSERT/UPDATE/DELETE. Verwenden Sie client.records für Schreibvorgänge Methoden.
sql_columns

Zurückgeben einer vereinfachten Liste von SQL-verwendbaren Spalten für eine Tabelle.

Jedes Diktat enthält name (logischer Name für SQL), type (Dataverse-Attributtyp), is_pk (Primärschlüsselkennzeichnung) und label (Anzeigename). Virtuelle Spalten werden immer ausgeschlossen, da der SQL-Endpunkt sie nicht abfragen kann.

Beispiel:


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

builder

Erstellen Sie einen Fluent-Abfrage-Generator für die angegebene Tabelle.

Gibt einen QueryBuilder Wert zurück, der mit Filter-, Auswahl- und Bestellmethoden verkettet und dann direkt über .execute()ausgeführt werden kann.

builder(table: str) -> QueryBuilder

Parameter

Name Beschreibung
table
Erforderlich
str

Tabellenschemaname (z. B. "account").

Gibt zurück

Typ Beschreibung
QueryBuilder

Eine An diesen Client gebundene QueryBuilder-Instanz.

Beispiele

Erstellen und Ausführen einer Abfrage fließend:


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

Mit erstellungsfähiger Ausdrucksstruktur:


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

fetchxml

Gibt ein inert-Objekt zurück FetchXmlQuery .

Es wird keine HTTP-Anforderung ausgeführt, bis execute das zurückgegebene Objekt aufgerufen oder execute_pages aufgerufen wird.

Wird für SQL-JOIN Szenarien, aggregierte Abfragen oder andere Vorgänge verwendet, die der OData-Generatorendpunkt nicht ausdrücken kann.

Beispiel:


   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

Parameter

Name Beschreibung
xml
Erforderlich
str

Wohlgeformte FetchXML-Abfragezeichenfolge. Das Stammelement <entity name="..."> bestimmt den Entitätssatzendpunkt.

Gibt zurück

Typ Beschreibung
FetchXmlQuery

Inert-Abfrageobjekt mit .execute() und .execute_pages() Methoden.

Ausnahmen

Typ Beschreibung
ValueError

Fehlt das FetchXML-Element <entity> oder das Entitätsattribut name .

odata_bind

Erstellen Sie einen @odata.bind Eintrag zum Festlegen eines Nachschlagefelds.

Ermittelt automatisch den Namen der Navigationseigenschaft und den Entitätssatznamen aus Metadaten. Gibt ein diktieren, das mit einer Erstellungs- oder Aktualisierungsnutzlast zusammengeführt werden kann.

Beispiel:


   # 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]

Parameter

Name Beschreibung
from_table
Erforderlich
str

Schemaname der Entität, die erstellt/aktualisiert wird.
to_table
Erforderlich
str

Schemaname der Zielentität, auf die die Nachschlagepunkte verweisen.
target_id
Erforderlich
str

GUID des Zieldatensatzes.

Gibt zurück

Typ Beschreibung
dict[str, str]

Ein Diktat wie {"NavProp@odata.bind": "/entityset(guid)"}.

Ausnahmen

Typ Beschreibung
ValueError

Wenn keine Beziehung zwischen den Tabellen gefunden wurde.

odata_expand

Gibt den Namen der Navigationseigenschaft $expand von einer Tabelle in eine andere zurück.

Ermittelt über Beziehungsmetadaten. Gibt die genaue PascalCase-Zeichenfolge für den expand= Parameter zurück.

Beispiel:


   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

Parameter

Name Beschreibung
from_table
Erforderlich
str

Schemaname der Quelltabelle (z. B. "contact").
to_table
Erforderlich
str

Schemaname der Zieltabelle (z. B. "account").

Gibt zurück

Typ Beschreibung
str

Der Name der Navigationseigenschaft (PascalCase).

Ausnahmen

Typ Beschreibung
ValueError

Wenn keine Navigationseigenschaft für das Ziel gefunden wurde.

odata_expands

Entdecken Sie alle $expand Navigationseigenschaften aus einer Tabelle.

Gibt Einträge für jede ausgehende Suche (einzelwertige Navigationseigenschaft) zurück. Jeder Eintrag enthält den genauen Namen der PascalCase-Navigationseigenschaft, die für $expand und @odata.bindden Namen des Zielentitätssatzes benötigt wird.

Beispiel:


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

Parameter

Name Beschreibung
table
Erforderlich
str

Schemaname der Tabelle (z. B. "contact").

Gibt zurück

Typ Beschreibung
list[dict[str, Any]]

Liste der Diktaten, jeweils mit:

  • nav_property – PascalCase-Navigationseigenschaft für $expand

  • target_table – Logischer Zielentitätsname

  • target_entity_set – Zielentitätssatz (für @odata.bind)

  • lookup_attribute – der logische Name der Nachschlagespalte

  • relationship – Name des Beziehungsschemas

odata_select

Gibt eine Liste der logischen Spaltennamen zurück, die geeignet sind.$select

Kann direkt an client.records.get(table, select=...).

Beispiel:


   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]

Parameter

Name Beschreibung
table
Erforderlich
str

Schemaname der Tabelle (z. B. "account").
include_system
Erforderlich
bool

Systemspalten einschließen (Standardeinstellung False).

Nur Schlüsselwortparameter

Name Beschreibung
include_system
Standardwert: False

Gibt zurück

Typ Beschreibung
list[str]

Liste der logischen Spaltennamen in Kleinbuchstaben.

sql

Führen Sie eine schreibgeschützte SQL-Abfrage mit der Dataverse-Web-API aus.

Der Dataverse SQL-Endpunkt unterstützt eine breite Teilmenge von 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 * wird nicht unterstützt – Geben Sie Spaltennamen explizit an. Wird verwendet sql_columns , um verfügbare Spaltennamen für eine Tabelle zu ermitteln.

Nicht unterstützt: SELECT >>*<<, Unterabfragen, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, Window Functions, string/date/math functions, INSERT/UPDATE/DELETE. Verwenden Sie client.records für Schreibvorgänge Methoden.

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

Parameter

Name Beschreibung
sql
Erforderlich
str

Unterstützte SQL SELECT-Anweisung.

Gibt zurück

Typ Beschreibung
list[Record]

Liste der Record Objekte. Gibt eine leere Liste zurück, wenn keine Zeilen übereinstimmen.

Ausnahmen

Typ Beschreibung
ValidationError

Wenn sql es sich nicht um eine Zeichenfolge handelt oder leer ist.

Beispiele

Grundlegende Abfrage:


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

JOIN mit Aggregation:


   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_columns

Zurückgeben einer vereinfachten Liste von SQL-verwendbaren Spalten für eine Tabelle.

Jedes Diktat enthält name (logischer Name für SQL), type (Dataverse-Attributtyp), is_pk (Primärschlüsselkennzeichnung) und label (Anzeigename). Virtuelle Spalten werden immer ausgeschlossen, da der SQL-Endpunkt sie nicht abfragen kann.

Beispiel:


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

Parameter

Name Beschreibung
table
Erforderlich
str

Schemaname der Tabelle (z. B. "account").
include_system
Erforderlich
bool

Wenn False (Standard) spalten, die mit allgemeinen Systemsuffixen enden (_base, versionnumber, , timezoneruleversionnumberutcconversiontimezonecode, importsequencenumber, ), overriddencreatedonwerden ausgeschlossen.

Nur Schlüsselwortparameter

Name Beschreibung
include_system
Standardwert: False

Gibt zurück

Typ Beschreibung
list[dict[str, Any]]

Liste der Spaltenmetadaten-Diktats.