Drupal search with OpenSearch

Drupal search with OpenSearch: how the integration works and when to choose it

When core or database search no longer meets a Drupal site's needs, the decision is which self-hosted search backend to run. The supported method is the Search API OpenSearch module, which indexes Search API indexes into an OpenSearch cluster that your organization runs in infrastructure it controls. Search API handles the content sources, fields, processors and query building inside Drupal, and the OpenSearch module handles the connection and index operations against the cluster. Before you plan around it, confirm on Drupal.org which Drupal core versions the module supports for your target release, because module support can lag core releases. OpenSearch is released under the *Apache License, Version 2.0*, and the OpenSearch FAQ does not describe a paid edition of the software. It is a fork of open source Elasticsearch 7.10, and it is wire-compatible with that version, which is why teams coming from Elasticsearch often evaluate it. The licensing difference is the main reason some teams choose it over Elasticsearch. Choosing it over Solr is a team decision, not a default: weigh your team's existing Solr operations skills, the search features your site relies on, and the cluster support model you want, then document that reasoning so later upgrades have a clear basis.

Ask your team and your integrator to confirm three things early. First, the exact OpenSearch version you will run, checked against the module's stated compatibility and the OpenSearch releases page, since versions move on a fixed minor-release cadence. Second, whether your cluster must be reachable from the web tier, the Drupal workers or both, because that shapes network and TLS design. Third, who owns cluster patching and upgrades after launch, since a search cluster that falls behind its maintenance window becomes a security exposure of its own.

What you need before connecting Drupal to OpenSearch

Connecting Drupal to OpenSearch touches the Drupal codebase, a search cluster you operate, the network between them and the accounts that bind them. Settle these six items before any indexing work starts, because each one changes the module versions, the TLS setup and the access model you build.

A supported Drupal release

Start on Drupal 11, the current major version, which requires PHP 8.3 or later. Drupal 10 reaches end of life on December 9, 2026, so a Drupal 10 site that will connect to OpenSearch now also needs an upgrade plan. Check your PHP runtime and extension versions against the requirement before installing anything. Confirm which Search API and OpenSearch module releases support your Drupal version on Drupal.org.

A running OpenSearch cluster

Choose the OpenSearch version you will run and the window in which you will patch it. Versions stay in maintenance for a limited period and then reach end of life, so pick a release line with a clear support horizon. Decide who owns cluster upgrades, how often they happen and how indices are reindexed when mappings change. Confirm the install method your team will operate, such as containers, Kubernetes or packages.

Network paths and TLS certificates

Drupal web and cron nodes must reach the OpenSearch HTTP port, and the cluster must accept those connections through your firewall and load balancer rules. Plan TLS for client traffic, including which certificate authority issues it, how Drupal trusts that authority and how renewal is handled. Test the path from every Drupal node, not only from one workstation, because queue workers and cron often run on different hosts.

Least-privilege service accounts

Create a dedicated OpenSearch user for Drupal rather than reusing an administrator login. Grant it only the index and document permissions needed to create, update and query the Search API indices. Keep the credential in your secrets store, not in settings files committed to Git. Use role-based access control and, where content is sensitive, document-level or field-level security to limit what each search user can see.

Search API and the OpenSearch module

Install Search API and the OpenSearch module with Composer so that versions are pinned in composer.json and composer.lock and move through your normal release process. Confirm that the module release you choose declares compatibility with your Drupal core version and that its OpenSearch client library supports your cluster version. Enable the modules in a non-production environment first and keep the module set in configuration under version control.

A decision on Drupal 7 sites

If any site in scope still runs Drupal 7, decide before this work starts whether it migrates first. Drupal 7 security support ended on January 5, 2025, and Drupal 6 and 7 sites cannot be updated in place to current versions. Migration creates a new site and rebuilds the theme, so search settings and index definitions will be recreated rather than carried over. Teams that must stay on Drupal 7 for a period should ask an extended support provider listed on Drupal.org how they will cover that gap.

