AirStat CLI

Command-line tool for AirMettle's AirStat service on Azure. Generate AirTree histograms and run queries against data stored in your own Azure Blob Storage.

Installation

pip install airstat

Quick Start

1. Authenticate once with your Microsoft account (organizational or personal).
2. Create two small JSON configuration files.
3. Run the generate command.

1. Authenticate

airstat auth login

This starts a device-code flow. Follow the instructions in your terminal (you'll be asked to open a browser and enter a short code). Your token is cached locally so you only need to do this occasionally.

Other useful auth commands:

airstat auth status     # Show who you're logged in as
airstat auth logout     # Clear cached credentials

2. Create Configuration Files

You need two files:

profile.json – Your storage account and target service

{
  "bucket_props": {
    "account_name": "yourstorageaccount",
    "account_key": "YOUR_STORAGE_ACCOUNT_KEY",
    "container": "your-container",
    "object": "your-input-file.bin"
  }
}

• bucket_props: Location of your input data in Azure Blob Storage. • airstat_url (optional): The CLI talks to AirMettle's AirStat service by default. Set this only to target a different AirStat deployment.

airstat.json – The AirTree request you want to run

{
  "airtree": {
    "config": "1DxT",
    "schema": {
      "id": "binary",
      "dtype": "double"
    }
  }
}

See the samples/ directory in the source repository for more complete examples (including 2D/3D/4D configs).

3. Run a Generate Operation

airstat generate -p profile.json -a airstat.json

The CLI will:

• Use your cached Microsoft token
• Send the request to the configured Airstat service (protected by Azure Easy Auth)
• Return the result

How Authentication Works

The CLI uses Microsoft Authentication Library (MSAL) with the device code flow. You authenticate interactively once. The resulting access token is sent as a Bearer token to the Airstat service.

No secrets are required on your machine beyond the one-time interactive login.

Configuration Files

---

File	Purpose	Required for
profile.json	Storage account + optional Airstat URL	All commands
airstat.json	The actual AirTree request (config + schema)	generate, query

Examples

The samples/ folder contains ready-to-use airstat.json request bodies. Each file holds only the airtree payload — pair it with your own profile.json (storage account, plus optional service URL override) via -p and -a.

Generate (/api/v1/generate)

Sample file	Config	Input schema	Notes
airstat.json	1DxT	binary (double)	Minimal 1D example
1DxT_generate.json	1DxT	binary (double)	13-bit, most compact
1DxF_generate.json	1DxF	binary (double)	16-bit, fastest
1DxP_generate.json	1DxP	binary (double)	20-bit, highest precision
2DxP_generate.json	2DxP	Parquet (PAR1)	2 columns
2DxF_generate.json	2DxF	Parquet (PAR1)	2 columns
3DxP_generate.json	3DxP	Parquet (PAR1)	3 columns
3DxF_generate.json	3DxF	Parquet (PAR1)	3 columns
4DxP_generate.json	4DxP	Parquet (PAR1)	4 columns
4DxF_generate.json	4DxF	Parquet (PAR1)	4 columns
4DxPc_generate.json	4DxPc	Parquet (PAR1)	4 columns

1D configs require a raw binary blob; set bucket_props.object in profile.json to your .bin file. Supported binary dtypes: double, float, int32, int64.

2D–4D configs require a Parquet file; set dimInfo.colName to match your column names.

airstat generate -p profile.json -a samples/1DxT_generate.json
airstat generate -p profile.json -a samples/2DxP_generate.json

Query (/api/v1/query)

Query samples target an existing histogram in blob storage (the output of a prior generate). Point bucket_props.object in profile.json at that .airtree file.

Sample file	Query type	Typical histogram
minvalue_query.json	minvalue	1D
maxvalue_query.json	maxvalue	1D
mincount_query.json	mincount	1D
maxcount_query.json	maxcount	1D
topk_query.json	topk	1D
percentile_query.json	percentile	1D
cdf_query.json	cdf	1D
box_query.json	box	2D
grid_query.json	grid	2D

airstat query -p profile.json -a samples/minvalue_query.json 
airstat query -p profile.json -a samples/grid_query.json

Notes

• The package is built with the required Entra client ID pre-bundled. You do not need to set any environment variables.
• All network calls to the Airstat service are authenticated with your Microsoft identity.

License

MIT — see the LICENSE file. Use of the AirStat services themselves is governed by your service agreement (e.g., via the Microsoft commercial marketplace).