Quick start

Installation

SQLAlchemy-Searchable is available on PyPI. It can be installed using pip:

pip install SQLAlchemy-Searchable

SQLAlchemy-Searchable requires Python 3.10 or newer, either the cPython or PyPy implementation.

Configuration

The first step to enable full-text search functionality in your app is to configure SQLAlchemy-Searchable using make_searchable() function by passing it your declarative base class:

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy_searchable import make_searchable

class Base(DeclarativeBase):
    pass

make_searchable(Base.metadata)

Define models

Then, add a search vector column to your model and specify which columns you want to be included in the full-text search. Here’s an example using an Article model:

from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy_utils.types import TSVectorType

class Article(Base):
    __tablename__ = "article"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    content: Mapped[str]
    search_vector: Mapped[TSVectorType] = mapped_column(
        TSVectorType("name", "content")
    )

The search vector is a special column of TSVectorType data type that is optimized for text search. Here, we want the name and content columns to be full-text indexed, which we have indicated by giving them as arguments to the TSVectorType constructor.

Create and populate the tables

Now, let’s create the tables and add some sample data. Before creating the tables, make sure to call sqlalchemy.orm.configure_mappers() to ensure that mappers have been configured for the models:

from sqlalchemy import create_engine
from sqlalchemy.orm import configure_mappers, Session

engine = create_engine("postgresql://localhost/sqlalchemy_searchable_test")
configure_mappers()  # IMPORTANT!
Base.metadata.create_all(engine)

session = Session(engine)

article1 = Article(name="First article", content="This is the first article")
article2 = Article(name="Second article", content="This is the second article")

session.add(article1)
session.add(article2)
session.commit()

Performing searches

After we’ve created the articles and populated the database, we can now perform full-text searches on them using the search() function:

from sqlalchemy import select
from sqlalchemy_searchable import search

query = search(select(Article), "first")
article = session.scalars(query).first()
print(article.name)
# Output: First article

API

sqlalchemy_searchable.make_searchable(metadata: ~sqlalchemy.sql.schema.MetaData, mapper: type[~sqlalchemy.orm.mapper.Mapper[~typing.Any]] = <class 'sqlalchemy.orm.mapper.Mapper'>, manager: ~sqlalchemy_searchable.SearchManager = <sqlalchemy_searchable.SearchManager object>, options: ~sqlalchemy_searchable.SearchOptions | None = None) → None

Configure SQLAlchemy-Searchable for given SQLAlchemy metadata object.

Parameters:

• metadata – SQLAlchemy metadata object

• options – SearchOptions instance for configuration

sqlalchemy_searchable.search(query: Select, search_query: str, vector: Column[TSVectorType] | None = None, regconfig: str | None = None, sort: bool = False) → Select

Search given query with full text search.

Parameters:

• search_query – the search query

• vector – search vector to use

• regconfig – postgresql regconfig to be used

• sort – Order the results by relevance. This uses cover density ranking algorithm (ts_rank_cd) for sorting.