opensolr-haystack

Haystack integration for Opensolr — managed Apache Solr as a DocumentStore, with server-side embeddings and native hybrid (BM25 + kNN) retrieval.

See it live (real news index, hybrid + AI answer): https://search.opensolr.com/news__dense?q=how+am+I+supposed+to+save+money%3F

No embedder components needed in your pipeline — texts and queries are embedded on Opensolr's GPU infrastructure (multilingual E5-large-instruct, 1024 dimensions, cosine).

Product page: opensolr.com/langchain · free forever, no card, at opensolr.com

pip install opensolr-haystack

from haystack import Document, Pipeline
from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore
from haystack_integrations.components.retrievers.opensolr import OpensolrHybridRetriever

# credentials default to OPENSOLR_EMAIL / OPENSOLR_API_KEY env vars
store = OpensolrDocumentStore(index="mysite__dense", create_if_missing=True)

store.write_documents([
    Document(content="Hybrid search fuses BM25 with vector similarity"),
    Document(content="Cats sleep sixteen hours a day"),
])

pipe = Pipeline()
pipe.add_component("retriever", OpensolrHybridRetriever(document_store=store))
result = pipe.run({"retriever": {"query": "how do keyword and semantic search combine?"}})
print(result["retriever"]["documents"])

Note there is no embedder in the pipeline — not for documents, not for the query. The store embeds server-side at both index and query time.

There is a public demo account. Point the package at it and everything in this README works immediately, with no signup:

export OPENSOLR_EMAIL=mcp@opensolr.com
export OPENSOLR_API_KEY=420b8b23e7b12dc8ab838932145a5065

mcp_demo_d1__dense is already loaded with 300 news articles, so search, filtering and grounded answers work the moment you connect. You also get the write path: create your own index on the account, ingest into it and query it. Deletion is not available on this shared key: no index here can be deleted or reconfigured by hand. Whatever you create is removed automatically after 3 days.

Know what you are working with:

• Anything you create there is deleted after 3 days. Automatically, without warning or export. That includes indexes you created and every document in them.
• The account is shared with everyone reading this. Your index is visible to them and they can add documents to it, as you can to theirs. Nobody can delete or reconfigure an index here (that is switched off for this key), but never put anything real, private or client-owned in it.
• The limits are per index, and deliberately small. 200 MB of bandwidth and 50 MB of disk per index. Bandwidth is the one you will hit first: it covers a demo, a tutorial and a proof of concept, and it will not carry an application.

When you want an index that is private, yours and still there next week, get your own key — free forever, no card — and change the two variables above. Nothing else in your code changes.

OpensolrHybridRetriever fuses BM25 and kNN scores per document via Opensolr's native {!hybrid} Solr query parser:

OpensolrHybridRetriever(
    document_store=store,
    top_k=10,
    hybrid=True,     # False = pure semantic kNN
    alpha=0.5,       # 0 = all semantic … 1 = all lexical
)

Standard Haystack filters are supported and map to Solr fq:

pipe.run({"retriever": {
    "query": "search engines",
    "filters": {"field": "meta.category", "operator": "==", "value": "docs"},
}})

The query string understands the operators people already expect from a search box. They work in every mode — keyword, hybrid and pure vector.

They compose: +laptop +"13 inch" -refurbished returns only 13-inch laptops and never a refurbished one.

A prefixed term (+ or -, word or phrase) becomes a filter, applied to the whole result set. That matters as soon as a vector is involved: the semantic side of a hybrid search has no concept of negation, so left as query text -refurbished would actually pull refurbished listings towards the top rather than removing them. As a filter it binds every document, whichever side of the search found it, and the exclusion is absolute.

An unprefixed phrase ("machine learning" with no + in front) is a keyword-side relevance signal rather than a filter — use +"machine learning" when you need it enforced.

+ and - only count at the start of a word, so e-mail, covid-19 and 1+1 are searched for literally.

• Vector indexes live in the vector regions: the Opensolr servers that run the web crawler, whatever their Solr version. The list is live, never written in the package: store.client.vector_regions() returns the regions that take new indexes right now (environment id, country, Solr version). location= takes an environment id from that list, or a short form such as us, de or fi, matched against the live list by environment id or country. Additional dedicated regions can be deployed on request (paid add-on): support@opensolr.com.
• Every index is also plain Apache Solr with the native /select API — facets, highlighting, spellcheck included.
• Siblings: langchain-opensolr · llama-index-opensolr · opensolr-mcp

Writes go through Opensolr's Data Ingestion API — the same pipeline the Drupal and WordPress connectors use. It is asynchronous: documents are queued, then embeddings, sentiment, language and all crawler-identical derived fields are computed server-side, and documents become searchable within about a minute. Progress is visible in Control Panel → Data Ingestion — a per-job status board (queued / processing / completed / failed, with processed / success / failed document counts per job) — and via the ingest_status API. Each document's identity is its uri (the Solr id is md5(uri)): pass a real URL in metadata ({"uri": "https://..."}), or a deterministic one is synthesized from your id. Re-submitting the same uri updates the document. Pass {"rtf": True, "uri": "https://.../file.pdf"} and the server extracts the text from PDF/DOCX/XLSX for you.

