.create ingestion mapping command

  • Article
  • 12/20/2024

Applies to: ✅ Azure Data Explorer

Creates an ingestion mapping that can be associated with a specific format and a specific table or database.

If a mapping with same name in the given scope already exists, .create fails. Use .create-or-alter instead.

Permissions

At least Database Ingestor permissions are required to create a database ingestion mapping, and at least Table Ingestor permissions are required to create a table ingestion mapping.

Syntax

.create table TableName ingestion MappingKind mapping MappingName MappingFormattedAsJson

.create database DatabaseName ingestion MappingKind mapping MappingName MappingFormattedAsJson

Learn more about syntax conventions.

Parameters

Name Type Required Description
TableName string ✔️ The name of the table.
DatabaseName string ✔️ The name of the database.
MappingKind string ✔️ The type of mapping. Valid values are csv, json, avro, parquet, and orc.
MappingName string ✔️ The name of the mapping.
MappingFormattedAsJson string ✔️ The ingestion mapping definition formatted as a JSON value.

Note

  • Once created, the mapping can be referenced by its name in ingestion commands, instead of specifying the complete mapping as part of the command.
  • If a mapping with the same name is created in both the table scope and the database scope, the mapping in the table scope will have higher priority.
  • When ingesting into a table and referencing a mapping whose schema does not match the ingested table schema, the ingest operation will fail.

Examples

Create a table and database with CSV ingestion mapping

The following example creates a table, MyTable with CSV ingestion mapping Mapping1 and a database, MyDatabase with CSV ingestion mapping Mapping2.

.create table MyTable ingestion csv mapping "Mapping1"
'['
'   { "column" : "rownumber", "DataType":"int", "Properties":{"Ordinal":"0"}},'
'   { "column" : "rowguid", "DataType":"string", "Properties":{"Ordinal":"1"}}'
']'

.create database MyDatabase ingestion csv mapping "Mapping2"
'['
'   { "column" : "rownumber", "DataType":"int", "Properties":{"Ordinal":"0"}},'
'   { "column" : "rowguid", "DataType":"string", "Properties":{"Ordinal":"1"}}'
']'

Output

Name Kind Mapping Database Table
mapping1 CSV [{"Name":"rownumber","DataType":"int","CsvDataType":null,"Ordinal":0,"ConstValue":null},{"Name":"rowguid","DataType":"string","CsvDataType":null,"Ordinal":1,"ConstValue":null}] MyDatabase MyTable
mapping2 CSV [{"Name":"rownumber","DataType":"int","CsvDataType":null,"Ordinal":0,"ConstValue":null},{"Name":"rowguid","DataType":"string","CsvDataType":null,"Ordinal":1,"ConstValue":null}] MyDatabase

Create ingestion mapping with escape characters

The following example creates a table, test_table with JSON ingestion mapping test_mapping_name. To avoid errors, backslashes are used to escape single quotes in the JSON path strings.

.create table test_table ingestion json mapping "test_mapping_name"
'['
'{"column":"timeStamp","path":"$[\'timeStamp\']","datatype":"","transform":null},{"column":"name","path":"$[\'name\']","datatype":"","transform":null},{"column":"x-opt-partition-key","path":"$[\'x-opt-partition-key\']","datatype":"","transform":null}'
']'

Related content

  • For detailed descriptions of various ingestion mapping formats, such as CSV, JSON, Avro, Parquet, and Orc, see Data mappings.
  • To learn more about JSON mapping as an ingestion source, see JSON mapping