Updated 28 September 2026

`cinderq` 0.9.3

A single static binary that reads the release files sitting next to it. It opens no sockets, writes nothing outside the current directory, and will refuse to run against a dataset whose checksum does not match its manifest.

MIT licence · one file, 4.1 MB · builds for Linux and macOS, x86-64 and arm64

Pointing it at the data

The tool looks for the dataset in three places, in order: the path in --data, then the CINDERCORE_DATA environment variable, then the working directory. A directory is valid if it holds a CSV, a JSONL and a matching schema-*.json from the same release.

$ tar xzf cindercore-1.6.0.tar.gz && cd cindercore-1.6.0
$ cinderq --version
cinderq 0.9.3 (dataset v1.6.0, 412 records, loaded in 23 ms)

$ export CINDERCORE_DATA=$HOME/data/cindercore-1.6.0
$ cinderq list --limit 3
CC-0012  fireclay 30% Al2O3    fireclay  1350 C
CC-0014  fireclay 36% Al2O3    fireclay  1400 C
CC-0031  fireclay, phosphate-bonded plastic  fireclay  1540 C
3 of 412 records

Subcommands

Command	What it does
list	Prints id, name, family and service temperature for every record. Respects `--limit` and `--sort`.
get <id>	Prints one record in full, every field, empty ones included.
filter	Selects records by family, temperature or an expression, and projects the fields you ask for.
stats	Minimum, median, maximum and count for one numeric field, optionally grouped.
diff <a> <b>	Compares two release directories field by field and prints what changed.
validate <file>	Checks a CSV or JSONL against the schema. This is what contributors run before sending anything.

Flags

Flag	Default	Meaning
--data <dir>	.	Where the release files live.
--family <name>	-	One of the eleven family values. Repeatable; repeats are an OR.
--min-temp <C>	-	Shorthand for `--where 'max_service_c>=C'`.
--where <expr>	-	One comparison on one field: `<`, `<=`, `=`, `>=`, `>`, `!=`. No boolean operators, deliberately.
--fields <a,b,c>	id,name,family,max_service_c	Which columns to print, in the order given.
--format <f>	table	`table`, `csv` or `json`.
--sort <field>	id	Prefix with a minus for descending. Empty values always sort last.
--limit <n>	0 (all)	Stops after n records.
--include-nulls	off	Keeps records whose filtered field is empty, and keeps empty cells in CSV output.
--explain	off	Adds a line per record naming the source ids and the confidence flag behind the values printed.

There is no query language beyond one comparison, and that is a design decision rather than a missing feature. Anything more complicated is better done by piping CSV into whatever you already use for tables.

Worked examples

One record, everything in it

$ cinderq get CC-0168
id                      CC-0168
name                    direct-bonded silicon carbide
family                  silicon-carbide
aliases                 SiC DB; recrystallised SiC brick
al2o3_pct               1.2
sio2_pct                2.4
mgo_pct                 -
cr2o3_pct               -
c_free_pct              0.0
max_service_c           1650
max_service_atmosphere  reducing
air_limit_c             1400
k_1000_w_mk             20.0
k_ref_c                 1000
k_method                hot-wire
bulk_density_g_cm3      2.72
open_porosity_pct       15.0
ccs_mpa                 110.0
hmor_mpa                -
rul_t05_c               -
thermal_shock_cycles    30
shock_protocol          water-quench-1000
slag_index              5
source_ids              S-007; S-022
confidence              high
updated                 2026-09-28

Note the two temperature fields disagreeing on purpose: 1 650 °C is the reducing-atmosphere limit, 1 400 °C is what the same source gives for air. A reader who takes only max_service_c will oversize the material by 250 °C.

Low conductivity at high temperature

$ cinderq filter --min-temp 1700 --where 'k_1000_w_mk<3' \
    --fields name,k_1000_w_mk,bulk_density_g_cm3,confidence --sort k_1000_w_mk
name                        k_1000_w_mk  bulk_density_g_cm3  confidence
zirconia, CaO-stabilised    2.00         4.90                medium
mullite-zirconia            2.20         2.80                high
dense castable, 90% Al2O3   2.40         3.00                high
chrome-corundum             2.60         3.40                high
4 records (3 suppressed: k_1000_w_mk empty, use --include-nulls)

The suppression line matters. Three records could have qualified and were dropped because nobody published their conductivity, which is a different statement from "they conduct more than 3 W/(m·K)".

Grouped statistics

$ cinderq stats --by family --field max_service_c
family             n    min   median  max
carbon-graphite    14   1500  1800    2000
chrome-bearing     22   1600  1700    1800
corundum           31   1700  1750    1800
fireclay           58   1250  1400    1540
high-alumina       96   1400  1600    1700
insulating         67   1000  1260    1760
magnesia           34   1600  1650    1700
magnesia-carbon    19   1650  1700    1700
silica             16   1600  1650    1700
silicon-carbide    27   1500  1600    1650
zirconia-bearing   28   1600  1700    1800
412 records in 11 groups

What changed between releases

$ cinderq diff ../cindercore-1.5.1 .
+ 23 records added (all family=high-alumina or insulating)
~ 9 records changed:
  CC-0090  k_method      (empty) -> hot-wire
  CC-0118  k_method      (empty) -> panel
  CC-0311  k_ref_c       1000 -> 400
  CC-0334  bulk_density_g_cm3  0.128 (unchanged, note rewritten)
  ...
- 0 records withdrawn
schema: 0 fields added, 0 removed, 1 constraint tightened

Checking your own file before sending it

$ cinderq validate my-additions.csv
my-additions.csv: 4 rows
  row 2: ok
  row 3: error  family 'alumina' is not in the family enumeration
  row 4: error  source_ids is empty; at least one id from sources.csv is required
  row 5: warn   k_1000_w_mk present without k_method (rejected since v1.6.0)
1 valid, 2 errors, 1 warning
$ echo $?
3

Exit codes

Code	Meaning
0	Command ran, at least one record matched.
2	Command ran, nothing matched. Useful in shell conditionals.
3	Validation failed, or the dataset does not satisfy its own schema.
4	Bad usage: unknown flag, malformed expression, unknown field name.
5	Dataset not found, unreadable, or checksum mismatch against the manifest.

Version 0.9.3 is pre-1.0 and the flag names may still move. The output of --format json is stable and is the thing to parse; the table format is for humans and gets realigned whenever a column grows.

Building it yourself

The source is one Rust crate with no dependencies outside the standard library and a CSV reader. A release build takes under a minute on a laptop:

$ git clone https://git.cindercore.dev/cinderq.git
$ cd cinderq && cargo build --release
$ ./target/release/cinderq --version

The test suite includes the whole published dataset as a fixture, so cargo test also tells you whether the data in your working copy is internally consistent. Problems with the tool itself go to tools@cindercore.dev; problems with the numbers go to data@cindercore.dev.