Finding data

This section covers how to search for data using constraints

This article takes a long-form look at how searches in Bubble work.

For a more concise, technical list of settings, constraints, and operators, see our core reference entry on searches.

Reference: Searching

Dynamic expressions: This article covers different dynamic expressions. If you're new to dynamic expressions, we recommend reading the article below first.

Article: Dynamic expressions

Once you've added and updated data in your database, you'll need a way to find that data and display it around your app. This article covers how searching works, from a basic query to sorting, isolating a single record, and the different data sources you can pull from.

Doing a search

Whenever you need to find data in the database, you perform a search using the Do a search for data source. This sets up a dynamic query with specific constraints, and Bubble returns all things of that data type that match. You can search for one data type at a time, such as User.

Say you want to find all users named John. First, set the Type of content to User, then pick Do a search for in the Data source dropdown.

Then add a constraint that tells Bubble to return only users whose name is John. The result is always a list, even when it contains just one thing.

This is how database queries work at their core: you tell Bubble what kind of data to search for, then give it one or more constraints that each thing in the returned list has to match. You can use a search in all sorts of places:

• To display results on a screen

• As part of a workflow, for example to make changes to one or more things

• As part of a conditional expression

Data sources like Do a search for are one of the building blocks of dynamic expressions. To read more about working with expressions, see the article below.

Article: Dynamic expressions

Static and dynamic constraints

In the example above, the constraint was a static value: the name John. You can also set a constraint as a dynamic value, so it changes based on something in your app.

For example, instead of a fixed name, you could point the constraint at the value of an input field. That lets your users type a name and search the database for matching users.

Element data sources using Do a search for stay synced with the database in real time. Any change in the database, even one made by another user, shows up in your app right away, with no need to manually refresh the search.

The exception is a search that was initially fetched in a workflow.

Display name

By default, a dynamic expression shows as the expression itself, such as Do a search for. You can optionally give it a more descriptive label, like "Search for John". The label doesn't change how the search works, it just helps keep your app organized and easy to review.

To change the display name, click on the expression and edit the field Display name.

Sorting the results

Sometimes you'll want to sort the results a particular way, like showing users alphabetically or tasks by priority or deadline. Sorting is useful both for displaying a list and for finding one specific record. For example, to load the last user created in your database, you can sort the list by creation date and then isolate the newest one with the first item or last item operator, depending on the sort order.

Sorting on the search directly

You can set the sort order directly when you perform the search.

Set the sort order in the search itself using the Sorting section. Here, users are sorted by last name in ascending order, since Descending order is set to "no".

Sorting with an operator

In some cases you'll be working with a list that isn't loaded from a search, or you'll need to apply sorting after another operator in the expression.

Applying sorting as an operator (with examples)

When you add sorting as an operator instead of on the search itself, the sorting is applied on the list that Do a search for returns. In other words, the search runs first and hands back its results, and only then does the sorted operator reorder them. The order of operations is what makes this useful: any step that happens between the search and the sort, like filtering, merging, or combining lists, is reflected in the final order. This comes in handy in a few situations:

• Sorting a merged list. You combine two searches with :merged with, then sort the whole thing. Each search sorts independently, so the combined list needs sorting applied after the merge.

• Sorting a list stored on a field. A field that holds a list of things (like a user's list of favorite blog posts) has no search to sort. You sort the list after retrieving it.

• Sorting another element's data. When your data source is another repeating group's list rather than a fresh search, sorting happens on that referenced list.

• Sorting a list that came from an API call. Data returned by the API Connector isn't a database search, so any ordering has to be applied to the returned list afterward.

• Sorting after :intersect with. When you narrow two lists down to their shared items, the intersection is a new list that you then sort.

• Re-sorting a list in a custom state. If you've stored a list in a custom state, sorting it for display happens after you pull it back out of the state. Sorting a list built through :plus item or :minus item. When you've added or removed individual items from a list, the modified list is sorted afterward.

For those cases, use the sorted operator:

Add the sorted operator to a search by typing "sort" and selecting it from the operator list.

Lists versus single things

Bubble handles database records in two ways: as a single item, or as a list. Understanding this distinction matters, because the two are treated differently. When you load data into container elements, for example, a group expects a single thing, while a repeating group or table (web) or mobile lists expects a list.

A search always returns a list, even when only one thing matches. In that case it's a list with a count of one, but it's still a list.

Loading a single record from a list

When a data source returns a list, like Do a search for does, any Bubble element or operator that expects a single item will flag an error in the issue tracker. To resolve this, you tell Bubble to load just one record from the list by adding an operator to the expression.

Operator	What it returns
First item	The first item in the list. Which one that is depends on how the list is sorted (by creation date, by default).
Last item	The last item in the list. Which one that is depends on how the list is sorted (by creation date, by default).
Random item	A pseudorandom item from the list.
Item #	A single item at the index number you specify, such as Item 5. This operator requires you to enter a number.

Combining search constraints with the first item operator often gets you to the exact thing you're after. For example, you could search users with the Email field as a constraint. Since emails are unique, providing an existing user's email address returns the right record. Applying first item to that result turns the list into a single thing.

Turning a single record into a list

Sometimes you'll need to go the other way, turning a single item into a list, even if that list holds only the one record. To do this, use the converted to list operator.

This comes up whenever something in your app expects a list but what you have is a single thing.

Converting a single record into a list examples

• Passing it to an action that expects a list. Some workflow actions (such as Copy a list of things) take a list of things. If you only have a single record but the action needs a list, converting it lets you pass it through.

• Setting a list field on another thing. A field that stores a list of things expects a list value. To save a single record into it, convert it first.

• Passing a single record to a backend workflow that takes a list. If a backend workflow's parameter is defined as a list of things, a single record needs converting before you can send it.

Other data sources

Searching with Do a search for is one way to find data, but not the only one. Depending on what you need, another data source may get you there more directly.

Data source	Description	Returns
Do a search for	Searches the database using constraints.	A list of things
Current user	The user currently using the app.	One thing
Current page thing	The record currently loaded onto the page with the Go to page action.	One thing
Get data from page URL	A thing retrieved from a URL parameter that contains a unique ID.	One thing
Thing's X	A value stored in a field on another thing, such as Current User's Company.	A list or a single item, depending on the field

Other ways to learn

Core reference

• Searching

Video lessons

• How to use search constraints

• How to use the Do a search for data source