Collections
Nitric Collections simplify storing and querying data in easily accessible documents.
Collections
A collection in a unique collection of unstructured data that is made up of many documents. Collections can most often be thought of as a category of related documents. E.g. countries
Documents
A document is a uniquely identifiable item within a collection. It can be thought of as a simple JSON
document. E.g. if countries
was a collection then usa
might be a document within that collection.
Sub-collections
A sub-collection is a collection that belongs to a single document. If we use usa
as a parent document example then states
might be a sub-collection that holds states within that country.
Create a collection
Declaring a collection for your application can be done in a single line of config-as-code using the nitric SDK:
import { collection } from '@nitric/sdk';const countries = collection('Countries').for('reading', 'writing', 'deleting');
Writing a document
You can create a new document by using an existing collection reference to create a new document reference, then setting a value for the document.
await countries.doc('USA').set({name: 'United States of America',population: 329500000,});
Reading a document
Just like with writing, you can read a document by using it's reference.
const doc = await countries.doc('USA').get();
Deleting a document
To delete a document that already exists, use the delete()
method on the document reference.
await countries.doc('USA').delete();
Querying a collection
Simple queries on collections are supported as well
const query = countries.query()// query string prefixes.where('name', 'startsWith', 'United')// query on equality.where('name', '==', 'United States of America')// query on inequality.where('name', '!=', 'Canada')// query on gt, lt, gte and lte as well.where('population', '>=', 100000000);
Results can be iterated either by paging or streaming
// Pagingconst results = await query.fetch();// Use the paging token in next query to fetch the next pageconst token = results.pagingToken;for (const doc of results.documents) {// Do something with your documentsconsole.log(doc.id);}// Streamingconst stream = query.stream();stream.on('data', (snapshot) => {// Get document snapshots});
Working with sub-collections
Working with a sub-collection is very similar to working with a collection
const states = countries.doc('USA').collection('States');// Get a reference to a document on the sub collectionconst stateOfColorado = states.doc('Colorado');
Nitric supports a single depth of sub-collection
Querying sub-collections
You can query same named sub-collections across all documents in a collection. For example query states from every country.
const allStates = countries.collection('States');const foundStates = allStates.query().stream();foundStates.on('data', (doc) => {// do something...});
This sub-collection reference is only queryable, since it's really an aggregate of all States
sub-collections across all Countries
documents. i.e. Query every state in every country.
What's next?
- Learn more about collections and documents in our reference docs.