Your data
Indexes
An index keeps filters and sorts on a field fast as a collection grows; create, inspect and delete indexes from the console.
An index keeps the values of a field sorted, so a filter or a sort on that field goes straight to the documents it needs. Without an index, a filter reads every document in the collection. That is fine for a thousand documents and slow for a million.
Add an index on the fields your app filters or sorts by. For example, an index on email makes the search of a user by email fast, however many users you have.
What you get:
-
Fast reads on large collections. A filter or a sort on an indexed field stays fast as the collection grows.
-
No duplicates. A unique index refuses a second document with the same value.
-
Documents that expire. A TTL index deletes documents after a time.
Every collection has an index on _id already. The rest you add under Indexes.
Create an index
-
Open Indexes and expand the collection.
-
Click Add index and give it a name, such as
email-uniqueorcategory-price. -
Type the Keys: which fields, and
1for ascending,-1for descending, or"text"for full-text search. -
Add Options if you need them, and click Create index.
Both fields are JSON, checked as you type. Building an index on a collection that already has data takes a moment.
| Option | What it does |
|---|---|
|
Refuses a document whose value already exists in another. Fails with |
|
Indexes only documents that have the field. With |
|
Makes it a TTL index: a document is deleted that many seconds after the date in the indexed field. |
|
The index’s name. The console fills it from the Index name field. |
Each plan allows so many indexes on a collection, _id aside: 10 on Free, 20 on Starter, 30 on Pro. The one beyond the cap is refused with 403 and the reason; changing an index that exists is never refused.
The patterns that cover most apps
| Keys and options | Use it for |
|---|---|
|
A filter on one field, such as |
|
A filter on the first field and a sort on the second, such as |
|
No two documents with the same email. |
|
Unique when present, optional otherwise. |
|
Sessions, tokens, logs: gone when |
|
Keyword search with |
The examples use ?filter, which only a caller with allowFilter may send. Most apps query through an aggregation instead. An index works the same way there: it serves the $match and $sort stages that use its fields.
Change or delete an index
An index cannot be edited. To change one, delete it and create it again with the new definition. The Delete action asks for confirmation and is immediate; until you create a replacement, queries that used it scan the collection. The _id index cannot be deleted.
From a script
| Operation | API |
|---|---|
List |
|
Create |
|
Delete |
|
A 406 Not Acceptable on create means the definition was refused: duplicates under a unique index, or a name already used by a different index. The response says which.
Do it from the command line
You can keep your indexes in git and apply them with ulabase setup. The steps below add a unique index on the users' email and an index that expires sessions:
import { defineSetup, step } from '@ulabase/cli';
export default defineSetup('Indexes', [
// no two users with the same email
step('users email unique', {
check: ({ service }) => service.indexExists('users', 'email-unique'),
apply: ({ service }) =>
service.createIndex('users', 'email-unique', { email: 1 }, { unique: true }),
}),
// a session is deleted when its expiresAt date has passed
step('sessions expire', {
check: ({ service }) => service.indexExists('sessions', 'expires-at'),
apply: ({ service }) =>
service.createIndex('sessions', 'expires-at', { expiresAt: 1 }, { expireAfterSeconds: 0 }),
}),
]);
The check looks only at the name of the index. An index cannot be changed: to change its keys or options, create it with a new name and delete the old one with service.fetch('/users/_indexes/<name>', { method: 'DELETE' }).
Related pages
-
Collections and documents: the filters and sorts the indexes speed up.
-
Schemas: rules on one document. A unique index is a rule across documents.
-
Constraints: rules across the whole collection that an index cannot express.