Data modeling

We know it’s unlikely that our pilots would carry more than a dozen weapons. On the other hand, imagine we wanted to model galaxies, stars, planets, etc, for a SpaceMaps app. Since each galaxy can have billions of stars, this might not be a great idea:

If you attempted to list all of the stars in the Milky Way like that, your galaxy document would become huge.

Documents can be, at most, 8 MB in size. Smaller documents are better, as they consume fewer read operations and are faster to read and write. See Limits for more details.

The nesting pattern is not a great fit for use cases where the data either could grow indefinitely, or is unbound.

For example, in SpaceAdvisor, our app for reviewing space hotels and restaurants, we definitely do not want to store reviews inside the properties documents:

Again, one problem here is that documents could potentially become huge and we don’t want that. Additionally, accessing heavily nested data often requires more coding, so it should only be done in the context of your access patterns, as we’ll discuss in the next few sections.

Another important consideration, before nesting entities in a single document, is knowing in advance what access patterns that we are going to need on those entities. This is critical in document-based databases as your design is usually coupled to your access patterns.

For example, you might think that it would be okay to store the planets and their moons together in our SpaceMaps app.

You might assume that this pattern is perfect for this use case. After all, it’s unlikely that a planet would have more than, say, a couple hundred moons in some extreme cases and this number would practically never change.

But what if at some point we wanted to list and sort all the moons in our SpaceMaps app? This nesting pattern wouldn’t be appropriate for this use case as we wouldn’t be able to index and query the moons properly.

Finally, even if your use case perfectly fits the nesting pattern, you have to consider how often you are going to update that document. The more frequently you update a document, the less efficient this pattern becomes.

Obviously, we can also use the Reference type to reference other documents. To demonstrate this, let’s revisit our SpaceMaps app.

We already have a Planets collection from a previous part of this tutorial. For reference, here’s the document for Earth:

Now, let’s create a Moons collection:

And let’s create a moon document with a reference to a planet document:

We just created a one-to-many relationship since it is possible for many moons to share the same planet.

We can now retrieve all of the moons in our database using the Documents function — to avoid creating an index, like we saw in a previous part of the tutorial:

We could also create an index to find all of the moons for a given planet:

Then we can query the index:

If you’d like to enforce a one-to-one relationship, you can do that by creating an index with a unique constraint, like we saw in the previous part of the tutorial:

Now, if we try to create another moon that is related to planet Earth, we get an error:

In the relational world, it’s very common to model many-to-many relationships with an entity using a join table, or a bridging table.

This is done in part because, with a rigid schema, you’d need to add more columns to relate a row to other rows. But there is another important reason which actually solves our problem. When modeling a relationship with an independent entity, you can assign data to that relationship.

What if we actually had a collection to track the repairs that also associated technicians with spaceships?

And now, let’s create the first repair:

So now we know the status of a ship repair and which technicians are assigned to it. Neat.

Let’s start a repair:

And now let’s finish the repair:

Great!

Now with this simple index, we can see all of their repairs and their info:

Not bad! But how long do repairs actually take?

We could have added a duration property to our documents and stored a value when ending a repair, but where is the fun in that? With FQL, there are other ways to accomplish this.

For example, we could just determine the duration when querying our data without having to implement it in our application logic:

Whoa.

Again, this query may seem complicated, but we already know most of this query works from previous sections in this tutorial.

Here’s the new part:

What this does is check that startTimestamp or endTimestamp are not missing from the document. If both exist, then return the time difference in minutes.

Let’s go step-by-step.

There is another way to solve this. Do you remember index bindings from the previous part of this tutorial? These are computed values calculated beforehand.

The decision to use index bindings comes down to how often you need to know the duration of the repairs. As explained in the previous part of the tutorial, bindings consume more storage but less CPU, so you have to account for that when deciding to use bindings.

That said, here’s a possible index to return the duration using a binding and the same conditional logic. We’re also returning a custom object instead of the full document, which might make more sense when listing repairs instead of showing a detail view to your users.

Let’s query it: