Les OneLake-tabelldata (forhåndsvisning)

Bruk OneLake-tabelllese-API-et for å lese rader fra en Delta Lake- eller Apache Iceberg-tabell i OneLake.

For å lese tabelldata, send én forespørsel om å starte en lesesesjon. API-et returnerer én eller flere uavhengige resultatstrømmer basert på størrelsen på dataene som må returneres. Applikasjonen din kan laste ned disse strømmene parallelt, noe som hjelper den å lese store mengder tabelldata raskere. Etter nedlasting av strømmene, behandle deres Apache Arrow-postbatcher for å sette sammen det komplette resultatet.

API-et leser tabellen fra et konsistent tidspunkt, slik at hver resultatstrøm inneholder data fra samme øyeblikksbilde, selv om tabellen endres mens lesingen pågår. Den håndhever også OneLake-autorisasjon, rad-nivå sikkerhet (RLS) og kolonne-nivå sikkerhet (CLS) for den autentiserte innringeren. Dette betyr at applikasjonen din kun mottar radene og kolonnene som kalleren har tillatelse til å få tilgang til, uten å måtte gjenskape disse sikkerhetskontrollene i sin egen kode.

Important

OneLake-tabelllese-API-et er for øyeblikket i offentlig forhåndsvisning. Funksjoner og oppførsel kan endre seg før generell tilgjengelighet.

Forutsetninger

1. Send en forespørsel om tabellrader

Send en POST forespørsel til tabellens /read rute for å starte en leseøkt.

  1. Bygg forespørsels-URL-en ved å erstatte plassholderne med identifikatorene for arbeidsområdet, elementet, skjemaet og tabellen du ønsker å lese.

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

  2. Inkluder lesealternativene som søknaden din krever i forespørselen. Bruk columns valget for å angi hvilke kolonner som skal returneres.

  3. Lagre alle ugjennomsiktige strømidentifikatorer fra det vellykkede svaret. Et stort resultat kan være delt over flere strømmer. Du må hente hver strøm for å motta alle radene.

Svaret starter en lesesesjon over et konsistent øyeblikksbilde av tabellversjonene som trengs for forespørselen din. Hver strøm fra dette svaret bruker det samme øyeblikksbildet.

2. Last ned alle resultatstrømmer

Bruk hver strømidentifikator fra responsen for å hente den tilsvarende delen av tabellen som leses.

En lesesesjon utløper etter 60 minutter. Hent hver strøm før økten utløper. Hvis du stopper etter å bare ha hentet noen strømmer, vil du ikke motta det komplette resultatet.

  1. For hver strømidentifikator i tildelingssvaret, send en autentisert GET forespørsel.

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

  2. Åpne svardelen med en Apache Arrow IPC-strømleser.

  3. Behandle postbatchene etter hvert som de ankommer. Strømming av batchene unngår å laste hele resultatet inn i minnet.

  4. Gjenta forespørselen for hver strømidentifikator og kombiner resultatene i henhold til applikasjonens behandlingsmodell.

Hvert /readStream svar er en uavhengig Apache Arrow IPC-strøm. Bruk Apache Arrow-biblioteket som applikasjonsspråk for å lese postbatchene fra hvert svar. For mer informasjon om strømformatet, se Serialisering og interprosesskommunikasjon (IPC).

Responsdelen inneholder rå Apache Arrow IPC-strømdata, inkludert skjemainformasjonen som trengs for å tolke postbatchene. Ikke stol på rekkefølgen, eller anta at posisjonen til en strøm i responsen bestemmer dens posisjon i det komplette resultatet.

Forstå OneLake-sikkerheten for tabelllese-API

API-et håndhever OneLake-sikkerheten ved å bruke identiteten som bærertokenet ditt representerer:

  • Hvis du ikke har tillatelse til å se tabellen, returnerer tjenesten et ikke-funnet-svar.
  • Hvis rad-nivå sikkerhet (RLS) filtrerer ut alle rader du kan se, lykkes forespørselen, men returnerer et tomt Arrow-svar.
  • Hvis du bruker en wildcard-kolonneprojeksjon, inkluderer responsen kun kolonner som kolonnenivå sikkerhet (CLS) lar deg se.
  • Hvis du eksplisitt ber om en kolonne du ikke kan se, returnerer tjenesten et ikke-funnet svar.

Siden uautoriserte tabeller og kolonner returnerer ikke-funnet-svar, bør du ikke bruke et ikke-funnet svar for å avgjøre om en ressurs eksisterer.

Hensyn og begrensninger

  • Tabelllese-API-et støtter ikke snarveier på tvers av regioner.
  • Du blir fakturert for operasjonen POST /read . Å hente data ved å bruke /readStream utløser ikke en separat tabelllesefaktureringshendelse. For mer informasjon, se Table read API consumption.
  • Sist oppdatert