How Search API maps Drupal fields onto OpenSearch indexes

A Search API index is the contract between Drupal and OpenSearch. In Drupal, you choose the entity types and bundles to index, select the fields to send, and assign each field a Search API data type such as text, string, integer, date or a reference. Processors then transform the values before they leave Drupal: HTML is stripped, text is tokenized, stop words may be removed, and entity references are resolved into the labels a search user will actually type. Those steps decide what OpenSearch stores and what it can match, so the index definition deserves the same review as a database schema. Ask your team to list every field a user will search, filter or sort on, and confirm with the Search API OpenSearch module documentation on Drupal.org how each data type is written to the OpenSearch mapping.

The costly decisions are the ones made early. A field indexed as a string cannot be searched for words inside it, a field indexed as text is analyzed with the analyzer you configure, and a date stored in the wrong format will silently break range filters. Facets and More Like This both depend on this design. A facet needs a field that is stored in a form suitable for aggregation, and More Like This compares the terms of the source document, so the fields you choose to include in the index determine the quality of the suggestions. Changing a field type, analyzer or tokenization rule usually means creating a new index mapping and reindexing all content, which takes time on large sites and must be planned against your release process. Before design starts, confirm which facet types and More Like This options the module supports on Drupal.org and whether they work with your OpenSearch version.

Setup sequence: from cluster to verified Drupal search

This sequence takes a team from an empty OpenSearch cluster to a Drupal site that indexes content, serves facets and similar-content results, and can be promoted to production with a tested rollback. Each step ends with a check that tells the next step is safe to start.

Size and install the OpenSearch cluster
The platform or infrastructure team chooses an installation method from those OpenSearch documents, such as Docker, Helm, the Kubernetes Operator, tarball, RPM, Debian packages or the Ansible playbook, and sizes nodes, storage and heap for the expected document count and query load. Confirm the exact OpenSearch version against the current releases page and the maintenance status of each version before you pin it. The step is done when every node joins one cluster and the cluster health endpoint reports green in the staging environment.
Enable TLS and create Drupal roles
The security engineer enables TLS for node-to-node and client traffic, then creates a dedicated service user for Drupal with a role limited to the index patterns that Drupal will write and read. Decide early whether the Security plugin's role-based access control, document-level security or field masking is needed for your content, and document that decision. The step is done when Drupal's credentials authenticate over HTTPS, and a request to an index outside the role's scope is refused.
Install Search API and the OpenSearch module
A Drupal developer installs Search API and the OpenSearch module with Composer in a staging copy of the site, pinning versions in composer.json and committing the lock file. Check the module's Drupal.org project page for its supported Drupal core versions before you run the install. The step is done when the modules are enabled, the Search API admin pages load and the site's status report shows no errors for the search dependencies.
Create the server and index configuration
The Drupal developer creates a Search API server that points to the cluster endpoint and the Drupal service user, then creates an index tied to the content types and entities the site will search. Store the credentials in environment configuration or a secrets manager rather than in exported configuration. The step is done when the server's connection test succeeds and the index appears in the OpenSearch cluster with the expected settings.
Map fields and set processors
The search lead maps each Drupal field to an index field with an explicit type, such as text for body copy, keyword for facet values and date for publication dates, and sets processors for tokenization, HTML stripping, language and access checks. Review the mapping before the first full index, because changing field types later usually means rebuilding the index. The step is done when a sample node's indexed fields match the mapping sheet, and the sample's facet and text values appear as expected in the index document.
Configure facets and More Like This
The search lead adds facets to the search view for the fields that editors and visitors need to filter on, then configures the More Like This block or query on the fields that best describe similar content. Test relevance with a small set of real queries agreed with the content owners. The step is done when each facet returns the correct counts for a test filter and the similar-content block returns relevant items for three or more sample pages.
Run the initial index and confirm counts
The developer runs the initial indexing batch with Drush or the Search API admin screen, then compares the count of published, searchable Drupal entities with the document count in the OpenSearch index. Investigate any gap, including unpublished items, excluded bundles and entities that failed a processor. The step is done when the counts reconcile, the error log for the batch is clean and a search from the front end returns the expected results.
Promote to production with aliases and rollback
The platform team creates the production index behind an alias so Drupal queries the alias rather than a fixed index name. They rebuild into a new index, switch the alias when counts and tests pass, and keep the previous index until the new one has run stably, so the alias can be pointed back if needed. Rehearse the switch and the rollback in staging first. The step is done when the rollback has been tested end to end and the runbook names the owner of each action.