Don't need vectors? Pure keyword search skips the embedding call entirely — zero AI quota. It runs on any Opensolr index that has title, description and text fields, including indexes outside the vector regions and older Solr versions (see Index requirements).

Search your index with a photo instead of a text query. Opensolr reads the picture three ways — visual labels (what it depicts), OCR text (words printed on it), and any barcode / QR code — and turns that into an ordinary search. Nothing new is stored in Solr; the picture simply becomes words.

# What the picture reads as (labels, OCR text, barcodes) — no search yet:
read = store.image_to_words("photo.jpg")   # path, bytes, or base64
# {'text': 'red running shoe', 'mode': 'clip',
#  'labels': ['running shoe', 'sneaker'], 'codes': ['0123456789012']}

# Search the index with the picture:
docs = store.search_by_image("photo.jpg", top_k=4)          # engine picks the best reading
docs = store.search_by_image("photo.jpg", using="meaning")  # visual labels
docs = store.search_by_image("photo.jpg", using="text")     # only OCR text
docs = store.search_by_image("photo.jpg", using="code")     # exact barcode / QR match
docs = store.search_by_image("photo.jpg", using="all")      # labels + OCR + codes

search_by_image forwards the same tuning as search — hybrid, lexical, alpha, fresh_bias, filters — so an image query runs through the exact hybrid pipeline a text query does.

OpensolrConverter turns files into Haystack Documents — one per PDF page (meta["page_number"]), one per any other file. It takes file paths, folders and ByteStreams:

from haystack_integrations.components.converters.opensolr import OpensolrConverter

converter = OpensolrConverter(document_store=store)
docs = converter.run(sources=["./contracts", "scan.png"], meta={"team": "legal"})["documents"]
# meta: file_path, page_number, is_ocr, language, content_type (+ yours)

Or index them straight into the store — no converter, no splitter, PDFs page by page:

result = store.write_files("./contracts", pattern="*.pdf", metadata={"team": "legal"})
# {"documents": [{path, source, uri, id}], "pending": [], "failed": [], "jobs": [...]}

• Each file is read on Opensolr's servers: its text, the text in its pictures (OCR, more than 100 languages), a short description of the pictures without text. Word, RTF, OpenDocument, text, HTML and picture files (scans) are one document each; a PDF is one document per page.
• The bytes travel once: a file the account already sent (same content) is not uploaded again. Pictures read by OCR count 0.5 of an AI request each; a file read before is free.
• Files still being read when timeout runs out are under result["pending"] (the converter logs them): run again to get them, nothing is sent twice.
• An indexed file's uri is https://ingest.opensolr.com/<index>/<source>, where source is its path from the folder you sent (meta["source"]); sending it again replaces it. Its date is the file's modification time.

