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¶
Open Storage → Add connection, then select a backend and mode.
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.
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.
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/catalogfor 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,textanddocument_id. Leavefield_mappingempty. Registration samples existing points to check their keys. Verify dimensions, distance metric and a known search result in the intended collection.
Role |
Purpose |
|---|---|
|
Dense embedding used in similarity search. |
|
Text to return in the matching passage. |
|
Stable row identity, also used to break ties. |
|
Chunk identity ContextBase uses when writing and retrieving appended records. Side indexing also uses a usable chunk ID for each row. |
|
Field for a chunk’s description and metadata, required for appending. |
|
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=keepleaves the added rows available to external readers.?appended_rows=purgedeletes 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.