Mapping Drupal content, facets and roles to OpenSearch

This table compares each kind of Drupal source data with the Search API field or processor that carries it, the OpenSearch field type or setting it lands in, and the decision it forces. Read it before the index is built, because changing a mapping later usually means reindexing. Exact option names for Search API OpenSearch and the target OpenSearch version must be confirmed against the module and the cluster release you plan to run.

Drupal source	Search API field or processor	OpenSearch field type or setting	Decision it drives
Full-text body fields (body, abstracts, rendered text)	Rendered text field with text processors such as HTML filter and tokenizer, boosted by field weight	Analyzed text field with a language-appropriate analyzer	Whether to index rendered output or raw fields, and which analyzer handles stemming and stop words
Faceted taxonomy references (terms, tags, categories)	Entity reference with the taxonomy term label processor, plus term ID field for filters	Keyword field for exact term IDs and labels, separate from the analyzed text copy	Whether facets filter on IDs (stable across renames) or on labels (readable but fragile)
Date fields (published, updated, event dates)	Date field with the Search API date processor, or timestamp conversion	Date type with a stated timezone and format	Whether date range facets use UTC or site timezone, and how unpublished or empty dates sort
Language	Language field and per-language index or field suffix, depending on design	Keyword language field, with analyzers chosen per language	Whether one index serves all languages with per-language fields or each language gets its own index
Permission filtering (node access, roles, unpublished content)	Access-aware index with node access and user-role fields stored as keyword values, applied as query filters	Keyword fields for roles or groups, filtered in every query	Whether the search layer enforces access itself or only indexes published public content; confirm how OpenSearch Security roles relate to Drupal permissions
Numeric and boolean flags (price, status, featured)	Integer, float or boolean fields from the Drupal entity	Numeric or boolean type, with mapping set before first index	Which fields can be used for sorting and range facets without reindexing
Media and attachment text (extracted file content)	Field from an extraction processor, if the attachments module is used	Analyzed text field, sized for large documents	Whether extracted file text is indexed at all, and who reviews it for sensitive content

Securing the OpenSearch cluster behind Drupal search

A Drupal search index usually holds content that is public, internal or restricted, so the cluster needs the same care as any other data store. The controls below work together: encryption and network isolation protect the transport, role-based access limits what Drupal can do, and audit logs show who changed what. Each one needs a decision about your environment before the build starts.

TLS for node and client traffic

Enable TLS on both the transport layer between cluster nodes and the HTTP layer that Drupal's Search API connector calls. Without it, index content and credentials travel in clear text inside your network. Confirm which certificate authority issues node and client certificates, how certificates are renewed, and whether the Drupal host trusts that authority. Plan the renewal procedure before the first production certificate expires, since a lapsed certificate stops search for every site that depends on it.

Drupal holds only the index privileges it needs

Create a dedicated OpenSearch role for the Drupal site that grants access only to its own index pattern and the actions the connector uses, such as indexing, updating and searching. Do not reuse an administrator account or a role that can delete indices or change cluster settings. Review the role whenever the connector or the index naming changes. A Drupal compromise then exposes only the search index, not the rest of the cluster.

Separate credentials per environment

Give development, staging and production their own cluster users and passwords, and keep them out of settings.php, Git repositories and exported configuration. Store them in a secrets manager or in environment variables injected at deployment, and rotate them on a schedule your security team sets. Ask your Drupal hosting team how the connection settings are deployed, because copying a production database to a lower environment can also copy a working search credential.

