Läsa tabelldata i OneLake (förhandsversion)

Använd OneLake-tabellens läs-API för att läsa rader från en Delta Lake- eller Apache Iceberg-tabell i OneLake.

För att läsa tabelldata, skicka en förfrågan om att starta en lässession. API:et returnerar en eller flera oberoende resultatströmmar baserat på storleken på den data som behöver returneras. Din applikation kan ladda ner dessa strömmar parallellt, vilket hjälper den att snabbare läsa stora mängder tabelldata. Efter att ha laddat ner dataströmmarna bearbetar du deras recordbatcher i Apache Arrow för att sammanställa det fullständiga resultatet.

API:et läser tabellen från en konsekvent tidpunkt, så varje resultatström innehåller data från samma ögonblicksbild, även om tabellen ändras medan läsningen pågår. Den upprätthåller också OneLake-auktorisation, radnivåsäkerhet (RLS) och kolumnnivåsäkerhet (CLS) för den autentiserade uppringaren. Detta innebär att din applikation endast får de rader och kolumner som anroparen är auktoriserad att komma åt, utan att behöva återskapa dessa säkerhetskontroller i sin egen kod.

Important

OneLake-tabellläsnings-API:et är för närvarande i offentlig förhandsvisning. Funktioner och beteenden kan ändras före allmän tillgänglighet.

Förutsättningar

1. Skicka en begäran om tabellrader

Skicka en POST förfrågan till tabellens /read rutt för att starta en lässession.

  1. Bygg förfrågan-URL:en genom att ersätta platshållarna med identifierare för arbetsytan, objektet, schemat och tabellen du vill läsa.

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

  2. Inkludera de läsalternativ som din ansökan kräver i förfrågan. Använd columns alternativet för att ange vilka kolumner som ska returneras.

  3. Spara varje ogenomskinlig strömidentifierare från det lyckade svaret. Ett stort resultat kan vara uppdelat över flera strömmar. Du måste hämta samtliga strömmar för att få alla rader.

Svaret inleder en lässession med en konsistent ögonblicksbild av de tabellversioner som krävs för begäran. Varje dataström från det här svaret använder samma ögonblicksbild.

2. Ladda ner varje resultatström

Använd varje strömidentifierare från svaret för att hämta dess motsvarande del av tabellens läsresultat.

En lässession går ut efter 60 minuter. Hämta alla strömningar innan sessionen löper ut. Om du slutar efter att bara ha hämtat några strömmar får du inte hela resultatet.

  1. För varje strömidentifierare i allokeringssvaret, skicka en autentiserad GET förfrågan.

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

  2. Öppna svarsdelen med en Apache Arrow IPC-strömläsare.

  3. Bearbeta postbatcherna allteftersom de kommer in. Att strömma batcherna undviker att ladda hela resultatet i minnet.

  4. Upprepa förfrågan för varje strömidentifierare och kombinera resultaten enligt applikationens bearbetningsmodell.

Varje /readStream svar är en oberoende Apache Arrow IPC-ström. Använd Apache Arrow-biblioteket för ditt applikationsspråk för att läsa postbatcharna från varje svar. För mer information om strömformatet, se Serialisering och interprocesskommunikation (IPC).

Svarsinnehållet innehåller råa Apache Arrow IPC-strömdata, inklusive schemainformation som behövs för att tolka recordbatcherna. Lita inte på radordningen, eller anta att positionen för en ström i svaret bestämmer dess position i det fullständiga resultatet.

Förstå OneLake-säkerheten för tabellläsnings-API:et

API:et upprätthåller OneLake-säkerheten genom att använda den identitet som din bärartoken representerar:

  • Om du inte har behörighet att visa tabellen returnerar tjänsten ett svar om att tabellen inte hittades.
  • Om radnivåsäkerhet (RLS) filtrerar bort varje rad du kan se, lyckas förfrågan men returnerar ett tomt Arrow-svar.
  • Om du använder en jokerkolumnprojektion inkluderar svaret endast kolumner som kolumnnivåsäkerhet (CLS) tillåter dig att visa.
  • Om du uttryckligen begär en kolumn som du inte kan se returnerar tjänsten ett ”hittades inte”-svar.

Eftersom obehöriga tabeller och kolumner returnerar icke-hittade svar, använd inte ett inte-hittat svar för att avgöra om en resurs existerar.

Överväganden och begränsningar

  • Table Read API:et stöder inte genvägar över regioner.
  • Du debiteras för operationen POST /read . Att hämta data med /readStream genererar inte någon separat debiteringshändelse för tabelläsning. För mer information, se Table read API consumption.
  • Uppdaterades senast