QueryOperations Classe

Namespace para operações de consulta.

Acessado por meio de client.query. Fornece operações de consulta e pesquisa em tabelas do Dataverse.

Exemplo:


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

Construtor

QueryOperations(client: DataverseClient)

Parâmetros

Nome Description
client
Obrigatório
DataverseClient

A instância pai DataverseClient .

Métodos

builder

Crie um construtor de consultas fluente para a tabela especificada.

Retorna um QueryBuilder que pode ser encadeado com métodos de filtro, seleção e ordem e, em seguida, executado diretamente por ..execute()
fetchxml

Retornar um objeto inerte FetchXmlQuery .

Nenhuma solicitação HTTP é feita até execute ou execute_pages é chamada no objeto retornado.

Use para cenários SQL-JOIN, consultas de agregação ou outras operações que o ponto de extremidade do construtor OData não pode expressar.

Exemplo:


   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

Crie uma @odata.bind entrada para definir um campo de pesquisa.

Descobre automaticamente o nome da propriedade de navegação e o nome do conjunto de entidades dos metadados. Retorna um ditado de entrada única que pode ser mesclado em uma carga de criação ou atualização.

Exemplo:


   # 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

Retorne o nome da propriedade de navegação de $expand uma tabela para outra.

Descobre por meio de metadados de relação. Retorna a cadeia de caracteres PascalCase exata para o expand= parâmetro.

Exemplo:


   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 as $expand propriedades de navegação de uma tabela.

Retorna entradas para cada pesquisa de saída (propriedade de navegação com valor único). Cada entrada contém o nome exato da propriedade de navegação PascalCase necessário e $expand@odata.bind, além do nome do conjunto de entidades de destino.

Exemplo:


   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

Retornar uma lista de nomes lógicos de coluna adequados para $select.

Pode ser passado diretamente para client.records.get(table, select=...).

Exemplo:


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

Execute uma consulta SQL somente leitura usando a API Web do Dataverse.

O ponto de extremidade sql do Dataverse dá suporte a um amplo 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 * não há suporte – especifique os nomes de coluna explicitamente. Use sql_columns para descobrir os nomes de coluna disponíveis para uma tabela.

Sem suporte: SELECT >>*<<, subconsultas, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, funções de janela, cadeia de caracteres/data/funções matemáticas, INSERT/UPDATE/DELETE. Para gravações, use client.records métodos.
sql_columns

Retorne uma lista simplificada de colunas utilizáveis por SQL para uma tabela.

Cada ditado contém name (nome lógico para SQL), type (tipo de atributo dataverse), is_pk (sinalizador de chave primária) e label (nome de exibição). As colunas virtuais são sempre excluídas porque o ponto de extremidade do SQL não pode consultá-las.

Exemplo:


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

builder

Crie um construtor de consultas fluente para a tabela especificada.

Retorna um QueryBuilder que pode ser encadeado com métodos de filtro, seleção e ordem e, em seguida, executado diretamente por ..execute()

builder(table: str) -> QueryBuilder

Parâmetros

Nome Description
table
Obrigatório
str

Nome do esquema da tabela (por exemplo "account").

Retornos

Tipo Description
QueryBuilder

Uma instância do QueryBuilder associada a esse cliente.

Exemplos

Crie e execute uma consulta fluentemente:


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

Com árvore de expressão 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

Retornar um objeto inerte FetchXmlQuery .

Nenhuma solicitação HTTP é feita até execute ou execute_pages é chamada no objeto retornado.

Use para cenários SQL-JOIN, consultas de agregação ou outras operações que o ponto de extremidade do construtor OData não pode expressar.

Exemplo:


   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

Nome Description
xml
Obrigatório
str

Cadeia de caracteres de consulta FetchXML bem formada. O elemento raiz <entity name="..."> determina o ponto de extremidade do conjunto de entidades.

Retornos

Tipo Description
FetchXmlQuery

Objeto de consulta inerte com .execute() e .execute_pages() métodos.

Exceções

Tipo Description
ValueError

Se o FetchXML estiver faltando um elemento raiz <entity> ou o atributo de entidade name .

odata_bind

Crie uma @odata.bind entrada para definir um campo de pesquisa.

Descobre automaticamente o nome da propriedade de navegação e o nome do conjunto de entidades dos metadados. Retorna um ditado de entrada única que pode ser mesclado em uma carga de criação ou atualização.

Exemplo:


   # 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