Document and field restrictions for restricted content

Where some indexed content is restricted, such as internal memos or unpublished case data, use document-level security to limit which roles see which documents, and field-level security or field masking to hide sensitive fields from roles that may search the rest of the record. Map these roles to the groups that already govern access on the Drupal side. Test the rules with a user from each group, because a field that is hidden in the index may still appear in a result snippet if the template renders it.

Audit logs for administrative and query activity

Turn on audit logging in the Security plugin so administrative actions, authentication events and, where your policy requires it, search requests are recorded. Decide which events go to a central log store, how long they are kept and who may read them. Review the log configuration after each upgrade, because the volume of query logging can affect storage planning. Logs are only useful if someone checks them, so name the owner of the review.

Network isolation from the public internet

Place the cluster on a private network segment reachable only from the Drupal application servers, the administrator bastion and the monitoring system. Do not publish port 9200 or the Dashboards interface to the internet, and restrict access to Dashboards through your VPN or identity-aware proxy. Confirm that anonymous search requests from the public site go through Drupal, not directly to OpenSearch. Verify the isolation with a scan from outside the approved network as part of acceptance testing.

Choosing how to install and run the OpenSearch cluster

Docker is the fastest way to prove that Drupal can reach an OpenSearch endpoint, that Search API OpenSearch maps your fields as expected and that facets and More Like This behave well on sample content. The installation is quick, but a container started by hand is not a production operating model. Teams usually run it on a single host, keep configuration in a Compose file and treat the data as disposable.

Operator: usually the Drupal developer or a platform engineer working in a non-production environment.
Patching: image tags must be updated by hand, so align them with the maintenance releases listed on the OpenSearch releases page.
Backups: snapshots are often skipped in labs, which is acceptable only if the index can be rebuilt from Drupal content.
Capacity: host resources are shared with other services, so memory limits and disk growth need explicit watching.
Security settings: confirm whether the security plugin is enabled and how demo certificates are replaced before any real content is indexed.

Before a pilot becomes a shared environment, confirm with your team which of these steps will be rebuilt as code and who owns the snapshot repository.

Testing relevance, facets and upgrades before go-live

Before go-live, verify the integration in four layers: index completeness, relevance, facets and access control. Start with a clean reindex in staging: delete the Search API index, rebuild it from scratch, and compare the indexed item count per datasource against the number of published, indexable entities in the database for each content type and language. Discrepancies usually point to excluded bundles, unpublished content that the processors include, or failed batches visible in the Drupal logs. Next, run a fixed set of known queries (for example, a product name, a policy number and a misspelling) and record the expected top results agreed with the content owners. Store the list in version control so the same checks run again after every mapping change in the Search API index configuration. Treat any drop in the expected result as a regression to explain before launch, not a tuning detail to fix later.

Facet verification is a direct comparison. For a sample of values on each facet, such as a taxonomy term or a content type, count the matching nodes with a database query or a Views preview on unindexed filters and compare the result with the facet count returned by OpenSearch. Check multi-value fields and multilingual content separately, because duplicated or missing language rows often explain mismatched counts. Spot-check More Like This output on representative content: short pages, long articles, and items with few tags, since recommendations are weakest where the content has little shared text. Permission-filtered results need a test with a user in each role that matters to your organization, including anonymous users, and a check that restricted items never appear in results, counts or facets for those roles, not only in the rendered page. Upgrades need their own rehearsal. OpenSearch ships a new minor version about every eight weeks according to the project's release page, and maintenance versions receive bug fixes and security patches but no new features. That cadence means a cluster will be patched often, so the process should be routine. Rehearse a minor upgrade in staging with a snapshot taken first, then rerun the query set and facet checks against the upgraded cluster. Confirm with the vendor and your platform team which upgrade path your installed version supports, and check the Drupal 11 and OpenSearch module compatibility notes for the Search API connector release you run before you schedule the production window.

