QueryOperations Classe

Espace de noms pour les opérations de requête.

Accessible via client.query. Fournit des opérations de requête et de recherche sur des tables Dataverse.

Exemple :


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

Constructeur

QueryOperations(client: DataverseClient)

Paramètres

Nom Description
client
Obligatoire
DataverseClient

Instance parente DataverseClient .

Méthodes

builder

Créez un générateur de requêtes Fluent pour la table spécifiée.

Retourne une QueryBuilder valeur qui peut être chaînée avec des méthodes de filtre, de sélection et d’ordre, puis exécutées directement via .execute().
fetchxml

Retourne un objet inert FetchXmlQuery .

Aucune requête HTTP n’est effectuée jusqu’à ce qu’elle executeexecute_pages soit appelée sur l’objet retourné.

Utilisez pour SQL-JOIN scénarios, les requêtes d’agrégation ou d’autres opérations que le point de terminaison du générateur OData ne peut pas exprimer.

Exemple :


   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

Générez une @odata.bind entrée pour définir un champ de recherche.

Détecte automatiquement le nom de la propriété de navigation et le nom du jeu d’entités à partir des métadonnées. Retourne une dictée à entrée unique qui peut être fusionnée dans une charge utile de création ou de mise à jour.

Exemple :


   # 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

Retournez le nom de la propriété de navigation d’une $expand table à une autre.

Découvre par le biais de métadonnées de relation. Retourne la chaîne PascalCase exacte pour le expand= paramètre.

Exemple :


   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

Découvrez toutes les $expand propriétés de navigation d’une table.

Retourne des entrées pour chaque recherche sortante (propriété de navigation à valeur unique). Chaque entrée contient le nom exact de la propriété de navigation PascalCase nécessaire et $expand@odata.bind, plus le nom du jeu d’entités cible.

Exemple :


   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

Retourne une liste de noms logiques de colonne appropriés pour $select.

Peut être transmis directement à client.records.get(table, select=...).

Exemple :


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

Exécutez une requête SQL en lecture seule à l’aide de l’API Web Dataverse.

Le point de terminaison Dataverse SQL prend en charge un large sous-ensemble de 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 * n’est pas pris en charge : spécifiez explicitement les noms de colonnes. Permet sql_columns de découvrir les noms de colonnes disponibles pour une table.

Non pris en charge : SELECT >>*<<, sous-requêtes, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, fonctions de fenêtre, fonctions string/date/math, INSERT/UPDATE/DELETE. Pour les écritures, utilisez des client.records méthodes.
sql_columns

Retourne une liste simplifiée de colonnes utilisables par SQL pour une table.

Chaque dict contient name (nom logique pour SQL), type (type d’attribut Dataverse), is_pk (indicateur de clé primaire) et label (nom complet). Les colonnes virtuelles sont toujours exclues, car le point de terminaison SQL ne peut pas les interroger.

Exemple :


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

builder

Créez un générateur de requêtes Fluent pour la table spécifiée.

Retourne une QueryBuilder valeur qui peut être chaînée avec des méthodes de filtre, de sélection et d’ordre, puis exécutées directement via .execute().

builder(table: str) -> QueryBuilder

Paramètres

Nom Description
table
Obligatoire
str

Nom du schéma de table (par exemple "account").

Retours

Type Description
QueryBuilder

Instance QueryBuilder liée à ce client.

Exemples

Générez et exécutez une requête couramment :


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

Avec l’arborescence d’expressions composable :


   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

Retourne un objet inert FetchXmlQuery .

Aucune requête HTTP n’est effectuée jusqu’à ce qu’elle executeexecute_pages soit appelée sur l’objet retourné.

Utilisez pour SQL-JOIN scénarios, les requêtes d’agrégation ou d’autres opérations que le point de terminaison du générateur OData ne peut pas exprimer.

Exemple :


   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

Paramètres

Nom Description
xml
Obligatoire
str

Chaîne de requête FetchXML bien formée. L’élément racine <entity name="..."> détermine le point de terminaison du jeu d’entités.

Retours

Type Description
FetchXmlQuery

Objet de requête inert avec .execute() et .execute_pages() méthodes.

Exceptions

Type Description
ValueError

Si fetchXML manque un élément racine <entity> ou l’attribut d’entité name .

odata_bind

Générez une @odata.bind entrée pour définir un champ de recherche.

Détecte automatiquement le nom de la propriété de navigation et le nom du jeu d’entités à partir des métadonnées. Retourne une dictée à entrée unique qui peut être fusionnée dans une charge utile de création ou de mise à jour.

