A blob is a large value: a file, a long text, an image. In a script it is an object with type and size. A blob that a job makes is stored only when the script emits or returns it.
blobs.make(contents, { type })a blob of text, bytes or data
blobs.file(path, { type })a blob of a file, read only when the blob is read
blobs.read(blob, { as, from, length })the contents, or a part of them
blobs.count(blob)the number of items
blobs.items(blob, { from, count })an iterator over the items, reading one at a time
Options:
typethe media type; default text/plain for text, application/octet-stream for bytes, application/json for data, and by its extension for a file
as"text", "bytes" or "json"; default "text"
fromthe first byte to read, or the number of items to skip; default 0
lengththe number of bytes to read; default to the end
countthe number of items; default all
A blob's items depend on its type.
text/csv, text/tab-separated-valuesthe rows after the header, each a map from the header's names
application/jsonthe entries of a list; any other value is one item
application/jsonlthe values, one on each line
any other text typethe lines
any other typenone
Sizes:
a blobany size
a result that is not a blobat most 64 MiB, held in memory: one read, or one item
a result with { as: "blob" }any size, written into the job's scratch directory as it arrives
fs.write, exec.run, compress and http read a blob a part at a time. Array.from(blobs.items(blob)) keeps every item in memory, so give it from and count. Skipping with from reads the skipped items, and blobs.count reads the whole blob.
Errors:
bad_inputan argument that is not a blob, a type with no items, contents that do not parse as the type, or a read or an item over 64 MiB
not_foundblobs.file: the file does not exist
not_permittedblobs.file: the operating system refuses the runner
Needs fs.read:path for the file that blobs.file reads, and nothing otherwise.
This script totals a column of a CSV file, one row at a time.
allow: [fs.read:/srv/reports/**]
const table = blobs.file("/srv/reports/2026/q3.csv", { type: "text/csv" })
let total = 0
for (const row of blobs.items(table)) total += Number(row.amount)
return total // gives 42This script makes a blob, counts its lines and returns it.
const report = blobs.make("line one\nline two\n", { type: "text/plain" })
blobs.count(report) // gives 2
Array.from(blobs.items(report, { from: 1 })) // gives ["line two"]
return { report }