Velo: Querying Items that Reference Other Items

Some collections contain items that reference items that are stored in a different collection. For example, a Books collection may contain a Writer field, which references an Authors collection. Using Velo, you can retrieve referenced items' details using different techniques. This article explains how.

In this example, a book is the "item" and the author is the "referenced item."

Retrieving Referenced Item IDs

Using Velo, when you query an item that references other items, by default you receive the IDs of the referenced items in the query's results.

Let's query our Books collection for novels. For each novel, we want to see the referenced author.

Consider the following code that runs the query and displays the results in the table we created above.

Copy

We see that the Author field contains ID values. We can't see the author's name, nationality, and so on. 

To see the referenced information in addition to the IDs, there are other Velo functions we can use: queryReferenced() and include().

At the end of this article, we describe when to use each of these functions.

Retrieving Referenced Items with queryReferenced()

Use the queryReferenced() function to to include referenced items for the specified properties in your query's results. For example, we want to see novels in our Books collections along with the author's name and nationality. The author's name and nationality exist in an Authors collection.

Example

Let's query our Books collection again for novels, but this time we want to see the author's name and nationality. 

First, let's look at the following code that sets up our table. We're going to take this opportunity to demonstrate how to set up table columns for an object, because we won't be loading rows directly from a collection. We'll add rows to the table using an object that we create instead.   

Now let's look at code that runs the query and displays the both the results and the referenced results in our table: 

Now we see the Author and Nationality field values. 

Retrieving Referenced Items with include()

Add the include() function to your query chain to include referenced items in your query's results.

This function is a bit simpler to use than queryReferenced(). But it does have limitations. Review the comparison between queryReferenced() and include() to decide which function to use.

When setting up our columns, we use the period  .  notation to access the nested, referenced items. Because the referenced items are in a different collection, we prefix their names with the name of the referencing property from the first collection. 

Example

Let's query our Books collection again for novels. Again, we want to see the author's name and nationality. This time we will demonstrate how to use include() instead of queryReferenced().

Consider the following code that runs the query and displays the results in a table: 

Copy

Now we see the Author and Nationality field values.

When to Use Each Function

This table can help you decide when to use queryReferenced() and include().

Functionality / LimitationqueryReferenced()include()
Can reference multiple items in one query

If you want to see many items and their referenced data in one query, it's easier to use include().
NoYes
Can reference one item that references multiple items in one queryYesNo
Can reference multiple items that reference multiple items in one queryNoNo
Can trigger hooksNoYes
Can reference more than 50 items

Use queryReferenced() if you anticipate more than 50 items as a result of your query, even if you use the limit() function.
YesNo
Can list up to 50 referenced items

Use queryReferenced( ) if you anticipate more than 50 referenced items will be returned as a result of your query.
YesNo
Works with promises

Working with promises lets you catch errors and send alerts.
YesNo
Did this help?