pandas.DataFrame.to_json#

DataFrame.to_json(path_or_buf=None, *, orient=None, date_format=None, double_precision=10, force_ascii=True, date_unit='ms', default_handler=None, lines=False, compression='infer', index=None, indent=None, storage_options=None, mode='w')[源代码]#

将对象转换为 JSON 字符串。

注意 NaN 和 None 将被转换为 null，日期时间对象将被转换为 UNIX 时间戳。

参数:

path_or_bufstr, 路径对象, 类文件对象, 或 None, 默认 None

字符串、实现 os.PathLike[str] 的路径对象，或实现 write() 函数的类文件对象。如果为 None，结果将作为字符串返回。

orientstr

指示预期的 JSON 字符串格式。

系列：
- 默认是 ‘index’
- 允许的值是：{‘split’, ‘records’, ‘index’, ‘table’}。
DataFrame:
- 默认是 ‘columns’
- 允许的值是：{‘split’, ‘records’, ‘index’, ‘columns’, ‘values’, ‘table’}。
JSON 字符串的格式：
- ‘split’ : 像字典一样 {‘index’ -> [index], ‘columns’ -> [columns], ‘data’ -> [values]}
- ‘records’ : 列表形式 [{column -> value}, … , {column -> value}]
- ‘index’ : 类似字典 {index -> {column -> value}}
- ‘columns’ : 类似字典 {column -> {index -> value}}
- ‘values’ : 仅仅是值数组
- ‘table’ : 类似字典 {‘schema’: {schema}, ‘data’: {data}}
描述数据，其中数据组件类似于 orient='records'。

date_format{None, ‘epoch’, ‘iso’}

日期转换的类型。’epoch’ = 时间戳毫秒，’iso’ = ISO8601。默认值取决于 orient。对于 orient='table'，默认值是 ‘iso’。对于所有其他或方向，默认值是 ‘epoch’。

自 3.0.0 版本弃用: ‘epoch’ 日期格式已被弃用，并将在未来版本中移除，请改用 ‘iso’ 格式。

double_precisionint, 默认 10

编码浮点值时要使用的十进制位数。可能的最大值是15。传递大于15的double_precision将引发ValueError。

force_ascii布尔值, 默认为 True

强制编码字符串为 ASCII。

date_unitstr, 默认 ‘ms’ (毫秒)

编码的时间单位，控制时间戳和ISO8601的精度。可以是’s’, ‘ms’, ‘us’, ‘ns’之一，分别代表秒、毫秒、微秒和纳秒。

default_handler可调用，默认为 None

如果对象无法转换为适合JSON的格式，则调用的处理程序。应接收一个参数，即要转换的对象，并返回一个可序列化的对象。

行布尔值, 默认为 False

如果 ‘orient’ 是 ‘records’，则写出以行分隔的 json 格式。如果 ‘orient’ 不正确，则会抛出 ValueError，因为其他格式不是类列表的。

压缩str 或 dict，默认 ‘infer’

用于实时压缩输出数据。如果 ‘infer’ 并且 ‘path_or_buf’ 是类路径，则从以下扩展名检测压缩：’.gz’, ‘.bz2’, ‘.zip’, ‘.xz’, ‘.zst’, ‘.tar’, ‘.tar.gz’, ‘.tar.xz’ 或 ‘.tar.bz2’（否则不压缩）。设置为 None 表示不压缩。也可以是一个字典，键 'method' 设置为 {'zip', 'gzip', 'bz2', 'zstd', 'xz', 'tar'} 之一，其他键值对将转发给 zipfile.ZipFile, gzip.GzipFile, bz2.BZ2File, zstandard.ZstdCompressor, lzma.LZMAFile 或 tarfile.TarFile，分别。例如，以下内容可以传递以实现更快的压缩并创建可复现的 gzip 存档：compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}。

Added in version 1.5.0: 增加了对 .tar 文件的支持。

