Setting Up Your Vector Database (VDB)

Last updated: June 11, 2026

In order to use GenAI for self-hosted environments, you must set up a vector database (VDB).

For the complete MongoDB Atlas setup instructions, see the official MongoDB Atlas documentation.

Deploying an Atlas Cluster

1. Follow the instructions in the MongoDB documentation to deploy an Atlas cluster. Ensure that you deploy it in the same region as your Sisense deployment.

Configuring a Database User

1. Follow the instructions in Configure Database Users to create a database user.

   1. Set the authentication method to use a user name and password.

      

   2. Set the user privileges to read and write for your database.

      

Generating an Application API Key

1. Follow the instructions in Programmatic Access to Cloud Manager to generate an application API key. Ensure that there are permissions to create a search index.

   

Connecting the Cluster to the Sisense Deployment

1. Follow the instructions in Configure IP Access List Entries to whitelist the Sisense deployment IP address for network access.

   

2. Follow the instructions in Programmatic Access to Cloud Manager to whitelist the Sisense deployment IP address for search index creation.

   

Connecting the Atlas Cluster to Your Sisense Deployment

1. Follow the instructions in Get Connection String to obtain your MongoDB connection string (including the database name) which you will use in Sisense. Ensure that the Atlas db name is included in the connection string in the following format:

   mongodb+srv://<user>:<password>@<cluster domain>/<db_name>?retryWrites=true&w=majority

   In the connection string above, replace the following fields with your own information:

   • <user> - your login user name

   • <password> - your password

   • <cluster domain> - the domain name

   • <db_name> - the DB name

   

Setting the Service Provider to Atlas

1. Set the following environment variables via the terminal:

   • kubectl -n sisense set env deployment ai-integration SERVICE_PROVIDER=atlas

   • kubectl -n sisense set env deployment ai-services SERVICE_PROVIDER=atlas

Troubleshooting VDB Connection Issues

Sisense tests the MongoDB connection string when you enable the vector database. If the test fails, the connection is not saved — the connection string may appear to save but is no longer present after you refresh the page or navigate away and return. The most common causes are described below.

Escaping special characters in the connection string

Sisense validates the connection string against the MongoDB URI standard (RFC 3986) before attempting to reach your database. In a MongoDB URI, the @ character is reserved — it marks the boundary between the credentials and the server address:

mongodb+srv://<user>:<password>@<cluster domain>/<db_name>?retryWrites=true&w=majority

If the user name or password contains a reserved character (for example, an @ in the password), the driver cannot determine where the credentials end and the host begins, and it rejects the string as invalid before any connection is attempted. This surfaces as an error such as:

pymongo.errors.InvalidURI: Username and password must be escaped according to RFC 3986

You must percent-encode any reserved characters in the user name or password before pasting the connection string into Sisense. The most common characters and their encodings are:

Character	Encoded
@	%40
:	%3A
/	%2F
%	%25
#	%23
?	%3F

Encode only the user name and password — leave the rest of the URI, including the @ that comes immediately before the host, unchanged. For example, if your password is p@ss:word, the connection string should be:

mongodb+srv://myuser:p%40ss%3Aword@your-host/yourdb?retryWrites=true&w=majority

Most MongoDB drivers provide a helper to do this safely. For example, in Python:

from urllib.parse import quote_plus
password = quote_plus("p@ss:word")

Encode each value only once. Encoding an already-encoded value (for example, %40 → %2540) will fail again.

Authentication failed (error code 18)

If the connection string is saved but the vector database is still not enabled after you return to the configuration screen, MongoDB may be rejecting the credentials. This appears in the internal logs as:

pymongo.errors.OperationFailure: Authentication failed. code: 18, codeName: 'AuthenticationFailed'

Error code 18 means the server reached MongoDB and MongoDB refused the credentials — this is not a network issue, a TLS issue, or a sign that MongoDB is down. It is caused by one of the following:

• Wrong or stale credentials — the user name or password does not match the actual MongoDB user (for example, the password was rotated after the connection string was created).

• Wrong authSource — the user exists and the password is correct, but authentication runs against the wrong database. MongoDB authenticates against the database named in authSource (or the default if none is given). If the user was created in one database but the connection string authenticates against another (such as admin), MongoDB cannot find that user and returns code 18. This is the most common "but my credentials are definitely right" case.

• Unescaped special characters in the password — reserved characters that are not percent-encoded cause the wrong password to be sent to MongoDB, which fails with the same code 18. See the section above.

To confirm the fix:

• Verify that the raw user name and password connect successfully via mongosh directly against the same cluster.

• Confirm that authSource matches the database where the MongoDB user was created.

• Re-enter the connection string into Sisense with all special characters percent-encoded — and only once.