Common OpenSearch and Drupal search failures and their fixes

This table pairs each common symptom in a Drupal site using Search API with OpenSearch with its most likely integration cause and the fix to try first. Read it as a triage list: start from what users or editors see, check the cause column against your configuration, and confirm each fix in a staging copy before changing production. Most of these failures trace back to the Drupal side of the connection rather than the cluster itself.

Symptom	Likely cause	Fix
Index never updates after content is saved	Search API indexing is disabled for the index, or the queue is not processed because cron or the queue worker is not running	Confirm the index is enabled and tracking changes, check that cron or a scheduled Drush job processes the search indexing queue, and run a manual index batch to compare results
TLS handshake fails between Drupal and the cluster	The certificate chain is incomplete, the CA is not trusted by the PHP process, or the hostname in the connection URL does not match the certificate	Install the full chain on the cluster endpoint, point the client at a CA bundle the web user can read, and make the connection host match a subject or SAN entry
Facets are empty or show wrong values	The field is not indexed as a type that supports faceting, or the field mapping changed without reindexing the content	Set the field's data type and facet option in the index, clear and rebuild the index, then check the mapping on the cluster matches the Drupal field definition
Reindex fails with mapping conflicts	A field changed type in Drupal (for example text to entity reference) while the existing index still holds the old mapping	Create a new index version with the updated mapping, reindex into it, switch the Search API server or index to the new target, and remove the old index after verification
More Like This returns weak or unrelated results	The comparison fields are too few, too short or not the body and title fields editors expect, or content is too thin to match	Choose fields with meaningful text for the similarity query, tune the minimum term and document frequency settings, and test with a sample of real nodes before release
Search results include content users should not see	The index has no access or role filter, or the query path skips the Search API access check, so restricted entities are returned	Enable content access processing on the index, index the access-related fields, and verify with test accounts of each role that restricted items are absent from results and suggestions
Cluster health warnings after a version change	A contributed or custom plugin is not compatible with the new OpenSearch version, or the upgrade was not rehearsed against a copy of the index	Check the OpenSearch release and plugin compatibility before upgrading, rehearse the upgrade on a restored copy of the cluster, and reindex or re-verify Search API queries before cutover

Questions buyers ask before connecting Drupal to OpenSearch

What does it cost to connect Drupal to OpenSearch?

The cost depends on the scope of the written work, not on a standard package. OpenSearch itself is released under the Apache License, Version 2.0, and the OpenSearch FAQ does not describe a paid edition, so the software line item is usually the infrastructure you run it on. Your quote will separate the one-time work (Search API configuration, index mapping, facets, More Like This, testing and handover) from recurring costs (hosting, storage, patching and any support retainer). The main drivers are the number of indexes, content volume, facet and language complexity, and whether the cluster runs in your cloud account, a data center or an air-gapped network. Ask for each cost component to be listed on its own line.

How long does an OpenSearch search integration take?

Duration follows from the same drivers as cost: how many indexes and content types are in scope, how many languages must be searched, how complex the facets are, and how many environments the cluster must span. Smaller projects with one index and a few facets move faster than multilingual estates with several indexes and access rules. Most engagements are fixed-scope, so the timeline is agreed in writing before work starts and should show the stages for mapping, indexing, relevance testing, cutover and handover. Ask the team to tie each milestone to a deliverable and to name the dependencies on your identity, network and hosting teams.

What does our team need to provide for the work?

Expect to supply access and decisions rather than code. You will need a named owner for search requirements, a content owner who can confirm which fields and content types must be searchable and facetable, and a platform owner who can provide the OpenSearch hosts or cloud accounts, network paths from the Drupal servers, TLS certificates and secrets storage. Someone must also decide who may see which content, because OpenSearch Security supports role-based access control, document-level and field-level security and audit logs. Without those decisions, index mapping and access rules cannot be finalized.

Can our own team build this without a partner?

