Mata in från lagring

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.

Anteckning

Den här inmatningsmetoden är avsedd för utforskning och prototyper. Använd den inte i produktions- eller högvolymscenarier.

Behörigheter

Du måste ha minst tabell-Ingestor-behörighet för att kunna köra det här kommandot.

Syntax

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

Läs mer om syntaxkonventioner.

Parametrar

Namn	Typ	Obligatorisk	Beskrivning
async	string		Om kommandot anges returneras omedelbart och fortsätter inmatningen i bakgrunden. Resultatet av kommandot innehåller ett OperationId värde som sedan kan användas med .show operation kommandot för att hämta slutförandestatus för inmatning och resultat.
TableName	string	✔️	Namnet på den tabell som data ska matas in i. Tabellnamnet är alltid i förhållande till databasen i kontexten. Om inget schemamappningsobjekt anges används schemat för databasen i kontexten.
SourceDataLocator	string	✔️	En enskild 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 i enextern tabell.

Anteckning

Vi rekommenderar att du använder dolda strängliteraler för SourceDataPointer. Tjänsten rensar autentiseringsuppgifter i interna spårningar och felmeddelanden.

Inmatningsegenskaper

Viktigt

• I köade data 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.

I följande tabell visas de egenskaper som stöds av Azure Data Explorer, beskriver dem och innehåller exempel:

Egenskap	Beskrivning	Exempel
ingestionMapping	Ett strängvärde som anger hur data ska mappas 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 dataomfången matas in skapas. 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 den Lookback har angetts kontrollerar du att egenskapen i måltabellens gällande sammanslagningsprincip för utrymmen är justerad mot 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 kommandona .append och .set-or-append . De enda tillåtna schematilläggen har ytterligare kolumner tillagda i tabellen i slutet.	Om det ursprungliga tabellschemat är (a:string, b:int)är (a:string, b:int, c:datetime, d:string)ett giltigt schematillägg , 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 mata in av: taggar.	Egenskaperna with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') anger att om det redan finns data med taggen ingest-by:Part0001 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 inmatningen ska 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 false antas.	with (ignoreFirstRecord=false)
policy_ingestiontime	Ett booleskt värde som, om det anges, beskriver om inmatningstidsprincipen ska aktiveras i en tabell som skapas med 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 .set-or-replace kommandot . 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 som ska associeras med inmatade data, formaterade som en JSON-sträng	with (tags="['Tag1', 'Tag2']")
validationPolicy	En JSON-sträng som anger vilka valideringar som ska köras under 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 faktiskt 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 lagrings-anslutningssträng anger vilken auktoriseringsmetod som ska användas för åtkomst till lagringen. Beroende på auktoriseringsmetoden kan huvudkontot behöva beviljas behörigheter 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-läsare	Läsare
Sas-token (delad åtkomst)	Lista + läsa	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.
Hanterade identiteter	Storage Blob Data-läsare	Läsare

Returer

Resultatet av kommandot är en tabell med så många poster som det finns datashards ("extents") som genereras av kommandot . Om inga datashards har genererats returneras en enda post med ett tomt (nollvärdes) utrymmes-ID.

Namn	Typ	Description
ExtentId	guid	Den unika identifieraren för den 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 .show operation kommandot .

Anteckning

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 klustret 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. Observera även användningen av dolda strängar ( h framför strängvärdena) 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 autentisering med hanterad identitet. Mer information om autentiseringsmetoden för hanterad identitet finns i Översikt över autentisering av hanterad identitet.

.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ördunkkning för den hemliga delen av anslutningssträng.

.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 in från Amazon S3 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 enskild fil in från Amazon S3 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')