Atlas Search Introduction

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 or NOT.
  • 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:

  1. WordPress Atlas Search plugin
  2. 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.

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

The Atlas Search plugin can be installed manually but will more likely be installed implicitly as part of our Atlas Blueprints setup.

This is the standard path for Atlas Search plugin installation The Atlas Blueprints pipeline will have:

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

  1. 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})
  2. Select the ‘Save Settings’ button for the changes to take effect.

Atlas Search Plugin Settings

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:

  1. Click the ‘Atlas Search’ menu item in the WP Admin panel, then click the ‘Sync’ sub-menu item to bring up the below view.
  2. 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.
  3. Await the ‘Sync Completed Successfully’ status message.
  4. 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 point Resume & Delete buttons will be available for resuming from point of failure or purging & restarting the content sync respectively.

Atlas Search Plugin Data Sync

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.

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:

Atlas Search Plugin Data Sync

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 {
      id
      status
      title
    }
  }
}
  • Querying CPTs:
{
  branches(where: {search: "Austin"}) {
    nodes {
      address
    }
  }
}

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 of streetAddress, contactName & workOrderNumber:
{
  projects(where: {search: "Austin"}) {
    nodes {
      streetAddress
      contactName
      workOrderNumber
    }
  }
}

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 {
      streetAddress
      contactName
      workOrderNumber
    }
  }
}
  • Using AND search operator:
{
  projects(where: {search: "New York AND Texas"}) {
    nodes {
      streetAddress
      contactName
      workOrderNumber
    }
  }
}
  • Using OR search operator:
{
  projects(where: {search: "New York OR Texas"}) {
    nodes {
      streetAddress
      contactName
      workOrderNumber
    }
  }
}

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.

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.

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!

Atlas Search Plugin Config