Exemple :


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

Paramètres

Nom Description
from_table
Obligatoire
str

Nom du schéma de l’entité en cours de création/mise à jour.
to_table
Obligatoire
str

Nom du schéma de l’entité cible vers qui pointe la recherche.
target_id
Obligatoire
str

GUID de l’enregistrement cible.

Retours

Type Description
dict[str, str]

Une dictée comme {"NavProp@odata.bind": "/entityset(guid)"}.

Exceptions

Type Description
ValueError

Si aucune relation n’est trouvée entre les tables.

odata_expand

Retournez le nom de la propriété de navigation d’une $expand table à une autre.

Découvre par le biais de métadonnées de relation. Retourne la chaîne PascalCase exacte pour le expand= paramètre.

Exemple :


   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

Paramètres

Nom Description
from_table
Obligatoire
str

Nom du schéma de la table source (par exemple "contact").
to_table
Obligatoire
str

Nom du schéma de la table cible (par exemple "account").

Retours

Type Description
str

Nom de la propriété de navigation (PascalCase).

Exceptions

Type Description
ValueError

Si aucune propriété de navigation n’a été trouvée pour la cible.

odata_expands

Découvrez toutes les $expand propriétés de navigation d’une table.

Retourne des entrées pour chaque recherche sortante (propriété de navigation à valeur unique). Chaque entrée contient le nom exact de la propriété de navigation PascalCase nécessaire et $expand@odata.bind, plus le nom du jeu d’entités cible.

Exemple :


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

Paramètres

Nom Description
table
Obligatoire
str

Nom du schéma de la table (par exemple "contact").

Retours

Type Description
list[dict[str, Any]]

Liste des dictées, chacune avec :

  • nav_property – Propriété de navigation PascalCase pour $expand

  • target_table – Nom logique de l’entité cible

  • target_entity_set – jeu d’entités cibles (pour @odata.bind)

  • lookup_attribute : nom logique de colonne de recherche

  • relationship – nom du schéma de relation

odata_select

Retourne une liste de noms logiques de colonne appropriés pour $select.

Peut être transmis directement à client.records.get(table, select=...).

Exemple :


   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]

Paramètres

Nom Description
table
Obligatoire
str

Nom du schéma de la table (par exemple "account").
include_system
Obligatoire
bool

Inclure des colonnes système (par défaut False).

Paramètres de mot clé uniquement

Nom Description
include_system
Valeur par défaut: False

Retours

Type Description
list[str]

Liste des noms logiques de colonnes minuscules.

sql

Exécutez une requête SQL en lecture seule à l’aide de l’API Web Dataverse.

Le point de terminaison Dataverse SQL prend en charge un large sous-ensemble de 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 * n’est pas pris en charge : spécifiez explicitement les noms de colonnes. Permet sql_columns de découvrir les noms de colonnes disponibles pour une table.

Non pris en charge : SELECT >>*<<, sous-requêtes, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, fonctions de fenêtre, fonctions string/date/math, INSERT/UPDATE/DELETE. Pour les écritures, utilisez des client.records méthodes.

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

Paramètres

Nom Description
sql
Obligatoire
str

Instruction SQL SELECT prise en charge.

Retours

Type Description
list[Record]

Liste d’objets Record . Retourne une liste vide lorsqu’aucune ligne ne correspond.

Exceptions

Type Description
ValidationError

S’il sql ne s’agit pas d’une chaîne ou est vide.

Exemples

Requête de base :


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

JOIN avec agrégation :


   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

Retourne une liste simplifiée de colonnes utilisables par SQL pour une table.

Chaque dict contient name (nom logique pour SQL), type (type d’attribut Dataverse), is_pk (indicateur de clé primaire) et label (nom complet). Les colonnes virtuelles sont toujours exclues, car le point de terminaison SQL ne peut pas les interroger.

Exemple :


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

Paramètres

Nom Description
table
Obligatoire
str

Nom du schéma de la table (par exemple "account").
include_system
Obligatoire
bool

Lorsque False (valeur par défaut), les colonnes qui se terminent par des suffixes système courants (_base, versionnumber, timezoneruleversionnumber, utcconversiontimezonecode, importsequencenumber, overriddencreatedon) sont exclues.

Paramètres de mot clé uniquement

Nom Description
include_system
Valeur par défaut: False

Retours

Type Description
list[dict[str, Any]]

Liste des dictées de métadonnées de colonne.