How Drupal search inside PDFs works with Search API attachments
If users cannot find a policy because the answer sits inside a PDF or Word file, the fix is to index the text of those files, not just their titles and metadata. The Search API attachments module (search_api_attachments) does this for Drupal: it extracts text from file attachments such as PDFs and office documents and adds that text to a Search API index, so a query can match words inside the file and return the node that carries it. The module's 10.0.13 release supports Drupal ^10.3 or ^11, so that is the version line to plan around for a new build.
The module does not read binary formats on its own. It hands each file to an extraction service, and Apache Tika is the service most often used for this job. In a typical design, Drupal stores the uploaded file, the extractor returns plain text, and Search API stores that text in the index alongside the node fields. Confirm with the module documentation which extractor types and versions your release supports, how the extractor is reached (local binary or HTTP service), and which file types are covered, because support for scanned images, password-protected files and older office formats depends on the extractor and its configuration.
Decide early which fields and file types enter the index, and who may find which documents. Indexed text is only as safe as the access rules applied at query time, so confirm that your search backend filters results by the same node access and file permissions that protect the original document. Plan for re-indexing when the extractor or its version changes, and for how long extracted text is retained. Each of these choices sets the size of the index, the cost of running the extraction service, and the work needed to test the result before a policy portal goes live.
What you need in place before indexing attachments
Attachment indexing depends on the Drupal version, the search backend, the extraction service and the file layer working together. Check each of these before you configure fields, because a gap in one usually appears as empty or missing search results rather than a clear error.
Drupal version alignment
The Search API attachments 10.0.13 release supports Drupal ^10.3 or ^11, so the site must already run one of those lines before the module is added. Drupal 7 and older sites must be migrated into a new site first, because they cannot be updated in place and their themes must be rebuilt. Confirm PHP and database versions against the Drupal system requirements for your target core version, since they set the baseline for the extraction workload.
Existing Search API backend
Attachment text is added to an index that already exists, so the team needs a Search API server it already operates, such as Solr, OpenSearch or a database backend. Confirm who owns that cluster, its sizing, backups and upgrade schedule, because extracted text can increase index size significantly. Decide early whether document text will sit in the same index as nodes or in a dedicated index.
Reachable Apache Tika service
Apache Tika runs as a separate Java service that Drupal calls over the network to extract text from PDFs and office files. Plan the Java runtime version, the host or container, and the network path from the web and cron nodes to the Tika port, including any firewall or service mesh rules. Confirm the Tika version and its supported file formats with the Apache Tika project before you size the service.
File storage and private access
Document libraries usually store uploads in the private file system, and the extraction step must be able to read those files without exposing them publicly. Check the file system path, permissions for the web user and the container volume, and whether files live on shared or object storage. Test that an unpublished or access-restricted document is not indexed for users who cannot view it.
Cron and queue capacity
Extraction is slow compared with indexing plain fields, and large libraries can create long backlogs during the first full index. Confirm that cron or a queue worker runs often enough, has time limits that allow large files to finish, and does not compete with page traffic. Ask the team who will watch failed items and how retries will be reported.
Security and extraction scope
Extraction services parse untrusted files, so the Tika service should run in a restricted network segment with no internet egress and with limits on memory and processing time. Agree which file types, maximum sizes and user upload roles are allowed before go-live. Record these decisions so reviewers can trace which content is searchable and why.
How to configure attachment indexing step by step
This sequence takes a Drupal site from a bare Search API setup to a verified index in which the text inside uploaded PDFs and office files is searchable and respects the access rules of the content that carries them. Each step ends with a check you can run before moving on, so problems surface while the scope is still small.
Confirm the module and dependency versions
Before installing anything, confirm that your Drupal core version is supported by the Search API attachments release you plan to use. The 10.0.13 release supports Drupal ^10.3 or ^11, so a site on an older core needs a version decision first. Confirm the Search API and file-related dependencies that the release requires, and record the PHP version against the Drupal PHP requirements. Done when the target versions are written down in the project plan and agreed with the site owner.
Install the module and dependencies with Composer
Require the Search API attachments module and its dependencies through Composer in the project's codebase, not by copying files into the webroot. Run the install on a development environment first, then enable the module and its Search API dependencies with Drush. Commit the updated composer.json and composer.lock so the change is reproducible on staging and production. Done when
drush pm:listshows the module enabled andcomposer showreports the expected version.Deploy and verify the Tika service
Deploy Apache Tika as a separate service in infrastructure you control, reachable from the Drupal web and cron hosts but not from the public internet. Confirm the exact Tika server build and the Java runtime it needs with your extraction vendor or the module documentation, because these details change between releases. Send a sample PDF and a sample Word file to the service over HTTP and check that plain text is returned. Done when both samples return readable text and the service logs show the requests were processed.
Point the module at the extraction service
In the module settings, enter the Tika server address and any timeout and file size limits your environment requires. Set the limits deliberately, since very large or malformed files are the most common reason extraction fails or stalls indexing. Store the endpoint in environment configuration rather than in exported site config where that is required by your deployment standards. Done when the module's status or a test extraction from the admin interface returns text for a sample file.
Add the file field to the Search API index
Open the Search API index for your content type or media entity, and add the file or media field that holds the uploaded documents. Map the file field to the attachment datasource so the extracted text is attached to the parent content item. Keep the title, summary and taxonomy fields in the index so that document metadata and extracted text are searched together. Done when the index field list shows the attachment field and the index status reports the expected number of items.
Set processors and field types for search
Enable the processors that handle extracted content, such as text tokenization and content access checks, and assign the attachment field a fulltext type so it contributes to relevance. Decide whether extracted text should be weighted below titles and summaries, and document that choice for the search team. Avoid indexing raw binary content or unused fields, as these add cost without improving results. Done when a saved index configuration is exported and reviewed, and the field boost values match the agreed relevance design.
Run a test index on a sample set
Choose a representative sample of PDFs and office files, including at least one scanned or image-heavy PDF, one password-protected file if your portal allows them, and one large file. Index only that sample first, then review the Search API index status and the Drupal and Tika logs for extraction errors. Check the logs for a line confirming successful extraction for each sample file. Done when every sample either returns extracted text or fails with a logged reason that you have assessed.
Verify search results, permissions and access
Run test queries that contain phrases known to appear inside specific sample documents, and confirm that the parent content is returned with the expected ranking. Log in as users with different roles and check that restricted documents do not appear in their results, because extracted text must follow the access rules of the parent content. Also confirm that unpublished or revoked items drop out of the index after changes. Done when expected phrases return the right items for each test role and no restricted content leaks into results.
Which file fields and metadata map into the search index
This table compares the source fields that can feed a Search API index for uploaded documents, what each one contributes to search, and how access is inherited. Read it as a checklist to confirm in your own module version before you build the index. The main takeaway is that extracted text is only as trustworthy as the access rules on the parent entity and file.
| Source field | What it contributes to the index | Access and notes |
|---|---|---|
| File entity | Links each indexed item to the stored PDF or office file and its parent record | Confirm the file entity is indexed as its own datasource or through its parent node in your version |
| Extracted text | Plain text produced by the extraction service, searched as full text | Depends on the extraction service handling scanned or image-only pages; test with representative files |
| File name | Matches on document titles when names are meaningful | Often weak for relevance; consider boosting only if names follow a controlled convention |
| MIME type | Lets you filter results to PDFs, Word or spreadsheet files | Confirm the field is exposed to facets in your configured index |
| Parent node title | Carries the policy or record title into file matches | Useful when files are attached to policy pages rather than searched alone |
| Taxonomy terms | Supports facets such as department, policy owner or document type | Terms on the parent node must be added to the index explicitly |
| Access and publish status | Determines whether unpublished or restricted documents can appear in results | Confirm that node access grants and file permissions are enforced at query time, not only at display |
Securing the extraction path and the documents it reads
Text extraction turns uploaded files into searchable content, so the extraction service, the file queue and the index all inherit the sensitivity of the documents. The cards below cover network exposure, input limits, access rules, personal data in the index and a patch cadence that covers both Drupal and Tika.
Keep Tika off public networks
Run the Tika server on a private network segment that only the Drupal application servers and the indexing workers can reach. It accepts raw document bytes and returns extracted text with no authentication built in, so an exposed instance can be used to push arbitrary files through a parser. Confirm the listening address, firewall rules and any reverse proxy in front of it, and test from outside the segment to prove the port is closed.
Limit file types and sizes
Decide which MIME types are sent for extraction and reject everything else before it reaches the service. Set a maximum file size in Drupal's file validation and a matching limit on the extraction side so one oversized or malformed file cannot exhaust memory or hang a worker. Parsers are a common source of vulnerabilities, so review which formats your portal truly needs, such as PDF and common office formats, and leave out legacy types you do not use.
Respect private file access
Files in the private file system are served through Drupal's access checks, but the extracted text lands in the search index, where node or file access rules must still apply. Check that the Search API attachments configuration indexes text under the same access conditions as the parent entity, and that a user without permission cannot see a snippet through search results, facets or autocomplete. Test with at least one restricted document and one anonymous user.
Protect personal data in extracted text
Policies, forms and case files often contain names, addresses or identifiers that become searchable once extracted. Decide which fields and files are indexed, set retention for the index and any cached extraction output, and document who can query it. Removing a source file should also remove its extracted text from the index, so confirm that deletion and reindexing behave as your records policy requires.
Patch Drupal and Tika on a schedule
Drupal bugfix releases come out on the first Wednesday of each month and security releases on the third Wednesday, so schedule Drupal and contributed module updates against those windows. Track Tika and its parser library releases separately, because a Drupal update does not patch the extraction service. Test each update in staging with a sample document set, then roll it out with the Tika container version pinned in your deployment record.
Why extraction quality varies across real document libraries
Extraction quality will differ from file to file, so the scope should be set by testing your own library rather than by assumptions about how Tika handles PDFs. Search API attachments passes each file to the extraction service, which returns whatever text it can recover, and the indexed result is only as good as that text. Four kinds of file reliably behave differently: scanned PDFs without a text layer, which return little or no text unless optical character recognition is part of the pipeline; password-protected files, which the extractor may refuse to open; corrupt or truncated uploads, which can fail partway through; and very large files, which can exhaust memory or hit timeouts in the extraction service.
Build a representative sample before you commit to a scope. Pull a set of files from each document type and source system in your library, and include the awkward cases on purpose: a batch of scanned policy scans, files from older office suites, documents with embedded images or tables, and the largest files you hold. Run them through the same Tika version and configuration you plan to use in production, then record for each file whether text was extracted, whether the result is complete, and how long extraction took. Confirm the Tika release and its supported formats with the extraction service documentation for the version you choose, since those details change between releases.
Use the results to decide what the search index will and will not promise. You may decide that scanned documents go to a separate OCR step, that encrypted files are flagged for manual handling, that files above a size limit are indexed by metadata only, or that failed files appear in an error report for the content owner. Agree these rules with the people who own the document library, because they determine what users can find and what they will expect to find, and they set the workload for whoever supports the site after launch.
Common reasons attachment search returns nothing
This table lists the failures that most often leave a document search empty, with the cause and fix for each. Work through the rows in order, since indexing problems upstream of the search index (extraction, queues, access) hide every later check.
| Symptom | Likely cause | Fix |
|---|---|---|
| Tika endpoint unreachable | The Drupal web or PHP tier cannot open a connection to the Tika server, so extraction fails silently or logs errors. | Confirm the Tika host and port from the web containers or servers, not from your workstation. Open network rules between those tiers and check the extraction service logs for failed requests. |
| Indexing not running | Cron or the queue worker has stalled, so items marked for indexing never reach the search backend. | Check cron and queue run times in the Drupal status report, then run the queue worker manually and watch the Search API tracker for pending items. Keep the worker under a process supervisor. |
| Files not attached to indexed entities | The file field is not added to the index, or the file lives on a related entity that the index does not follow. | Open the index's fields screen and confirm the file field is listed with the attachment processor enabled. Add the relationship if the file is on a referenced node or paragraph. |
| Private files blocked by access rules | Private files are not readable by the indexing process, or the index lacks access checks that match the viewing user's permissions. | Confirm the indexing context can read private files and that access-aware search filters match your policy model. Test with a user who holds each role that should see the document. |
| Scanned PDFs with no text | The PDF contains page images only, so there is no text layer for Tika to extract. | Run OCR on scanned documents before upload or in a separate pipeline, then reindex. Ask your document owners which archives are scanned, since this is often invisible until testing. |
| Index not rebuilt after field changes | Adding or changing a file field or processor does not reprocess existing content automatically. | Mark the index for reindexing after any field or processor change and allow the rebuild to finish before testing. Document this step in the change process for the policy portal. |
| Extraction size or type limits | Large or unusual file types exceed configured limits or fall outside the types the extraction service handles. | Review the allowed file extensions and size limits in the attachment settings and in the extraction service. Test representative files from each library, including older office formats. |
What buyers ask before hiring help with document search
What drives the cost of indexing PDFs and documents in Drupal?
The main drivers are the size of the library, the variety of file types, how many extraction failures need resolving, how complex the access model is, and which Search API backend receives the extracted text. A library of text-based PDFs with one file type is a different job from a decade of scanned files, Word documents, spreadsheets and archives with mixed permissions. Costs come from planning and configuration time, custom code for filtering or access checks, testing against real samples, and the infrastructure work to run the extraction service. Ask any partner for a written scope that lists these drivers separately so you can see what each one adds.
How long does document search work usually take?
The duration depends on the scope agreed in writing, not on a general rule. The work is shorter when the site already runs Search API, the file types are few and clean, and the access rules are simple. It is longer when the library needs OCR decisions, large reindexing runs, custom access filters, or a new extraction service built and hardened in your environment. Ask for a timeline tied to named deliverables such as the extraction service in place, the test corpus indexed, the failure report reviewed, and the production index rebuilt. Any date you are given should trace back to those milestones.
What do we need to supply before the work starts?
Plan to provide a representative set of sample files, the access rules that decide who may see each document, and a place to run the extraction service. The sample set should include the awkward cases: scanned pages, password-protected files, large attachments, and old office formats. Access rules are usually held in your directory or in Drupal roles and node permissions, so the owner of those rules must be available during design. You will also need to decide where Apache Tika runs, which affects network paths, memory limits and who patches it. Confirm these items with your team before you sign a fixed-scope agreement.
Can our internal team set this up without a partner?
Yes, if you have engineers who know Drupal configuration, Search API and how to operate a service such as Apache Tika. The Search API attachments module is a contributed project on Drupal.org, so you can install and test it with your own staff. The harder parts are usually the access model, the failure handling for files that will not parse, and the operations plan for the extraction service. Teams that lack one of those skills often use a partner for planning and a review of the access design, then keep day-to-day ownership in-house. Check that the module release you pick supports your Drupal version before you commit.
What is the Search API attachments module and which Drupal versions does it support?
Search API attachments lets a Drupal site extract and search the text inside file attachments such as PDFs and office documents. According to its Drupal.org project page, release 10.0.13 supports Drupal ^10.3 or ^11. Older Drupal 7 sites cannot use this path directly, because Drupal 6 and 7 sites are migrated into a new site rather than updated in place, so that migration must be planned first. Confirm the exact release and its dependencies on the project page before you build, because module requirements change between releases.
What recurs after launch, such as updates and reindexing?
Several things recur. Drupal core and contributed modules receive bugfix releases on the first Wednesday of each month and security releases on the third Wednesday, so the search and attachment modules need regular updates and regression checks. The extraction service also needs patching, and its version has to stay compatible with the Java runtime and the hosts that run it. Reindexing happens when you change the extraction settings, add file types, fix parsing failures, or change the index fields. Ask the partner to separate one-time build work from a recurring support arrangement, and to describe how reindex runs are scheduled and monitored.
How do we handle files that fail to extract?
Expect some failures in any real library. Corrupt files, encrypted PDFs, scans without a text layer and unusual office formats will fail or return little text. Plan a failure report that lists each file, the reason, and an owner who decides whether to repair, re-export, run OCR, or exclude the file from search. Count the failures in your sample set early, because the number of failures to resolve is one of the strongest cost drivers. Make sure failed files do not block the rest of the index and that users are not shown partial text as if it were complete.
How DeployOpen scopes and delivers document search
DeployOpen plans, builds, documents and supports Drupal search over PDFs and office files inside your own infrastructure, including the extraction service, the Search API attachments configuration and the indexing pipeline. Each engagement starts from a written scope that defines which document types, sources and search behaviors are in and out.
How we scope
- Inventory the document types, file sizes and volumes that the Drupal site must index before any build begins
- Agree in writing which extraction service, Drupal version and hosting model the search work will use
- Define access rules so that search results respect the permissions on each source entity and private file
- Engagements are fixed-scope, with deliverables and timelines agreed in writing before work starts
How we build
- Install and configure the Search API attachments module on the Drupal version your site already runs
- Connect the site to a Tika extraction service deployed on servers or clusters you control
- Map extracted text and file metadata to Search API fields and test relevance on representative documents
- Test scanned, encrypted and malformed files, and record how each failure appears to editors and users
How we hand over
- Deliver configuration as code and document the module versions, indexes and processor settings used
- Write runbooks for reindexing, adding a new file type and restarting the extraction service
- Document the trade-offs chosen for file size limits, timeouts and text extraction depth for your team to review
- Walk your administrators and developers through the setup and record open decisions for follow-up
How we support
- Ongoing support, upgrades and continuous testing are available as retainers after handover
- Track Search API attachments and Tika releases and plan upgrades against your Drupal core schedule
- Re-test search permissions and extraction after each core or module update before changes reach production
- Confirm with your team which support tier, response expectations and reporting cadence fit your policy portal
