QueryBuilder Classe

Interface fluente para compilar e executar consultas OData em um cliente de sincronização.

Fornece encadeamento de métodos para construir consultas complexas com expressões de filtro composáveis. Pode ser usado autônomo (via build()) ou associado a um cliente (via execute).

Construtor

QueryBuilder(table: str)

Parâmetros

Nome Description
table
Obrigatório
str

Nome do esquema de tabela para consulta.

Exemplos

Construção de consulta autônoma:


   from PowerPlatform.Dataverse.models import col

   query = (QueryBuilder("account")
            .select("name")
            .where(col("statecode") == 0)
            .top(10))
   params = query.build()
   # {"table": "account", "select": ["name"],
   #  "filter": "statecode eq 0", "top": 10}

Métodos

execute

Execute a consulta e retorne os resultados.

Retorna um QueryResult com todas as páginas coletadas. Use execute_pages para iteração lenta por página.

Esse método só está disponível quando o QueryBuilder foi criado por meio de client.query.builder(table). Instâncias autônomas QueryBuilder devem ser usadas build() para obter parâmetros e passá-los client.records.list() manualmente.

Pelo menos um de select(), where()ou top() deve ser chamado antes execute(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Preterido desde a versão The:by_page o parâmetro foi preterido. Use execute_pages para iteração lenta por página ou simples execute() (sem sinalizador) para o resultado ansioso padrão.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   for record in (client.query.builder("account")
                  .select("name")
                  .where(col("statecode") == 0)
                  .execute()):
       print(record["name"])
execute_pages

Rendimento preguiçosamente um QueryResult por página HTTP.

Cada iteração dispara uma solicitação de rede por meio de @odata.nextLink. Um tiro – não itera mais de uma vez.

Pelo menos um de select(), where()ou top() deve ser chamado antes execute_pages(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   for page in (client.query.builder("account")
                .select("name")
                .where(col("statecode") == 0)
                .execute_pages()):
       process(page.to_dataframe())
to_dataframe

Execute a consulta e retorne os resultados como um DataFrame pandas.

Preterido desde o uso da versão:QueryBuilder.execute().to_dataframe() Ao invés. QueryBuilder.to_dataframe() será removido em uma versão futura.

Todas as páginas são consolidadas em um único DataFrame.

Esse método só está disponível quando o QueryBuilder foi criado por meio de client.query.builder(table).

Pelo menos um de select(), where()ou top() deve ser chamado antes to_dataframe(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   df = (client.query.builder("account")
         .select("name", "telephone1")
         .where(col("statecode") == 0)
         .top(100)
         .execute()
         .to_dataframe())

execute

Execute a consulta e retorne os resultados.

Retorna um QueryResult com todas as páginas coletadas. Use execute_pages para iteração lenta por página.

Esse método só está disponível quando o QueryBuilder foi criado por meio de client.query.builder(table). Instâncias autônomas QueryBuilder devem ser usadas build() para obter parâmetros e passá-los client.records.list() manualmente.

Pelo menos um de select(), where()ou top() deve ser chamado antes execute(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Preterido desde a versão The:by_page o parâmetro foi preterido. Use execute_pages para iteração lenta por página ou simples execute() (sem sinalizador) para o resultado ansioso padrão.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   for record in (client.query.builder("account")
                  .select("name")
                  .where(col("statecode") == 0)
                  .execute()):
       print(record["name"])

execute(*, by_page=<object object>) -> QueryResult | Iterator[QueryResult]

Parâmetros somente de palavra-chave

Nome Description
by_page
Valor padrão: <object object at 0x0000021A213288E0>

Retornos

Tipo Description
QueryResult,
Iterator[QueryResult]

QueryResult com todas as páginas coletadas (padrão) ou iterador de página (preterido by_page=True).

Exceções

Tipo Description
ValueError

Se nenhuma selectwheretop restrição tiver sido definida.
RuntimeError

Se a consulta não foi criada por meio de client.query.builder()

execute_pages

Rendimento preguiçosamente um QueryResult por página HTTP.

Cada iteração dispara uma solicitação de rede por meio de @odata.nextLink. Um tiro – não itera mais de uma vez.

Pelo menos um de select(), where()ou top() deve ser chamado antes execute_pages(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   for page in (client.query.builder("account")
                .select("name")
                .where(col("statecode") == 0)
                .execute_pages()):
       process(page.to_dataframe())

execute_pages() -> Iterator[QueryResult]

Retornos

Tipo Description
Iterator[QueryResult]

Iterador de por página QueryResult.

Exceções

Tipo Description
ValueError

Se nenhuma selectwheretop restrição tiver sido definida.
RuntimeError

Se a consulta não foi criada por meio de client.query.builder()

to_dataframe

Execute a consulta e retorne os resultados como um DataFrame pandas.

Preterido desde o uso da versão:QueryBuilder.execute().to_dataframe() Ao invés. QueryBuilder.to_dataframe() será removido em uma versão futura.

Todas as páginas são consolidadas em um único DataFrame.

Esse método só está disponível quando o QueryBuilder foi criado por meio de client.query.builder(table).

Pelo menos um de select(), where()ou top() deve ser chamado antes to_dataframe(); caso contrário, um ValueError é gerado para evitar verificações acidentais de tabela completa.

Exemplo:


   from PowerPlatform.Dataverse.models import col

   df = (client.query.builder("account")
         .select("name", "telephone1")
         .where(col("statecode") == 0)
         .top(100)
         .execute()
         .to_dataframe())

to_dataframe() -> DataFrame

Retornos

Tipo Description
Dataframe

DataFrame que contém todos os registros correspondentes. Retorna um DataFrame vazio quando nenhum registro corresponde.

Exceções

Tipo Description
ValueError

Se nenhuma selectwheretop restrição tiver sido definida.
RuntimeError

Se a consulta não foi criada por meio de client.query.builder()