.ingest i
Gäller för: ✅Microsoft Fabric✅Azure Data Explorer
Kommandot .ingest into matar in data i en tabell genom att "hämta" data från en eller flera molnlagringsfiler.
Kommandot kan till exempel hämta 1 000 CSV-formaterade blobar från Azure Blob Storage, parsa dem och mata in dem i en enda måltabell.
Data läggs till i tabellen utan att befintliga poster påverkas och utan att tabellens schema ändras.
Not
Den här inmatningsmetoden är avsedd för utforskning och prototyper. Använd den inte i produktions- eller högvolymscenarier.
Not
Den här inmatningsmetoden är avsedd för utforskning och prototyper. Använd den inte i produktions- eller högvolymscenarier. Mer information om inmatningsalternativ finns i Översikt över datainmatning.
Behörigheter
Du måste ha minst Table Ingestor behörighet att köra det här kommandot.
Syntax
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Läs mer om syntaxkonventioner.
Parametrar
| Namn | Typ | Krävs | Beskrivning |
|---|---|---|---|
async |
string |
Om det anges returnerar kommandot omedelbart och fortsätter inmatningen i bakgrunden. Resultatet av kommandot innehåller ett OperationId värde som sedan kan användas med kommandot .show operation för att hämta status och resultat för inmatningsslut. |
|
| TableName | string |
✔️ | Namnet på den tabell som data ska matas in i. Tabellnamnet är alltid relativt databasen i kontext. Om inget schemamappningsobjekt anges används schemat för databasen i kontexten. |
| SourceDataLocator | string |
✔️ | En enda eller kommaavgränsad lista över lagringsanslutningssträngar. En enda anslutningssträng måste referera till en enda fil som hanteras av ett lagringskonto. Inmatning av flera filer kan göras genom att ange flera anslutningssträngar eller genom att mata in från en fråga av en extern tabell. |
Not
Vi rekommenderar att du använder dolda strängliteraler för SourceDataLocators. Tjänsten rensar autentiseringsuppgifter i interna spårningar och felmeddelanden.
Egenskaper för inmatning
Viktig
I köad inmatning batchas data med hjälp av inmatningsegenskaper. Ju mer distinkta egenskaper för inmatningsmappning som används, till exempel olika ConstValue-värden, desto mer fragmenterad blir inmatningen, vilket kan leda till prestandaförsämring.
Följande tabell visar och beskriver de egenskaper som stöds och innehåller exempel:
| Egenskap | Beskrivning | Exempel |
|---|---|---|
ingestionMapping |
Ett strängvärde som anger hur du mappar data från källfilen till de faktiska kolumnerna i tabellen. Definiera värdet format med relevant mappningstyp. Se datamappningar. |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(inaktuell: avroMapping, csvMapping, jsonMapping) |
ingestionMappingReference |
Ett strängvärde som anger hur du mappar data från källfilen till de faktiska kolumnerna i tabellen med hjälp av ett namngivet mappningsprincipobjekt. Definiera värdet format med relevant mappningstyp. Se datamappningar. |
with (format="csv", ingestionMappingReference = "Mapping1")(inaktuell: avroMappingReference, csvMappingReference, jsonMappingReference) |
creationTime |
Datetime-värdet (formaterat som en ISO8601 sträng) som ska användas när datamängderna matas in. Om det är ospecificerat används det aktuella värdet (now()). Att åsidosätta standardvärdet är användbart när du matar in äldre data, så att kvarhållningsprincipen tillämpas korrekt. När du anger det kontrollerar du att egenskapen Lookback i måltabellens princip för effektiv omfattningssammanslagning är justerad med det angivna värdet. |
with (creationTime="2017-02-13") |
extend_schema |
Ett booleskt värde som, om det anges, instruerar kommandot att utöka schemat för tabellen (standardvärdet är false). Det här alternativet gäller endast för kommandona .append och .set-or-append. De enda tillåtna schematilläggen har fler kolumner som lagts till i tabellen i slutet. |
Om det ursprungliga tabellschemat är (a:string, b:int)skulle ett giltigt schematillägg vara (a:string, b:int, c:datetime, d:string), men (a:string, c:datetime) skulle inte vara giltigt |
folder |
För kommandon för inmatning från fråga mappen som ska tilldelas till tabellen. Om tabellen redan finns åsidosätter den här egenskapen tabellens mapp. | with (folder="Tables/Temporary") |
format |
Dataformatet (se dataformat som stöds). | with (format="csv") |
ingestIfNotExists |
Ett strängvärde som, om det anges, förhindrar inmatning från att lyckas om tabellen redan har data taggade med en ingest-by: tagg med samma värde. Detta säkerställer idempotent datainmatning. Mer information finns i inmatning: taggar. |
Egenskaperna with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') anger att om data med taggen ingest-by:Part0001 redan finns så slutför du inte den aktuella inmatningen. Om den inte redan finns bör den här nya inmatningen ha den här taggen inställd (om en framtida inmatning försöker mata in samma data igen.) |
ignoreFirstRecord |
Ett booleskt värde som, om det är inställt på true, anger att inmatning bör ignorera den första posten i varje fil. Den här egenskapen är användbar för filer i CSVoch liknande format, om den första posten i filen är kolumnnamnen. Som standard antas false. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Ett booleskt värde som, om det anges, beskriver om du vill aktivera inmatningstidsprincip i en tabell som skapas av det här kommandot. Standardvärdet är true. |
with (policy_ingestiontime=false) |
recreate_schema |
Ett booleskt värde som, om det anges, beskriver om kommandot kan återskapa schemat för tabellen. Den här egenskapen gäller endast för kommandot .set-or-replace. Den här egenskapen har företräde framför egenskapen extend_schema om båda anges. |
with (recreate_schema=true) |
tags |
En lista över taggar att associera med inmatade data, formaterad som en JSON-sträng | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Ett booleskt värde som, om det är inställt på true, anger att filer med tillägget .gz inte komprimeras. Den här flaggan behövs ibland vid inmatning från Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
En JSON-sträng som anger vilka valideringar som ska köras vid inmatning av data som representeras med CSV-format. En förklaring av de olika alternativen finns i Datainmatning. |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (detta är standardprincipen) |
zipPattern |
Använd den här egenskapen när du matar in data från lagring som har ett ZIP-arkiv. Det här är ett strängvärde som anger det reguljära uttryck som ska användas när du väljer vilka filer i ZIP-arkivet som ska matas in. Alla andra filer i arkivet ignoreras. | with (zipPattern="*.csv") |
Autentisering och auktorisering
Varje lagringsanslutningssträng anger den auktoriseringsmetod som ska användas för åtkomst till lagringen. Beroende på auktoriseringsmetoden kan huvudkontot behöva beviljas behörighet för den externa lagringen för att utföra inmatningen.
I följande tabell visas de autentiseringsmetoder som stöds och de behörigheter som krävs för att mata in data från extern lagring.
| Autentiseringsmetod | Azure Blob Storage/Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| personifiering | Storage Blob Data Reader | Läsare |
| SAS-token (Shared Access) | Lista + läsning | Den här autentiseringsmetoden stöds inte i Gen1. |
| Microsoft Entra-åtkomsttoken | ||
| Åtkomstnyckel för lagringskonto | Den här autentiseringsmetoden stöds inte i Gen1. | |
| hanterad identitet | Storage Blob Data Reader | Läsare |
Returnerar
Resultatet av kommandot är en tabell med lika många poster som det finns datashards ("extents") som genereras av kommandot. Om inga datashards genererades returneras en enskild post med ett tomt (nollvärdes)-omfattnings-ID.
| Namn | Typ | Beskrivning |
|---|---|---|
| ExtentId | guid |
Den unika identifieraren för datashard som genererades av kommandot. |
| ItemLoaded | string |
En eller flera lagringsfiler som är relaterade till den här posten. |
| Varaktighet | timespan |
Hur lång tid det tog att utföra inmatning. |
| HasErrors | bool |
Om den här posten representerar ett inmatningsfel eller inte. |
| OperationId | guid |
Ett unikt ID som representerar åtgärden. Kan användas med kommandot .show operation. |
Not
Det här kommandot ändrar inte schemat för tabellen som matas in i. Vid behov "tvingas" data till det här schemat under inmatningen, inte tvärtom (extra kolumner ignoreras och saknade kolumner behandlas som null-värden).
Exempel
Azure Blob Storage med signatur för delad åtkomst
I följande exempel instrueras databasen att läsa två blobar från Azure Blob Storage som CSV-filer och mata in innehållet i tabellen T.
... representerar en signatur för delad åtkomst i Azure Storage (SAS) som ger läsåtkomst till varje blob. Fördunklade strängar (h framför strängvärdena) används för att säkerställa att SAS aldrig registreras.
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
Azure Blob Storage med hanterad identitet
I följande exempel visas hur du läser en CSV-fil från Azure Blob Storage och matar in innehållet i tabellen T med hjälp av hanterad identitetsautentisering. Autentiseringen använder det hanterade identitets-ID (objekt-ID) som tilldelats Azure Blob Storage i Azure. Mer information finns i Skapa en hanterad identitet för lagringscontainrar.
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
Följande exempel är för att mata in data från Azure Data Lake Storage Gen 2 (ADLSv2). Autentiseringsuppgifterna som används här (...) är autentiseringsuppgifterna för lagringskontot (delad nyckel) och vi använder endast strängfördunkling för den hemliga delen av anslutningssträngen.
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
I följande exempel matas en enda fil in från Azure Data Lake Storage (ADLS). Den använder användarens autentiseringsuppgifter för att få åtkomst till ADLS (så det finns inget behov av att behandla lagrings-URI:n som innehåller en hemlighet). Den visar också hur du anger inmatningsegenskaper.
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
Amazon S3 med en åtkomstnyckel
I följande exempel matas en enda fil från Amazon S3 in med hjälp av ett åtkomstnyckel-ID och en hemlig åtkomstnyckel.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
Amazon S3 med en försignerad URL
I följande exempel matas en enda fil från Amazon S3 in med hjälp av en försignerad URL.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')