Nome Description
from_table
Obrigatório
str

Nome do esquema da entidade que está sendo criada/atualizada.
to_table
Obrigatório
str

Nome do esquema da entidade de destino para a qual a pesquisa aponta.
target_id
Obrigatório
str

GUID do registro de destino.

Retornos

Tipo Description
dict[str, str]

Um ditado como {"NavProp@odata.bind": "/entityset(guid)"}.

Exceções

Tipo Description
ValueError

Se nenhuma relação for encontrada entre as tabelas.

odata_expand

Retorne o nome da propriedade de navegação de $expand uma tabela para outra.

Descobre por meio de metadados de relação. Retorna a cadeia de caracteres PascalCase exata para o expand= parâmetro.

Exemplo:


   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

Nome Description
from_table
Obrigatório
str

Nome do esquema da tabela de origem (por exemplo, "contact").
to_table
Obrigatório
str

Nome do esquema da tabela de destino (por exemplo). "account"

Retornos

Tipo Description
str

O nome da propriedade de navegação (PascalCase).

Exceções

Tipo Description
ValueError

Se nenhuma propriedade de navegação for encontrada para o destino.

odata_expands

Descubra todas as $expand propriedades de navegação de uma tabela.

Retorna entradas para cada pesquisa de saída (propriedade de navegação com valor único). Cada entrada contém o nome exato da propriedade de navegação PascalCase necessário e $expand@odata.bind, além do nome do conjunto de entidades de destino.

Exemplo:


   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

Nome Description
table
Obrigatório
str

Nome do esquema da tabela (por exemplo "contact").

Retornos

Tipo Description
list[dict[str, Any]]

Lista de ditados, cada um com:

  • nav_property – Propriedade de navegação PascalCase para $expand

  • target_table – nome lógico da entidade de destino

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

  • lookup_attribute – o nome lógico da coluna de pesquisa

  • relationship – nome do esquema de relação

odata_select

Retornar uma lista de nomes lógicos de coluna adequados para $select.

Pode ser passado diretamente para client.records.get(table, select=...).

Exemplo:


   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

Nome Description
table
Obrigatório
str

Nome do esquema da tabela (por exemplo "account").
include_system
Obrigatório
bool

Incluir colunas do sistema (padrão False).

Parâmetros somente de palavra-chave

Nome Description
include_system
Valor padrão: False

Retornos

Tipo Description
list[str]

Lista de nomes lógicos de coluna minúscula.

sql

Execute uma consulta SQL somente leitura usando a API Web do Dataverse.

O ponto de extremidade sql do Dataverse dá suporte a um amplo 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 * não há suporte – especifique os nomes de coluna explicitamente. Use sql_columns para descobrir os nomes de coluna disponíveis para uma tabela.

Sem suporte: SELECT >>*<<, subconsultas, CTE, HAVING, UNION, RIGHT/FULL/CROSS JOIN, CASE, COALESCE, funções de janela, cadeia de caracteres/data/funções matemáticas, INSERT/UPDATE/DELETE. Para gravações, use client.records métodos.

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

Parâmetros

Nome Description
sql
Obrigatório
str

Instrução SQL SELECT com suporte.

Retornos

Tipo Description
list[Record]

Lista de Record objetos. Retorna uma lista vazia quando nenhuma linha corresponde.

Exceções

Tipo Description
ValidationError

Se sql não for uma cadeia de caracteres ou estiver vazia.

Exemplos

Consulta básica:


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

JOIN com agregação:


   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

Retorne uma lista simplificada de colunas utilizáveis por SQL para uma tabela.

Cada ditado contém name (nome lógico para SQL), type (tipo de atributo dataverse), is_pk (sinalizador de chave primária) e label (nome de exibição). As colunas virtuais são sempre excluídas porque o ponto de extremidade do SQL não pode consultá-las.

Exemplo:


   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

Nome Description
table
Obrigatório
str

Nome do esquema da tabela (por exemplo "account").
include_system
Obrigatório
bool

Quando False (padrão), as colunas que terminam com sufixos comuns do sistema (_base, , versionnumber, timezoneruleversionnumber, utcconversiontimezonecode, importsequencenumber, overriddencreatedon) são excluídas.

Parâmetros somente de palavra-chave

Nome Description
include_system
Valor padrão: False

Retornos

Tipo Description
list[dict[str, Any]]

Lista de ditados de metadados de coluna.