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, path object, file-like object, or None, default None

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

orientstr

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

  • Series

    • 默认是 ‘index’

    • 允许的值为：{{‘split’, ‘records’, ‘index’, ‘table’}}。

  • DataFrame

    • 默认是 ‘columns’

    • 允许的值为：{{‘split’, ‘records’, ‘index’, ‘columns’, ‘values’, ‘table’}}。

  • JSON 字符串的格式

    • ‘split’ : dict 类型 {{‘index’ -> [index], ‘columns’ -> [columns], ‘data’ -> [values]}}

    • ‘records’ : list 类型 [{{column -> value}}, … , {{column -> value}}]

    • ‘index’ : dict 类型 {{index -> {{column -> value}}}}

    • ‘columns’ : dict 类型 {{column -> {{index -> value}}}}

    • ‘values’ : 仅值的数组

    • ‘table’ : dict 类型 {{‘schema’: {{schema}}, ‘data’: {{data}}}}

    描述数据，其中 data 部分类似于 orient='records'。

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

日期转换类型。“epoch”=epoch 毫秒，“iso”=ISO8601。默认值取决于 orient。对于 orient='table'，默认值为 ‘iso’。对于所有其他 orient，默认值为 ‘epoch’。

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

double_precisionint, 默认值 10

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

force_asciibool, 默认值 True

强制编码字符串为 ASCII。

date_unitstr, 默认值 ‘ms’ (毫秒)

编码时使用的时间单位，控制时间戳和 ISO8601 的精度。‘s’、‘ms’、‘us’、‘ns’ 分别表示秒、毫秒、微秒和纳秒。

default_handlercallable, 默认值 None

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

linesbool，默认 False

如果 ‘orient’ 是 ‘records’，则输出逐行分隔的 json 格式。如果 ‘orient’ 不正确，则会引发 ValueError，因为其他格式不是列表类型的。

compressionstr or dict, default ‘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}。

indexbool 或 None, 默认值 None

当 ‘orient’ 是 ‘split’、‘index’、‘column’ 或 ‘table’ 时，索引才会被使用。其中，‘index’ 和 ‘column’ 不支持 index=False。如果列名是字符串 ‘index’ 且具有空的 Index 或本身就是 ‘index’，则会引发 ValueError。

indentint, 可选

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

storage_optionsdict, optional

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

modestr, 默认值 ‘w’ (写入)

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

返回:
None or str

如果 path_or_buf 为 None，则返回生成的 json 格式作为字符串。否则返回 None。

另请参阅

read_json

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

注意

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

orient='table' 在 ‘schema’ 下包含一个 ‘pandas_version’ 字段。它存储了用于模式最新修订的 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 进行 DataFrame 的编码/解码

>>> 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 来编码/解码 Dataframe。

>>> 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 来编码/解码 Dataframe。

>>> 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"
        }}
    ]
}}
本页内容