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.

1
function theRegularFindExample() {
2
    
3
  // Query the Books collection for novels only
4
  wixData.query('Books')
5
    .eq('genre', 'Novel')
6
    .find()
7
    .then((myResults) => {      
8
        
9
     // Set up table columns
10
     $w("#table1").columns = [
11
      {
12
       "id": "col1",
13
       "dataPath": "title",
14
       "label": "Book",
15
       "width": 100,
16
       "visible": true,
17
       "type": "string",
18
      },
19
      {
20
       "id": "col2",
21
       "dataPath": "genre",
22
       "label": "Genre",
23
       "width": 100,
24
       "visible": true,
25
       "type": "string",
26
      },
27
      {
28
       "id": "col3",
29
       "dataPath": "writer",
30
       "label": "Author",
31
       "width": 200,
32
       "visible": true,
33
       "type": "richText",
34
       "linkPath": "doc"
35
      }
36
     ];
37
              
38
     // Display the query results in the table
39
     $w("#table1").rows = myResults.items;
40
   })
41
}

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: 

1
async function theIncludeExample() {
2

3
  wixData.query('Books')
4
    .eq('genre', 'Novel')
5
    .include("writer")
6
    .find()
7
    .then((myResults) => {
8
      if (myResults.items.length > 0) {
9
        let books = myResults.items;
10
        $w("#table2").rows = books;
11
      } else {
12
        console.log("No results found.");
13
      }
14
  })
15
}

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().