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')[source]

Преобразовать объект в JSON-строку.

Обратите внимание, что NaN и None будут преобразованы в null, а объекты datetime будут преобразованы в метки времени UNIX.

Parameters:

path_or_buf:str, path object, file-like object, or None, default None

Строка, объект пути (реализующий os.PathLike[str]) или файл-подобный объект, реализующий функцию write(). Если None, результат возвращается в виде строки.

orient:str

Указание ожидаемого формата 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’ : список подобный [{column -> value}, … , {column -> value}]

  • ‘index’ : dict подобный {index -> {column -> value}}

  • ‘columns’ : dict подобный {column -> {index -> value}}

  • ‘values’ : только массив значений

  • ‘table’ : dict подобный {‘schema’: {схема}, ‘data’: {данные}}

  Описание данных, где компонент данных подобен orient='records'.

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

Тип преобразования даты. ‘epoch’ = метки времени в миллисекундах, ‘iso’ = ISO8601. Значение по умолчанию зависит от orient. Для orient='table', значение по умолчанию — ‘iso’. Для всех других ориентаций значение по умолчанию — ‘epoch’.

double_precision:int, default 10

Количество десятичных знаков, используемых при кодировании чисел с плавающей запятой. Максимальное возможное значение равно 15. Передача double_precision больше 15 приведет к ошибке ValueError.

force_ascii:bool, default True

Принудительно кодировать строку в ASCII.

date_unit:str, default ‘ms’ (milliseconds)

Единица измерения времени для кодирования, управляет точностью временных меток и ISO8601. Одно из значений: ‘s’, ‘ms’, ‘us’, ‘ns’ для секунды, миллисекунды, микросекунды и наносекунды соответственно.

default_handler:callable, default None

Обработчик, вызываемый, если объект не может быть преобразован в подходящий для JSON формат. Должен принять один аргумент, который является объектом для преобразования, и вернуть сериализуемый объект.

lines:bool, default False

Если ‘orient’ равен ‘records’, записывать данные в формате JSON с разделителями строк. Вызовет ValueError, если неверный ‘orient’, поскольку другие не являются спископодобными.

compression:str or dict, default ‘infer’

Для сжатия выходных данных «на лету». Если ‘infer’ и ‘path_or_buf’ имеет тип path, тогда определить сжатие по следующим расширениям: ‘.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}.

New in version 1.5.0: Добавлена поддержка файлов .tar.

Изменено в версии 1.4.0: Поддержка Zstandard.

index:bool or None, default None

Индекс используется только при ‘orient’ равном ‘split’, ‘index’, ‘column’ или ‘table’. Из этих значений ‘index’ и ‘column’ не поддерживают index=False.

indent:int, optional

Длина отступа, используемого для индексирования каждой записи.

storage_options:dict, optional

Дополнительные параметры, подходящие для конкретного подключения к хранилищу, например, хост, порт, имя пользователя, пароль и т.д. Для HTTP(S) URL-адресов пары ключ-значение передаются в urllib.request.Request в качестве параметров заголовка. Для других URL-адресов (например, начинающихся с «s3://» и «gcs://») пары ключ-значение передаются в fsspec.open. Подробнее см. fsspec и urllib, и больше примеров опций хранения можно найти здесь.

mode:str, default ‘w’ (writing)

Укажите режим ввода/вывода для вывода при передаче path_or_buf. Допустимые значения — только ‘w’ (запись) и ‘a’ (добавление). mode=’a’ поддерживается только тогда, когда lines равно True, а orient равно ‘records’.

Returns:

None or str

Если path_or_buf равен None, возвращает результирующий JSON-формат в виде строки. В противном случае возвращает None.

См. также

read_json

Преобразование JSON-строки в объект pandas.

Примечания

Поведение indent=0 отличается от поведения stdlib, которое не отступает вывод, но вставляет новые строки. В настоящее время indent=0 и значение по умолчанию indent=None в pandas эквивалентны, хотя это может измениться в будущей версии.

orient='table' содержит поле ‘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"
        ]
    ]
}

Кодирование/декодирование DataFrame с использованием JSON-формата 'records'. Обратите внимание, что метки индекса не сохраняются при этом кодировании.

>>> 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"
    }
]

Кодирование/декодирование DataFrame с использованием JSON-формата 'index':

>>> 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"
    }
}

Кодирование/декодирование DataFrame с использованием JSON-формата 'columns':

>>> 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"
    }
}

Кодирование/декодирование DataFrame с использованием JSON-формата 'values':

>>> 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"
        }
    ]
}