Indexes

Indexes make equality lookups extremely fast. They are stored in a separate .idx.json file next to the collection.

Declaring Indexes

const users = db.collection({
  name: 'users',
  autoId: true,
  indexes: ['email', 'city', 'profile.username']  // nested fields supported
});

How Indexes Look on Disk

users.idx.json example:

{
  "email": {
    "alice@example.com": 0,
    "bob@example.com": 1
  },
  "city": {
    "Lagos": [0, 2, 5],
    "Abuja": 1
  }
}

Unique values are stored as a number (array index). Non-unique values become an array of indexes.

Why It Is Fast

Without an index the library must scan every document (O(n)). With an index, looking up a key in a JavaScript object is O(1). Even with hundreds of thousands of documents the lookup stays almost instant.

Automatic Maintenance

Indexes are automatically updated on every insert, update and delete. After deletions the indexes are rebuilt to keep array positions correct.