Atlas Search Introduction
Atlas Search (Beta)
Having setup WordPress and created some content, you may find that your content search has some issues:
- Unexpected search results, either not finding what you were looking for or the most relevant result is buried far down on the list.
- Unable to query with search operators such as
AND
,OR
orNOT
. - Advanced WordPress data types are not native to search:
- Requires another plugin for ACF (Advanced Custom Fields) types
- Doesn’t support ACM (Atlas Content Modeler) types
Atlas Search is designed to address all these issues in one place and in an easy to use manner. It will improve search result relevancy, support advanced search query operators and add support for advanced WordPress data types.
Atlas Search is for the headless developer using the WordPress WPGraphQL & REST APIs. It is composed of 2 parts:
- WordPress Atlas Search plugin
- An Atlas Search provider backend
The easiest way to get started with Atlas Search (Beta) is to request an Atlas sandbox account for free via Atlas "Headless" WordPress site. Once a sandbox account in created you can install all requirements for Atlas Search in just one click, via Atlas BluePrints.
If you already have an Atlas account and an Atlas App that you wish to evaluate Atlas Search with, fill in the enrolment form and jump to the Installation without Blueprints instructions below.
Contents
- Getting an Atlas Search Account - How to register for an account & get a 'namespace'.
- Installing the Atlas Search Plugin - Methods of installing the Atlas Search plugin.
- Installation via Blueprints - Standard approach to the plugin installation.
- Installation without Blueprints - Alternate approach to the plugin installation.
- Configuring the Atlas Search Plugin - Making the Atlas Search plugin talk to the Atlas Search server.
- Content Data Sync - How to clone/ sync WordPress data into Atlas Search
- Using Atlas Search - A series of sample GraphQL queries that demonstrate Atlas Search’s functionalities.
- Querying Standard WP Data Types WP Data Types - Queries with Posts, Pages, CPT
- Querying ACM/ ACF Types - Queries for Atlas Content Modeller or Advanced Custom Fields
- Getting More Specific with Queries - Queries with
AND
,NOT
&OR
- Advanced Configuration of Atlas Search - Advanced features that allow extra configurability for Atlas Search.
Handling Typos with Fuzzy Search - Resolving queries with
n
number of typosFiltering and Boosting Searchable Content - Configure what WP Data Types & Fields are searchable, & set custom weightings to prioritize what matters to you.
Getting an Atlas Search Account
To get started with Atlas Search, you will need to fill in the enrolment form. Please note that this is limited to 1 enrollment per email. After submission of the form you will receive an Atlas Search 'setup' email with the your own personal provider backend URL & Access Token. Do not share this setup email or the Atlas Search credentials
Installing the Atlas Search Plugin
The Atlas Search plugin can be installed manually but will more likely be installed implicitly as part of our Atlas Blueprints setup.
Installation via Blueprints
This is the standard path for Atlas Search plugin installation The Atlas Blueprints pipeline will have:
- Installed & activated the WP-GraphQL plugin.
- Installed & activated the Atlas Search plugin.
Installation without Blueprints
This section only applies if you did not acquire the Atlas Search plugin via Atlas Blueprints. To install the Atlas Search plugin you will need to have an instance of WordPress and can access the ‘WP Admin’ panel. In the WP Admin panel, before installing the Atlas Search plugin, you will need to download & activate the WP-GraphQL plugin from the WordPress.org plugin repository. The Atlas Search plugin can then be installed & activated as per its documentation.
Configuring Atlas Search Plugin
Configuring the Atlas Search plugin enables both the Content Sync & Search Querying functionalities.
After successful installation, via one of the methods discussed in the Plugin Installation section, the Atlas Search
menu item will appear in the left navigation panel of the WP Admin panel.
- Click this
Atlas Search
menu item. By default it will bring you to the default sub-menu ‘Settings’ view, where you will populate the following inputs with the values from the setup email you have received after completing the Getting an Account section:- URL (ie.
https://{atlas-env}/sync/{yoursite}/graphql
) - Access Token (ie.
{your-unique-access-token}
)
- URL (ie.
- Select the ‘Save Settings’ button for the changes to take effect.
Content Sync
Once you have installed & configured the Atlas Search plugin it will be necessary to run an initial content sync, which will send all pre-existing content on the WP site to Atlas Search for indexing.
After this initial sync, the Atlas Search plugin will continue to auto-sync content in real-time whenever content additions or modifications occur on WP.
Note that, if any content modifications occur while the Atlas Search plugin is deactivated or uninstalled, it will be necessary to re-run this content sync to send the untracked data to Atlas Search.
Content sync is performed via the Atlas Search plugin’s UI, as follows:
- Click the ‘Atlas Search’ menu item in the WP Admin panel, then click the ‘Sync’ sub-menu item to bring up the below view.
- Click the
Synchronize Now
button. Content Sync can take some time to complete, especially with large data sets. The content sync loading bar provides information on progress. - Await the ‘Sync Completed Successfully’ status message.
- In the event that the sync process does not complete successfully, an error message of
Unexpected sync error occurred. Please try to Resume the sync or Delete what did sync, then start the sync process again
will be displayed - at which pointResume
&Delete
buttons will be available for resuming from point of failure or purging & restarting the content sync respectively.
Once the Atlas Search’s Content Sync has completed you are free to query the content via the WPGraphQL and REST APIs. The API search functions will look & feel just like they did before but behind the scenes the WordPress Search is now intercepted and delegated to the Atlas Search provider backend.
Using Atlas Search
Once the initial content sync has completed, & while the Atlas Search plugin remains “active”, Atlas Search will enhance your WP search experience.
The WP-GraphQL plugin is a good place to test this search experience. That plugin includes an instance of the ‘GraphiQL’ IDE, where one can interface in the browser with their WordPress data, via GraphQL queries. Atlas Search overrides the default search functionality for WPGraphQL queries on all Atlas Search supported WP data types.
Below is a screenshot of WP-GraphQL plugin & GraphiQL view, where Atlas Search has overrriden the default WP search behavior, followed by some sample queries:
Querying Standard WP Data Types:
For querying standard WordPress data types (Posts, Pages & Custom Post Types (CPT)) some examples with Atlas Search are:
- Querying Posts/ Pages:
{{either ‘posts’ or ‘pages’}(where: {search: "CSS"}) {nodes {idstatustitle}}}
- Querying CPTs:
{branches(where: {search: "Austin"}) {nodes {address}}}
Querying ACM or ACF Types:
Atlas Search also integrates with the Atlas Content Modeler (ACM) & Advanced Custom Fields (ACF). Default WP search requires plugins for ACF & doesn’t support ACM at all.
- Querying ACM type of
project
, with fields ofstreetAddress
,contactName
&workOrderNumber
:
{projects(where: {search: "Austin"}) {nodes {streetAddresscontactNameworkOrderNumber}}}
Getting More Specific with Queries:
Atlas Search treats spaces as ‘OR’ by default, whereas the default WordPress search treats spaces as AND
. With Atlas Search, however, you can explicitly specify the AND
, OR
& NOT
keywords within your search query & you can combine them too - this provides enhanced specificity for your querying needs:
- Using
NOT
search operator:
{projects(where: {search: "Austin NOT Minnesota"}) {nodes {streetAddresscontactNameworkOrderNumber}}}
- Using
AND
search operator:
{projects(where: {search: "New York AND Texas"}) {nodes {streetAddresscontactNameworkOrderNumber}}}
- Using
OR
search operator:
{projects(where: {search: "New York OR Texas"}) {nodes {streetAddresscontactNameworkOrderNumber}}}
Advanced Configuration of Atlas Search
For those users who have more specific functionality needs Atlas Search provides a series of advanced configurations to give you the most control on your data search.
Handling Typos with Fuzzy Search
Atlas Search will attempt to search for an exact match to every word in a search query if Fuzziness
is not enabled. By default, however, Fuzziness is enabled on a fresh plugin install, & it employs a default one-letter-per-word tolerance ("distance"), so you can immediately see the benefits. With this default Fuzziness setup you type "Hallo Warld" and you will get the results for both "Hello" and "World".
This Fuzziness can be toggled, along with modifying this per-word distance (to, let's assume, the maximum distance of 2) in the plugin menu’s ‘Search Config’ view - in this case a search query of "Haalo Waald" would work as per the previous example, yielding also the results for both "Hello" and "World".
Please note that the higher the fuzziness distance allowed the greater the performance & relevancy hit will be to your search experience.
Filtering And Boosting Searchable Content
Atlas Search, by default, will search all supported WP Data Type objects (Posts, Pages, CPTs, ACFs, ACMs, etc.) by all of their supported fields (string, number, boolean, other WP Data Type objects).
Atlas Search will then return results where each field-match to the search query term(s) are given an equal weighting (1), thus the objects with most search-match occurrences will rise to the top. In some cases this may not be the desired behavior, for example:
- It may not be correct to consider some specific fields as searchable
- Searches matching some fields should be considered more relevant than others
To cater for these type of use cases, Atlas Search provides both a field-level filter (‘searchable’ field toggle), and a field-level weighting slider, which can be found in the plugin menu’s ‘Search Config’ view.
The field-level filter permits the configuration for each field to be included/excluded from consideration in search queries.
The field-level weighting slider permits the configuration of some fields to be considered more relevant than others when decising on ordering of search results. The higher the weighting, the more relevant it is deemed to be.
Remember to press the ‘Save’ button to persist any configuration modifications!