How Drupal search with Elasticsearch works
A Drupal site usually outgrows its built-in search when editors need faceted results across large content volumes, when relevance has to be tuned beyond what the database can offer, or when search traffic starts competing with the site's own database. At that point the team must choose a supported search backend and decide who runs it. Elasticsearch Connector provides a Search API backend for Elasticsearch, using the official Elasticsearch PHP client. Search API collects the content and fields you select, and the connector sends them to an Elasticsearch cluster for indexing and querying. Drupal does not host the cluster, so the search engine becomes another system your team must operate.
This page covers how the connector fits into a Search API setup, how content fields are mapped to index fields, how relevance is tuned, and why some teams compare OpenSearch before committing. The cluster, its Elasticsearch version and its hosting are decisions made in your own infrastructure, whether that is virtual machines, Kubernetes or an on-premises data center. Confirm the Elasticsearch versions the connector release you plan to use supports on its Drupal.org project page before you pick a cluster version, because the client library and the server must agree.
Before any build starts, decide three things: which content types and fields belong in the index, who owns the cluster after launch, and how indexing is triggered when content changes. Each choice affects effort. A small index of a few content types is very different from a multilingual index that feeds faceted listings across several sites. Ask any partner to write these decisions into the scope so that the mapping work, the cluster sizing and the operations plan are priced and tested against the same assumptions.
What you need before connecting Drupal to Elasticsearch
Connecting Drupal to Elasticsearch involves two sides that must agree: the Drupal site, with its PHP runtime, Search API and connector module, and the cluster, with its version, credentials and network path. Confirm each item below before any indexing work starts, because a mismatch on either side is the most common reason a first connection fails.
Drupal core version and PHP runtime
Choose Drupal 10 or Drupal 11 on purpose. Drupal 10 requires PHP 8.1 or later and Drupal 11 requires PHP 8.3 or later, and no supported Drupal version runs on PHP 7. Drupal 10 reaches end of life on December 9, 2026, so confirm that date against your own upgrade plan before you build an index that will need to move to Drupal 11 later. Check the PHP version on every environment, not only production.
Search API and the connector module
Search API defines the indexes, fields and processors that Drupal sends to a backend. Elasticsearch Connector supplies the backend itself and uses the official Elasticsearch PHP client to talk to the cluster. Confirm on the project page which Drupal branch each release supports, and pin the connector version in Composer rather than assuming the latest release matches your core version.
A supported Elasticsearch version
Match the cluster version to the version range listed in the connector's release notes on its project page. Do not assume that a newer Elasticsearch release is supported because it exists. Ask your team whether the cluster will be an Elastic product, and confirm the licensing terms that apply to that version before you commit to it.
A dedicated service account
Create a separate cluster user for Drupal with only the index privileges it needs: create, write, read and manage on the indexes the site uses. Avoid the built-in administrative user, and store the credentials in your secrets manager or environment configuration rather than in exported Drupal configuration. Record who owns the account and how its password or API key rotates.
Network path between Drupal and the cluster
Confirm which hosts can reach the Elasticsearch HTTP port, including web servers, cron or queue workers and any staging environments. In containerized or multi-server Drupal deployments, the workers that run indexing are often separate from the web nodes, so test from each of them. Ask your network team to document firewall rules and any proxy in the path.
TLS certificates and trust
Plan certificates for the cluster's HTTP endpoint and confirm that the Drupal runtime trusts the issuing certificate authority. Decide whether to use a private CA, how certificates are renewed, and who is notified before expiry. Test the connection with the exact hostname that Drupal will use, because a certificate valid for a different name will fail even when the network path is open.
Configuration sequence for the Elasticsearch backend
This sequence takes a Drupal site from installed modules to a verified Elasticsearch index that the site can query. Each step closes with a check so the team knows the layer below works before building on it.
Install and enable the search modules
The developer adds Search API and Elasticsearch Connector to the codebase with Composer, then enables both modules with Drush or the Extend screen in a development environment. Confirm the Elasticsearch Connector project page on Drupal.org for the release line that matches your Drupal version before you install it. The step is done when both modules show as enabled, the Search API configuration pages load, and the Elasticsearch Connector backend type appears in the server form.
Create the cluster connection
The developer creates a Search API server that uses the Elasticsearch Connector backend and enters the cluster endpoint, scheme and port, plus the credentials the site will use. Keep credentials in environment-level configuration or your secrets store rather than in exported configuration files. Confirm the cluster version with the platform team, since the Elasticsearch PHP client and the Drupal module must support it. The check is a successful connection test from the server page, with the cluster name and status visible to the team.
Create the search index
On the Search API index form, the developer links the index to the server, names it, and sets the index options that affect how documents are stored and searched. Decide early whether one index serves all languages and content types or whether separate indices are needed, because changing this later means rebuilding the index. The check is that the index appears on the server's index list with a status showing it is enabled but not yet indexed.
Choose datasources and fields
The developer selects the content types, users or other entity types to index, then adds only the fields that search users need, including titles, body text, taxonomy references and the facets planned for the search page. Map fields to the correct Search API types so text fields are analyzed and filter fields are stored as exact values. The check is a field list reviewed against the search requirements, with any unneeded fields removed before the first index run.
Configure processors
The developer enables processors such as HTML filtering, tokenization, stemming, language handling and ignored-character settings, and orders them so that text is cleaned before it reaches the index. Test the effect on a few sample nodes by viewing the indexed text where the module exposes it. The check is that sample content produces the expected tokens, and that processor order matches the plan agreed with the content team.
Run the initial index and verify counts
The developer or site operator starts the initial indexing run, either from the index page or with a Drush command in a non-production environment first. When the run finishes, compare the number of published items in Drupal with the document count the cluster reports for the index, and investigate any gap, such as unpublished items, access restrictions or failed batches. Review the index mapping in the cluster to confirm field types match the plan. The check is that counts agree within the expected exclusions and the mapping shows no unexpected dynamic fields.
Add the search view or page
The developer builds a search page or view on the Search API index, adds the exposed keyword filter, the facet blocks and the result fields, and sets sorting and pagination. Test queries against known content with expected hits, including a term that should not match, a phrase and a filtered query. The check is that each test query returns the documents the team expected, and that results respect the access rules of the site.
Mapping Drupal fields to Elasticsearch index fields
This table compares each common Drupal field type with the Search API field type it maps to, the Elasticsearch type it usually lands in, and whether it serves full-text search, facets, or filtering and access. Read each row as a decision: the same Drupal value can be indexed as analyzed text or as an exact keyword, and that choice drives both relevance and facet behavior. Confirm the final types against your Elasticsearch version and the Search API configuration before indexing production content.
| Drupal field | Elasticsearch field type | Full-text, facet or filter | Notes |
|---|---|---|---|
| Title and body text | text, with a keyword sub-field | Full-text searched | Analyzed text drives relevance; the keyword sub-field supports exact sorting and matching. |
| Entity reference (node to node) | keyword or integer | Filter, sometimes facet | Index referenced IDs or titles so filters match exactly; index titles as text only if users search by them. |
| Taxonomy term reference | keyword | Facet and filter | Index term IDs for stable facets and a separate text field for term names if searchable. |
| Date and datetime | date | Filter and sort | Use a single timezone convention and a date type so range queries and sorting behave predictably. |
| Boolean (published, promoted) | boolean | Filter | Filter on published status for every index so unpublished content never appears to anonymous viewers. |
| File or image name and extracted text | text | Full-text searched | Extracted document text needs an extraction step; confirm the attachment processor you plan to use. |
| Access control (node grants, roles) | keyword (multi-value) | Filter for access | Store the grant or role values per item so each query can restrict results to what the viewer may see. |
How relevance tuning and facets are set up
Relevance tuning in a Search API setup happens in the Search API index configuration, where the field boosts, processors and facet definitions decide what matches and how results are ordered. Field boosts raise or lower the weight of title, summary, taxonomy and body fields, so a match in a title counts for more than a match in a long body. Processors shape the text before and after it is indexed. Tokenization splits text into terms, stemming reduces words to a common root so that "install" and "installing" match, and highlighting controls which excerpt is shown with a result. Stopword handling decides which common words are dropped, and synonym lists let a search for a product code or abbreviation find the full name. Facets are configured per field in the Search API view or index, and each facet needs a field that holds clean, single-valued or deliberately multi-valued terms, such as content type, sector or publication year.
Tuning is iterative and should start from a fixed set of test queries with expected results. Write down twenty to fifty real queries from site search logs or stakeholder interviews, mark which documents must appear first for each one, and record the current order before changing anything. Each change to boosts, stopwords or synonyms is then measured against the same list, which stops the team from fixing one query while breaking three others. Changes to analyzers, token filters or field mappings usually require reindexing the content into Elasticsearch, because existing documents were stored with the old analysis. Plan that reindex as a step in the release, not an afterthought, and confirm how long it takes on a copy of production content.
Before designing the processor chain, confirm which processors, analyzers and mapping options your version of Elasticsearch Connector supports on its Drupal.org project page. Support differs between connector releases and between the Elasticsearch versions they target, so do not assume a Search API processor works until it is tested against your cluster. Also confirm how the connector maps Drupal field types to Elasticsearch field types, because a facet on a field mapped as analyzed text rather than as a keyword field will not filter as expected. Record the decisions, the test query set and the reindex procedure in the project documentation so that the next person tuning relevance can repeat the results.
Securing the connection and the index
The Drupal site and the Elasticsearch cluster trust each other with credentials, and the index holds a copy of content that may not be public. Each card below covers one control that keeps that trust narrow, from where secrets live to how the connector is patched.
Keep credentials out of the codebase
Store the cluster username, password or API key in environment variables or a secrets manager, and reference them from the Drupal configuration rather than committing them to version control. Confirm that exported configuration in the Drupal config directory contains no secret values, and that backups of the database and files are treated as sensitive because they may hold connector settings. Rotate the credential on a schedule you can document, and confirm that rotation does not require a code release.
Verify TLS on the cluster endpoint
Serve the cluster endpoint over HTTPS and configure the Elasticsearch PHP client so it verifies the server certificate against the correct certificate authority. Disabling verification to clear a connection error is the most common shortcut and should be treated as a failed check. Confirm the certificate chain includes the internal CA, that hostnames match the names Drupal uses, and that certificate expiry is monitored, since a lapsed certificate will stop indexing and search without changing any Drupal code.
Scope roles to the Drupal indexes
Create a dedicated Elasticsearch user for the connector with privileges limited to the index names and operations Search API needs, typically creating and writing to its own indexes and reading them for queries. Avoid cluster-wide administrator rights and avoid sharing the account with log shippers or other applications. Ask the team to list which index patterns the role covers and to test that the connector fails when it tries to touch an index outside that list.
Restrict network paths between zones
Place the search cluster in a network zone that accepts connections only from the Drupal web and cron hosts on the required port. Deny direct access from user networks and from the public internet, and make sure administrative access to the cluster goes through a separate path. Check the rules from both sides: the Drupal hosts should reach the cluster, and nothing else should, including containers or staging environments that copy the production configuration.
Keep private content out of the index
Search API indexes whatever the datasource and processors provide, so unpublished nodes, restricted fields and content behind access rules can end up searchable by anyone who can query the index. Decide which entities and fields are indexed, and use the access-check processors and a per-user filter at query time where visibility depends on the viewer. Test with an anonymous user and a user from each role, because a query that works for an editor can expose content to a visitor.
Patch the connector with core updates
The Drupal Security Team publishes advisories for core and contributed projects, so the Elasticsearch Connector, Search API and the Elasticsearch PHP client belong in the same update routine as Drupal itself. Subscribe to advisories for these projects, include them in staging tests after each release window, and record which versions are running in production. Ask who owns the update decision and how quickly a critical advisory can be applied outside the normal schedule.
Common failures when Drupal indexes into Elasticsearch
This table lists the failures teams most often hit when the Elasticsearch Connector sends Search API content to a cluster, with the likely cause, the fix and the log to read first. Work down the rows in order when indexing stops, because connection and authentication problems hide the later ones. Confirm exact log locations and connector settings against your own Drupal and cluster versions.
| Failure | Likely cause | Fix and first log to check |
|---|---|---|
| Connection refused or TLS verification errors | The connector's server URL points to the wrong host or port, the cluster listens only on an internal interface, or the cluster certificate is not trusted by the Drupal web and cron hosts. | Confirm the URL and port from the Drupal server with a plain HTTPS request. Add the cluster CA to the trust store used by PHP. Check the Drupal recent log messages (Reports, Recent log messages) for the cURL error text before changing the connector. |
| Authentication failures | The API key, username or password in the server configuration is expired, rotated or entered with extra whitespace, or the account lacks index create and write privileges on the target index pattern. | Test the same credentials against the cluster outside Drupal. Store secrets in your secrets manager or environment settings rather than in exported configuration. Check the Drupal log for HTTP 401 or 403 responses and the cluster audit or security logs for the rejected user. |
| Index mapping conflicts after a field type change | Search API field types changed (for example, text to string or integer to date) but the existing index keeps the old mapping, so the cluster rejects new documents with mapper parsing errors. | Plan a new index version, reindex into it and switch the search index alias when ready. Avoid editing a live mapping in place. Check the Drupal log entries from the Search API indexing step and the cluster log for mapper_parsing_exception messages. |
| Items stuck in the queue | Cron is disabled, runs too rarely or times out, or the Search API queue worker is not run by any process, so tracked items never leave the queue. | Confirm the cron schedule and that the Search API index's batch or queue settings match your volume. Run the indexing task manually once to confirm it works, then fix the scheduler. Check the Drupal log and the queue item count in the Search API index status page. |
| Results missing because of access filtering | Search API applies node access or user-based filters at query time, so content hidden from the current role is correctly excluded, but the indexed access data is stale or the search index was built without access checks. | Compare results for an anonymous user and an administrator with the same query. Reindex affected items after changing node grants. Confirm the index has the content access fields and that the processor for node access is enabled. Check the Drupal log for query errors. |
| Relevance regressions after a mapping change | A change to analyzers, field boosts, tokenizers or the choice of text or keyword fields alters scoring, so queries that worked before now rank differently or miss partial words. | Keep a fixed set of test queries with expected top results and rerun them after every mapping change. Review boosts in the Search API index settings first, then analyzer settings in the index mapping. Use the cluster search slow log and query explain output to see why scores moved. |
Questions teams ask before connecting Drupal to Elasticsearch
What drives the cost of connecting Drupal to Elasticsearch?
The cost follows the size of the search design: how many content types and Search API indexes you need, how much relevance tuning the business expects, how complex the access rules are, and where the cluster runs. Each of these adds mapping work, testing and review. Recurring costs include cluster hosting, monitoring, backups and updates to the Elasticsearch Connector module and Drupal core. Ask for a written, fixed-scope quote that lists each index, each content type, the access model, the hosting environment and what happens after launch, so you can compare the options on the same basis.
How long does a Drupal Elasticsearch project usually take?
Duration depends on scope rather than on a fixed number of weeks. A single index on a few content types with standard keyword search is a much smaller job than several indexes with facets, multilingual fields, role-based result filtering and tuned ranking. Ask the partner to show the phases, the review points and the dependencies, such as cluster provisioning and access approvals, that can hold up the schedule. A timeline should appear in the written scope, tied to deliverables, not as a general estimate.
What does our team need to provide for the work?
The work needs access to a non-production Elasticsearch cluster with credentials scoped to the indexes in use, and a named content owner who can approve field mappings and confirm which content should be searchable. Your team should also supply a set of representative test queries with the results people expect, since relevance tuning cannot be judged without them. Expect to provide staging copies of the Drupal site, network routes between Drupal and the cluster, and a decision on who signs off each release.
Can our internal team build this without a partner?
Yes, if you have a developer comfortable with Drupal configuration and Search API, and someone who can operate Elasticsearch. The Elasticsearch Connector module provides the Search API backend using the official Elasticsearch PHP client, so the core integration is standard Drupal work. The harder parts are index design, relevance tuning and running the cluster safely. Whether to build in-house or hire help depends on how many people you can spare, how quickly you need results and whether the search work will be maintained by the same team afterward.
What breaks most often in Drupal Elasticsearch integrations?
Most failures come from mismatched field mappings, indexes that drift from the content model after a Drupal change, and access rules that are applied in the interface but not in the query. Other common problems include cluster version incompatibility, unmonitored disk pressure and indexing jobs that fall behind during bulk updates. Ask the partner how each index is rebuilt, how mapping changes are versioned, and how test queries are rerun after every release so regressions are caught before users see them.
Does the access model need extra work for restricted content?
Yes. If some content is visible only to certain roles, departments or customers, the index must carry the fields needed to filter results, and the query must enforce those filters every time. Ensure that unpublished, restricted or private content never appears in the index unless it is filtered out at query time. Ask for a written list of the roles and content visibility rules, and a test plan that checks results for each role, because a configuration error here can expose data.
Should we host Elasticsearch or choose OpenSearch instead?
The choice depends on licensing, support and the features you need. The Elasticsearch Connector is the module that uses Elasticsearch as a Search API backend, while OpenSearch is distributed under the Apache License, Version 2.0, and its FAQ describes no paid edition. The OpenSearch FAQ also says it is a fork of Elasticsearch 7.10, so compatibility decisions need testing against the exact versions you run. Compare the licence terms of your target Elasticsearch release with your own legal review, and confirm module support for the backend you select before committing to a cluster.
When teams choose OpenSearch instead
The main reason teams look at OpenSearch is licensing. OpenSearch is released under the Apache License, Version 2.0, and the OpenSearch FAQ does not describe any paid edition of the software. Before you choose, confirm the current license terms of the Elasticsearch version you plan to run, including any subscription, feature tier or redistribution conditions that apply to your organization. Those terms change over time, so record the version you checked and the date you checked it, and have your legal or procurement team sign off on the result.
OpenSearch is a fork of open source Elasticsearch 7.10, and the OpenSearch Dashboards project derives from Kibana 7.10.2. It is governed under the OpenSearch Software Foundation, a Linux Foundation project, although the Foundation is not involved in the technical oversight of the project itself. Its wire compatibility with Elasticsearch 7.10 means many client patterns carry over, but that compatibility does not extend to every Elasticsearch release. Confirm which Elasticsearch version your Drupal site and the Search API stack actually target before you assume the two clusters behave alike.
Choosing OpenSearch changes the Drupal side too. The OpenSearch integration for Search API is a separate contributed module with its own server configuration, index mapping and setup, so you cannot simply repoint an Elasticsearch Connector server to a new cluster. Budget for a full reindex and a review of query behavior, including analyzers, facets and relevance boosts, because switching backends later affects result ordering and any tuning you have already done. Treat the backend choice as a one-time architecture decision and test it on a copy of your content before it reaches production.
How DeployOpen scopes and delivers Drupal search with Elasticsearch
DeployOpen plans, builds, documents and supports Elasticsearch as a Search API backend inside infrastructure you control. Engagements are fixed-scope, with the index design, field mapping, relevance tuning and handover agreed in writing before build work starts. Ongoing support and upgrades are available as a retainer.
How we scope
- Inventory the content types, fields, taxonomies and access rules that the Elasticsearch index must reflect.
- Confirm the Elasticsearch version, hosting model and whether the cluster is licensed and supported in your environment.
- Record the written scope: index design, search views, relevance goals, environments, deliverables and acceptance tests.
How we build
- Configure the Elasticsearch Connector backend and Search API indexes in a development environment, with mappings version-controlled.
- Tune analyzers, field boosts and facets against a representative query set agreed with your editors and users.
- Test indexing on content changes, cron or queue behavior, reindexing and failure handling before any production cut-over.
How we hand over
- Deliver the configuration as code, with index mappings, Search API settings and environment notes documented for your team.
- Run a joint walkthrough of reindexing, adding a field to the index and diagnosing an empty or stale result set.
- Provide runbooks covering cluster access, credentials, backups and the steps for moving the search index between environments.
How we support
- Offer retainers for monitoring, Drupal and Elasticsearch upgrades, relevance review and security patching on a planned schedule.
- Track Drupal core releases, including the security release window, and test the search module stack against each update.
- Confirm with your team which Elasticsearch or OpenSearch version and support window you will run, and plan upgrades against it.
