Quick start#

Installation#

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

pip install SQLAlchemy-Searchable

SQLAlchemy-Searchable requires Python 3.8 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 declarative_base
from sqlalchemy_searchable import make_searchable

Base = declarative_base()
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 import Column, Integer, String, Text
from sqlalchemy_utils.types import TSVectorType

class Article(Base):
    __tablename__ = "article"

    id = Column(Integer, primary_key=True)
    name = Column(String(255))
    content = Column(Text)
    search_vector = 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, mapper=<class 'sqlalchemy.orm.mapper.Mapper'>, manager=<sqlalchemy_searchable.SearchManager object>, options={})[source]#

Configure SQLAlchemy-Searchable for given SQLAlchemy metadata object.

Parameters:

  • metadata – SQLAlchemy metadata object

  • options – Dictionary of configuration options

sqlalchemy_searchable.search(query, search_query, vector=None, regconfig=None, sort=False)[source]#

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.