在 1.4.0 版本发生变更: Zstandard 支持。

索引布尔值或无，默认无

索引仅在 ‘orient’ 为 ‘split’、’index’、’column’ 或 ‘table’ 时使用。其中，’index’ 和 ‘column’ 不支持 index=False。如果列名为字符串 ‘index’ 且 Index 为空，或者如果它是 ‘index’，将引发 ValueError。

缩进int, 可选

用于缩进每个记录的空白长度。

storage_optionsdict, 可选

对于特定的存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于HTTP(S) URL，键值对会作为头选项转发到 urllib.request.Request。对于其他URL（例如以“s3://”和“gcs://”开头），键值对会转发到 fsspec.open。请参阅 fsspec 和 urllib 获取更多详情，关于存储选项的更多示例请参考这里。

模式str, 默认 ‘w’ (写入)

在提供 path_or_buf 时指定输出模式。接受的参数仅为 ‘w’（写入）和 ‘a’（追加）。mode=’a’ 仅在 lines 为 True 且 orient 为 ‘records’ 时支持。

返回:

None 或 str: 如果 path_or_buf 是 None，则返回生成的 json 格式字符串。否则返回 None。

参见

read_json: 将 JSON 字符串转换为 pandas 对象。

备注

indent=0 的行为与标准库不同，标准库不会缩进输出，但会插入换行符。目前，indent=0 和默认的 indent=None 在 pandas 中是等效的，尽管这可能会在未来的版本中发生变化。

orient='table' 在 ‘schema’ 下包含一个 ‘pandas_version’ 字段。这存储了在最新修订的 schema 中使用的 pandas 版本。

例子

>>> from json import loads, dumps
>>> df = pd.DataFrame(
...     [["a", "b"], ["c", "d"]],
...     index=["row 1", "row 2"],
...     columns=["col 1", "col 2"],
... )

>>> result = df.to_json(orient="split")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
{
    "columns": [
        "col 1",
        "col 2"
    ],
    "index": [
        "row 1",
        "row 2"
    ],
    "data": [
        [
            "a",
            "b"
        ],
        [
            "c",
            "d"
        ]
    ]
}

使用 'records' 格式化的 JSON 编码/解码一个数据帧。请注意，使用此编码时索引标签不会保留。

>>> result = df.to_json(orient="records")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
[
    {
        "col 1": "a",
        "col 2": "b"
    },
    {
        "col 1": "c",
        "col 2": "d"
    }
]

使用 'index' 格式化的 JSON 编码/解码一个数据框：

>>> result = df.to_json(orient="index")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
{
    "row 1": {
        "col 1": "a",
        "col 2": "b"
    },
    "row 2": {
        "col 1": "c",
        "col 2": "d"
    }
}

使用 'columns' 格式化 JSON 编码/解码一个数据框：

>>> result = df.to_json(orient="columns")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
{
    "col 1": {
        "row 1": "a",
        "row 2": "c"
    },
    "col 2": {
        "row 1": "b",
        "row 2": "d"
    }
}

使用 'values' 格式化 JSON 编码/解码一个数据框：

>>> result = df.to_json(orient="values")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
[
    [
        "a",
        "b"
    ],
    [
        "c",
        "d"
    ]
]

使用表模式进行编码：

>>> result = df.to_json(orient="table")
>>> parsed = loads(result)
>>> dumps(parsed, indent=4)  
{
    "schema": {
        "fields": [
            {
                "name": "index",
                "type": "string"
            },
            {
                "name": "col 1",
                "type": "string"
            },
            {
                "name": "col 2",
                "type": "string"
            }
        ],
        "primaryKey": [
            "index"
        ],
        "pandas_version": "1.4.0"
    },
    "data": [
        {
            "index": "row 1",
            "col 1": "a",
            "col 2": "b"
        },
        {
            "index": "row 2",
            "col 1": "c",
            "col 2": "d"
        }
    ]
}