On this page

Connections and storage

What each mode owns

Managed (managed)

Start a new corpus. ContextBase creates, populates and deletes the space’s table or collection. Several spaces can share a server.

Attached (attached)

Search an existing table or collection. A compatible layout and the space owner’s confirmation can enable writes. The original corpus survives space deletion.

Either mode can use an external server. An attached registration serves one space. If two registrations point to the same table or collection, both spaces search every row, including each other’s additions. To isolate access, point them at separate targets or use credentials that reach separate targets.

Register a storage server

  1. Open Storage → Add connection, then select a backend and mode.

  2. Enter a host reachable from ContextBase. From a container, use the service hostname. Set TLS and credentials for a remote server. Omitted fields use deployment defaults when the adapter supplies them.

  3. In attached mode, enter the existing Table or collection. For PostgreSQL, set the schema in the connection settings. Configure a field mapping if pgvector, Chroma or Weaviate uses custom names. In managed mode, ContextBase assigns the table or collection name.

  4. Save. Core checks the connection and validates the target and its fields in attached mode. In Spaces → Create space, pick the registered backend, an embedding model and a compatible pipeline. Search for a known passage with dense retrieval to verify the connection.

Core includes all four adapters below. For API registration, read the backend schema at GET /api/v1/vector-backends/catalog. Send POST /api/v1/vector-backends with a signed-in bearer credential. This body registers a managed Qdrant service.

{
  "kind": "qdrant",
  "mode": "managed",
  "connection": {
    "location": "http://qdrant:6333"
  }
}

Replace the example hostname and supply your server’s connection fields. Use the returned ID as vector_backend_id. The response omits connection settings and secrets. Select an installation registration or one from your account. Space creation and permissions

To rotate credentials, replace the whole configuration in Storage or with PUT /api/v1/vector-backends/{id}. This resets write confirmation for an attached backend. Delete a registration after removing its space references.

Which searches can run

Backend

Dense search

BM25

SPLADE

Knowledge graph

PostgreSQL (pgvector)

Yes

Yes

Yes

Managed only

Qdrant

Yes

Managed only

Managed only

Managed only

Chroma

Yes

Yes

Yes

Unavailable

Weaviate

Yes

Yes

Yes

Managed only

  • PostgreSQL accepts host, database, schema and credentials. Qdrant takes a URL and optional API key.

  • Chroma supports host, TLS, token, tenant and database. Weaviate takes separate HTTP and gRPC addresses and an optional API key.

  • See GET /api/v1/vector-backends/catalog for allowed values.

Dense vectors live in the selected store. ContextBase keeps BM25, SPLADE and graph data in its own database. Build side indexes before using BM25 or SPLADE on an attached corpus. Graph construction requires a compatible managed backend and an LLM. Attached Weaviate cannot store structural or hierarchical chunks. Preflight reports incompatible pipelines before save. Search and answers

Attach an existing index

Use the original embedding model and dimensions, with compatible normalization and query instructions. In pgvector, match the vector column’s dimensions and use vector_cosine_ops for a dense cosine index. A managed pgvector index supports up to 2,000 dimensions. For larger vectors, choose a narrower embedding or another backend. pgvector compatibility limits

  • pgvector, Chroma or Weaviate. Map each role to the existing column, property or metadata field in Storage. The form marks the configurable names.

  • Qdrant. Use one unnamed vector per point and payload keys node_id, text and document_id. Leave field_mapping empty. Registration samples existing points to check their keys. Verify dimensions, distance metric and a known search result in the intended collection.

Role

Purpose

vector

Dense embedding used in similarity search.

text

Text to return in the matching passage.

identity

Stable row identity, also used to break ties.

chunk

Chunk identity ContextBase uses when writing and retrieving appended records. Side indexing also uses a usable chunk ID for each row.

described

Field for a chunk’s description and metadata, required for appending.

document

Optional document identity for grouping rows from the same source. Without it, foreign rows appear as separate documents.

Map vector, text and identity for reading. Add chunk and described to enable appending if validation passes. An empty mapping assumes the ContextBase layout. For custom names, map each role explicitly.

Validate a small example

Attach PostgreSQL table knowledge.passages with an embedding vector, body text and record_id key.

{
  "kind": "pgvector",
  "mode": "attached",
  "connection": {
    "schema": "knowledge"
  },
  "storage": "passages",
  "field_mapping": {
    "vector": "embedding",
    "text": "body",
    "identity": "record_id"
  }
}

Fill in your server’s connection settings. This mapping gives read-only access. On space creation, select the original embedding model and check preflight. Then search a known phrase and confirm the returned text and source. For an empty target, verify the connection, target and mapping before writing.

Append or remove content

To upload, use a writable connection and a layout marked append in the registry. Read-only layouts reject uploads. As space owner, review sample rows and confirm the corpus in the upload form, or send POST /api/v1/spaces/{id}/storage/confirm with a bearer credential. Upload one test document and verify it in search. ContextBase uses ownership markers to identify the space’s appended rows for writes and deletes.

On space deletion, the interface shows the appended row count when it can determine it. The API requires appended_rows even if that count is zero or unknown. Without it, the API returns 428 with the target, available count and suggested choice.

  • ?appended_rows=keep leaves the added rows available to external readers.

  • ?appended_rows=purge deletes the rows added by this space.

Build and check side indexes

For an attached pgvector, Chroma or Weaviate space, start with dense search. As owner, build side indexes in Settings → Storage and diagnostics or with POST /api/v1/spaces/{id}/storage/index. Poll GET at the same path for status, completed indexes and indexed/skipped row counts. Add BM25 or SPLADE to the pipeline after the pass completes.

The pass can scan the full external corpus and call the SPLADE model. It builds both indexes and skips the space’s own appended rows, which are indexed during ingestion. Dense search remains available.

After changes to external rows or index settings, send POST /api/v1/spaces/{id}/storage/index/check to check the current corpus. Rebuild stale indexes. If coverage is low, check skipped rows and field mapping. Test metadata filters on a known row. Filters can use only mapped descriptions that the row owner supplied.

storage compatibility, StorageFieldMapping, SpaceStorageConfirm and SpaceSideIndex.

ContextBase0.1.0

Search the documentation