FlutterFlow Docs
Search…
Actions
Creating Subcollections
​Collections that are created inside the document are called subcollections. For example, to store a post's comments, you could have a comments subcollection inside the top-level posts collection.
Subcollection is best when you have several queries/filters or search on a collection that is based on the other collection. For example, loading or searching the comments of a specific post. (i.e show all comments of a specific post that have more likes, show all comments of a specific post by specific order, etc.)
At this time, FlutterFlow supports one level of nesting (e.g. collection -> subcollection). Second level nesting is not currently supported ( e.g. collection -> subcolleciton 1 -> subcollection 2)
Subcollection

Prerequisites

Before getting started with this section:

Working with subcollections

In this section, you'll learn to work with subcollections by building an example that allows you to see all messages and post a new message in a chat room (example below).
Here are a few tips on how subcollections work in FlutterFlow:
  • You can create a subcollection document under an existing reference if there is a subcollection defined.
  • You can either specify the reference to query a subcollection (UserA -> favorites) or can do a β€œcollectionGroup” query across all subcollections (all Users -> Favorites) by not specifying the reference.
Chat room example
Before we begin, we need to identify the collections and define the database structure. So looking at the requirement, it's very clear that we'll need two collections. One for storing chat room details and another for storing its messages. And we need to display the messages only for a specific chat room. So having the message collection as a subcollection of the chat rooms seems to be a good option.
Here's what the database structure looks like:
Database structure for chat room example
Building the chat room example comprises the following steps:

1. Creating a collection

Create the collection called chat_rooms as per the instructions here. This will be used to hold the chat room details. While defining the scheme for chat_rooms collection, add the fields to display its name i.e chat_room_name.
Creating collection

2. Creating a subcollection

To create the message subcollection:
  • Click on the Firestore from the Navigation Menu (left side of your screen).
  • Click on the (+) Plus sign button. (right side of Collection label)
  • A popup will appear, Enter the collection name as messages.
  • Turn on the Is Subcollection toggle.
  • The dropdown list with existing collections will appear. Click on the Unset and select the parent collection. Which is chat_rooms in this case.
  • Click Create Button.
  • Define the document scheme using the instructions here. While defining the scheme for message collection, add the fields such as message (to store message body) and from (to store the sender name).
Creating subcollection

3. Add data to the collection

Add some chat room details using the instruction here.
Adding data to the collection

4. Building chat room listing page

The first page shows the chat room listing and when you tap, it opens the new page and shows all messages.
The steps to build the chat room page are as follows:
  1. 1.
    Query the chat_rooms collection and display the chat room names in a ListTile (inside ListView) using the instructions here.
  2. 2.
    Add the Navigate To action on Tap of the ListTile and open the messages page using the instructions here. Note: While navigating, pass the chat room record to the next page. Learn how to pass data to the next page here.
Building chat room listing page

5. Building messages page

The next page shows all the messages and allows you to send messages in the chat room.
The steps to build the chat room page are as follows:
  1. 1.
    ​Design a page​
  2. 2.

1. Design a page

To design a page:
  • Create/Select a page and give it a name.
  • Select the AppBar widget and remove the existing back button. Move to the property editor (on the right) and turn on the Show Default Button.
  • Inside the Column widget, drag the ListView widget from the Layout Elements tab (in the Widget Panel) or add it directly from the widget tree.
  • Drag the ListTile widget from the Base Elements tab and drop it inside the ListView. Also, remove its Subtitle.
  • Inside the Column, add a TextField to send a message and give it a name.
  • Add a Button to add send a message.
Design a page

2. Query Subcollection

To query a subcollection:
  • Select the ListView widget from the widget tree or from the canvas area. Make sure to choose the ListView widget, not the ListTile.
  • Click on the Backend Query tab (on the right side of your screen).
  • Set the Query Type to Query Collection.
  • Scroll down to find the Collection dropdown and set it to the subcollection i.e messages.
  • Now you need to provide the reference of the parent collection. In this case, it would be the reference of chat_rooms. So inside the chat_rooms Reference box, set the Value Source to From Variable.
  • Set the Source to the Chat record sent from the previous page. Note: Learn how to pass data to the next page here.
  • Set Available Options to reference.
  • Set the Query Type to List of Documents.
  • (Optional) By default, the result of this query will automatically refresh when the items are added/updated/deleted inside the collection. Checkmark the Single Time Query to load the result only once and not refresh when any updates are made.
  • Click Save.
Query a subcollection

3. Show data in UI elements

After querying the subcollection, display the actual content inside the UI elements.
To show data in UI elements:
  • Select the ListTile Widget from the widget tree or from the canvas area.
  • Move to property editor and scroll down to the Title section.
  • Click on the Set from Variable text. (This will open a new panel)
    • Find the Source dropdown, click on unset and select the [collection] Record (from ListView) from the list.
    • Under the Available Options, click on Unset and select the field that you wish to show.
    • Click Save.
Show message content in ListTile title

4. Add action to send message

After displaying all the messages, it's time to send a message into the subcollection.
The steps to send a message in messages subcollection are as follows:
  • Select Button from the widget tree or from the canvas area.
  • Select Actions from the Properties panel (the right menu), and click Open. This will open an Action flow Editor in a new popup window.
  • Click on + Add Action.
  • On the right side, search and select the Database action and then select Create Document.
  • Set the Collection to the subcollection i.e messages.
  • You can create a subcollection document under an existing reference if there is a subcollection defined. So now you need to provide the reference of the parent collection. In this case, it would be the reference of chat_rooms. So inside the chat_rooms Reference box, set the Source to the Chat record sent from the previous page. Note: Learn how to pass data to the next page here.
  • Set Available Options to reference.
  • Under the Set Fields section, click on the + Field button.
  • Click on the Field name.
  • Scroll down to find the Value Source dropdown and change it to From Variable.
  • Find the Source dropdown and change it to Widget State.
  • Find the Available Options dropdown and set it to the Name of the TextField.
  • Click Close.
Adding action to send message
When you run the app, it should like the visual shown at the start of the section.