QueryOperations Clase

Espacio de nombres para las operaciones de consulta.

Acceso a través de client.query. Proporciona operaciones de consulta y búsqueda en tablas de Dataverse.

Ejemplo:


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

Constructor

QueryOperations(client: DataverseClient)

Parámetros

Nombre Description
client
Requerido
DataverseClient

Instancia primaria DataverseClient .

Métodos

builder

Cree un generador de consultas fluida para la tabla especificada.

Devuelve un QueryBuilder que se puede encadenar con los métodos filter, select y order y, a continuación, se ejecuta directamente a través de .execute().
fetchxml

Devuelve un objeto inert FetchXmlQuery .

No se realiza ninguna solicitud HTTP hasta execute que se llama a o execute_pages en el objeto devuelto.

Se usa para escenarios de SQL-JOIN, consultas de agregado u otras operaciones que el punto de conexión del generador de OData no puede expresar.

Ejemplo:


   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

Cree una @odata.bind entrada para establecer un campo de búsqueda.

Detecta automáticamente el nombre de la propiedad de navegación y el nombre del conjunto de entidades de los metadatos. Devuelve un dict de entrada única que se puede combinar en una carga de creación o actualización.

Ejemplo:


   # 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

Devuelve el nombre de la propiedad de navegación a $expand de una tabla a otra.

Detecta a través de metadatos de relación. Devuelve la cadena PascalCase exacta para el expand= parámetro .

Ejemplo:


   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

Descubra todas las $expand propiedades de navegación de una tabla.

Devuelve entradas para cada búsqueda saliente (propiedad de navegación con un solo valor). Cada entrada contiene el nombre exacto de la propiedad de navegación PascalCase necesaria para $expand y @odata.bind, además del nombre del conjunto de entidades de destino.

Ejemplo:


   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

Devuelve una lista de nombres lógicos de columna adecuados para $select.

Se puede pasar directamente a client.records.get(table, select=...).

Ejemplo:


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

Ejecute una consulta SQL de solo lectura mediante la API web de Dataverse.

El punto de conexión de SQL de Dataverse admite un amplio subconjunto 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 * no se admite: especifique los nombres de columna explícitamente. Use sql_columns para detectar nombres de columna disponibles para una tabla.

No compatible: SELECT >>*<<, subconsultas, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, window functions, string/date/math functions, INSERT/UPDATE/DELETE. Para escrituras, use client.records métodos.
sql_columns

Devuelve una lista simplificada de columnas utilizables de SQL para una tabla.

Cada dict contiene name (nombre lógico para SQL), (tipo de atributo Dataverse), typeis_pk (marca de clave principal) y label (nombre para mostrar). Las columnas virtuales siempre se excluyen porque el punto de conexión sql no puede consultarlas.

Ejemplo:


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

builder

Cree un generador de consultas fluida para la tabla especificada.

Devuelve un QueryBuilder que se puede encadenar con los métodos filter, select y order y, a continuación, se ejecuta directamente a través de .execute().

builder(table: str) -> QueryBuilder

Parámetros

Nombre Description
table
Requerido
str

Nombre del esquema de tabla (por ejemplo, "account").

Devoluciones

Tipo Description
QueryBuilder

Instancia de QueryBuilder enlazada a este cliente.

Ejemplos

Compile y ejecute una consulta con fluidez:


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

Con árbol de expresiones compuestas:


   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

Devuelve un objeto inert FetchXmlQuery .

No se realiza ninguna solicitud HTTP hasta execute que se llama a o execute_pages en el objeto devuelto.

Se usa para escenarios de SQL-JOIN, consultas de agregado u otras operaciones que el punto de conexión del generador de OData no puede expresar.

Ejemplo:


   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

Parámetros

Nombre Description
xml
Requerido
str

Cadena de consulta FetchXML con formato correcto. El elemento raíz <entity name="..."> determina el punto de conexión del conjunto de entidades.

Devoluciones

Tipo Description
FetchXmlQuery

Objeto de consulta inert con .execute() métodos y .execute_pages() .

Excepciones

Tipo Description
ValueError

Si falta un elemento raíz <entity> o el atributo de entidad name FetchXML.

odata_bind

Cree una @odata.bind entrada para establecer un campo de búsqueda.

Detecta automáticamente el nombre de la propiedad de navegación y el nombre del conjunto de entidades de los metadatos. Devuelve un dict de entrada única que se puede combinar en una carga de creación o actualización.

Ejemplo:


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

