write_ndjson: Write a dataset to CDISC Dataset-JSON NDJSON

In artoo: Lossless CDISC-Native Input and Output for Clinical Datasets

Write a dataset to CDISC Dataset-JSON NDJSON

Description

Serialize a data frame to the newline-delimited variant of CDISC Dataset-JSON v1.1 (.ndjson): line 1 carries the complete metadata block, every following line one row array. The streaming end of the artoo workflow (spec -> apply_spec -> write_ndjson) for datasets too large for the array-form .json file; a thin wrapper over write_dataset() with format = "ndjson".

Usage

write_ndjson(
  x,
  path,
  on_invalid = c("error", "translit", "fold", "replace", "ignore"),
  created = NULL,
  strict = FALSE
)

Arguments

x	The dataset to write. ⁠<data.frame>: required⁠. Typically the output of apply_spec(), carrying artoo_meta.
path	Destination .ndjson path. ⁠<character(1)>: required⁠. A .ndjson.gz path writes gzip-compressed bytes.
on_invalid	Policy for values that are not valid UTF-8. ⁠<character(1)>: default "error"⁠. One of "error" (abort with artoo_error_codec), "replace" (substitute ⁠?⁠ and warn with artoo_warning_encoding), "ignore" (drop the invalid bytes), or "translit" / "fold" (accepted for pipeline symmetry; behave as "error" here, since a byte-level invalidity has no character fold). See write_json() for when this fires.
created	Creation timestamp. ⁠<POSIXct(1)> | NULL⁠. NULL (default) stamps the current time into datasetJSONCreationDateTime; freeze it for byte-stable output.
strict	Suppress the ⁠_artoo⁠ extension block. ⁠<logical(1)>: default FALSE⁠. See write_json(): the same extension semantics apply to the metadata line.

Details

Bounded memory, both directions. The writer streams slabs of per-column JSON literals and read_ndjson() parses slab-sized line batches, so a multi-million-row dataset never materializes a whole rows array the way the .json codec must. A .ndjson.gz path gzips the stream transparently.

Value

The input x, invisibly, so a write can sit mid-pipeline.

See Also

read_ndjson() for the inverse; write_json() for the array-form file; write_dataset() for the generic dispatcher.

Examples

spec <- artoo_spec(cdisc_adam_datasets, cdisc_adam_variables, codelists = cdisc_codelists)

# ---- Example 1: write a conformed dataset as NDJSON ----
#
# apply_spec() attaches the metadata; write_ndjson() streams the metadata
# line and one row per line.
adsl <- apply_spec(cdisc_adsl, spec, "ADSL", conformance = "off")
path <- tempfile(fileext = ".ndjson")
write_ndjson(adsl, path)
readLines(path, n = 2)[2]

# ---- Example 2: gzip the stream via the file extension ----
#
# A .ndjson.gz path compresses transparently; read_ndjson() inflates it.
gz <- tempfile(fileext = ".ndjson.gz")
write_ndjson(adsl, gz)
nrow(read_ndjson(gz))

artoo documentation built on July 23, 2026, 1:08 a.m.