St. Nebula
83 lines
3.3 KiB
Markdown
83 lines
3.3 KiB
Markdown
# Firestore Indexes Reference
|
|
|
|
Indexes allow Firestore to ensure that query performance depends on the size of the result set, not the size of the database.
|
|
|
|
## Index Types
|
|
|
|
### Single-Field Indexes
|
|
In Standard Edition, Firestore **automatically creates** a single-field index for every field in a document (and subfields in maps).
|
|
* **Support**: Simple equality queries (`==`) and single-field range/sort queries (`<`, `<=`, `orderBy`).
|
|
* **Behavior**: You generally don't need to manage these unless you want to *exempt* a field.
|
|
|
|
### Composite Indexes
|
|
A composite index stores a sorted mapping of all documents based on an ordered list of fields.
|
|
* **Support**: Complex queries that filter or sort by **multiple fields**.
|
|
* **Creation**: These are **NOT** automatically created. You must define them manually or via the console/CLI.
|
|
|
|
## Automatic vs. Manual Management
|
|
|
|
### What is Automatic?
|
|
* Indexes for simple queries.
|
|
* Merging of single-field indexes for multiple equality filters (e.g., `where("state", "==", "CA").where("country", "==", "USA")`).
|
|
|
|
### When Do I Need to Act?
|
|
If you attempt a query that requires a composite index, the SDK will throw an error containing a **direct link** to the Firebase Console to create that specific index.
|
|
|
|
**Example Error:**
|
|
> "The query requires an index. You can create it here: https://console.firebase.google.com/project/..."
|
|
|
|
## Query Support Examples
|
|
|
|
| Query Type | Index Required |
|
|
| :--- | :--- |
|
|
| **Simple Equality**<br>`where("a", "==", 1)` | Automatic (Single-Field) |
|
|
| **Simple Range/Sort**<br>`where("a", ">", 1).orderBy("a")` | Automatic (Single-Field) |
|
|
| **Multiple Equality**<br>`where("a", "==", 1).where("b", "==", 2)` | Automatic (Merged Single-Field) |
|
|
| **Equality + Range/Sort**<br>`where("a", "==", 1).where("b", ">", 2)` | **Composite Index** |
|
|
| **Multiple Ranges**<br>`where("a", ">", 1).where("b", ">", 2)` | **Composite Index** (and technically limited query support) |
|
|
| **Array Contains + Equality**<br>`where("tags", "array-contains", "news").where("active", "==", true)` | **Composite Index** |
|
|
|
|
## Best Practices & Exemptions
|
|
|
|
You can **exempt** fields from automatic indexing to save storage or strictly enforce write limits.
|
|
|
|
### 1. High Write Rates (Sequential Values)
|
|
* **Problem**: Indexing fields that increase sequentially (like `timestamp`) limits the write rate to ~500 writes/second per collection.
|
|
* **Solution**: If you don't query on this field, **exempt** it from simple indexing.
|
|
|
|
### 2. Large String/Map/Array Fields
|
|
* **Problem**: Indexing limits (40k entries per doc). Indexing large blobs wastes storage.
|
|
* **Solution**: Exempt large text blobs or huge arrays if they aren't used for filtering.
|
|
|
|
### 3. TTL Fields
|
|
* **Problem**: TTL (Time-To-Live) deletion can cause index churn.
|
|
* **Solution**: Exempt the TTL timestamp field from indexing if you don't query it.
|
|
|
|
## Management
|
|
|
|
### Config files
|
|
Your indexes should be defined in `firestore.indexes.json` (pointed to by `firebase.json`).
|
|
|
|
```json
|
|
{
|
|
"indexes": [
|
|
{
|
|
"collectionGroup": "cities",
|
|
"queryScope": "COLLECTION",
|
|
"fields": [
|
|
{ "fieldPath": "country", "order": "ASCENDING" },
|
|
{ "fieldPath": "population", "order": "DESCENDING" }
|
|
]
|
|
}
|
|
],
|
|
"fieldOverrides": []
|
|
}
|
|
```
|
|
|
|
### CLI Commands
|
|
|
|
Deploy indexes only:
|
|
```bash
|
|
npx -y firebase-tools@latest deploy --only firestore:indexes
|
|
```
|