Note
This feature is currently an experimental feature.
This topic describes how to create, delete, prewarm, and name Collections and Namespaces. The Collection name tech_docs and Namespace name my_knowledge in the examples are consistent with those in Quick start with Agent hybrid search.
Collection management
Collection is the top-level container in this scenario. Parameters such as vector indexes and full-text indexes are configured at the Collection level, and these parameters are fixed in the Collection schema. All Namespaces under a Collection share the index configuration defined by that Collection.
Notice
In use_namespace=True mode, a Collection itself does not support data manipulation (DML or DQL) operations; these must be performed through a Namespace. Calling methods such as add or query directly on a Collection will throw an exception.
Create a Collection
create_collection
The sample code is as follows:
# Import the pyseekdb module
from pyseekdb import Schema, VectorIndexConfig, IVFConfiguration, FulltextIndexConfig
# Create Collection
collection = client.create_collection(
# Collection Name
name="tech_docs",
# Collection schema
schema=Schema(
# Create a vector index
vector_index=VectorIndexConfig(
# IVF Index Configuration
ivf=IVFConfiguration(dimension=384, distance="cosine"),
# Text Embedding Function
embedding_function=DefaultEmbeddingFunction(),
),
# Full-text index configuration
fulltext_index=FulltextIndexConfig(analyzer="ik"),
),
# Whether to Use Namespace
use_namespace=True,
)
Parameters |
Type |
Default value |
Note |
|---|---|---|---|
| name | string | — | Collection name (required). Only letters, numbers, and underscores are allowed, with a maximum length of 512 characters. |
| schema | None | Index configuration. In this scenario, only IVF vector indexes and full-text indexes are supported. For more information, see Indexes and embedding functions. | |
| embedding_function | DefaultEmbeddingFunction() | Automatic text vectorization function. Do not use it as a top-level parameter of create_collection; otherwise, it will be ignored. Setting it to None indicates that vectors are passed manually. For more information, see Indexes and embedding functions |
|
| use_namespace | boolean | False | Whether to enable Namespace mode. Set this parameter to True in this scenario. When the value is False, data operations are performed directly at the Collection level without going through the Namespace isolation path. |
For detailed descriptions of index-related parameters, see Indexes and embedding functions.
get_or_create_collection
You can also use the get_or_create_collection interface to create a Collection. This interface can be called repeatedly. If a Collection already exists, it returns the existing Collection; if not, it creates a new one. The sample code is as follows:
from pyseekdb.utils.embedding_functions import DefaultEmbeddingFunction
collection = client.get_or_create_collection(
"tech_docs",
schema=Schema(
vector_index=VectorIndexConfig(
ivf=IVFConfiguration(dimension=384, distance="cosine"),
embedding_function=DefaultEmbeddingFunction(),
),
fulltext_index=FulltextIndexConfig(analyzer="ik"),
),
use_namespace=True,
)
If a Collection with the same name exists, subsequent creation parameters such as schema and use_namespace will not modify the existing Collection's configuration. To change the index or Namespace mode, delete and rebuild the Collection or use a new name.
Get, list and check
# Gets the specified Collection (throws an exception if it does not exist).
collection = client.get_collection("tech_docs")
# List all Collections
collections = client.list_collections()
for c in collections:
print(c.name)
# Determine if it exists
if client.has_collection("tech_docs"):
print("Already exists")
Delete a Collection
client.delete_collection("tech_docs")
delete_collection is a synchronous operation: the call completes the deletion immediately and returns without waiting for background asynchronous tasks.
Namespace management
Namespace is the basic unit of data isolation. In use_namespace=True mode, all DML and DQL operations are performed on Nmespaces. Data is completely isolated between different Namespaces.
Naming rules and limitations
Constraints |
Note |
|---|---|
| Type | string |
| Character set | Only letters (a-z, A-Z), numbers (0-9), and underscores (_) are allowed. |
| Length | Up to 256 characters |
| Not Null | Empty string not allowed |
| Unique | Unique within the same Collection |
Notice
Calling methods such as create_namespace on a Collection with use_namespace=False will throw a ValueError: Namespace is not enabled for this collection.
Create and retrieve
# Create Namespace
ns = collection.create_namespace("my_knowledge")
print(ns.namespace_id) # The Namespace ID automatically assigned by the system.
# Gets an existing Namespace. Throws an exception if the Namespace does not exist.
ns = collection.get_namespace("my_knowledge")
# Get or create (automatically created if not present, idempotent)
ns = collection.get_or_create_namespace("my_knowledge")
List, check and delete
# List all Namespaces under the current Collection.
namespaces = collection.list_namespaces()
for ns in namespaces:
print(f"{ns.name} -> {ns.namespace_id}")
# Determine if it exists
if collection.has_namespace("my_knowledge"):
print("Already exists")
# Delete Namespace (async operation)
collection.delete_namespace("my_knowledge")
delete_namespace is an asynchronous operation. It returns immediately upon invocation, while the actual data deletion task is executed gradually in the background.
Data preview and statistics
# Data Volume
print(ns.count()) # 3
# Quickly preview the first N data records
preview = ns.peek(limit=5)
for i in range(len(preview["ids"])):
print(f"{preview['ids'][i]}: {preview['documents'][i]}")
Prewarm
If a Namespace has not been accessed for a long time, it will become "cold" (the cluster center cache for vector indexes is evicted), resulting in a high latency for the first request when queried again. You can call prewarm to actively load the cache:
ns.prewarm()
It is recommended to call this method after writing large amounts of data or before reusing a Namespace that has been idle for a long time. Prewarming is a Namespace-level operation, so each Namespace must be prewarmed separately.
References
- You can view the progress of Collection and Namespace deletion tasks through the
DBA_OB_AGENT_DB_BACKGROUND_TASKSview. For details, see Monitoring and maintenance.