Parámetros

Nombre Description
from_table
Requerido
str

Nombre de esquema de la entidad que se va a crear o actualizar.
to_table
Requerido
str

Nombre de esquema de la entidad de destino a la que apunta la búsqueda.
target_id
Requerido
str

GUID del registro de destino.

Devoluciones

Tipo Description
dict[str, str]

Un dict como {"NavProp@odata.bind": "/entityset(guid)"}.

Excepciones

Tipo Description
ValueError

Si no se encuentra ninguna relación entre las tablas.

odata_expand

Devuelve el nombre de la propiedad de navegación a $expand de una tabla a otra.

Detecta a través de metadatos de relación. Devuelve la cadena PascalCase exacta para el expand= parámetro .

Ejemplo:


   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

Parámetros

Nombre Description
from_table
Requerido
str

Nombre de esquema de la tabla de origen (por ejemplo, "contact").
to_table
Requerido
str

Nombre de esquema de la tabla de destino (por ejemplo, "account").

Devoluciones

Tipo Description
str

Nombre de la propiedad de navegación (PascalCase).

Excepciones

Tipo Description
ValueError

Si no se encuentra ninguna propiedad de navegación para el destino.

odata_expands

Descubra todas las $expand propiedades de navegación de una tabla.

Devuelve entradas para cada búsqueda saliente (propiedad de navegación con un solo valor). Cada entrada contiene el nombre exacto de la propiedad de navegación PascalCase necesaria para $expand y @odata.bind, además del nombre del conjunto de entidades de destino.

Ejemplo:


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

Parámetros

Nombre Description
table
Requerido
str

Nombre de esquema de la tabla (por ejemplo, "contact").

Devoluciones

Tipo Description
list[dict[str, Any]]

Lista de dicts, cada uno con:

  • nav_property – Propiedad de navegación PascalCase para $expand

  • target_table : nombre lógico de entidad de destino

  • target_entity_set : conjunto de entidades de destino (para @odata.bind)

  • lookup_attribute : el nombre lógico de la columna de búsqueda.

  • relationship : nombre del esquema de relación

odata_select

Devuelve una lista de nombres lógicos de columna adecuados para $select.

Se puede pasar directamente a client.records.get(table, select=...).

Ejemplo:


   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]

Parámetros

Nombre Description
table
Requerido
str

Nombre de esquema de la tabla (por ejemplo, "account").
include_system
Requerido
bool

Incluir columnas del sistema (valor predeterminado False).

Parámetros de palabra clave únicamente

Nombre Description
include_system
Valor predeterminado: False

Devoluciones

Tipo Description
list[str]

Lista de nombres lógicos de columna minúsculas.

sql

Ejecute una consulta SQL de solo lectura mediante la API web de Dataverse.

El punto de conexión de SQL de Dataverse admite un amplio subconjunto 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 * no se admite: especifique los nombres de columna explícitamente. Use sql_columns para detectar nombres de columna disponibles para una tabla.

No compatible: SELECT >>*<<, subconsultas, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, window functions, string/date/math functions, INSERT/UPDATE/DELETE. Para escrituras, use client.records métodos.

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

Parámetros

Nombre Description
sql
Requerido
str

Instrucción SELECT de SQL admitida.

Devoluciones

Tipo Description
list[Record]

Lista de Record objetos. Devuelve una lista vacía cuando no coinciden filas.

Excepciones

Tipo Description
ValidationError

Si sql no es una cadena o está vacía.

Ejemplos

Consulta básica:


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

JOIN con agregación:


   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

Devuelve una lista simplificada de columnas utilizables de SQL para una tabla.

Cada dict contiene name (nombre lógico para SQL), (tipo de atributo Dataverse), typeis_pk (marca de clave principal) y label (nombre para mostrar). Las columnas virtuales siempre se excluyen porque el punto de conexión sql no puede consultarlas.

Ejemplo:


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

Parámetros

Nombre Description
table
Requerido
str

Nombre de esquema de la tabla (por ejemplo, "account").
include_system
Requerido
bool

Cuando False (valor predeterminado), se excluyen las columnas que terminan con sufijos comunes del sistema (_base, versionnumber, timezoneruleversionnumber, utcconversiontimezonecode, , importsequencenumber). overriddencreatedon

Parámetros de palabra clave únicamente

Nombre Description
include_system
Valor predeterminado: False

Devoluciones

Tipo Description
list[dict[str, Any]]

Lista de dicts de metadatos de columna.