Domínio da API REST para execução de consultas DAX

A API Execute DAX Queries permite-lhe executar consultas DAX contra modelos semânticos do Power BI e recuperar resultados em formato IPC Apache Arrow de forma programática, um formato binário colunar concebido para análises de alto desempenho. Ao devolver os resultados das consultas diretamente no formato Arrow, a API elimina a sobrecarga de serialização e dá à sua aplicação acesso a dados fortemente tipados e prontos para análise.

Porquê Arrow?

O endpoint existente Execute Queries devolve os resultados em JSON. O mais recente endpoint Execute DAX Queries devolve resultados exclusivamente no formato Apache Arrow IPC, um formato binário colunar concebido para análises de alto desempenho. A tabela seguinte compara os dois formatos de resposta:

	JSON (API de Execução de Consultas)	Arrow (API de Execução de Consultas DAX)
Formato	JSON orientado a linhas	IPC de Flecha Colunar
Tamanho da carga útil	Maior (overhead de codificação de strings)	Tamanho menor (comprimido, binário)
Fidelidade de tipos	Lossy (tudo é string/número)	Sem Perdas (data nativa, decimal, int64)
Desserialização	Análise sintática + coerção de tipo	Leitura zero-copy para o DataFrame
Melhor para	Pequenas consultas, integrações simples	Grandes conjuntos de resultados, fluxos de trabalho de análise

Tip

Use a API Execute DAX Queries para qualquer aplicação cliente que possa consumir fluxos binários Arrow IPC — isto inclui Python (pyarrow), C# (Apache.Arrow), Java, Rust, Go e outras linguagens com suporte a biblioteca Arrow. Para plataformas low-code/no-code, fluxos de Power Automate ou outras soluções que só conseguem consumir JSON, continue a utilizar a antiga API Execute Queries. Embora a API Execute Queries não tenha os parâmetros avançados disponíveis na API Execute DAX Queries (como queryTimeout e resultsetRowcountLimit), continua a ser a escolha apropriada quando é necessária uma saída JSON.

Formato IPC Apache Arrow

O Apache Arrow define um formato de memória colunar independente da linguagem que tem sido amplamente adotado em todo o ecossistema de dados, tornando-o uma das representações de dados mais amplamente suportadas disponíveis. O formato de streaming Arrow IPC (Inter-Process Communication) utiliza metadados de esquema para envolver lotes colunares de registos, possibilitando:

• Leituras zero-copy — os clientes podem mapear a resposta diretamente para a memória sem precisar de analisar ou copiar dados entre buffers.
• Cross-language support — existem bibliotecas nativas para Python (pyarrow), C# (Apache.Arrow), Java, Rust, Go, JavaScript e outras, pelo que pode consumir resultados em praticamente qualquer linguagem.
• Compressão eficiente — A compressão do LZ4 reduz o tamanho da carga útil.
• Designação esquema-primeiro — cada fluxo Arrow começa com uma mensagem de esquema que declara nomes de colunas, tipos e metadados, para que os clientes conheçam o layout exato dos dados antes de lerem qualquer linha.

Mapeamento do tipo DAX para Arrow

A API Execute DAX Queries mapeia os tipos de dados DAX para tipos Arrow da seguinte forma:

Tipo DAX	Tipo de flecha	Notes
Número inteiro	int64	Inteiro direto de 64 bits
Decimal	double	Ponto flutuante de dupla precisão
Moeda (decimal fixo)	decimal128(19, 4)	Precisão de quatro decimais sem perdas
Double	double	Ponto flutuante de dupla precisão
DateTime	date64	Milissegundos desde a era Unix
booleano	bool
String	utf8	Codificado em dicionário por padrão para maior eficiência
Binary	binary
Variant	dense_union	união de int64, moeda, bool, date64, float64, utf8

Quando usar o endpoint Arrow

Utilize o ponto final Arrow quando:

• Recupere mais do que algumas centenas de linhas de um modelo semântico.
• Inserir resultados em pandas, polars, Spark ou outras ferramentas de processamento colunar.
• Construa um serviço de nível médio que atue como intermediário para consultas DAX destinadas aos consumidores finais.
• É necessário tipos numéricos ou de data precisos sem coerção manual de tipos.

Para consultas simples e pequenas ou pesquisas rápidas e ad hoc onde o JSON é preferido, a API mais antiga Execute Queries continua a ser uma escolha direta.

Considerações e limitações

Antes de adotar a API Executar Consultas DAX, reveja as seguintes diferenças e restrições em comparação com a antiga API Executar Consultas:

	API de Execução de Consultas	Executar API de Consultas DAX
Ponto final	executeQueries	executeDaxQueries
Requisito de capacidade	Funciona em Pro, PPU e Premium/Fabric	Capacidade Premium ou Fabric apenas
Definições do inquilino	API REST de Execução de Conjuntos de Dados (em Definições do Desenvolvedor)	Dataset Execute Queries REST API (em Definições de programador) e Permitir endpoints XMLA e Analisar no Excel com modelos semânticos on-premises (em Definições de integração) são obrigatórios. Permitir que os principais de serviço utilizem APIs Power BI (em Developer settings) é necessário apenas ao autenticar com um principal de serviço.
Entrada de consulta	queries[] Array (uma consulta por chamada)	Cadeia única query (múltiplas EVALUATE instruções permitidas)
Formatos de resposta	Só JSON	Apenas Arrow IPC
Parâmetros adicionais	Limitado	queryTimeout, resultsetRowcountLimit, schemaOnly, executionMetrics, memoryLimit
Streaming	Não transmitido em streaming	Transmissão contínua de ponta a ponta (transferência segmentada)
Limites de tamanho do resultado	Limite rígido de 100.000 linhas e 1.000.000 de valores por consulta	Sem linha fixa ou limite de valores (usar resultsetRowcountLimit para limitar se necessário)
Paginação	Não suportado	Não suportado — uso TOPN ou resultsetRowcountLimit para resultados grandes
Biblioteca Arrow necessária	Não (apenas JSON)	Sim — é necessária uma biblioteca Arrow (como pyarrow ou Apache.Arrow) para desserializar a resposta

Conteúdo relacionado

• Comece com a API REST Execute DAX Queries
• Tutorial: Construa um serviço de execução de consultas DAX de nível intermédio
• Tutorial: Extração de Python de alto volume para ciência de dados
• Boas práticas para a API REST Execute DAX Queries
• Executar Consultas DAX Referência da API REST
• Power BI APIs REST