Build row records
A web API expects one JSON object per row.
Pandas · Module
df.to_dict
Converts a DataFrame into a dictionary-like structure whose shape is selected with orient. It can also use a custom mapping class and optionally omit index metadata for split or tight output.
- Since
- 2.0.0
How it works
Call to_dict with an orientation that matches the structure your consumer expects. The default nests values by column and then index; alternatives produce lists, Series, split or tight metadata structures, row records, or index-keyed mappings. into controls the mapping type, while index controls index metadata for split and tight output.
Syntax
DataFrame.to_dict(*orient='dict', ***, *into=<class 'dict'>*, *index=True*)Parameters
| Name | Type | Description |
|---|---|---|
orient | str | Output orientation: dict, list, series, split, tight, records, or index. |
into | class | Mapping subclass used for mappings in the returned value; defaults to dict. |
index | bool | Whether to include the index, and index names for tight; may be False only for split or tight. |
Returns
A dict, list, or collections.abc.MutableMapping representation of the DataFrame; its form depends on orient.
Key points
orientselects the output structure, including nested mappings, lists, Series, records, or index-keyed values.orient="list"maps every column to its sequence of values.orient="series"maps each column name to a pandas Series.orient="split"separates index labels, column labels, and data into distinct entries.orient="tight"provides split-style data plus index-name and column-name metadata.orient="records"produces one column-to-value mapping per row.orient="index"uses each index label as an outer key and nests column values beneath it.
Common mistakes
- The
indexargument cannot be disabled for orientations other thansplitandtight. - Changing
orientchanges both the shape and type of the returned representation, so consumers must handle the selected format.
Example: Convert rows to dictionaries
import pandas as pd
df = pd.DataFrame(
{"name": ["Ada", "Linus"], "score": [98, 95]},
index=["a", "b"],
)
rows = df.to_dict(orient="records")
print(rows)Converts each row into a dictionary keyed by column name.
When to use it
Export columns as lists
A consumer needs column arrays without nested index mappings.
Create split or tight structures
A format must retain labels and their names separately from values.
Customize the mapping type
A mapping implementation such as an ordered or specialized dictionary is required.
Interview questions
QWhat does DataFrame.to_dict do, and what is its default orientation?
to_dict converts a DataFrame into a dictionary-like representation, and orient determines the shape. The default dict orientation maps each column to an inner mapping from index to value.
Follow-up: How would you serialize rows for an API? Use orient="records", which returns a list-like sequence of dictionaries where each dictionary maps column names to row values.
QHow do records and index differ?
Use orient="records" for row-oriented dictionaries, or orient="index" when the index should be the outer key. The former is list-like, while the latter is index-keyed and contains column-to-value mappings.
Follow-up: Which orientation preserves column and index arrays separately? split does so with index, columns, and data; tight additionally includes index and column names.
QWhat do the into and index parameters control?
into specifies the mapping class used for mappings in the result, defaulting to dict. index controls whether index information is included, and it can be False only with split or tight.
Follow-up: What happens with orient="tight" and the default index=True? The result includes index, columns, data, index names, and column names.
Related
DataFrame.from_dictDataFrame.to_jsonDataFrame.to_records