FAQ

FAQ

What is JAZMIN, in one sentence?

A file format for lists of records that is small, fast to search without loading, optionally encrypted, and shareable in parts, with libraries for JavaScript/TypeScript, .NET and browsers.

Is it free?

Yes. The libraries, viewer and specification are open source under the MIT license.

Is it a database?

No. A JAZMIN file is written, then read many times, like an export or an archive. It can be changed cheaply (append) and queried with indexes, but it has one writer at a time and no transactions across files. Use it for exports, archives, caches, hand-overs and data you query; keep a database for data many people change at once.

How is it different from JSON with gzip?

Gzipped JSON is small, but to find one record you must decompress and parse all of it. JAZMIN is smaller still (61% smaller than gzipped JSON on the benchmark data), finds a record by reading one chunk (1.4–1.7 ms instead of 100–265 ms for 200,000 records), is typed (exact decimals, real dates), and can be encrypted and shared in parts. See Why JAZMIN.

How is it different from Parquet, Avro or SQLite?

• Parquet is also columnar and compressed, built for analytics engines aggregating huge columns. JAZMIN is built for applications: record lookups, filters, paging, per-person encryption and access, embedded documents, and a JSON-like API in JavaScript and .NET with no dependencies.
• Avro is row-based, for messages and streams; it has no indexes or per-chunk statistics.
• SQLite is a database: great for many small changes, but its files aren't compressed or encrypted without extensions, and one file can't give different people different parts of it.

Can other languages read JAZMIN files?

The libraries cover Node.js, .NET and browsers today. The format is fully specified (an RFC-style draft and a Protocol Buffers schema, see Format Overview) and uses only standard algorithms (Deflate, AES-GCM, HKDF, PBKDF2, ECDSA), so a reader in another language is a well-defined job. Meanwhile, toJSON / toCSV and the CLI convert files for any tool.

How do I look inside a file?

• jazmin inspect file.jzm and jazmin query file.jzm --limit 10 (Command-Line Tool);
• the viewer, in any browser;
• toJSON(open('file.jzm')) in code.

Does the viewer upload my data?

No. The file is read on your device, in the browser; nothing is sent anywhere. Only the parts needed are read from disk.

Is it safe to email a .jzm file?

If it's encrypted, the content is protected: without the key it shows only its size and that it's encrypted. Send the key by a different channel (or not at all: give people access keys through your app). For files that must stop opening after a date, use online keys.

What if I lose the key?

The data can't be recovered. There's no back door. Keep keys in a secret manager, and back them up as you back up the data.

How big can a file be?

Item	Limit
Rows per file	2^53 in JavaScript, 2^63 in .NET
One section (a chunk, an index page, the header)	4 GiB
Integers	64-bit signed (JavaScript returns bigint beyond ±2^53)
Dates	Millisecond precision; .NET supports years 1–9999

Beyond these, the format sets no file-size limit (offsets are 64-bit), and size barely affects speed: writing and reading stream with one chunk in memory, and opening reads only the catalog. The largest published benchmark is 1,000,000 rows × 300 columns (643 MB; 6.3 GB as JSON).

Can several programs read the same file at once?

Yes, any number of readers, in any number of processes. Within a program, use one reader per thread (readers aren't thread-safe; opening is cheap).

Can several programs write at once?

One at a time. append, update and compact take a lock file; a second writer gets a clear error. Readers keep reading the version they opened while a writer works, on Windows too.

Can I change a file?

Yes: insert, upsert and delete rows, change metadata, add or remove embedded files and grants, with update() (a rewrite, atomic) or append() (cost proportional to the change). See Updating, Appending and Compacting.

Does it handle nested data?

Yes, three ways: json columns hold any nested value; several tables hold related records without repeating them; and export shapes turn flat rows into nested JSON or XML on the way out.

Why do decimals come back as strings in JavaScript?

A JavaScript number can't hold every decimal exactly (0.1 + 0.2 !== 0.3). JAZMIN keeps them exact and returns text such as '1520.75'. In .NET they map to decimal. Filters compare decimals by value ('12.5' equals '12.50').

Why are my dates in UTC?

Dates are stored as instants, in UTC, with millisecond precision, so every reader agrees on them. Show them in the reader's time zone when you display them.

Does it work on phones and offline?

Yes. The viewer installs as an app and works offline; the browser module reads and writes files on the device. Field apps can capture records offline and send them back later.

Which version should I use?

The latest, 1.2. Every 1.x release writes the same file format, and 1.0 and 1.1 read 1.2's files unless you turn on compact indexes. See Versions and Compatibility.

Where do I report a bug or ask for a feature?

Bugs and features: the repository's issues. Security problems: privately, as described in Security Model.