Yes, if your team has Drupal development experience, operates search clusters and can own the result after launch. The Search API OpenSearch integration is configured through Drupal's administrative interface and code, and OpenSearch can be installed with Docker, Helm, the OpenSearch Kubernetes Operator, tarball, RPM, Debian packages or an Ansible playbook. The hard parts are usually relevance tuning, mapping decisions that are costly to change later, and running a cluster with patching and backups. Ask a partner to scope only the parts you lack, and write down who owns each piece at handover.

Why choose OpenSearch instead of Solr or Elasticsearch?

The decision is mostly about licensing, lineage and operating model. OpenSearch is a fork of open source Elasticsearch 7.10, and OpenSearch Dashboards derives from Kibana 7.10.2. All software in the OpenSearch project is released under the Apache License, Version 2.0, and the project is governed by the OpenSearch Software Foundation, a Linux Foundation project. Solr is a separate project with its own release line and governance. Elasticsearch is available under licenses that differ from OpenSearch's, so check current terms with the vendor. Compare the search features you need, your operations skills and your support options before deciding. The Drupal side is the same Search API layer either way, so the choice does not change how content is modeled.

How do OpenSearch upgrades and Drupal upgrades affect each other?

They are separate release trains, so each upgrade needs its own compatibility check. OpenSearch targets a new minor version about every eight weeks, and each version stays under maintenance until the next major version enters maintenance or one year passes, whichever is longer. During maintenance it receives bug fixes and security patches but no new features. Drupal core has its own schedule: bugfix releases on the first Wednesday of each month, security releases on the third Wednesday, and new majors about every three years. Plan the Search API module, the OpenSearch client and the cluster version together, test indexing and queries on a staging copy, and schedule the cluster move so index compatibility is confirmed first. Ask the partner to show the upgrade order and rollback steps in the quote.

What should a fixed-scope quote for this work list?

A fixed-scope quote should list each deliverable with its acceptance test, so you can see what is included and what is excluded. Ask for the content types and fields in scope, the number of indexes, the facet and sort list, language handling, More Like This placement, the hosting model and the cluster topology, and the access rules to be enforced in OpenSearch Security. It should also state the testing approach for relevance and access, the handover documentation, the training included, the post-launch support options and any retainer for patching and upgrades. Confirm which items the quote excludes, such as content cleanup or front-end design, and ask who holds the runbooks and credentials at the end.

How DeployOpen scopes, builds and supports Drupal search with OpenSearch

DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, and Drupal search with OpenSearch follows the same method. The work starts with a written scope, moves through a tested build and ends with documented handover and an optional support retainer.

How we scope

Review the Drupal content types, fields and search views that need indexing, faceting and More Like This
Confirm where the OpenSearch cluster will run, who operates it and which network zones can reach it
Agree the index mapping, access rules and relevance expectations in writing before build work begins
Document the Drupal, Search API and OpenSearch versions the scope targets and the upgrade path they require

How we build

Configure the Search API OpenSearch connection, index mapping and field processors in a version-controlled Drupal codebase
Build facet and More Like This views, then test result relevance against representative content sets
Enable TLS for node and client traffic and apply role-based access controls through the OpenSearch Security plugin
Verify reindexing, cron-driven updates and failure behavior in a staging environment that mirrors production

How we hand over

Deliver written runbooks covering cluster sizing, snapshots, index rebuilds and common indexing errors
Document the index schema, Search API configuration and custom code so your team can maintain it after launch
Walk your engineers through monitoring, audit log review and the steps for adding fields or changing mappings
Record the decisions made during scoping, including why OpenSearch was chosen over Solr or Elasticsearch

How we support

Offer ongoing support, upgrades and continuous testing as a retainer after handover, agreed in writing
Plan OpenSearch minor and maintenance upgrades alongside Drupal security release windows
Confirm with your team which OpenSearch release line you run, since maintenance support ends on a published schedule
Re-test search relevance and access controls after each Drupal or OpenSearch upgrade before moving to production

Drupal search with OpenSearch