Back to docs · Beta
When to use it
A document collection you want readable and writable over a stable HTTP contract, with filtering and paging applied by Firestore itself rather than after the fact.
What to grant
roles/datastore.user on the project, scoped to the database where possible.
Setup
1. Create a service account and grant it access
In the Google Cloud console, create a service account and grant it roles/datastore.user.
gcloud projects add-iam-policy-binding YOUR_PROJECT \
--member=serviceAccount:endpointos@YOUR_PROJECT.iam.gserviceaccount.com \
--role=roles/datastore.user2. Download the key file
Create a JSON key and download it. You paste the whole file, and it is encrypted at rest.
gcloud iam service-accounts keys create key.json \
--iam-account=endpointos@YOUR_PROJECT.iam.gserviceaccount.com3. Connect it in EndpointOS
Create a resource, choose Firestore, and enter the project id, the collection, and the key file. Leave the database id blank unless you use a non-default database.
What you will be asked for
- Google Cloud project id: The project that owns the Firestore database. Find it in the Google Cloud console header, next to the project name.
- Database id (optional): Optional. Leave blank for the default database, which is what most projects use.
- Collection: The top-level collection to expose. Documents are read by id from within it.
- Service account JSON, stored encrypted: Paste the whole key file, starting with '{'. The account needs roles/datastore.user on the project. Stored encrypted.
What the API supports for this source
Generated from the same declaration the API enforces on every request, so it cannot promise something a request would be rejected for.
| Filtering | equals, not equal, one of, greater than, greater or equal, less than, less or equal on any declared field |
|---|---|
| Sorting | Any field you declare. Not createdAt or updatedAt, which this source does not maintain |
| Search (q) | Not supported |
| Writes | create, update, delete |
| Paging | limit and offset |
| Record count | Approximate: the total reflects the page |
Worth knowing first
- Filtering runs as a Firestore structured query, so the database applies it rather than us filtering after reading. Equality, not-equal, one-of and the four comparisons are all supported.
- Firestore needs a composite index for some filter combinations. If a request fails asking for one, the error carries a console link that creates it.
- Filter values are type-sensitive: Firestore stores 42 and "42" as different values, so a field holding numbers must be declared as a number on the resource or filters will match nothing.
- Sorting works on your own fields. Be aware of a Firestore rule that surprises people: a document MISSING the field you sort by is left out of the results entirely, so sorting a collection where the field is optional returns fewer rows than not sorting. Without a sort, results are ordered by document id.
- createdAt and updatedAt are not sortable here, because Firestore does not maintain them. A request that tries is rejected rather than returning nothing.
- Record counts are not exact: Firestore does not report a total for a query without a separate aggregation call.
If something goes wrong
FAILED_PRECONDITION, with a request for an index
Why: Firestore needs a composite index for this combination of filters and ordering, and does not create one automatically.
Fix: Follow the console link in the error, which creates the index it wants. The request works once the index finishes building.
A filter returns nothing when you can see matching documents
Why: Firestore compares by type as well as value, so a number filter will not match a field stored as a string.
Fix: Declare the field with the type Firestore actually stores, then filter again.
Sorting returns fewer documents than not sorting
Why: Firestore leaves out any document that does not have the field being sorted by. This is Firestore behaviour, not a filter being applied.
Fix: Sort by a field every document has, or backfill the field on the documents missing it.
Cannot be sorted by createdAt
Why: Firestore does not maintain createdAt or updatedAt, so there is no such field to order by.
Fix: Sort by one of your own fields, or write your own timestamp into each document and sort by that.
Permission denied
Why: The service account lacks roles/datastore.user, or is scoped to a different database.
Fix: Grant roles/datastore.user, and set the database id if you are not using the default database.