QueryOperations Kelas

Buat penyusun kueri yang fasih untuk tabel yang ditentukan.

Mengembalikan QueryBuilder yang dapat dirangkai dengan metode filter, pilih, dan pesanan, lalu dijalankan langsung melalui .execute().

builder(table: str) -> QueryBuilder

Parameter

Mengembalikan

Contoh

Buat dan jalankan kueri dengan lancar:

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

Dengan pohon ekspresi yang dapat disusun:

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

Mengembalikan objek inert FetchXmlQuery .

Tidak ada permintaan HTTP yang dibuat sampai execute atau execute_pages dipanggil pada objek yang dikembalikan.

Gunakan untuk skenario SQL-JOIN, kueri agregat, atau operasi lain yang tidak dapat diekspresikan oleh titik akhir pembuat OData.

Example:

   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

Mengembalikan

Pengecualian

Buat @odata.bind entri untuk mengatur bidang pencarian.

Menemukan nama properti navigasi dan nama kumpulan entitas secara otomatis dari metadata. Mengembalikan dict entri tunggal yang dapat digabungkan ke dalam payload buat atau perbarui.

Example:

   # 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

Mengembalikan

Pengecualian

Mengembalikan nama properti navigasi ke $expand dari satu tabel ke tabel lainnya.

Menemukan melalui metadata hubungan. Mengembalikan string PascalCase yang tepat untuk expand= parameter .

Example:

   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

Mengembalikan

Pengecualian

Temukan semua $expand properti navigasi dari tabel.

Mengembalikan entri untuk setiap pencarian keluar (properti navigasi bernilai tunggal). Setiap entri berisi nama properti navigasi PascalCase yang tepat yang diperlukan untuk $expand dan @odata.bind, ditambah nama kumpulan entitas target.

Example:

   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

Mengembalikan

Mengembalikan daftar nama logika kolom yang cocok untuk $select.

Dapat diteruskan langsung ke client.records.get(table, select=...).

Example:

   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

Parameter Kata Kunci-Saja

Mengembalikan

Jalankan kueri SQL baca-saja menggunakan Dataverse Web API.

Titik akhir SQL Dataverse mendukung subset T-SQL yang luas:

   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 * tidak didukung – tentukan nama kolom secara eksplisit. Gunakan sql_columns untuk menemukan nama kolom yang tersedia untuk tabel.

Tidak didukung: SELECT >>*<<, subqueries, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, window functions, string/date/math functions, INSERT/UPDATE/DELETE. Untuk menulis, gunakan client.records metode.

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

Parameter

Mengembalikan

Pengecualian

Contoh

Kueri dasar:

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

JOIN dengan agregasi:

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

Mengembalikan daftar kolom yang dapat digunakan SQL yang disederhanakan untuk tabel.

Setiap dict berisi name (nama logis untuk SQL), type (Jenis atribut Dataverse), is_pk (bendera kunci primer), dan label (nama tampilan). Kolom virtual selalu dikecualikan karena titik akhir SQL tidak dapat mengkuerinya.

Example:

   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

Parameter Kata Kunci-Saja

Mengembalikan