Ovládnutí spouštění dotazů DAX REST API

Rozhraní API pro spouštění DAX dotazů umožňuje spouštět DAX dotazy na sémantických modelech Power BI a programově načítat výsledky ve formátu Apache Arrow IPC, což je sloupcový binární formát navržený pro vysoce výkonné analýzy. Když vrátíte výsledky dotazu přímo ve formátu Arrow, rozhraní API eliminuje režii serializace a poskytuje aplikaci přístup k silného typu datům připraveným k analýze.

Diagram zobrazující architekturu rozhraní REST API Execute DAX Queries. Klientské aplikace (Python, C#, PowerShell) odesílají požadavky POST a přijímají datové proudy IPC se šipkami ze služby Power BI. Kanál zpracování datového proudu šipky zobrazuje šest fází na straně klienta: Příjem, deserializace, ověření, materializace, transformace a zpracování.

Proč Arrow?

Existující koncový bod Execute Queries vrátí výsledky ve formátu JSON. Novější koncový bod Execute DAX Queries vrací výsledky výhradně ve formátu Apache Arrow IPC, sloupcovém binárním formátu navrženém pro vysoce výkonné analýzy. Následující tabulka porovnává dva formáty odpovědí:

JSON (rozhraní API pro spouštění dotazů) Arrow (spustit API dotazů DAX)
Formát JSON orientovaný na řádky Sloupcová šipka IPC
Velikost datové části Větší (náklady na kódování řetězců) Menší (binární, komprimované)
Věrnost typů Ztrátový (vše je ve formátu řetězce/čísla) Bezeztrátové (nativní datum, desetinné číslo, int64)
Deserializace Parsování + přetypování Čtení do datového rámce bez kopírování
Nejlepší pro Malé dotazy, jednoduché integrace Velké sady výsledků, analytické kanály

Tip

Použijte rozhraní API pro spouštění dotazů DAX pro libovolnou klientskou aplikaci, která může využívat binární Arrow IPC streamy – to zahrnuje Python (pyarrow), C# (Apache.Arrow), Java, Rust, Go a další jazyky s podporou knihovny Arrow. U platforem pro nízkokódová/bez kódu řešení, toků Power Automate nebo jiných řešení, která mohou používat pouze JSON, nadále používejte starší API Execute Queries. Přestože rozhraní API pro spouštění dotazů nemá pokročilé parametry dostupné v dotazech DAX (například queryTimeout a resultsetRowcountLimit), zůstává v případě potřeby výstupu JSON správnou volbou.

Formát Apache Arrow IPC

Apache Arrow definuje formát sloupcové paměti nezávislý na jazyce, který byl široce přijat v ekosystému dat, takže je jednou z nejrozšířenějších reprezentací dat dostupných. Formát streamování IPC (Inter-Process Communication) obaluje dávky sloupcových záznamů metadaty schématu, což umožňuje:

  • Čtení s nulovou kopií – klienti mohou namapovat odpověď přímo do paměti, aniž by museli analyzovat nebo kopírovat data mezi vyrovnávacími pamětmi.
  • – nativní knihovny existují pro Python (pyarrow), C# (Apache.Arrow), Java, Rust, Go, JavaScript a další, takže můžete výsledky využívat prakticky v libovolném jazyce.
  • Efektivní komprese – komprese LZ4 snižuje velikost datové části.
  • Design "Schema-first" — každý Arrow stream začíná schématickou zprávou, která určuje názvy sloupců, datové typy a metadata, aby klienti znali přesné rozložení dat před čtením jakýchkoli řádků.

Mapování typu DAX na Arrow

Rozhraní API pro spouštění dotazů DAX mapuje datové typy DAX na typy se šipkami následujícím způsobem:

Typ DAX Typ šipky Poznámky
Celé číslo int64 Přímé 64bitové celé číslo
Decimal double Plovoucí desetinná čárka s dvojitou přesností
Měna (pevné desetinné číslo) decimal128(19, 4) Bezeztrátová přesnost čtyř desetinných míst
Double double Plovoucí desetinná čárka s dvojitou přesností
Datum a čas date64 Milisekundy od epochy Unixu
logický bool
String utf8 Kódováno pomocí slovníku ve výchozím nastavení kvůli efektivitě
Binary binary
Variant dense_union Unie int64, měna, bool, date64, float64, utf8

Kdy použít koncový bod šipky

Koncový bod šipky použijte v následujících případech:

  • Načtení více než několika stovek řádků ze sémantického modelu
  • Výsledky můžete vložit do frameworků pandas, polars, Spark nebo dalších sloupcových zpracovatelských frameworků.
  • Sestavte službu střední úrovně, která zprostředkovává dotazy DAX pro koncové uživatele.
  • Potřebujete přesné numerické nebo datumové typy bez nutnosti ručního přetypování.

U jednoduchých, malých dotazů nebo rychlých ad hoc vyhledávání, u kterých se preferuje JSON, zůstává starší rozhraní API pro spouštění dotazů jednoduchou volbou.

Úvahy a omezení

Než začnete používat rozhraní API pro spouštění dotazů DAX, projděte si následující rozdíly a omezení v porovnání se starším rozhraním API pro spouštění dotazů:

Spouštění rozhraní API pro dotazy Spouštění rozhraní API dotazů DAX
Koncový bod executeQueries executeDaxQueries
Požadavek na kapacitu Funguje na platformách Pro, PPU a Premium/Fabric Pouze kapacita Premium nebo Fabric
Nastavení nájemce Rozhraní REST API pro spouštění dotazů datové sady (v nastavení pro vývojáře) Spouštění dotazů Datasetu přes rozhraní REST API (v Nastavení pro vývojáře) a Povolit koncové body XMLA a analyzování v Excelu pomocí místními sémantickými modely (v Nastavení integrace) jsou vyžadovány. Povolit služební instanční objekty pro použití rozhraní API Power BI (v nastavení pro vývojáře) se vyžaduje pouze při ověřování instančním objektem.
Zadání dotazu queries[] pole (jeden dotaz na jedno volání) Jeden query řetězec (povoleno více EVALUATE příkazů)
Formáty odpovědí Pouze JSON Pouze Arrow IPC
Další parametry Omezené queryTimeout, resultsetRowcountLimit, schemaOnly, , executionMetricsmemoryLimit
Streaming Není streamováno Kompletní streamovaný přenos (kouskovaný přenos)
Omezení velikosti výsledku Pevný limit 100 000 řádků a 1 000 000 hodnot na dotaz Žádný pevný limit řádku nebo hodnoty (v případě potřeby se používá resultsetRowcountLimit k omezení počtu řádků nebo hodnot)
Stránkování Nepodporováno Nepodporováno – použití TOPN nebo resultsetRowcountLimit pro velké výsledky
Vyžadovaná knihovna Arrow Ne (pouze JSON) Ano – k deserializaci odpovědi se vyžaduje knihovna šipek (například pyarrow nebo Apache.Arrow).

Související obsah

  • Last updated on