Create a vector database

A vector database is bound to exactly one embeddings serving name. The model is referenced through the serving name so the database keeps working if the model is replaced behind the same serving name. Renaming a database is safe; renaming a serving name will detach the database.

Embedding model must be running

A database that points at a stopped embeddings instance will fail every search. Stopping the instance to save cost is fine if you are willing to wait for a cold start on the next search.

Steps

  1. Confirm the embedding model

    Open the Instances page and make sure an embeddings instance is running. The vector database stores the serving name, not the model id directly.

  2. Pick a slug

    Lowercase, dashes, no spaces. The slug is part of the public URL of the database and stays stable across renames.

  3. Set the display name and description

    Free text. Shown in the list page and the detail header.

  4. Choose indexing mode

    Direct for small batches (synchronous), Jobs for large imports (asynchronous).

  5. Index a first batch

    Use the playground or POST /index-direct with a small JSON document set. Confirm the documents show up in the listing.

  6. Smoke test a search

    Open the playground and run a search. Confirm scores are non-zero and metadata round-trips.

Create payload

The create endpoint accepts a small JSON object. The slug is the only immutable identifier you should rely on from client code.

create-payload.json
1{
2  "slug": "support-kb",
3  "name": "Support knowledge base",
4  "description": "Articles used by the in-product assistant",
5  "embedding_serving_name": "qwen3-vl-2b-demo"
6}

Status transitions

  • provisioning — the backing index is being created. Usually a few seconds.
  • ready — the database accepts index, search, and recommendation calls.
  • failed — the platform stores an error_message. Open the database detail page for the exact reason and the suggested remediation.