Demo to preview the settings
Introduction
Building a search engine for your website used to be a tedious process. You had to perfect long searches in the Bubble database and worry about the performance.
But now you can search your data in real-time with Algolia without having to worry about any of these issues.
Prerequisites
For using the plugin you'll need to get the API credentials from Algolia. Create your development account at: https://www.algolia.com/developers/
Algolia Setup
1. Register for an account
Go to http://algolia.com and register for an account. You have 14 days of free trial to evaluate Algolia. Select the data center with the least latency or the closest to your location.
2. Creating your first index
If you don’t have a real set of data, you can use Algolia’s sample records (click on the use sample user profile records button). If you have a real set of data, you can import them as JSON or CSV.
3. Your Algolia index
The Algolia indices page shows you the data belonging to your index and allows you to search it in real-time.
For example, you can type Lina in the search input to retrieve all the profiles that contain the word Lina in them.
4. Configuring ranking for your index
Locate the upper tab under your index and select "Configuration" then "Ranking and Sorting" to set up the ranking factors for your search. Algolia offers many ranking factors, we’re going to briefly mention the most important factors. They do have good documentation and decent support if you need to customize your index furthermore.
We suggest you keep the default values for the following fields unless you face any issue with them later on:
- Min chars to accept 1 typo
- Min chars to accept 2 typos
- Allow typos on numeric tokens
- Ignore plural
- Disable typo-tolerance on
- Query words interpretation
- Ranking
Attributes to index: Lets you select the attributes you want algolia to search. For instance, you want to search the email address but never search the home address field.
Custom Ranking: It allows you to specify the popularity of your data. Say the number of followers defines how important a person is, making it more relevant when sorting search results.
Optional words: Whenever you’re searching text or sentences rather than keywords, optional words are the most important configuration. It will instruct the search engine to skip the defined optional words (also known as Stop words).
Optional words are a list of commonly used words (such as “a”, “the”, etc.) that are deemed irrelevant because they occur frequently and matching those words would not make be helpful when aiming to return relevant data.
Here’s a list of stop words for the English language, you can also find the list for other languages.
Synonyms: Synonyms list would be helpful to define equivalent keywords. For instance: “any”, “whatever” and “whatsoever” will be treated as if they were the same word.
Remove words if no results: In most cases, this setting is very useful as Algolia tries to re-run your search during the same API call by removing 1 word at a time.
Use lastWords if you want to remove words from the end of the search query, or firstWords if you want to remove words from the beginning of the search query.
5. Configuring display for your index
We suggest you keep the default values for the following fields unless you face any issue with them later on:
- Max Values Per Facet
- Unretrievable attributes
- Attributes to snippet
- Replace synonyms in the highlight
- Highlight prefix tag
- Highlight postfix tag
- Attribute for distinct
- Distinct
Attributes for faceting: Faceting is a very useful feature offered by Algolia. It lets you categorize your data according to a certain field. For instance, you can categorize the data by company, language or country.
Hits per page: Like many other configuration options, the “hits per page” can be overridden at query-time. Meaning that when you send the request to Algolia using their API, you can provide a new value that will override the one saved in your index settings. This setting is used to specify the number of results to show per page.
Attributes to retrieve: Defines the attributes you want to retrieve, by default it returns all attributes.
In order to have the filtering option from „Algolia Search” element working it is needed to set up filtering and faceting in Algolia Dashboard.
Steps for setting up filtering and faceting:
1. Open the Search tab in your Algolia dashboard, and find tab "Configuration".
2. Select “Searchable attributes” and add there all the needed attributes by which you want to filter.
3. Select “Facets” and add there all the needed attributes by which you want to filter.
Bubble Setup and Usage
Visual Elements
1. Searching your data in real-time
At this point, we provide a really simple way to search for Algolia data from the Bubble app using the plugin.
Algolia Simple Search - element. Simply place the new element on page, installed element on the page should look like this.
Plugin Fields and States
Algolia Simple Search - properties & fields
The element fields themselves are documented, but here we provide descriptions for each field.
- Only as search - check this checkbox if you want the plugin to get data, just search.
- Index Name - is just the Algolia created index name. (text)
- Query - searching query, is a dynamic value Ex: An input value or external API provider data. (text)
- Type of Content - here you need to provide an app type, but the plugin itself comes with its app type, so here you need to provide the "Algolia Result" type. (Algolia Result)
- Fields to retrieve - Write here the name of the fields you want to get from Algolia. The name of the fields must correspond to the name of the fields in Algolia. Let's say we have an object structure in the Algolia index
In order for you to be able to get the name, description and name at the station, you must enter in "Fields to retrieve" in the appropriate way
- Hits Per Page - because Algolia uses pagination to return results, you need to provide how many hits per page you want to retrieve, min 1, max 1000. (number)
- Page - specify the page to retrieve. You will need to use this setting if you wish to retrieve specific pages. (number)
- Proximity - the precision of the proximity ranking criterion. The minimum (and best) proximity value between two matching words is 1. This is the engine default. Setting it to 2 (respectively N) would allow 1 (respectively N-1) additional word(s) to be found between two matching words without degrading the proximity ranking value.
- Geo Search - is a way to filter and sort results by distance or around certain geographical locations. You can limit your results to a street, to a city or cities, to one or more parts of the world. You can sort your results according to how near or far they are to certain defined geolocation.
- Around Lat-Lng - Search for entries around central geolocation, enabling a geo search within a circular area. By defining this central point, there are three consequences: a radius/circle is computed automatically, based on the density of the records near the point defined by this setting only records that fall within the bounds of the circle are returned records are ranked according to the distance from the center of the circle.
- Around Radius - Define the maximum radius for a geo search (in meters). This setting only works within the context of a radial (circular) geo search, enabled by Around Lat-Lng.
- Timeout - If you need a break before searching, please add in ms.
- Search begins when typing is finished
- Shuffle Hits - hits received from Algolia will be displayed randomly.
- Filter Unique Items -The "Filter Unique Items" field is used to filter out duplicate records from search results fetched from Algolia. Write the field by which we do the filtering Please note that if you have a numerical value, e.g., 40, and a text value, e.g., "40", they will both be displayed because they are different data types.
States
1. Algolia Simple Search - Algolia Result state
Algolia Result state is a complex object now so you can find all the information about your query and all the fields in one place. Contains lists of data grouped by user-defined field names in "Fields to Retrieve" from the element settings.
For example, if you set the selected fields to Name, Genre, Estimated Sales, First Post, and then in the Result state, you will have access to the above fields as follows: field 1 to get the name, field 2 for the genre, etc. on ...
Each of these fields is a list of values from your Algolia object. So field1 #1 is the first name element from your Algolia object, field1 #2 is the second, and so on..."
Each property name describes what kind of information it contains.
- query - your requested query. (text)
- params - your request params. (text)
- hitsPerPage - provided hits per page. (number)
- nbHits - total number of hits. (number)
- nbPages - total number of pages. (number)
- page - currently requested page. (number)
- field 1 - list of results that overlapping the first required field. (list of text)
- field 2 - list of results that overlapping the second required field. (list of text)
- ... 3, 4, 5, 6 ...
- field19 - list of results that overlapping the nineteenth required field. (list of text)
- field20 - list of results that overlapping the twentieth required field. (list of text)
You can display results in a repeating group by iterating through the results list (list of text) and extracting item by repeating group cell's index.
2. Suggestion state
This state keeps a list of keywords that the user has searched.
3. Result Recent Searches
As users come back to your site, they often want to revisit items they've seen before. For example, they want to look at a product they like in your store, or they want to rewatch a video they've watched before. With recent searches, you can create a great search state to guide users even before they start typing.
This state is filled in through the Action - Algolia Recent Searches. In simple words, whenever the Algolia Recent Searches action has a keyword in the "Query" field, this state will return the recent search data for the keyword. If the "Query" field is empty, the status will contain all recent searches.
IDs for new objects added - List of objectIDs of the saved objects in order. This property is only returned when using save objects.
Plugin Actions
1. Action: Recent Searches
an easy action to set, the first parameter is to set the plugin element where the data will be stored in element state
Query - This parameter will help you get the latest searches filtered after the keyword.
2. Action: Update objects
Update one or more attributes of an existing object. This call lets you update only a part of an existing object. Specifying existing attributes updates them in the object while specifying new attributes adds them.
As an example, you have an object in the Algolia database with this structure:
You want to edit the object, for this use the "Algolia Update Object" action
In the first field of action, we enter the keys.
In the second field of action, we enter the index name.
In the third field of action, we enter the Object Id that we want to edit.
In the fourth field of action, we introduce creating an object that will contain the fields that we want to edit to our object.
For example, you have in Algolia this object :
javascript{ "country": "Brazil", "geonameid": 3460773, "name": "Itapaci", "subcountry": "Goiás", "objectID": "17599877002" }
And you want to change the name field in 'Itapaci' in 'São Paulo' and add a new field 'Population', so in our action we add the fields we want to modify in the object or add them.
javascript{ "name'" : "São Paulo", "population" : "12.325.232" }
3. Action: Set Algolia settings
This action helps you to set search conditions right inside your app without having to go to Algolia Dashboard. What settings you have set, such data you will receive.
Index settings are built directly into your index at indexing time, and they impact every search. Only specified settings are overridden; unspecified settings are left unchanged. Specifying
null for a setting resets it to its default value. Index settings parameters
Searchable Attributes -The complete list of attributes used for searching. This setting is critical to establishing excellent relevance for two main reasons:
It limits the scope of a search to the listed attributes. Defining specific attributes as searchable gives you direct control over what information the search engine should look at.
Some attributes contain URLs; others exist for display purposes only. Such attributes are not useful for searching. It creates a priority order between attributes which the engine uses to improve relevance. The order in which the attributes appear determines their search priority.
Records with matches in the first attribute(s) of the list score higher on the attribute criterion than records with matches in the second attribute(s), which score higher than records with matches in the third attribute(s), and so on.
Attributes for Faceting - The complete list of attributes that will be used for faceting. Use this setting for 2 reasons: to turn an attribute into a facet to make any string attribute filterable.
By default, your index comes with no categories. By designating an attribute as a facet, enables Algolia to compute a set of possible values that can later be used to filter results or display these categories. You can also get a count of records that match those values.
Attributes to Retrieve -This parameter controls which attributes to retrieve and which not to retrieve. This setting helps to improve performance by reducing the size of records in the search response. You don’t always need to retrieve a completer response that includes every attribute in your index. Sometimes you may just want the most relevant attributes for the user and exclude others, for example, internal attributes for business purposes.
Ranking - You must specify a list of ranking criteria. The tie-breaking algorithm applies each criterion sequentially in the order they’re specified.
Custom Ranking - Each string must conform to the syntax asc(${attributeName}) or desc(${attributeName}) and specifies a (respectively) increasing or decreasing sort on an attribute. All sorts are applied in sequence by the tie-breaking algorithm in the order they are specified.
Relevancy Strictness - Controls the relevancy threshold below which less relevant results aren’t included in the results.
- Relevancy Strictness is available on applications having the Relevant sort feature enabled.
- You can set relevancyStrictness on virtual replicas only.
- The value must be an integer between 0 and 100 (inclusive).
Replicas - Creates replicas, exact copies of an index. The purpose of replicas is to create variants of your main index, where the data is the same and the variance is in the configuration (settings, synonyms, query rules).
The data in a replica is automatically synchronized with its primary index, which means that all indexing operations on an index (adding, updating, and deleting objects) are forwarded to its replica(s).
This is used mainly for: alternative sorting strategies A/B testing. The counterpart of replica, the primary parameter, is automatically added to a replica’s settings. primary stores the name of a replica’s primary index. The legacy name of the primary parameter is master.
Max Values Per Facet - Maximum number of facet values to return for each facet during a regular search. For performance reasons, the API enforces a hard limit of 1000 on
maxValuesPerFacet. Any value above that limit will be interpreted as 1000.Sort Facet Values By - When using facets, Algolia retrieves a list of matching facet values for each faceted attribute. This parameter controls in which order the facet values are retrieved within each faceted attribute. This parameter doesn’t control or impact how facet values are displayed on the UI. See facet value display to control how facet values should be displayed.
Min Word Size for Typo - Minimum number of characters a word in the query string must contain to accept matches with 1 typo.
Typo Tolerance - Controls whether typo tolerance is enabled and how it is applied.
4. Add Object
This action adds an object to the index, automatically assigning it an object ID. Now it is simple to add an object in Algolia. Add an object to the index, automatically assigning it an object ID.
If you need the object id to match the one in the bubble id, add the field objectID with bubble unique id value to the object.
5. Algolia Refresh
This method lets you search through the values of a facet attribute and select a subset of those values that meet a given criteria.
This action helps to refresh the Algolia database after you have added, edited, or deleted something.
6. Search for Facet Values
When you have thousands of different values for a given facet attribute, it’s impossible to display them all on a user interface.
With Search for facet values, you allow your users to search within a specific faceted attribute (for example, brands, authors, or categories) without needing to create a separate index.
You can still display the most common occurrences for each facet at the top, but also enable the user to search for a specific value for filtering.
Example:
To use this action, it is necessary to make some settings in the Algolia dashboard.
- Select "configuration”
- Search under the option "Facets”
- Here you set the field by which you search in "searchable”, and press the button “save setting”
Action setting:
Facet Name - Attribute name. For this to work, you must declare the attribute with
attributesForFaceting using the searchable() modifier.Facet Query - The search query used to search the facet attribute.
Filters - Here you can additionally add a filter. To create a filter correctly, please follow our documentation in the "Filtering" section.
Max Facet Hits - Maximum number of facet hits to return during a search for facet values. Data of this action will be stored in the following states:
- List Of Values - List with "Facet value”.
- Highlighted Values - List Highlighted values
- How many values of this type were found - List with the number of times the value is present in the dataset.
7. Delete Objects
Set the list of ids in the "List of objects id" field, separating them with ",”.
8. Add Objects
Add new objects to an index or replace existing objects with an updated set of attributes.
The save method is used to redefine the entire set of an object’s attributes (except its
objectID). In other words, it fully replaces an existing object.This method differs from partial update objects in a significant way:
- With Save Objects, you define an object’s full set of attributes. Attributes not specified will no longer exist. For example, if an existing object contains the
authorattribute, but you don’t define it in your update call, it removes theauthorattribute from that object.
- In contrast, when using Partial Update Objects, you can single out one or more attributes and create or update their content. If you don’t define an existing attribute in your update call, it doesn’t impact it.
Objects - A list of objects to save.
If the objectID exists, Algolia replaces the record
If the objectID is present but doesn’t exist, Algolia creates the record
If the objectID isn’t specified, the engine generates an objectID and returns it in the response.
Plugin Events
Algolia is loading
This event will let you know when the data is already in your Algolia's states.
List of objects was deleted
This event will show when the deletion of objects happened successfully.
Data has been added to Algolia
This event will show when the saving of objects happened successfully.
Filtering
Filtering allows your users to drill down and creates a smaller, more manageable set of data based on meaningful categories.
Filtering is primarily used in the context of front-end search. We call this faceting, where filters are displayed on the search UI as clickable items, allowing users to select one or more filters. This enables a more refined, drilled-down search experience.
Comparison Operators
- = : Checks if the values of two operands are equal or not, if yes then the condition becomes true.
- != : Checks if the values of two operands are equal or not, if values are not equal then the condition becomes true.
- <> : Checks if the values of two operands are equal or not, if values are not equal then the condition becomes true.
- > : Checks if the value of the left operand is greater than the value of the right operand, if yes then the condition becomes true.
- < : Checks if the value of the left operand is less than the value of the right operand, if yes the hen the condition becomes true.
- <= : Checks if the value of the left operand is less than or equal to the value of the right operand, if yes then the condition becomes true.
- !< : Checks if the value of the left operand is not less than the value of the right operand, if yes then the condition becomes true.
- !> : Checks if the value of the left operand is not greater than the value of the right operand, if yes then the condition becomes true.
Logical Operators
The following operators, which must be specified in CAPS, are supported:
- OR: must match any of the combined conditions (disjunction)
- AND: must match all of the combined conditions (conjunction)
- NOT: negates a filter
- TO: the area of variation between upper and lower limits on a particular scale.
Filter By String
For example, you have a database of books and you want to select all the books with a certain genre.
Algolia’s filters parameter allows you to leverage boolean operators (AND, OR, NOT) and parentheses to combine individual filters, similar to SQL expression syntax.
Result:
As an example now we want to find the fantasy genre only in Portugal, we will use the keyword 'AND'.
Result:
Now we are creating a filter to receive all the fantasy and adventure books, we will use the OR operator.
Result:
Filter By Numeric Value
Algolia allows you to numerically filter results, via comparison or a range. This only works if you’re using numeric values.
Algolia supports <, <=, =, !=, >= and > operators with the same semantics as in virtually all programming languages.
For example, you want to get all books written between 1887 and 1988, in such cases, we will use the operator "TO".
EX:
Result:
Filter By Boolean
Algolia allows you to filter results by boolean attributes. Imagine you have an eCommerce website, and you want users to search through available products. If you have a boolean attribute called
is_available, you can exclude all records where is_available is false. To do this, you must first declare is_available as an attribute for faceting.Filter By Date
Dates aren’t only useful for sorting. You can also leverage them to filter search results on a specific date range. Imagine you have a blog, and you want to provide time-based filters. For example, you may want to allow users to filter on recent posts, or only see posts from a certain period.
Before we can filter on a date, we need to add the date as a Unix timestamp. We don’t have to remove or change the date; instead, we can add a date_timestamp attribute with the proper format.
We can also use
TO and NOT operators here.Note that this attribute needs to be a numeric value for Algolia to be able to sort on it.
- We put data in Algolia in Unix timestamp.
2. Filter the data by time as follows. The bubble date must also be in unix format.
Algolia filters use a SQL-like syntax, which allows you to use comparison operators.
Result:
Filter an Array
What’s an array in the context of filtering? When you start filtering, many of your filter attributes will take only a single value per record.
For example, in a book index, if you filter by type of story (novel, short story), you only need to tag each book with a single value - normally, a book can’t be both a novel and a short story.
On the other hand, other attributes, like genre, can often contain multiple values: the same book can be included in the “crime”, “comedy”, and “historical” genres. The genre attribute, therefore, needs to be an array.
Generally speaking, any attribute that contains a list of values for a single record needs to be set up as an array. A single value attribute takes a string as a value; multiple values require an array, whose syntax changes depending on the programming language used.
Multilingual Search
Since Algolia’s search engine is language-agnostic, it supports all languages and alphabets, including symbol-based languages such as Chinese and Japanese.
Below are represented steps of how to organize your indices to enable multi-language search.
1. Create one index for all languages. Your records should contain text for each language.
2. In the plugin element -> in the "Fileds to Retrieve'' specify the field name exactly as in the records (point 1).
3. In Algolia Dashboard set the searchable attributes for all required languages.
FAQ
- Question: What are the key differences between this plugin and the bubble integration on Pro plans?
- Response: please find a feature comparison table below:
Algolia Search V 2.0 | Algolia integration to Bubble |
✅ Works with any plan. | Requires a Professional plan. |
✅ No need for manipulations in the app database | Requires object creation in the app database, same as in the Algolia dashboard. |
✅ The Algolia data can be displayed not only on search demand but also when loading pages. | Can only be used as a search tool. |
✅ The user can change the Algolia index settings from the Bubble app. | Algolia index settings can be changed only in the Algolia dashboard. |
✅ It can update, edit, delete, and add items from Algolia. | ❌ |
✅ Has action that preserves recent user searches. | ❌ |
✅ Has an action that searches for facet values. | ❌ |
✅ A search filter can be added. | ❌ |
✅ Has the possibility to trigger the search right after the user stops typing a search key, to reduce the number of requests to the Algolia platform (reducing the overall costs of the service). | ❌ |
Changelogs
Update 19.11.20 - Version
- Added new element action for providing a recent searches option
Update 28.11.21 - Version 3.19.0
- Added function (add an object, set setting, Get all data);
Update 21.02.22 - Version: 3.20.0.
- Added refresh action
Update 21.06.22 - Version 3.24.0
- added states lost
Update 06.10.22 - Version 3.28.0
- were added new actions "Search for Facet Values" and "Delete Objects”
Update 28.10.22 - Version 3.29.0
- Field updated
Update 21.01.23 - Version: 3.31.0.
- Added new action 'Save Objects’
Update 3.02.23 - Version: 3.34.0
- Added action "Add objects backend”
Update 27.02.23 - Version: 3.36.0
- Fixed problem parsing with field null
Update 16.03.23 - Version 3.37.0
- improved plugin with the higher-level access object
Update 4.04.23 - Version 3.38.0
- added field "Timeout”
Update 13.04.23 - Version 3.39.0
- improved search to decrease the number of requests to Algolia
Update 26.04.23 - Version 3.40.0
- added option: Search begins when taping is finished
Update 11.10.23 - Version 3.47.0
- Update Algolia to V4
Update 13.11.23 - Version 3.49.0
- Fixed action Refresh
Update 03.01.24 - Version 3.53.0
- fixed action Add objects (backend) and migrated plugin to version 4
Update 06.02.24 - Version 3.56.0
- Deprecated action "delete object".
Update 26.02.24 - Version 3.57.0
- Was added an action delete object in the backend.
Update 17.03.24 - Version 3.58.0
- Fixed the issue with the first letter always getting searched.
Update 03.04.24 - Version 3.59.0
- Was fixed action 'Refresh’
Update 03.04.24 - Version 3.60.0
- Algolia search - updated description
Update 08.04.24 - Version 3.61.0
- Added new options "Filtering unique items"
To avoid errors, after updating the plugin to version 3.29.0, please be sure to check the “Update Object” action setup.
