Knowledge Units (KU)

What is a Knowledge Unit?

A Knowledge Unit (KU) is the fundamental economic unit of RushDB. It represents a unit of structured knowledge created and maintained by RushDB from your raw data — during ingestion, modeling, or reasoning.

Raw data → RushDB → Structured Knowledge → KU

The more data you push and the richer its structure, the more knowledge RushDB creates, and the more KU are consumed.

Developer Mental Model

You never need to think about nodes, edges, CPU, RAM, or storage. You simply think:

More data → more knowledge → more KU

RushDB handles all the underlying storage and graph mechanics automatically. You pay only for the knowledge created and maintained on your behalf.

What Generates KU?

KU is generated by operations that create or maintain structured knowledge in RushDB:

Activity	Example
Ingesting records	db.records.create(), records.importJson()
Building relationships	db.records.attach()
Storing embeddings (number arrays)	Passing number[] arrays during ingestion
Compute-intensive operations	Vector similarity search, raw Cypher execution, multi-hop traversals
Maintaining stored knowledge	Ongoing footprint of stored records

Standard reads and queries (find, filter, paginate) never consume KU. Compute-intensive operations do because their cost scales with dataset size rather than the data written — running a semantic search across 10M records costs significantly more server compute than fetching a record by ID.

Note: The internal weights assigned to each operation type are not exposed. You interact only with your total KU consumption.

KU and Plan Limits

Each plan includes a monthly KU allowance:

Plan	Included KU / month
Free	100,000 KU
Pro	10,000,000 KU
Scale	Usage-based
Enterprise	Custom / platform license

When your workspace reaches its KU limit, write operations will be blocked until the next billing period or until you upgrade your plan.

How Nested JSON is Billed

When you ingest nested JSON, RushDB automatically decomposes it into separate linked records:

// Input: one nested object
{ "user": { "profile": { "name": "Alice", "age": 30 } } }

// RushDB creates:
// → Record: user     (0 own properties)
// → Record: profile  (2 properties: name, age)  → ~2 KU
// → Relationship: user → profile                → ~0.5 KU
// Total: ~2.5 KU

This means nesting does not multiply properties — it creates additional records and relationships, each billed independently.

Component	Cost
Each record created	weight per record
Each property stored on a record	weight per property
Each relationship formed between records	fractional weight (< 1×)

Note: Exact per-operation weights are not publicly exposed. You interact only with your total KU consumption.

KU Calculator

You can estimate your monthly KU consumption with this approximation:

estimated monthly KU
  ≈ records_per_day × 30 × (avg_properties + avg_child_records × relationship_weight)

Where:

• records_per_day — average number of top-level records ingested per day
• avg_properties — average number of scalar properties per record
• avg_child_records — average number of nested objects per record (each becomes a separate linked child record)
• relationship_weight — the fractional KU cost per relationship (less than 1×)

For a quick estimate, nesting depth maps approximately to a combined multiplier of 1.0 (flat) → 3.0 (deeply nested) on the base property count. This is an approximation — actual KU depends on the internal weighting of each operation type.

Storage Footprint

RushDB charges a small daily storage footprint KU for every record currently stored in your project. This covers the ongoing infrastructure cost of keeping your data queryable.

• Storage KU is calculated once per day, prorated against your monthly plan allowance.
• The charge is proportional to your current record count — fewer records, lower footprint.
• Deleting records reduces your ongoing footprint from the next daily cycle onward.
• KU consumed at creation time is never reversed by a later deletion.

Self-Hosted

When running RushDB in self-hosted mode (RUSHDB_SELF_HOSTED=true), KU tracking is disabled and no limits apply. Self-hosted deployments are fully unlimited.