# Semantic Search

Semantic Search allows users to search for assets in CKBox using natural language queries. It uses OpenAI as a third-party provider. To fully use Semantic Search capabilities in CKBox On-Premises, you need to set up additional infrastructure: a PostgreSQL database with the [pgvector](https://github.com/pgvector/pgvector) extension and an OpenAI API key.

> **Note**
>
> Semantic Search is an optional feature. If it is not configured, CKBox On-Premises will continue to work normally with all other features available. However, the Semantic Search functionality will be disabled.

For a general overview of Semantic Search capabilities, refer to the [Semantic Search documentation](../../../../ckbox/latest/features/ai-features.md#semantic-search).

<a id="prerequisites">

## Prerequisites

To enable Semantic Search, you need to provide:

1. A **PostgreSQL database with the pgvector extension** installed. This is a separate database from the main CKBox application database.
2. A valid **OpenAI API key**.

Both must be configured. If either is missing, Semantic Search will be disabled.

<a id="postgresql-with-pgvector">

## PostgreSQL with pgvector

The `pgvector` extension needs to be installed separately. Refer to the [pgvector installation instructions](https://github.com/pgvector/pgvector#installation) for details.

> **Note**
>
> Make sure the pgvector version you install is compatible with your PostgreSQL version.

<a id="preparing-the-database">

### Preparing the database

The database user should have at least the following privileges: `SELECT, INSERT, UPDATE, DELETE, CREATE, USAGE` and permission to execute `CREATE EXTENSION`.

<a id="openai-configuration">

## OpenAI configuration

For details on configuring the OpenAI provider, refer to the [OpenAI](configuration.md#openai) section of the Configuration guide.

<a id="semantic-search-database-configuration">

## Semantic Search database configuration

Configure the connection to the pgvector-enabled PostgreSQL database using environment variables prefixed with `ckbox_ai_worker_database_`. This prefix distinguishes them from the main application database.

To enable Semantic Search, set the `ckbox_ai_worker_database_driver` variable to `postgres`.

Then, you can provide:

* `ckbox_ai_worker_database_host` and `ckbox_ai_worker_database_port` to configure the database address (example: `127.0.0.1` and `5432`).
* `ckbox_ai_worker_database_user` and `ckbox_ai_worker_database_password` to configure the database user (example: `postgres` and `password`).
* `ckbox_ai_worker_database_database` and `ckbox_ai_worker_database_schema` to set the database name and schema (example: `ckbox-ai-worker` and `public`).

<a id="running-the-service">

## Running the service

To run CKBox On-Premises with Semantic Search enabled, follow the [Running the service](deployment.md#running-the-service) guide. Make sure to include the Semantic Search-specific environment variables (`OPENAI_API_KEY` and `CKBOX_AI_WORKER_DATABASE_*`) alongside the standard CKBox configuration.

---

Full index of the Cloud Services documentation: [llms.txt](../../../llms.txt)