.create ingestion mapping command
Applies to: ✅ Microsoft Fabric ✅ 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