search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso
App Search Documentation / app search: App Search Read Only Mode
App Search Read Only Mode

From Zero to Search

Guides

API Reference

App Search API Clients

Self-Managed App Search

Resources

App Search Read Only Mode

App Search supports a read-only mode, which allows a product operator to disable all writes from the application to the underlying Elasticsearch instance while keeping the application running and handling search requests. This mode could be used to perform maintenance on a deployment, create a consistent snapshot of the deployment’s data, or to perform a graceful upgrade to a newer version of the product without downtime.

Effects on the service

After read-only mode is enabled on an App Search deployment, all write requests to Elasticsearch indexes used by the application will start to fail and the application will handle those errors properly according to the situation. All API requests attempting to modify the state of the deployment will respond with an HTTP 503 message explaining the situation to the caller.

The following functionality will function as expected in read-only mode:

  • App Search Dashboard (only viewing operations, logs and analytics).
  • Search APIs
  • Read and listing API requests to control layer objects like engines, synonyms, etc.
  • Analytics API requests (with delayed data because analytics logs will not be indexed).

The implementation of the read-only mode means that after you change the read-only flag, all indexing requests will start failing with an HTTP 503 error and will need to be retried later. Your indexing code should be ready to properly handle those responses and retry until indexing succeeds.

Usage

Only service operators -- people with access to the infrastructure running the application that can run bin/*-search -- and owners of an admin API token can manage the read-only mode on an App Search deployment.

Please note: After the value of the read-only flag is set to true, it is persisted in Elasticsearch index settings. That means the read-only mode block will survive a full restart of the service and that of the underlying Elasticsearch cluster and will need to be explicitly removed from all indexes to disable the read-only mode.

CLI

To manage the read-only flag, an operator can run one of the following CLI commands:

./bin/app-search --enable-read-only-mode
./bin/app-search --disable-read-only-mode

API

The read-only mode status can also be viewed and managed via a set of internal APIs:

curl -X GET 'http://localhost:3002/api/as/v1/internal/read_only_mode'
curl -X PUT 'http://localhost:3002/api/as/v1/internal/read_only_mode' -d '{ "enabled": true }' -H "Content-Type: application/json"
curl -X PUT 'http://localhost:3002/api/as/v1/internal/read_only_mode' -d '{ "enabled": false }' -H "Content-Type: application/json"

For authentication, an operator could use one of two accepted methods:

  • App Search Admin API token, e.g. -H 'Authorization: Bearer admin-xyz'
  • ES credentials used to start the App Search instance --user elastic:changeme