On an index where PDFs are stored page by page (files indexed as above, PDFs sent to Data Ingestion with rtf, PDFs found by the Web Crawler), a search returns each PDF once, as its best page. Its metadata carries page_number (the page number), page_url (opens the PDF at that page, ...pdf#page=14), document_id, more_pages (its other matching pages, each with page and page_url) and matching_pages, and its uri; any other hit keeps exactly the metadata it was sent with. group_pages=False returns the pages as separate results.

date_from and date_to (YYYY-MM-DD, both included, either one can be left out) keep only the documents dated in that period (creation_date):

docs = store.search("rate decision", top_k=5, date_from="2026-01-01", date_to="2026-03-31")
# or in a pipeline:
OpensolrHybridRetriever(document_store=store, date_from="2026-01-01")

They combine with every other option — filters, fresh_bias, hybrid or lexical.

Everything this package does runs on an Opensolr index that sits in a vector region and carries the Opensolr vector schema — the configuration every Opensolr vector index runs. An index created through the package (create_index, create_if_missing) has both. An index made elsewhere may not: a server outside the vector regions, or a schema of its own. A vector region is an Opensolr server that runs the web crawler, whatever its Solr version; the regions that take new indexes come from the live vector_regions list, never from a list in the package.

The check is automatic. The first time the package touches an index, it asks the platform once whether that index can do what is asked: one request per index per client, kept for the client's life, never one per search. If the check itself cannot run (a network error, the platform busy), nothing is blocked: the operation runs exactly as it always did, and the check is tried again after 5 minutes. When an index differs from the Opensolr vector schema, a warning is logged once, on the opensolr logger, with the reasons and the fix.

What the check gates — only what cannot work otherwise:

The errors say exactly what is going on. A blocked operation raises OpensolrSchemaError (a subclass of OpensolrError) with .index, .capability and .report (the full check), and a message with every reason and the fix:

Index 'shop_it' cannot take documents or files through Data Ingestion. Index shop_it
is on IT-SOLR-9-6 (Milano, Italy), which is not a vector region: Data Ingestion,
server-side embeddings and hybrid search run only on the servers of a vector region
(DE-SOLR-9 (Germany, Solr 9.00), FINLAND9 (Finland, Solr 9.60), ...). This index
cannot be made ready: create a new index in one of the vector regions (...), for
example with create_index, and send your documents there.

When Solr itself refuses a request, OpensolrSolrError carries Solr's own reason and the index name; it is still an httpx.HTTPStatusError, so code that caught that before keeps working.

from haystack_integrations.document_stores.opensolr import OpensolrDocumentStore, OpensolrSchemaError, OpensolrSolrError

try:
    store.write_files("./contracts")
except OpensolrSchemaError as e:
    print(e.capability, e.report["fix"]["action"])   # ingestion new_index

See the details, and fix what can be fixed:

store.check_schema()   # ready, capabilities, server, Solr version, missing / different fields, problems, fix
store.apply_schema(force=False)   # installs the Opensolr vector schema; force=True when the index holds documents

apply_schema exists so an index of a vector region whose configuration was changed, or never set, can take everything this package does without being recreated: it installs the same configuration every Opensolr vector index runs, and replaces the index configuration. An index that already holds documents needs force=True; those documents keep the fields they were written with and must be sent again. An index outside the vector regions cannot take it — create a new index in a region from vector_regions and send your documents there. The package never installs the schema on its own.

Documents follow the Opensolr document model (title, description, text, meta_* custom fields). The whole schema, every field and every type suffix, is explained in the Index Schema Reference. To see your own copy: Control Panel → click your index → Configuration → Edit File → schema.xml. Prefer zero-effort data entry? Configure the Web Crawler in the Control Panel (Index Tools → WebCrawler): add your site URL, validate it, and Opensolr indexes the whole site for you.

One call: hybrid retrieval picks the top hits, whose content becomes the LLM context, and Opensolr's server-side LLM answers — no generator component, no LLM key:

answer = store.ai_answer(
    "what does the refund policy say?",
    rag_docs=3,        # how many hybrid hits feed the LLM (default 3)
    rag_words=1500,    # words of text taken from each hit (default 1500)
    # instruction="Answer in German, cite the exact titles you used",  # optional
)

Retrieval (search and RAG grounding) runs through the platform's tuned pipeline: global defaults → your index's saved Search Tuning (Control Panel → Index Settings → Search Tuning: semantic↔lexical balance, field weights, minimum match, search mode, vector candidate pool, content quality boost) → optional per-call overrides via tuning:

tuning={"search_mode": "keywords_required", "fw_title": 0.2,
        "mm": "strict", "vector_topk": 500, "quality_boost": 0.3}

Defaults match the platform's PHP configuration exactly — customize in the Control Panel once, or per call from code.

Rank newer documents higher without hiding anything older. Every score is multiplied by a recency curve on creation_date — full weight for a document published today, about half after a year:

store.similarity_search_with_score("solar inverter warranty", fresh_bias=True)
client.hybrid_search(index, query, fresh_bias=True)
client.ai_answer(index, question, tuning={"fresh_bias": 1})

It re-orders and never filters: the hit count is identical either way, nothing old becomes unreachable, and a document with no creation_date simply keeps its place instead of being pushed to the bottom. It applies to all three retrieval shapes — vector-only, keyword-only and the fused hybrid ranking — because the boost wraps the final score rather than one half of it. Off by default.

This is the same control visitors get as the Fresh toggle beside the sort options on the hosted Opensolr search page, so a query behaves identically here and there.

fresh_bias and freshness_boost are two different knobs and the names invite confusion. freshness_boost is a hard window in days — anything older is filtered out and the hit count drops. fresh_bias filters nothing.

Every release is validated against live Opensolr infrastructure — no mocks:

• Unit tests (offline): location matching against the live region list, filter→fq mapping, query building, escaping.
• End-to-end suite: the full write path through the async Data Ingestion queue (queued → server-side enrichment → searchable), semantic / hybrid / lexical retrieval, metadata round-trip, filters, id round-trip (your ids and the Solr md5(uri) ids), deletes by id and by query.
• Real-corpus validation: searches run against a 340-document replica of opensolr.com's own production search index. Verified: pure-semantic hits with zero keyword overlap ("how do I get my data back after a disaster" → backup & restore docs), cross-lingual queries (Romanian query → English content), exact-term surfacing in hybrid mode, all four hybrid modes, and the full alpha range 0 → 1.
• PDF ingestion: a real PDF ingested via rtf:true — server-side text extraction (13k+ chars), automatic content-type detection, then retrieved with a purely semantic query against its contents.
• Grounded RAG answers: ai_answer verified end-to-end — a question answerable only from the ingested PDF returns the correct answer, sourced from the PDF's extracted text via hybrid retrieval.

The store is exercised live (write via ingestion, DuplicatePolicy SKIP/FAIL, hybrid + lexical retrieval, filters, serde round-trip) before every release.

MIT license.