Skip to main content

​
CollectionsClient

Synchronous client for managing collections. Create, list, get, and delete collections using this client. Get a CollectionsClient instance from the main client: 
from topk_sdk import Client

client = Client(api_key="YOUR_KEY", region="aws-us-east-1-elastica")
collections = client.collections()

​
create()

Create a new collection with the specified schema. 
from topk_sdk.schema import text, int, semantic_index

collection = client.collections().create(
    "books",
    schema={
        "title": text().required().index(semantic_index()),
        "year": int().required()
    }
)
​
collection_name
str
required
The name of the collection to create. Must be unique within your project.
​
schema
Mapping[str, FieldSpec]
required
A dictionary mapping field names to field specifications. See Schema documentation for available field types and indexes.
​
return
Collection
The created collection object containing metadata like name, org_id, project_id, region, and schema.

​
list()

List all collections in your project. 
all_collections = client.collections().list()

for collection in all_collections:
    print(f"Collection: {collection.name}")
    print(f"Region: {collection.region}")
    print(f"Schema: {collection.schema}")
​
return
list[Collection]
A list of all collections in your project.

​
get()

Get information about a specific collection. 
collection = client.collections().get("books")

print(f"Name: {collection.name}")
print(f"Schema: {collection.schema}")
print(f"Region: {collection.region}")
​
collection_name
str
required
The name of the collection to retrieve.
​
return
Collection
The collection object containing metadata.

​
delete()

Delete a collection and all its documents.
This operation is irreversible. All documents in the collection will be permanently deleted.
client.collections().delete("books")
​
collection_name
str
required
The name of the collection to delete.
​
return
None
This method does not return a value.

​
AsyncCollectionsClient

Asynchronous client for managing collections. All methods are identical to CollectionsClient but return awaitables. 
from topk_sdk import AsyncClient
from topk_sdk.schema import text, semantic_index

client = AsyncClient(api_key="YOUR_KEY", region="aws-us-east-1-elastica")

# Create a collection
collection = await client.collections().create(
    "books",
    schema={"title": text().index(semantic_index())}
)

# List all collections
all_collections = await client.collections().list()

# Get a specific collection
collection = await client.collections().get("books")

# Delete a collection
await client.collections().delete("books")

​
create()

Create a new collection asynchronously.
​
collection_name
str
required
The name of the collection to create.
​
schema
Mapping[str, FieldSpec]
required
A dictionary mapping field names to field specifications.
​
return
Awaitable[Collection]
An awaitable that resolves to the created collection object.

​
list()

List all collections asynchronously.
​
return
Awaitable[list[Collection]]
An awaitable that resolves to a list of all collections.

​
get()

Get information about a specific collection asynchronously.
​
collection_name
str
required
The name of the collection to retrieve.
​
return
Awaitable[Collection]
An awaitable that resolves to the collection object.

​
delete()

Delete a collection asynchronously.
​
collection_name
str
required
The name of the collection to delete.
​
return
Awaitable[None]
An awaitable that resolves when the deletion is complete.

​
Collection Object

The Collection object represents a collection in TopK and is returned by the create(), get(), and list() methods. 
collection = client.collections().get("books")

# Access collection properties
print(collection.name)       # "books"
print(collection.org_id)     # Your organization ID
print(collection.project_id) # Your project ID
print(collection.region)     # "aws-us-east-1-elastica"
print(collection.schema)     # {"title": FieldSpec(...), ...}
​
name
str
The name of the collection.
​
org_id
str
The organization ID that owns the collection.
​
project_id
str
The project ID that owns the collection.
​
region
str
The region where the collection is stored.
​
schema
dict[str, FieldSpec]
The schema definition for the collection. Maps field names to their specifications.

​
Example: Full Workflow

Here’s a complete example showing how to create, use, and delete a collection: 
from topk_sdk import Client
from topk_sdk.schema import text, int, semantic_index, keyword_index
from topk_sdk.query import select, field, fn

# Initialize client
client = Client(api_key="YOUR_KEY", region="aws-us-east-1-elastica")

# Create a collection with schema
collection = client.collections().create(
    "books",
    schema={
        "title": text().required().index(semantic_index()),
        "description": text().index(keyword_index()),
        "year": int()
    }
)

print(f"Created collection: {collection.name}")

# Insert some documents
client.collection("books").upsert([
    {"_id": "1", "title": "The Great Gatsby", "year": 1925},
    {"_id": "2", "title": "1984", "year": 1949}
])

# Query the collection
results = client.collection("books").query(
    select(
        "title", "year",
        similarity=fn.semantic_similarity("title", "dystopian novel")
    ).topk(field("similarity"), 10)
)

print(f"Found {len(results)} results")

# List all collections
all_collections = client.collections().list()
print(f"Total collections: {len(all_collections)}")

# Get collection info
collection_info = client.collections().get("books")
print(f"Collection region: {collection_info.region}")

# Delete the collection
client.collections().delete("books")
print("Collection deleted")

Build docs developers (and LLMs) love

Get started for freeTalk to us