Læs OneLake-tabeldata (forhåndsvisning)

Brug OneLake-tabel-læse-API'en til at læse rækker fra en Delta Lake- eller Apache Iceberg-tabel i OneLake.

For at læse tabeldata skal du sende en anmodning om at starte en læsesession. API'et returnerer en eller flere uafhængige resultatstrømme baseret på størrelsen af de data, der skal returneres. Din applikation kan downloade disse strømme parallelt, hvilket hjælper den med at læse store mængder tabeldata hurtigere. Efter download af streams, behandl deres Apache Arrow-recordbatches for at samle det komplette resultat.

API'et læser tabellen fra et konsistent tidspunkt, så hver resultatstrøm indeholder data fra det samme snapshot, selvom tabellen ændres under læsningen. Den håndhæver også OneLake-autorisation, række-niveau sikkerhed (RLS) og kolonne-niveau sikkerhed (CLS) for den autentificerede opkalder. Det betyder, at din applikation kun modtager de rækker og kolonner, som kalderen har tilladelse til at tilgå, uden at skulle genskabe disse sikkerhedskontroller i sin egen kode.

Vigtig

OneLake-tabellæsnings-API'en er i øjeblikket i offentlig forhåndsvisning. Funktioner og adfærd kan ændre sig før den generelle tilgængelighed.

Forudsætninger

1. Send en anmodning om tabelrækker

Send en POST anmodning til tabellens /read rute for at starte en læsesession.

  1. Byg anmodnings-URL'en ved at erstatte pladsholderne med identifikatorerne for det arbejdsområde, element, skema og tabel, du vil læse.

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

  2. Inkluder de læsemuligheder, som din ansøgning kræver, i anmodningen. Brug muligheden columns for at angive, hvilke kolonner der skal returneres.

  3. Gem alle uigennemsigtige strømidentifikatorer fra det succesfulde svar. Et stort resultat kan blive delt over flere strømme. Du skal hente hver strøm for at modtage alle rækkerne.

Svaret starter en læsesession over et konsistent øjebliksbillede af de tabelversioner, der er nødvendige for din anmodning. Hver stream fra dette svar bruger det samme snapshot.

2. Download alle resultatstrømme

Brug hver strømidentifikator fra svaret til at hente den tilsvarende del af tabellen læst resultat.

En læsesession udløber efter 60 minutter. Hent alle streams, inden sessionen udløber. Hvis du stopper efter kun at have hentet nogle streams, får du ikke det fulde resultat.

  1. For hver strømidentifikator i allokeringssvaret sendes en autentificeret GET anmodning.

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

  2. Åbn svarkroppen med en Apache Arrow IPC streamlæser.

  3. Behandl recordbatches, efterhånden som de ankommer. Streaming af batchene undgår at indlæse det komplette resultat i hukommelsen.

  4. Gentag anmodningen for hver stream-identifikator og kombiner resultaterne i henhold til din applikations behandlingsmodel.

Hvert /readStream svar er en uafhængig Apache Arrow IPC-strøm. Brug Apache Arrow-biblioteket som dit applikationssprog til at læse recordbatches fra hvert svar. For mere information om strømformatet, se Serialisering og interproceskommunikation (IPC).

Responskroppen indeholder rå Apache Arrow IPC-strømdata, inklusive de skemaoplysninger, der er nødvendige for at fortolke postbatches. Stol ikke på rækkeorden, eller antag ikke, at positionen af en strøm i responsen bestemmer dens position i det samlede resultat.

Forstå OneLake-sikkerhed for table read API

API'en håndhæver OneLake-sikkerheden ved at bruge den identitet, som dit bærertoken repræsenterer:

  • Hvis du ikke har tilladelse til at se tabellen, returnerer tjenesten et svar med ikke-fundet.
  • Hvis række-niveau sikkerhed (RLS) filtrerer alle rækker fra, du kan se, lykkes anmodningen, men returnerer et tomt Arrow-svar.
  • Hvis du bruger en wildcard-kolonneprojektion, inkluderer responsen kun kolonner, som kolonne-niveau sikkerhed (CLS) tillader dig at se.
  • Hvis du eksplicit anmoder om en kolonne, du ikke kan se, returnerer tjenesten et ikke-fundet-svar.

Da uautoriserede tabeller og kolonner returnerer ikke-fundne svar, skal du ikke bruge et ikke-fundet svar til at afgøre, om en ressource eksisterer.

Overvejelser og begrænsninger

  • Table read API'en understøtter ikke genveje på tværs af regioner.
  • Du bliver faktureret for operationen POST /read . At hente data ved at bruge /readStream udsender ikke en separat tabellæsningsfaktureringsbegivenhed. For mere information, se Table read API forbrug.
  • Sidst opdateret den