 

AI Drupal・8 min read・Posted on October 30, 2026

# Drupal AI Search with PostgreSQL and pgvector for semantic media library search

 

 

 

 ![Abstract tiles in shades of blue, with a light blue sphere and a dark blue drop at the centre.](/sites/default/files/2026-11/drupal-ai-pgvector-media-search-j-soft-tiles.png) 

 



 

   Table of contents  - [Key takeaways](#key-takeaways)
- [What is semantic search](#what-is-semantic-search)
- [What is vector search](#what-is-vector-search)
- [Why use PostgreSQL and pgvector for Drupal semantic search](#why-use-postgresql-and-pgvector-for-drupal-semantic-search)
- [Set up image classification](#set-up-image-classification)
- [Set up the Postgres VDB provider](#set-up-the-postgres-vdb-provider)
- [Set up AI Search with Search API](#set-up-ai-search-with-search-api)
- [How long it takes](#how-long-it-takes)
- [Index and verify](#index-and-verify)
- [Set up the view](#set-up-the-view)
- [Conclusion](#conclusion)
- [Frequently asked questions](#frequently-asked-questions)
- [Do I need a separate vector database for semantic search in Drupal?](#do-i-need-a-separate-vector-database-for-semantic-search-in-drupal)
- [Which vector database should I use for Drupal AI Search: PostgreSQL, Milvus or Pinecone?](#which-vector-database-should-i-use-for-drupal-ai-search-postgresql-milvus-or-pinecone)
- [Does Drupal semantic search make an AI call for every search?](#does-drupal-semantic-search-make-an-ai-call-for-every-search)
 
  

 

If you work on a Drupal site, the media library is one of the tools you use most. It lets editors reuse images across pages instead of uploading the same file again and again. Finding the right image is another story. The media library search is keyword-based: it matches on the media name, so it only works if whoever uploaded the image named it the way you'd think to search for it. Search for “chef preparing pizza” and a photo of a chef tossing dough named IMG\_4821.jpg will never show up.

Keyword search remains useful when exact terms matter. Semantic search adds another retrieval approach by matching meaning and context, helping users find relevant content even when they use different words. In this post, we use Drupal AI Search with PostgreSQL and pgvector to build semantic image search for the media library.

**The short version: generate an AI description for every image, store the description embeddings in PostgreSQL with pgvector through the Postgres VDB Provider, and search them with a Drupal AI Search index and a view.**

## Key takeaways

- **Semantic search finds images by meaning.** A search for “chef preparing pizza” can find a file named IMG\_4821.jpg, because the match happens on what the image shows.
- **A vision model writes the searchable text.** The AI Image Classification recipe describes each image on save, and that description is what gets indexed.
- **PostgreSQL can be your vector database.** The Postgres VDB Provider stores vectors in PostgreSQL with pgvector, so teams already running PostgreSQL add semantic search on infrastructure they know.
- **The Search API workflow stays familiar.** AI Search works as a Search API backend, so you set up a server, an index and a view as you would for Solr.
- **It's quick to run.** In our demo, 16 images were described and indexed in under a minute and a half.
- **PostgreSQL suits most Drupal sites.** Milvus or Pinecone suit collections in the tens of millions of vectors, and switching is a setting on the search server.

## What is semantic search

Semantic search retrieves content based on meaning rather than relying only on matching words. One way to implement it is to convert content and queries into embeddings, numerical representations of meaning, and use vector similarity to find conceptually related items even when they use different wording.

## What is vector search

Vector search is the retrieval method used in this implementation. It represents each piece of content as a vector, a list of numbers produced by an embedding model, and retrieves items whose vectors are closest to the query's vector. A vector database is built or extended to store and compare these vectors. Semantic search is the goal and vector search provides the similarity mechanism here.

## Why use PostgreSQL and pgvector for Drupal semantic search

Drupal already has multiple vector database providers, such as Milvus, Pinecone, Qdrant, MariaDB, MySQL, SQLite, OpenSearch, Elasticsearch and Azure AI Search. This tutorial focuses on the [PostgreSQL VDB Provider](https://www.drupal.org/project/ai_vdb_provider_postgres). It is especially useful if your organisation already runs PostgreSQL infrastructure, wants to keep vector data within infrastructure it controls, or wants to avoid introducing and operating a separate specialised vector database.

pgvector is an open-source PostgreSQL extension for vector similarity search. It supports exact and approximate nearest-neighbour search, including cosine distance and L2 distance. It lets us use PostgreSQL as the vector store for the image descriptions in this example. The [pgvector documentation](https://github.com/pgvector/pgvector) describes its supported search methods.

## Set up image classification

For this blog, let's build a view of the media library that lets us search for and find images semantically.

First, set up any AI provider of your choice. For the demo, I am using the OpenAI provider. Choose a small model like text-embedding-3-small for embeddings, and also select a model for chat with vision. I am using GPT-5.6 Luna, which is very cheap.

Then apply the [AI Image Classification recipe](https://www.drupal.org/project/ai_recipe_image_classification). You can download it with Composer.

 ```
ddev composer require drupal/ai_recipe_image_classification
ddev drush recipe ../recipes/ai_recipe_image_classification
```

This recipe adds a new Image Description field to image media entities. It also enables AI Image alt text generation.

The recipe is shipped with an automator. An automator in Drupal is something you can configure on the fields of an entity. When triggered, it sends the data of the source field to the LLM and fills the field with the response. Here, the automator can be seen by editing the description field of the media entity.

  ![Drupal field settings for the media Image Description field, showing the AI automator enabled to generate descriptions from the image.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/01-media-description-field-ai-automator.png.webp?itok=AQb0Z16F) It's also worth looking at the automator prompt and the advanced settings section.

  ![The automator’s prompt asking the vision model to describe the image, with its advanced settings below.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/02-automator-prompt-advanced-settings.png.webp?itok=1aiSaAjx) This automator is triggered when a media item is saved. When saved, it sends the image to the default vision model, asks the model to describe what it sees in the image, and then stores that description in the description field. This description is what will be indexed in the vector database.

Bulk save the media entities to generate descriptions. The recipe adds a Save media bulk action to the media overview page at /admin/content/media. The automator only fills the field when it is empty, so media that already have a description are left as they are.

## Set up the Postgres VDB provider

Once the descriptions are ready, download the [Postgres VDB Provider](https://www.drupal.org/project/ai_vdb_provider_postgres) module. I will be doing this step in DDEV. It's quite easy. After installing the module, get the [ddev-pgvector add-on](https://github.com/robertoperuzzo/ddev-pgvector) to enable pgvector:

 ```
ddev add-on get robertoperuzzo/ddev-pgvector
ddev restart
```

pgvector enables vector database capabilities in Postgres. In a standard DDEV Drupal setup, content is usually stored in MariaDB, so this add-on also adds a separate PostgreSQL database container with pgvector included.

Neither the add-on nor the module switches on the vector extension inside the database, so do it once yourself. Without it, the search index cannot create its table.

 ```
ddev exec bash -c 'PGPASSWORD=ddev_password psql -h pgvector -U ddev_user -d ddev_embedding_db -c "CREATE EXTENSION IF NOT EXISTS vector;"'
```

Now enable the Postgres provider module and configure it at /admin/config/ai/vdb\_providers/postgres. These are the default connection settings that come with the DDEV add-on:

- **Host:** pgvector
- **Port:** 5432 (host and port can be found by running ddev describe)
- **Username:** ddev\_user
- **Password:** ddev\_password
- **Default database:** ddev\_embedding\_db

The default database is where your search indexes will be stored.

## Set up AI Search with Search API

Drupal AI Search provides a vector database backend for Drupal's Search API. That means the familiar server, index and Views workflow still applies. The [AI Search project page](https://www.drupal.org/project/ai_search) documents this integration.

Setting up AI Search is similar to setting up Solr search. Install the AI Search module. Add a search server with AI Search as the backend:

- Select text-embedding-3-small as the embedding model.
- Choose Postgres as the vector database.
- Give a collection name, e.g. image\_database\_index. This is the table where the vectors will be stored.

Now set up the index to index media items:

- Set the tracker to AI Search Chunked Tracker. The tracker is an index setting. With the default tracker, re-indexing can leave the vector table empty.
- Set the description field as the main content field, and media ID, alt text, etc. as contextual content. Main content is what gets chunked. Contextual content is added to every chunk, and both are turned into vectors together.

For more detail on servers, index fields and embedding configuration, see our guide to [setting up AI-powered semantic search in Drupal](/insights/setting-up-ai-powered-semantic-search-in-drupal).

  ![Search API settings in Drupal for the AI Search server and media index, using text-embedding-3-small and the Postgres vector database.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/03-search-api-ai-search-server-pgvector.png.webp?itok=VtLwyDdW) ### How long it takes

For this demo, I had 16 images. The AI vision model generated a description for each image in a median of 4 seconds, and indexing it for semantic search added a median of 0.8 seconds. All 16 images were described and indexed in under a minute and a half. Editors can use a bulk action to process an existing library in one step instead of re-saving each image by hand. These figures will vary with the hosting environment, the AI model and network latency, and the total time grows with the number of images.

## Index and verify

Now index the content. Once indexed, you can use a tool like Adminer to look at what was stored. Install the Adminer add-on for DDEV and launch it:

 ```
ddev add-on get ddev/ddev-adminer
ddev restart
ddev adminer
```

Log in to Postgres with the same username, password and other details set up above:

- **System:** PostgreSQL
- **Server:** pgvector
- **Username:** ddev\_user
- **Password:** ddev\_password
- **Database:** ddev\_embedding\_db

Select image\_database\_index. You will be able to see the indexed items and the stored embeddings.

  ![Adminer showing the image_database_index table in PostgreSQL, with indexed media items and their stored embeddings.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/04-adminer-image-database-index-embeddings.png.webp?itok=mkYxfDg2) ## Set up the view

Now create a new view with Index Image Database Index as the source. Configure it to render the image or display the fields. Add the Fulltext search filter and expose it. Whatever a visitor types is converted into an embedding with the same embedding model, and the results are sorted by similarity.

  ![Drupal Views configuration using the Image Database Index as its source, with an exposed Fulltext search filter.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/05-views-image-database-index-fulltext-filter.png.webp?itok=UIPP89h2) Try searching with different phrases. You will see relevant images being fetched semantically. For this demo, I indexed images related to a pizza shop.

If I search the media library for ‘happy customers’, I see no results.

  ![The standard Drupal media library search for “happy customers” returning no results.](/sites/default/files/styles/uncropped_960w_webp/public/2026-11/06-media-library-search-no-results.png.webp?itok=LwegWAmO) But when I try the same search in the view we just created, it returns the image of a group of friends sharing pizza.

  ![The semantic search view for “happy customers” returning a photo of friends sharing pizza.](/sites/default/files/styles/uncropped_720w_webp/public/2026-11/07-semantic-search-view-pizza-result.png.webp?itok=IPaz8ERY) ## Conclusion

PostgreSQL is a great choice for setting up semantic search and RAG, especially if you already manage PostgreSQL. Your vectors live in a database your team already knows how to run, instead of in yet another service, which means no new service to provision, patch, or pay for separately, and one fewer system in your incident-response list.

The trade-off shows up at scale: a dedicated vector database such as Milvus or Pinecone is built specifically for large-scale similarity search, so once a collection grows into the tens of millions of vectors or query volume gets heavy, a purpose-built provider typically holds its performance better than pgvector running alongside your regular Drupal workload on the same Postgres instance. For most Drupal sites, especially a media library or a single content type like this example, that ceiling is well out of reach, and Postgres is the simpler, cheaper starting point. If your needs change later, Drupal has great integrations for Pinecone and Milvus, and the vector database is a setting on your search server, so your index and views stay the same when you switch.

A well-made semantic search makes it easier for people to find the resources they are looking for, even when they don't know the exact words. With its growing AI ecosystem, Drupal makes it easy to set one up.

## Frequently asked questions

### Do I need a separate vector database for semantic search in Drupal?

No, not if you already run PostgreSQL. The PostgreSQL VDB Provider module lets Drupal AI Search store vectors in PostgreSQL using the pgvector extension, so there is no new service to provision, patch or pay for separately. You still need an embedding model from an AI provider.

### Which vector database should I use for Drupal AI Search: PostgreSQL, Milvus or Pinecone?

For most Drupal sites, PostgreSQL with the pgvector extension is the simpler and cheaper choice, especially if you already run PostgreSQL. Milvus or Pinecone typically perform better once a collection reaches tens of millions of vectors or query volume gets heavy. Switching is a setting on the Search API server, though you'll need to re-index.

### Does Drupal semantic search make an AI call for every search?

Yes, but only to an embedding model, not a chat model. Each query is converted into an embedding with the same model used for indexing, and the similarity search then runs in the vector database. With OpenAI's text-embedding-3-small, that costs $0.02 per million tokens, so a short search query costs a tiny fraction of a cent. Locally hosted embedding models are also an option if you'd rather not call an external API.

 



 

 

 

 

 ## Planning semantic search for your Drupal site? Let's talk.

 [ Contact Us  ](/contact)