Přečtěte si data z tabulky OneLake (náhled)

Použijte OneLake table read API pro čtení řádků z tabulky Delta Lake nebo Apache Iceberg v OneLake.

Pro čtení dat tabulky pošlete jeden požadavek na zahájení čtecí relace. API vrací jeden nebo více nezávislých výsledkových toků na základě velikosti dat, která je třeba vrátit. Vaše aplikace může tyto streamy stahovat paralelně, což jí pomáhá číst velké objemy tabulek rychleji. Po stažení streamů zpracujte jejich Apache Arrow record batchy a sestavte kompletní výsledek.

API čte tabulku z konzistentního časového bodu, takže každý proud výsledků obsahuje data ze stejného snímku, i když se tabulka během čtení změní. Dále vynucuje autorizaci OneLake, bezpečnost na úrovni řádků (RLS) a bezpečnost na úrovni sloupců (CLS) pro autentizovaného volajícího. To znamená, že vaše aplikace přijímá pouze řádky a sloupce, ke kterým má volající oprávnění přistupovat, aniž by musela tyto bezpečnostní kontroly reprodukovat ve svém vlastním kódu.

Important

API pro čtení tabulky OneLake je momentálně ve veřejném náhledu. Funkce a chování se můžou před obecnou dostupností změnit.

Předpoklady

1. Pošlete požadavek na řádky tabulky

Pošlete požadavek POST na cestu /read tabulky a zahajte relaci čtení.

  1. Vytvořte URL požadavku tak, že nahraďte zástupné identifikátory pro pracovní prostor, položku, schéma a tabulku, kterou chcete číst.

    POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read
Authorization: Bearer <BearerToken>

  2. Do žádosti zahrňte možnosti čtení, které vaše žádost vyžaduje. Použijte možnost columns k určení, které sloupce se mají vrátit.

  3. Uložte všechny neprůhledné identifikátory proudu z úspěšné odpovědi. Rozsáhlý výsledek může být rozdělen mezi více streamů. Musíte získat každý stream, abyste získali všechny řádky.

Odpověď zahajuje čtení přes konzistentní snímek verzí tabulek potřebných pro váš požadavek. Každý stream z této odpovědi používá stejný snímek.

2. Stáhněte si každý datový proud výsledků

Použijte každý identifikátor proudu z odpovědi k získání odpovídající části výsledku čtení tabulky.

Čtení končí po 60 minutách. Stáhněte všechny streamy před vypršením relace. Pokud ukončíte načítání po získání pouze několika streamů, neobdržíte kompletní výsledek.

  1. Pro každý identifikátor proudu v alokační odpovědi pošlete ověřený GET požadavek.

    GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID>
Authorization: Bearer <BearerToken>

  2. Otevřete tělo odpovědi pomocí čtečky streamů Apache Arrow IPC.

  3. Zpracovávejte dávky záznamů, jakmile dorazí. Streamování dávek zabraňuje načítání celého výsledku do paměti.

  4. Opakujte požadavek na každý identifikátor streamu a kombinujte výsledky podle modelu zpracování vaší aplikace.

Každá /readStream odpověď je samostatný IPC stream Apache Arrow. Použijte knihovnu Apache Arrow pro svůj aplikační jazyk pro čtení záznamových dávek z každé odpovědi. Pro více informací o formátu proudu viz Serializace a meziprocesová komunikace (IPC).

Tělo odpovědi obsahuje nezpracovaná data IPC streamu Apache Arrow, včetně informací o schématu potřebných k interpretaci dávek záznamů. Nespoléhejte se na pořadí řádků ani nepředpokládejte, že pozice proudu v odpovědi určuje jeho pozici v kompletním výsledku.

Pochopte bezpečnost OneLake pro tabulkové čtení API

API zajišťuje bezpečnost OneLake pomocí identity, kterou váš nositelný token reprezentuje:

  • Pokud nemáte povolení k zobrazení tabulky, služba vrátí odpověď nenalezená.
  • Pokud bezpečnost na úrovni řádku (RLS) filtruje každý řádek, který můžete vidět, požadavek uspěje, ale vrátí prázdnou šipkovou odpověď.
  • Pokud použijete projekci sloupců se zástupným znakem, odpověď bude obsahovat pouze sloupce, které vám zabezpečení na úrovni sloupců (CLS) umožňuje zobrazit.
  • Pokud výslovně požádáte o sloupec, který nemůžete zobrazit, služba vrátí odpověď „Nenalezeno“.

Protože neautorizované tabulky a sloupce vracejí odpovědi nenalezené, nepoužívejte odpověď nenalezenou k určení, zda zdroj existuje.

Úvahy a omezení

  • API pro čtení tabulek nepodporuje zkratky mezi regiony.
  • Za operaci vám účtují POST /read . Načítání dat pomocí /readStream nevyvolá samostatnou fakturační událost za čtení tabulky. Pro více informací viz Spotřeba API pro čtení tabulek.
  • Last updated on