polars.LazyFrame.sink_ndjson

LazyFrame.sink_ndjson(
    path: str | Path | IO[bytes] | IO[str] | PartitionBy,
    *,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    maintain_order: bool = True,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    sync_on_close: SyncOnCloseMethod | None = None,
    mkdir: bool = False,
    lazy: bool = False,
    engine: EngineType = 'auto',
    optimizations: QueryOptFlags = (,
), ) → LazyFrame | None

Evaluate the query in streaming mode and write to an NDJSON file.

This allows streaming results that are larger than RAM to be written to disk.

engine:StreamingDistributed

Parameters:

path

File path to which the file should be written.

compression

What compression format to use.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

compression_level

The compression level to use, typically 0-9 or None to let the engine choose.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

check_extension

Whether to check if the filename matches the compression settings. Will raise an error if compression is set to ‘uncompressed’ and the filename ends in one of (“.gz”, “.zst”, “.zstd”) or if compression != ‘uncompressed’ and the file uses an mismatched extension. Only applies if file is a path.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

maintain_order

Maintain the order in which data is processed. Setting this to False will be slightly faster.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

storage_options

Options that indicate how to connect to a cloud provider.

The cloud providers currently supported are AWS, GCP, and Azure. See supported keys here:

• aws
• gcp
• azure
• Hugging Face (hf://): Accepts an API key under the token parameter: {'token': '...'}, or by setting the HF_TOKEN environment variable.

If storage_options is not provided, Polars will try to infer the information from environment variables.

credential_provider

Provide a function that can be called to provide cloud storage credentials. The function is expected to return a dictionary of credential keys along with an optional credential expiry time.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

retries

Number of retries if accessing a cloud instance fails.

Deprecated since version 1.37.1: Pass {“max_retries”: n} via storage_options instead.

sync_on_close: { None, ‘data’, ‘all’ }

Sync to disk when before closing a file.

• None does not sync.
• data syncs the file contents.
• all syncs the file contents and metadata.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

mkdir: bool

Recursively create all the directories in the path.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

lazy: bool

Wait to start execution until collect is called.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

engine

Select the engine used to process the query (default "auto"). A Engine instance may also be passed. Supported engine names are:

• "auto": use the engine set by Config.set_engine_affinity or the POLARS_ENGINE_AFFINITY environment variable, falling back to "streaming" if unset.
• "in-memory": use the in-memory engine before writing, this is the default engine.
• "streaming": use the streaming engine, which processes queries in batches, reducing memory pressure and often outperforming the in-memory engine. This will soon become the default engine of Polars.
• "gpu": use the CUDA GPU engine (requires an Nvidia GPU and cudf-polars). Pass a GPUEngine object for fine-grained control.

If the selected engine cannot run the query, Polars falls back to the streaming engine.

optimizations

The optimization passes done during query optimization.

This has no effect if lazy is set to True.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Returns:

DataFrame

See also

PartitionBy

Examples

>>> lf = pl.scan_csv("/path/to/my_larger_than_ram_file.csv")  
>>> lf.sink_ndjson("out.ndjson")  

Sink to a BytesIO object.

>>> import io
>>> buf = io.BytesIO()  
>>> pl.LazyFrame({"x": [1, 2, 1]}).sink_ndjson(buf)  

Split into a hive-partitioning style partition:

>>> pl.LazyFrame({"x": [1, 2, 1], "y": [3, 4, 5]}).sink_ndjson(
...     pl.PartitionBy("./out/", key="x"),
...     mkdir=True
... )