detectImportOptions
Create import options based on file content
Description
opts = detectImportOptions(filename)readtable to control how MATLAB® imports tabular data. The type of the options returned depends on the
file extension.
For a spreadsheet file, the function returns a
SpreadsheetImportOptionsobject.For a text file, the function returns a
DelimitedTextImportOptionsorFixedWidthImportOptionsobject.For a JSON file, the function returns a
JSONImportOptionsFor an XML file, the function returns an
XMLImportOptionsobject.For a Microsoft® Word document, the function returns a
WordDocumentImportOptionsobject.For an HTML file, the function returns an
HTMLImportOptionsobject,
opts = detectImportOptions(filename,Name=Value)
Examples
Configure how readtable interprets your file using an import options object. For example, use an import options object to read only specified variables from a spreadsheet file.
First, create an import options object from a file by using detectImportOptions to detect aspects of your spreadsheet file, including variable names and types. In this case, detectImportOptions creates a SpreadsheetImportOptions object.
opts = detectImportOptions("patients.xls")opts =
SpreadsheetImportOptions with properties:
Sheet Properties:
Sheet: ''
Replacement Properties:
MissingRule: 'fill'
ImportErrorRule: 'fill'
MergedCellColumnRule: 'placeleft'
MergedCellRowRule: 'placetop'
Variable Import Properties: Set types by name using setvartype
VariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
VariableTypes: {'char', 'char', 'double' ... and 7 more}
SelectedVariableNames: {'LastName', 'Gender', 'Age' ... and 7 more}
VariableOptions: Show all 10 VariableOptions
Access VariableOptions sub-properties using setvaropts/getvaropts
VariableNamingRule: 'modify'
Range Properties:
DataRange: 'A2' (Start Cell)
VariableNamesRange: 'A1'
RowNamesRange: ''
VariableUnitsRange: ''
VariableDescriptionsRange: ''
To display a preview of the table, use preview
Specify which variables to import by modifying the import options object. Then, import the specified variables using readtable with the import options object. Display the first 5 rows of the table.
opts.SelectedVariableNames = ["Systolic","Diastolic"]; T = readtable("patients.xls",opts); T(1:5,:)
ans=5×2 table
Systolic Diastolic
________ _________
124 93
109 77
125 83
117 75
122 80
Configure how readtable interprets your file using an import options object. For example, use an import options object to read only a subset of a text file.
First, create an import options object by using detectImportOptions to detect aspects of your text file, including variable names and types, delimiters, and white-space characters. In this case, detectImportOptions creates a DelimitedTextImportOptions object.
opts = detectImportOptions("airlinesmall.csv")opts =
DelimitedTextImportOptions with properties:
Format Properties:
Delimiter: {','}
Whitespace: '\b\t '
LineEnding: {'\n' '\r' '\r\n'}
CommentStyle: {}
ConsecutiveDelimitersRule: 'split'
LeadingDelimitersRule: 'keep'
TrailingDelimitersRule: 'ignore'
EmptyLineRule: 'skip'
Encoding: 'ISO-8859-1'
Replacement Properties:
MissingRule: 'fill'
ImportErrorRule: 'fill'
ExtraColumnsRule: 'addvars'
Variable Import Properties: Set types by name using setvartype
VariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
VariableTypes: {'double', 'double', 'double' ... and 26 more}
SelectedVariableNames: {'Year', 'Month', 'DayofMonth' ... and 26 more}
VariableOptions: Show all 29 VariableOptions
Access VariableOptions sub-properties using setvaropts/getvaropts
VariableNamingRule: 'modify'
Location Properties:
DataLines: [2 Inf]
VariableNamesLine: 1
RowNamesColumn: 0
VariableUnitsLine: 0
VariableDescriptionsLine: 0
To display a preview of the table, use preview
Specify the subset of variables to import by modifying the import options object. Then, import the subset of data using readtable with the import options object.
opts.SelectedVariableNames = ["TaxiIn","TaxiOut"]; T = readtable("airlinesmall.csv",opts);
Detect import options for a Microsoft Word document file, specify the table to import, and then read the data.
The file MaintenanceReport.docx contains two tables. The last row of the second table contains a cell with merged columns that do not match the table variables.
Detect the import options using the detectImportOptions function. Specify to read from the second table by setting TableIndex to 2.
filename = "MaintenanceReport.docx"; opts = detectImportOptions(filename,'TableIndex',2)
opts =
WordDocumentImportOptions with properties:
Replacement Properties:
MissingRule: "fill"
ImportErrorRule: "fill"
EmptyRowRule: "skip"
MergedCellColumnRule: "placeleft"
MergedCellRowRule: "placetop"
ExtraColumnsRule: "addvars"
Variable Import Properties: Set types by name using setvartype
VariableNames: ["Description" "Category" "Urgency" "Resolution" "Cost"]
VariableTypes: ["string" "string" "string" "string" "string"]
SelectedVariableNames: ["Description" "Category" "Urgency" "Resolution" "Cost"]
VariableOptions: Show all 5 VariableOptions
Access VariableOptions sub-properties using setvaropts/getvaropts
VariableNamingRule: "preserve"
Location Properties:
TableSelector: "(//w:tbl)[2]"
DataRows: [2 Inf]
VariableNamesRow: 1
VariableUnitsRow: 0
VariableDescriptionsRow: 0
RowNamesColumn: 0
To skip reading rows that have cells with merged columns, set the MergedCellColumnRule property to 'omitrow'.
opts.MergedCellColumnRule = 'omitrow';Read the table from the Microsoft Word document file using the readtable function with the options object.
filename = "MaintenanceReport.docx";
T = readtable(filename,opts)T=3×5 table
Description Category Urgency Resolution Cost
_____________________________________________________________________ ____________________ ________ __________________ ________
"Items are occasionally getting stuck in the scanner spools." "Mechanical Failure" "Medium" "Readjust Machine" "$45"
"Loud rattling and banging sounds are coming from assembler pistons." "Mechanical Failure" "Medium" "Readjust Machine" "$35"
"There are cuts to the power when starting the plant." "Electronic Failure" "High" "Full Replacement" "$16200"
Detect import options for an HTML file, specify the table to import, and then read the data.
Detect the import options of the first table from the URL https://www.mathworks.com/help/matlab/text-files.html containing the text "readtable". Detect the import options using the detectImportOptions function and specify the table to read using the XPath query "//TABLE[contains(.,'readtable')]". Specify to not read variable names by setting ReadVariableNames to false.
url = "https://www.mathworks.com/help/matlab/text-files.html"; opts = detectImportOptions(url,'TableSelector',"//TABLE[contains(.,'readtable')]",'ReadVariableNames',false)
opts =
HTMLImportOptions with properties:
Replacement Properties:
MissingRule: "fill"
ImportErrorRule: "fill"
EmptyRowRule: "skip"
MergedCellColumnRule: "placeleft"
MergedCellRowRule: "placetop"
ExtraColumnsRule: "addvars"
Variable Import Properties: Set types by name using setvartype
VariableNames: ["Var1" "Var2"]
VariableTypes: ["string" "string"]
SelectedVariableNames: ["Var1" "Var2"]
VariableOptions: Show all 2 VariableOptions
Access VariableOptions sub-properties using setvaropts/getvaropts
VariableNamingRule: "preserve"
Location Properties:
TableSelector: "//TABLE[contains(.,'readtable')]"
DataRows: [1 Inf]
VariableNamesRow: 0
VariableUnitsRow: 0
VariableDescriptionsRow: 0
RowNamesColumn: 0
Read the table using the readtable function.
T = readtable(url,opts)
T=4×2 table
"readtable" "Create table from file"
"writetable" "Write table to file"
"readtimetable" "Create timetable from file"
"writetimetable" "Write timetable to file"
Import text data as a string data type by specifying import options.
Create an options object for the file.
opts = detectImportOptions('outages.csv');Specify which variables to import using readtable, and then show a summary. The data type of the selected variables is char.
opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)T: 1468×2 table
Variables:
Region: cell array of character vectors
Cause: cell array of character vectors
Statistics for applicable variables:
NumMissing
Region 0
Cause 0
Import text data as a string data type, and then create import options by specifying the TextType name-value pair.
opts = detectImportOptions('outages.csv','TextType','string');
Specify which variables to import using readtable, and then show a summary. The data type of the selected variables is now string.
opts.SelectedVariableNames = {'Region','Cause'};
T = readtable('outages.csv',opts);
summary(T)T: 1468×2 table
Variables:
Region: string
Cause: string
Statistics for applicable variables:
NumMissing
Region 0
Cause 0
Import the contents of an XML file into a table.
The students.xml file has three sibling nodes named Student, which each contain the same child nodes and attributes.
type students.xml<?xml version="1.0" encoding="utf-8"?>
<Students>
<Student ID="S11305">
<Name FirstName="Priya" LastName="Thompson" />
<Age>18</Age>
<Year>Freshman</Year>
<Address>
<Street xmlns="https://www.mathworks.com">591 Spring Lane</Street>
<City>Natick</City>
<State>MA</State>
</Address>
<Major>Computer Science</Major>
<Minor>English Literature</Minor>
</Student>
<Student ID="S23451">
<Name FirstName="Conor" LastName="Cole" />
<Age>18</Age>
<Year>Freshman</Year>
<Address>
<Street xmlns="https://www.mathworks.com">4641 Pearl Street</Street>
<City>San Francisco</City>
<State>CA</State>
</Address>
<Major>Microbiology</Major>
<Minor>Public Health</Minor>
</Student>
<Student ID="S119323">
<Name FirstName="Morgan" LastName="Yang" />
<Age>21</Age>
<Year>Senior</Year>
<Address>
<Street xmlns="https://www.mathworks.com">30 Highland Road</Street>
<City>Detriot</City>
<State>MI</State>
</Address>
<Major>Political Science</Major>
</Student>
</Students>
First, create an XMLImportOptions object by using detectImportOptions to detect aspects of your XML file. Read just the street names into a table by specifying the VariableSelectors name-value argument as the XPath expression of the Street element node. Register a custom namespace prefix to the existing namespace URL by setting the RegisteredNamespaces name-value argument.
opts = detectImportOptions("students.xml",RegisteredNamespaces=["myPrefix","https://www.mathworks.com"], ... VariableSelectors="//myPrefix:Street");
Then, import the specified variable using readtable with the import options object.
T = readtable("students.xml",opts)T=3×1 table
Street
___________________
"591 Spring Lane"
"4641 Pearl Street"
"30 Highland Road"
Input Arguments
Name of the file to read, specified as a character vector or string scalar.
Depending on the location of your file, filename can
take on one of these forms.
Location | Form | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| Current folder or folder on the MATLAB path | Specify the name of the file in
Example:
| ||||||||
File in a folder | If the file is not in the current folder or in
a folder on the MATLAB path, then specify the full or
relative path name in
Example:
Example:
| ||||||||
| Internet URL | If the file is specified as an internet uniform
resource locator (URL), then
Example:
| ||||||||
Remote Location | If the file is stored at a remote location,
then
Based on the remote location,
For more information, see Work with Remote Data. Example:
|
If filename includes the file extension, then
detectImportOptions determines the file format from
the extension. Otherwise, you must specify the 'FileType'
name-value pair to indicate the type of file.
The detectImportOptions function supports these file
extensions: .txt, .dat,
.csv, .xls,
.xlsb, .xlsm,
.xlsx, .xltm,
.xltx, .ods,
.json, .xml,
.docx, .html,
.xhtml, .htm,
.zip, .gz, and
.tar.
Compressed file formats are read as
files. Archived file formats are treated as folders. For example, the
function interprets mydatafiles.zip as a folder, so you
must specify a file within it, such as
mydatafiles.zip/file1.xlsx. For files ending with the
.gz extension, the function determines the file
format by using the extension preceding .gz. For example,
mydata.csv.gz is read as a CSV file. (since R2025a)
File extensions .xlsb and .ods are
only supported on platforms with Excel® for Windows®.
Data Types: char | string
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN, where Name is
the argument name and Value is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Example: detectImportOptions(filename,FileType="spreadsheet") indicates that
the specified file is a spreadsheet.
Data and Header Location
Number of header lines to skip at the beginning of the file, specified
as a nonnegative integer. If you do not specify this name-value
argument, detectImportOptions automatically detects
the number of lines to skip.
Reading of variable names and data begins with the first nonheader line.
Data Types: single | double
Range to read from the file, specified as a string scalar, character vector, or numeric vector in one of these forms.
Ways to Specify Range
| Description |
|---|---|
Starting element | Specify the starting element for the data as one of these values:
Using the starting element,
Example:
Example:
|
Rectangular range | Specify the rectangular range for the data as one of these values:
The
number of columns must match the number specified in
the Example:
Example:
|
Row range | Specify the beginning and ending rows using row
numbers in a string scalar or character vector of
the form
Using the specified row range,
Example:
|
Column range | Specify the beginning and ending columns using
A1 notation column letters in a string scalar or
character vector of the form
Using the specified column range,
The number of columns must match
the number specified in the
Example:
|
Named range (spreadsheet only) | You can create names to identify ranges in a
spreadsheet. For instance, you can select a
rectangular portion of the spreadsheet and call it
|
Unspecified or empty | If you do not specify this name-value argument,
Note:
Used range refers to the
rectangular portion of the file that actually
contains data.
|
Location of the data, specified as a string scalar, character vector,
positive integer, or N-by-2 array
of positive integers in one of these forms.
Ways to Specify
DataRange | Description |
|---|---|
Starting cell | Specify the starting cell for the data as a
string scalar or character vector containing a
column letter and row number, using A1 notation.
For example, Using the
starting cell,
Example:
|
Starting row | Specify the starting row containing the data using the positive row index. Using the specified row index,
Example:
|
Rectangular range | Specify the range using the form
Example:
|
Row range | Specify the beginning and ending rows using
row numbers in a string scalar or character vector
of the form
Using
the specified row range,
Example:
|
Column range | Specify the beginning and ending columns
using A1 notation column letters in a string
scalar or character vector of the form
Using
the specified column range,
Example:
|
Multiple row ranges | Specify multiple row ranges using an
A valid array of multiple row ranges must:
Use of
Example:
|
Empty | Do not read any data. Example:
|
Worksheet to read, specified as a positive integer indicating the
worksheet index or a string scalar or character vector containing the
worksheet name. By default, detectImportOptions reads
the first sheet.
If you specify a string scalar or character vector, the worksheet name
cannot contain a colon (:). To determine the names of
sheets in a spreadsheet file, use sheets =
sheetnames(filename). For more information, see sheetnames.
Example: 2
Example: "MySheetName"
Index of the table to read from a file containing multiple tables,
specified as a positive integer. By default,
detectImportOptions reads the first table.
If you specify TableIndex, the
detectImportOptions function automatically sets
TableSelector to the equivalent XPath
expression.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Table to read, specified as a string scalar or character vector. If
you do not specify this name-value argument,
detectImportOptions detects the table
location.
JSON Files
Specify the table to read as a string scalar or character vector
containing a JSON Pointer. You must specify
TableSelector as a valid RFC 6901 JSON
Pointer. For more information, see the IETF
definition of JSON Pointer.
An empty string ("") refers to the whole JSON
file.
Example:
TableSelector="/engineID"
XML, Microsoft Word, and HTML Files
Specify the table to read as a string scalar or character vector
containing an XPath expression. You must specify
TableSelector as a valid XPath version 1.0
expression.
| Selection Operation | Syntax |
|---|---|
| Select every node whose name matches the node you want to select, regardless of its location in the document. | Prefix the name with two forward slashes
(//). |
| Select the value of an attribute belonging to an element node. | Prefix the attribute with an at sign
(@). |
| Select a specific node in a set of nodes. | Provide the index of the node you want to
select in square brackets
([]). |
| Specify precedence of operations. | Add parentheses around the expression you want to evaluate first. |
Example:
TableSelector="//table[1]"
JSON key name or XML node name for the table data to read, specified as a string scalar or character vector.
Rule for cells merged across columns, specified as one of the values in this table.
| Import Rule | Behavior |
|---|---|
"placeleft" | Place the data in the leftmost cell and
fill the remaining cells with the contents of the
You can
set the |
"placeright" | Place the data in the rightmost cell and
fill the remaining cells with the contents of the
You can
set the |
"duplicate" | Duplicate the data in all cells. |
"omitrow" | Omit rows where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
Rule for cells merged across rows, specified as one of the values in this table.
| Import Rule | Behavior |
|---|---|
"placetop" | Place the data in the top cell and fill the
remaining cells with the contents of the
You can
set the |
"placebottom" | Place the data in the bottom cell and fill
the remaining cells with the contents of the
You can set the
|
"duplicate" | Duplicate the data in all cells. |
"omitvar" | Omit variables where merged cells occur. |
"error" | Display an error message and cancel the import operation. |
Variables
Read variable names, specified as a numeric or logical
1 (true) or
0 (false). If you do not
specify this name-value argument, detectImportOptions
automatically detects the presence of variable names.
Value | Description |
|---|---|
| Read variable names. |
| Do not read variable names. Create default
variable names of the form
|
| Unspecified | Automatically detect whether the region contains variable names. |
For text, spreadsheet, Microsoft Word, and HTML files, variable names are detected after header rows. For JSON files, variable names are detected from object key names (since R2026a). For XML files, variable names are detected from element node and attribute names.
If both ReadVariableNames and
ReadRowNames are true, then
detectImportOptions saves the name in the first
column of the first row of the region to read as the first dimension
name in the property
T.Properties.DimensionNames.
Rule for variable names, specified as one of these values:
"modify"— Convert invalid variable names (as determined by theisvarnamefunction) to valid MATLAB identifiers. This value is the default for text and spreadsheet files."preserve"— Preserve variable names that are not valid MATLAB identifiers, such as variable names that include spaces and non-ASCII characters. This value is the default for JSON, XML, Microsoft Word, and HTML files.
Variable and row names do not have to be valid MATLAB identifiers. They can include any characters, including spaces or non-ASCII characters. Also, they can start with any character, not just letters.
Expected number of variables, specified as a nonnegative integer. If
you do not specify this name-value argument,
detectImportOptions automatically detects the
number of variables.
Location of variable names, specified as a nonnegative integer.
If VariableNamesLine is 0, then
detectImportOptions does not detect variable
names. Otherwise, detectImportOptions detects the
variable names from the specified line.
If variable names exist, and both VariableNamesLine
and ReadVariableNames are unspecified,
detectImportOptions detects which line contains
variable names and imports them.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Location of variable names, specified as a string scalar, character vector, or positive integer in one of these forms.
Ways to Specify
VariableNamesRange | Description |
|---|---|
Starting cell | Specify the starting cell for the variable names as a string scalar or character vector containing a column letter and row number, using A1 notation. Example:
|
Rectangular range | Specify the range using the form
The range must span only one row. Example:
|
Number index | Specify the row containing the variable names using a positive row index. Example:
|
Row range | Specify the range using the form
Variable names must be in a single row. Example:
|
Unspecified or empty | Indicate that there are no variable names. Example:
|
Data Types: string | char | single | double
Location of variable names, specified as a nonnegative integer.
If VariableNamesRow is 0, then
detectImportOptions does not detect variable
names. Otherwise, detectImportOptions detects the
variable names from the specified row.
If you do not specify VariableNamesRow, and
ReadVariableNames is true
(default), then detectImportOptions imports variable
names. If both are unspecified, detectImportOptions
detects if a row contains variable names to import.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
JSON key names and XML node names to read as table variables,
specified as a string array, character vector, or cell array of
character vectors. If nested nodes have the same name,
VariableNodeNames selects the nodes at the top
level.
Example: VariableNodeNames=["XMLNodeName1","XMLNodeName2"]
Variables to read, specified as a string array, character vector, or
cell array of character vectors. If you do not specify this name-value
argument, detectImportOptions detects the location of
variables.
JSON Files
(since R2026a)
Specify the variables to read as a string array, character vector,
or cell array of character vectors containing JSON Pointers. You
must specify VariableSelectors as valid RFC 6901
JSON Pointers. For more information, see the IETF
definition of JSON Pointer.
An asterisk (*) in a
VariableSelectors value indicates an entire
array at that corresponding level is selected.
To read keys as variables, include the string
"Keys" with
VariableSelectors. For example,
VariableSelectors=["Keys" "/ID"
"/Name/FirstName"].
An empty string ("") refers to the whole JSON
file.
Example:
VariableSelectors="/enginetemp"
Example:
VariableSelectors=["/enginetemp1","/enginetemp2"]
XML Files
Specify the variables to read as
a string array, character vector, or cell array of character vectors
containing XPath expressions. You must specify
VariableSelectors as valid XPath version 1.0
expressions. For example, suppose you want to import the XML file
myFile.xml, which has this
structure:
<data>
<table category="ones">
<var>1</var>
<var>2</var>
</table>
<table category="tens">
<var>10</var>
<var>20</var>
</table>
</data>
| Selection Operation | Syntax | Example |
|---|---|---|
| Select every node whose name matches the node you want to select, regardless of its location in the document. | Prefix the name with two forward slashes
(//). | Select every node named
opts = detectImportOptions("myFile.xml",VariableSelectors="//var") |
| Select the value of an attribute belonging to an element node. | Prefix the attribute with an at sign
(@). | Select the value of the
opts = detectImportOptions("myFile.xml",VariableSelectors="//table/@category") |
| Select a specific node in a set of nodes. | Provide the index of the node you want to
select in square brackets
([]). | Select the first opts = detectImportOptions("myFile.xml",VariableSelectors="//table/var[1]") |
| Specify precedence of operations. | Add parentheses around the expression you want to evaluate first. | Select the first opts = detectImportOptions("myFile.xml",VariableSelectors="//table/var[1]") |
Select the first opts = detectImportOptions("myFile.xml",VariableSelectors="(//table/var)[1]") |
Rows
Read the first column as row names, specified as a numeric or logical
1 (true) or
0 (false).
Value | Description |
|---|---|
| Read row names from the first column of the region to read. |
| Read data from the first column of the region and do not create row names. |
If both ReadVariableNames and
ReadRowNames are true, then
detectImportOptions saves the name in the first
column of the first row of the region to read as the first dimension
name in the property
T.Properties.DimensionNames.
Location of row names, specified as a nonnegative integer.
If RowNamesColumn is 0, then
detectImportOptions does not detect row names.
Otherwise, detectImportOptions detects row names from
the specified column.
If you do not specify RowNamesColumn, and
ReadRowNames is true,
detectImportOptions detects the first column as
the row names.
Location of row names, specified as a string scalar, character vector, or positive integer in one of these forms.
Ways to Specify
RowNamesRange | Description |
|---|---|
Starting cell | Specify the starting cell for the row names as a string scalar or character vector containing a column letter and row number, using A1 notation. From the starting cell,
Example:
|
Rectangular range | Specify the range using the form
The number of rows must match the number of data rows, and the range must span only one column. Example:
|
Column range | Specify the range using the form
Row names must be in a single column. Example:
|
Number index | Specify the column containing the row names using a positive column index. Example:
|
Unspecified or empty | Indicate that there are no row names. Example:
|
Data Types: string | char | single | double
Row names, specified as a string scalar or character vector. If you do
not specify this name-value argument,
detectImportOptions does not import row names
unless ReadRowNames is true.
JSON Files
(since R2026a)
Specify the row names as a string scalar or character vector
containing a JSON Pointer. You must specify
RowNamesSelector as a valid RFC 6901 JSON
Pointer. For more information, see the IETF
definition of JSON Pointer.
Example:
RowNamesSelector="/engineID"
XML Files
Specify the row names as a string scalar or character vector
containing an XPath expression. You must specify
RowNamesSelector as a valid XPath version 1.0
expression.
Example:
RowNamesSelector="/RootNode/ChildNode"
XPath expression for selecting individual rows from a table, specified
as a string scalar or character vector. You must specify
RowSelector as a valid XPath version 1.0
expression.
If you do not specify this name-value argument,
detectImportOptions detects the location of
rows.
Example: "/RootNode/ChildNode"
XML nodes specifying rows, specified as a string scalar or character vector.
Data Types
Type for imported text data, specified as one of these values:
"char"— Import text data as character vectors. This value is the default for text and spreadsheet files."string"— Import text data as string arrays. This value is the default for JSON, XML, Microsoft Word, and HTML files.
Type for imported date and time data, specified as one of the values in this table.
| Value | Resulting Data Type |
|---|---|
"datetime" | MATLAB
|
"text" | The data type depends on the value of
|
"exceldatenum"
| Excel serial date numbers This value is valid only for spreadsheet files. A serial date number is a single number equal to the number of days from a given reference date. Excel serial date numbers use a different reference date than MATLAB serial date numbers. For more information on Excel dates, see Differences between the 1900 and the 1904 date system in Excel. |
Type for imported duration data, specified as one of the values in this table.
| Value | Resulting Data Type |
|---|---|
"duration" | MATLAB
|
"text" | The data type depends on the value of
|
Type for imported hexadecimal data, specified as one of the values in this table.
Value | Resulting Data Type |
|---|---|
| Detected data type;
|
| Unaltered input text |
| 8-bit integer, signed |
| 16-bit integer, signed |
| 32-bit integer, signed |
| 64-bit integer, signed |
| 8-bit integer, unsigned |
| 16-bit integer, unsigned |
| 32-bit integer, unsigned |
| 64-bit integer, unsigned |
The input file can represent hexadecimal values as text, using either
0x or 0X as a prefix and the
characters 0-9,
a-f, and
A-F as digits. Uppercase and
lowercase letters represent the same digits—for example,
"0xf" and "0xF" both represent
15.
Type for imported binary data, specified as one of the values in this table.
Value | Resulting Data Type |
|---|---|
| Detected data type;
|
| Unaltered input text |
| 8-bit integer, signed |
| 16-bit integer, signed |
| 32-bit integer, signed |
| 64-bit integer, signed |
| 8-bit integer, unsigned |
| 16-bit integer, unsigned |
| 32-bit integer, unsigned |
| 64-bit integer, unsigned |
The input file can represent binary values as text, using either
0b or 0B as a prefix and the
characters 0 and 1 as digits. For
example, 0b11111111 represents 255.
Locale for reading dates, specified as a string scalar or character
vector of the form
xx_YY
xxis a lowercase ISO 639-1 two-letter code indicating a language.YYis an uppercase ISO 3166-1 alpha-2 code indicating a country.
Use DateLocale to specify the locale in which
detectImportOptions interprets month and
day-of-week names and abbreviations.
This table lists some common values for the locale.
| Locale | Language | Country |
|---|---|---|
"de_DE" | German | Germany |
"en_GB" | English | United Kingdom |
"en_US" | English | United States |
"es_ES" | Spanish | Spain |
"fr_FR" | French | France |
"it_IT" | Italian | Italy |
"ja_JP" | Japanese | Japan |
"ko_KR" | Korean | Korea |
"nl_NL" | Dutch | Netherlands |
"zh_CN" | Chinese (simplified) | China |
Whether to remove nonnumeric characters from a numeric variable,
specified as a numeric or logical 1
(true) or 0
(false). For example, if
TrimNonNumeric is true, then
detectImportOptions detects
"$500/-" as 500.
Decimal separator character in numeric variables, specified as a
string scalar or single-character character vector. The separator
character distinguishes the integer part of a number from the decimal
part. For example, if the separator is ",", then
detectImportOptions detects the text
"3,14159" as the number
3.14159.
When converting to integer data types,
detectImportOptions rounds numbers with a decimal
part to the nearest integer. DecimalSeparator does
not accept numeric digits as values.
Thousands grouping character in numeric variables, specified as a
string scalar or character vector. The grouping character acts as a
visual separator, grouping a number at every three place values. For
example, if the grouping character is ",", then
detectImportOptions detects the text
"1,234,000" as 1234000.
Exponent characters, specified as a string scalar or character vector.
The default exponent characters are e,
E, d, and
D.
Example: "eE"
Data Cleaning
Placeholder text to treat as missing value, specified as a string
array, character vector, or cell array of character vectors.
detectImportOptions detects table elements
corresponding to this placeholder text as the missing value associated
with the data type of the element.
Example: "N/A"
Example: [".","NA","N/A"]
Rule for import errors, specified as one of the values in this table.
An import error occurs when detectImportOptions
cannot convert a text element to the expected data type.
| Import Error Rule | Behavior |
|---|---|
"fill" | Replace the data where the error occurred with
the contents of the You can set the
|
"error" | Display an error message and cancel the import operation. |
"omitrow" | Omit rows where errors occur. |
"omitvar" | Omit variables where errors occur. |
Rule for missing data, specified as one of the values in this table.
| Missing Rule | Behavior |
|---|---|
"fill" | Replace missing data with the contents of the
You can set the
|
"error" | Display an error message and cancel the import operation. |
"omitrow" | Omit rows that contain missing data. |
"omitvar" | Omit variables that contain missing data. |
For text files, Microsoft Word, and HTML files, data is considered missing if an expected field in a row does not exist. Because missing fields cause subsequent elements of a row to shift fields, the missing fields are interpreted at the end of the row.
For spreadsheet files, data is considered missing if the expected field in a row has no data and the field type is blank or empty.
For JSON and XML files, data is considered missing if an expected node does not exist.
Rule for extra columns in the data, specified as one of the values in
this table. detectImportOptions considers columns to
be extra if a row has more columns than expected.
| Extra Columns Rule | Behavior |
|---|---|
"addvars" | To import extra columns, create new variables.
If there are
|
"ignore" | Ignore the extra columns of data. |
"wrap" | Wrap the extra columns of data to new records. This action does not change the number of variables. |
"error" | Display an error message and cancel the import operation. |
Rule for empty lines in the data, specified as one of the values in
this table. detectImportOptions considers a line to
be empty if it contains only white-space characters.
| Empty Line Rule | Behavior |
|---|---|
"skip" | Skip the empty lines. |
"read" | Import the empty lines.
detectImportOptions parses an
empty line using the values specified in
VariableWidths,
VariableOptions,
MissingRule, and other relevant
arguments, such as Whitespace.
|
"error" | Display an error message and cancel the import operation. |
Rule for empty rows in the data, specified as one of the values in this table.
| Empty Line Rule | Behavior |
|---|---|
"skip" | Skip the empty rows. |
"read" | Import the empty rows.
detectImportOptions parses an
empty row using the values specified in
VariableWidths,
VariableOptions,
MissingRule, and other relevant
arguments, such as Whitespace.
|
"error" | Display an error message and cancel the import operation. |
Rule for empty columns in the data, specified as one of the values in this table.
| Empty Column Rule | Behavior |
|---|---|
"skip" | Skip the empty columns. |
"read" | Import the empty columns.
detectImportOptions parses an
empty column using the values specified in
VariableWidths,
VariableOptions,
MissingRule, and other relevant
arguments, such as Whitespace.
|
"error" | Display an error message and cancel the import operation. |
Rule for partial fields in the data, specified as one of the values in
this table. detectImportOptions considers a field to
be partially filled if it reaches the end of a line in fewer characters
than the expected width. This name-value argument applies only to fields
with fixed widths.
| Partial Field Rule | Behavior |
|---|---|
"keep" | Keep the partial field data and convert the text to the appropriate data type. If
|
"fill" | Replace missing data with the contents of the
You can set the
|
"omitrow" | Omit rows that contain partial data. |
"omitvar" | Omit variables that contain partial data. |
"wrap" | Begin reading the next line of characters. |
"error" | Display an error message and cancel the import operation. |
File Information
Type of file, specified as one of the values in this table.
| Value | File Type |
|---|---|
"spreadsheet" | Spreadsheet files |
"text" | Text files |
"delimitedtext" | Delimited text files |
"fixedwidth" | Fixed-width text files |
"json" | JSON files |
"xml" | XML files |
"worddocument" | Microsoft Word documents |
"html" | HTML files |
Specify this name-value argument when filename does not include the file extension or
when its extension is not in this list:
.txt,.dat, or.csvfor text files.xls,.xlsb,.xlsm,.xlsx,.xltm,.xltx, or.odsfor spreadsheet files.jsonfor JSON files.xmlfor XML files.docxfor Microsoft Word documents.html,.xhtml, or.htmfor HTML files
Character encoding scheme associated with the file, specified as
"system" or a standard character encoding scheme
name. When you do not specify any encoding,
detectImportOptions uses automatic character set
detection to determine the encoding when reading the file.
Since R2022a
HTTP or HTTPS request options,
specified as a weboptions object. The
weboptions object determines how to import data
when the specified filename is an internet URL
containing the protocol type "http://" or
"https://".
Text Parsing
Field delimiter character, specified as a string array, character
vector, or cell array of character vectors. Specify
Delimiter as any valid character such as a comma
"," or a period ".".
This table lists some commonly used field delimiter characters.
Specifier | Field Delimiter |
|---|---|
| Comma |
| Space |
| Tab |
| Semicolon |
| Vertical bar |
| Unspecified | If you do not specify this name-value
argument, |
To treat multiple characters as a single delimiter, specify
Delimiter as a string array or cell array of
character vectors. If you want to treat an unknown number of consecutive
delimiters as one, specify
ConsecutiveDelimitersRule="join".
Delimiter is valid only with delimited text files
and is not valid with fixed-width text files.
End-of-line characters, specified as a string array, character vector,
or cell array of character vectors. Common end-of-line characters
include the newline character ("\n") and the carriage
return ("\r"). If you specify
"\r\n", then
detectImportOptions treats the combination of the
two (\r\n) as end-of-line characters. If you specify
{"\r\n", "\r", "\n"}, then \r,
\n, and \r\n are all treated
as end-of-line characters.
The default end-of-line sequence is \n,
\r, or \r\n, depending on the
contents of your file.
Characters to treat as white space, specified as a string scalar or character vector containing one or more characters.
This table shows how to represent special characters that you cannot enter using ordinary text.
Special Character | Representation |
|---|---|
Percent |
|
Backslash |
|
Alarm |
|
Backspace |
|
Form feed |
|
New line |
|
Carriage return |
|
Horizontal tab |
|
Vertical tab |
|
Character whose Unicode® numeric value can be represented by
the hexadecimal number,
|
|
Character whose Unicode numeric value can be represented by
the octal number,
|
|
Example: " _"
Example: "?!.,"
Comment indicators for text to ignore, specified as a string array, character vector, or cell array of character vectors.
For example, specify a character, such as "%", to
ignore text following that character on the same line. Specify a string
array, such as ["/*","*/"], to ignore any text
between sequences.
detectImportOptions checks for comments only at the
start of each line, not within lines.
Example: ["/*","*/"]
Rule for leading delimiters in a delimited text file, specified as one of the values in this table.
| Rule | Behavior |
|---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Display an error message and cancel the import operation. |
Rule for trailing delimiters in a delimited text file, specified as one of the values in this table.
| Rule | Behavior |
|---|---|
"keep" | Keep the delimiter. |
"ignore" | Ignore the delimiter. |
"error" | Display an error message and cancel the import operation. |
Rule for consecutive delimiters in a delimited text file, specified as one of the values in this table.
| Rule | Behavior |
|---|---|
"split" | Split the consecutive delimiters into multiple fields. |
"join" | Join the delimiters into one delimiter. |
"error" | Display an error message and cancel the import operation. |
Whether to treat multiple delimiters as one, specified as a numeric or
logical 1 (true) or
0 (false).
Field widths of variables in a fixed-width text file, specified as a vector of positive integers. Each integer corresponds to the number of characters in a field that make up the variable.
Example: [10,7,4,26,7]
JSON and XML Parsing
Since R2026a
How strictly to follow JSON standards while parsing, specified as one of these values:
"lenient"– The values ofAllowComments,AllowInfAndNaN, andAllowTrailingCommasare set totrue."strict"– The values ofAllowComments,AllowInfAndNaN, andAllowTrailingCommasare set tofalse.
Since R2026a
Allow comments in the input file, specified as one of these values:
Numeric or logical
1(true) – Comments do not cause an error during import. Comments in the file are not considered data and are not read into MATLAB. Comments can start with "//" for single-line comments or start with "/*" and end with "*/" for multi-line comments.Numeric or logical
0(false) – Comments cause an error during import.
Since R2026a
Read Inf and NaN values in the
input file, specified as one of these values:
Numeric or logical
1(true) –InfandNaNvalues (includingInfinity,-Inf, and-Infinity) are read into MATLAB.Numeric or logical
0(false) –InfandNaNvalues cause an error during import.
Since R2026a
Read trailing commas in the input file, specified as one of these values:
Numeric or logical
1(true) – Trailing commas after a JSON array or JSON object do not cause an error during import.Numeric or logical
0(false) – Trailing commas cause an error during import.
Rule for repeated JSON (since R2026a) or XML
nodes in a given row of a table, specified as one of the values in this
table. For JSON files, this rule applies when the
VariableSelectors name-value argument contains a
JSON Pointer that points to an array. The array entries are considered
repeated nodes.
Rule | Behavior |
|---|---|
"addcol" | Add columns for each repeated node in a
variable to create a matrix in the associated
variable. For example: Input XML data <table>
<row>
<Var1>1</Var1>
<Var2>2</Var2>
<Var3>3</Var3>
<Var1>11</Var1>
<Var1>111</Var1>
</row>
<row>
<Var1>4</Var1>
<Var2>5</Var2>
<Var3>6</Var3>
</row>
<row>
<Var1>7</Var1>
<Var2>8</Var2>
<Var3>9</Var3>
</row>
</table>Output table Var1 Var2 Var3
_______________ ____ ____
1 11 111 2 3
4 NaN NaN 5 6
7 NaN NaN 8 9 |
"ignore" | Skip the repeated nodes. |
"error" | Display an error message and cancel the import operation. |
Whether to import XML attributes as variables in the output table,
specified as a numeric or logical 1
(true) or 0
(false). By default,
detectImportOptions detects XML attributes as
variables in the output table.
Suffix used to distinguish attributes from elements in the output
table, specified as a string scalar or character vector. This argument
specifies the suffix detectImportOptions appends to
all table variables that correspond to attributes in the input XML file.
If you do not specify AttributeSuffix, then
detectImportOptions appends the suffix
"Attribute" to all variable names corresponding
to attributes in the input XML file.
Example: "_att"
Set of registered XML namespace prefixes, specified as an
N-by-2 string array of prefixes and their
associated URLs. detectImportOptions uses these
prefixes when evaluating XPath expressions on an XML file.
You can use RegisteredNamespaces when you also
evaluate an XPath expression specified by a selector name-value
argument, such as VariableSelectors.
By default, detectImportOptions automatically
detects namespace prefixes to use in XPath evaluation. To select an XML
node with an undeclared namespace prefix, register a custom namespace
URL for the namespace prefix using the
RegisteredNamespaces name-value argument. For
example, assign the prefix myprefix to the URL
https://www.mathworks.com in an XML file that
does not contain a namespace prefix.
T = detectImportOptions(filename,VariableSelectors="/myprefix:Data", ... RegisteredNamespaces=["myprefix","https://www.mathworks.com"])
Variable Metadata
Location of variable units, specified as a nonnegative integer.
If VariableUnitsLine is 0, then
detectImportOptions does not detect variable
units. Otherwise, detectImportOptions detects the
variable units from the specified line.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Location of variable units, specified as a string scalar, character vector, or positive integer in one of these forms.
Ways to Specify
VariableUnitsRange | Description |
|---|---|
Starting cell | Specify the starting cell for the variable units as a string scalar or character vector containing a column letter and row number, using A1 notation. From the starting cell,
Example:
|
Rectangular range | Specify the range using the form
The range must span only one row. Example:
|
Number index | Specify the row containing the variable units using a positive row index. Example:
|
Row range | Specify the range using the form
Variable units must be in a single row. Example:
|
Unspecified or empty | Indicate that there are no variable units. Example:
|
Data Types: string | char | single | double
Location of variable units, specified as a nonnegative integer.
If VariableUnitsRow is 0, then
detectImportOptions does not detect variable
units. Otherwise, detectImportOptions detects the
variable units from the specified row.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Variable units, specified as a string scalar or character vector. If
you do not specify this name-value argument,
detectImportOptions does not import variable
units.
JSON Files
(since R2026a)
Specify the variable units as a string scalar or character vector
containing a JSON Pointer. You must specify
VariableUnitsSelector as a valid RFC 6901
JSON Pointer. For more information, see the IETF
definition of JSON Pointer.
Example:
VariableUnitsSelector="/statuses/metadata/units"
XML Files
Specify the variable units as a string scalar or character vector
containing an XPath expression. You must specify
VariableUnitsSelector as a valid XPath
version 1.0 expression.
Example:
VariableUnitsSelector="/RootNode/ChildNode"
Example:
VariableUnitsSelector="//table[1]/units/"
Location of variable descriptions, specified as a nonnegative integer.
If VariableDescriptionsLine is
0, then detectImportOptions does
not detect variable descriptions. Otherwise,
detectImportOptions detects the variable
descriptions from the specified line.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Location of variable descriptions, specified as a string scalar, character vector, or positive integer in one of these forms.
Ways to Specify
VariableDescriptionsRange | Description |
|---|---|
Starting cell | Specify the starting cell for the variable descriptions as a string scalar or character vector containing a column letter and row number, using A1 notation. From the starting
cell, Example:
|
Rectangular range | Specify the range using the form
The range must span only one row. Example:
|
Row range | Specify the range using the form
Variable descriptions must be in a single row. Example:
|
Number index | Specify the row containing the descriptions using a positive row index. Example:
|
Unspecified or empty | Indicate that there are no variable descriptions. Example:
|
Data Types: string | char | single | double
Location of variable descriptions, specified as a nonnegative integer.
If VariableDescriptionsRow is 0,
then detectImportOptions does not detect variable
descriptions. Otherwise, detectImportOptions detects
the variable descriptions from the specified row.
Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64
Variable descriptions, specified as a string scalar or character
vector. If you do not specify this name-value argument,
detectImportOptions does not import variable
descriptions.
JSON Files
(since R2026a)
Specify the variable descriptions as a string scalar or character
vector containing a JSON Pointer. You must specify
VariableDescriptionsSelector as a valid RFC
6901 JSON Pointer. For more information, see the IETF
definition of JSON Pointer.
Example:
VariableDescriptionsSelector="/statuses/metadata"
XML Files
Specify the variable descriptions as a string scalar or character
vector containing an XPath expression. You must specify
VariableDescriptionsSelector as a valid XPath
version 1.0 expression.
Example:
VariableDescriptionsSelector="/RootNode/RowNode/@Name"
Example:
VariableDescriptionsSelector="//table[1]/descriptions/*"
Output Arguments
Import options for the specified file, returned as a
SpreadsheetImportOptions,
DelimitedTextImportOptions,
FixedWidthImportOptions,
JSONImportOptions, or
XMLImportOptions object. The type of options object
depends on the type of file specified.
For text files (
.txt,.dat, or.csv), the function returns aDelimitedTextImportOptionsorFixedWidthImportOptionsobject.For spreadsheet files (
.xls,.xlsb,.xlsm,.xlsx,.xltm,.xltx, or.ods), the function returns aSpreadsheetImportOptionsobject.For JSON files (
.json), the function returns aJSONImportOptionsobject.For XML files (
.xml), the function returns anXMLImportOptionsobject.
Tips
Updating Property Values After Creating the Import Options Object: Use of dot notation is not recommended to update the properties of the import options object created by
detectImportOptions. When you set properties using dot notation, MATLAB does not re-detect all the import options for the file. Therefore, to update and re-detect all the properties, you must specify the new values by using name-value arguments. For example, update the value for theConsecutiveDelimitersRuleproperty and re-detect the import options as follows.opts = detectImportOptions(__,'ConsecutiveDelimitersRule','join')
Use XPath selectors to specify which elements of the XML input document to import. For example, suppose you want to import the XML file
myFile.xml, which has the following structure:This table provides the XPath syntaxes that are supported for XPath selector name-value arguments, such as<data> <table category="ones"> <var>1</var> <var>2</var> </table> <table category="tens"> <var>10</var> <var>20</var> </table> </data>VariableSelectorsorTableSelector.Selection Operation Syntax Example Result Select every node whose name matches the node you want to select, regardless of its location in the document. Prefix the name with two forward slashes ( //).data = readtable('myFile.xml', 'VariableSelectors', '//var')
data = 4×1 table var ___ 1 2 10 20Read the value of an attribute belonging to an element node. Prefix the attribute with an at sign ( @).data = readtable('myFile.xml', 'VariableSelectors', '//table/@category')
data = 2×1 table categoryAttribute _________________ "ones" "tens"Select a specific node in a set of nodes. Provide the index of the node you want to select in square brackets ( []).data = readtable('myFile.xml', 'TableSelector', '//table[1]')
data = 2×1 table var ___ 1 2Specify precedence of operations. Add parentheses around the expression you want to evaluate first. data = readtable('myFile.xml', 'VariableSelectors', '//table/var[1]')
data = 2×1 table var ___ 1 10data = readtable('myFile.xml', 'VariableSelectors', '(//table/var)[1]')
data = table var ___ 1
Version History
Introduced in R2016bYou can detect import options for JSON files. Specify optional name-value
arguments to control the import behavior. For example, set
AllowComments to false if you want
comments in the input JSON file to cause an error during import.
You can read data from compressed and archived files as a table.
When importing data from spreadsheets, you can specify how
detectImportOptions imports cells that are merged across rows
and columns by using the MergedCellRowRule and
MergedCellColumnRule name-value arguments.
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)