SQLAlchemy Solr Dialect

0.2.4.3 verified Mon Apr 27 auth: no python

Apache Solr dialect for SQLAlchemy, allowing Solr to be queried using SQLAlchemy ORM and Core. Current version 0.2.4.3, supports Python >=3.8 and Solr 6.x-9.x. Release cadence is irregular.

pip install sqlalchemy-solr

Common errors

error sqlalchemy.exc.ArgumentError: Could not determine version of SQLAlchemy ↓

cause Missing or incompatible SQLAlchemy version (e.g., 2.x).

fix

Install SQLAlchemy 1.4.x: pip install 'sqlalchemy>=1.4,<2.0'

error requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8983): Max retries exceeded ↓

cause Solr server not running or port incorrect.

fix

Start Solr or check host/port in connection string.

error ImportError: cannot import name 'savoir' from 'sqlalchemy_solr' ↓

cause Older version of sqlalchemy-solr without savoir module.

fix

Upgrade to >=0.2.4.0: pip install --upgrade sqlalchemy-solr

error solr.exceptions.SolrException: Error from Solr: org.apache.solr.common.SolrException: Collection not found: mycore ↓

cause Specified Solr core/collection does not exist.

fix

Use existing core name as database in URL.

Warnings

gotcha Engine URL must use 'solr://' prefix. The username and password are for HTTP basic auth, not Solr authentication. Database name is the Solr core/collection name. ↓

fix Use URL format: solr://username:password@host:port/solr/core_name

deprecated Python 3.8 support is the minimum; Python 3.7 and earlier will not work. ↓

fix Upgrade Python to 3.8+.

gotcha SQL compilation cache is disabled by default for Solr <9.0. This may impact performance. ↓

fix If using Solr >=9.0, enable cache by setting environment variable SQLALCHEMY_SOLR_CACHE=1 before engine creation.

breaking From version 0.2.4.0, the dialect returns native Python types instead of strings. Code relying on string results may break. ↓

fix Update code to handle int/float/datetime values directly.

Imports

create_engine
wrong
```
from sqlalchemy_solr import create_engine
```
correct
```
from sqlalchemy import create_engine
```
create_engine is from SQLAlchemy, not sqlalchemy-solr. The dialect is registered via URL prefix.
savoir
```
from sqlalchemy_solr import savoir
```
Utility to check Solr version compatibility.

Quickstart

Connect to a Solr core and run a basic SQL query.

from sqlalchemy import create_engine, text
import os

# Solr URL, default 'http://localhost:8983/solr'
solr_url = os.environ.get('SOLR_URL', 'http://localhost:8983/solr')
# Create engine with solr:// prefix, database name is Solr core/collection
engine = create_engine(f'solr://admin:@localhost:8983/solr/collection1')
with engine.connect() as conn:
    result = conn.execute(text("SELECT * FROM collection1 LIMIT 10"))
    for row in result:
        print(row)