# Cosdata Python SDK
A Python SDK for interacting with the Cosdata Vector Database.
## Installation
```bash
pip install cosdata-client
```
## Quick Start
```python
from cosdata.client import Client # Import the Client class
# Initialize the client (all parameters are optional)
client = Client(
host="http://127.0.0.1:8443", # Default host
username="admin", # Default username
password="admin", # Default password
verify=False # SSL verification
)
# Create a collection
collection = client.create_collection(
name="my_collection",
dimension=768, # Vector dimension
description="My vector collection"
)
# Create an index (all parameters are optional)
index = collection.create_index(
distance_metric="cosine", # Default: cosine
num_layers=10, # Default: 10
max_cache_size=1000, # Default: 1000
ef_construction=128, # Default: 128
ef_search=64, # Default: 64
neighbors_count=32, # Default: 32
level_0_neighbors_count=64 # Default: 64
)
# Generate some vectors (example with random data)
import numpy as np
def generate_random_vector(id: int, dimension: int) -> dict:
values = np.random.uniform(-1, 1, dimension).tolist()
return {
"id": id,
"values": values,
"metadata": { # Optional metadata
"created_at": "2024-03-20",
"category": "example"
}
}
# Generate and insert vectors
vectors = [generate_random_vector(i, 768) for i in range(100)]
# Add vectors using a transaction
with index.transaction() as txn:
txn.upsert(vectors)
# Search for similar vectors
results = index.query(
vector=vectors[0]["values"], # Use first vector as query
nn_count=5 # Number of nearest neighbors
)
# Fetch a specific vector
vector = index.fetch_vector(vector_id="1")
# Get collection information
collection_info = collection.get_info()
print(f"Collection info: {collection_info}")
# List all collections
print("Available collections:")
for coll in client.collections():
print(f" - {coll.name} (dimension: {coll.dimension})")
```
## API Reference
### Client
The main client for interacting with the Vector Database API.
```python
client = Client(
host="http://127.0.0.1:8443", # Optional
username="admin", # Optional
password="admin", # Optional
verify=False # Optional
)
```
Methods:
- `create_collection(name: str, dimension: int = 1024, description: Optional[str] = None) -> Collection`
- `get_collection(collection_name: str) -> Collection`
- `list_collections() -> requests.Response`
- `collections() -> Iterator[Collection]`
### Collection
Represents a collection in the vector database.
```python
collection = client.get_collection("my_collection")
```
Methods:
- `create_index(distance_metric: str = "cosine", ...) -> Index`
- `index(distance_metric: str = "cosine") -> Index`
- `get_info() -> Dict[str, Any]`
### Index
Manages indexes and vector operations.
```python
index = collection.create_index()
```
Methods:
- `create_transaction() -> Transaction`
- `transaction() -> Iterator[Transaction]` (context manager)
- `query(vector: List[float], nn_count: int = 5) -> Dict[str, Any]`
- `fetch_vector(vector_id: Union[str, int]) -> Dict[str, Any]`
### Transaction
Manages batch operations on vectors.
```python
# Using context manager (recommended)
with index.transaction() as txn:
txn.upsert(vectors)
# Manual transaction management
txn = index.create_transaction()
txn.upsert(vectors)
txn.commit() # or txn.abort()
```
Methods:
- `upsert(vectors: List[Dict[str, Any]]) -> Self`
- `commit() -> Optional[Dict[str, Any]]`
- `abort() -> Optional[Dict[str, Any]]`
## Best Practices
1. **Connection Management**
- Reuse the client instance across your application
- The client automatically handles authentication and token management
2. **Vector Operations**
- Use transactions for batch operations
- The context manager (`with` statement) automatically handles commit/abort
- Maximum batch size is 200 vectors per transaction
3. **Error Handling**
- All operations raise exceptions on failure
- Use try/except blocks for error handling
- Transactions automatically abort on exceptions when using the context manager
4. **Performance**
- Adjust index parameters based on your use case
- Use appropriate vector dimensions
- Consider batch sizes for large operations
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cosdata-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cosdata, database, embeddings, similarity-search, vector",
"author": null,
"author_email": "Cosdata <contact@cosdata.com>",
"download_url": "https://files.pythonhosted.org/packages/4c/78/d55c5c7cd99c3f768fd870caeda098e67930b1e2f3880aa705ff3b5e0125/cosdata_client-0.1.3.tar.gz",
"platform": null,
"description": "# Cosdata Python SDK\n\nA Python SDK for interacting with the Cosdata Vector Database.\n\n## Installation\n\n```bash\npip install cosdata-client\n```\n\n## Quick Start\n\n```python\nfrom cosdata.client import Client # Import the Client class\n\n# Initialize the client (all parameters are optional)\nclient = Client(\n host=\"http://127.0.0.1:8443\", # Default host\n username=\"admin\", # Default username\n password=\"admin\", # Default password\n verify=False # SSL verification\n)\n\n# Create a collection\ncollection = client.create_collection(\n name=\"my_collection\",\n dimension=768, # Vector dimension\n description=\"My vector collection\"\n)\n\n# Create an index (all parameters are optional)\nindex = collection.create_index(\n distance_metric=\"cosine\", # Default: cosine\n num_layers=10, # Default: 10\n max_cache_size=1000, # Default: 1000\n ef_construction=128, # Default: 128\n ef_search=64, # Default: 64\n neighbors_count=32, # Default: 32\n level_0_neighbors_count=64 # Default: 64\n)\n\n# Generate some vectors (example with random data)\nimport numpy as np\n\ndef generate_random_vector(id: int, dimension: int) -> dict:\n values = np.random.uniform(-1, 1, dimension).tolist()\n return {\n \"id\": id,\n \"values\": values,\n \"metadata\": { # Optional metadata\n \"created_at\": \"2024-03-20\",\n \"category\": \"example\"\n }\n }\n\n# Generate and insert vectors\nvectors = [generate_random_vector(i, 768) for i in range(100)]\n\n# Add vectors using a transaction\nwith index.transaction() as txn:\n txn.upsert(vectors)\n\n# Search for similar vectors\nresults = index.query(\n vector=vectors[0][\"values\"], # Use first vector as query\n nn_count=5 # Number of nearest neighbors\n)\n\n# Fetch a specific vector\nvector = index.fetch_vector(vector_id=\"1\")\n\n# Get collection information\ncollection_info = collection.get_info()\nprint(f\"Collection info: {collection_info}\")\n\n# List all collections\nprint(\"Available collections:\")\nfor coll in client.collections():\n print(f\" - {coll.name} (dimension: {coll.dimension})\")\n```\n\n## API Reference\n\n### Client\n\nThe main client for interacting with the Vector Database API.\n\n```python\nclient = Client(\n host=\"http://127.0.0.1:8443\", # Optional\n username=\"admin\", # Optional\n password=\"admin\", # Optional\n verify=False # Optional\n)\n```\n\nMethods:\n- `create_collection(name: str, dimension: int = 1024, description: Optional[str] = None) -> Collection`\n- `get_collection(collection_name: str) -> Collection`\n- `list_collections() -> requests.Response`\n- `collections() -> Iterator[Collection]`\n\n### Collection\n\nRepresents a collection in the vector database.\n\n```python\ncollection = client.get_collection(\"my_collection\")\n```\n\nMethods:\n- `create_index(distance_metric: str = \"cosine\", ...) -> Index`\n- `index(distance_metric: str = \"cosine\") -> Index`\n- `get_info() -> Dict[str, Any]`\n\n### Index\n\nManages indexes and vector operations.\n\n```python\nindex = collection.create_index()\n```\n\nMethods:\n- `create_transaction() -> Transaction`\n- `transaction() -> Iterator[Transaction]` (context manager)\n- `query(vector: List[float], nn_count: int = 5) -> Dict[str, Any]`\n- `fetch_vector(vector_id: Union[str, int]) -> Dict[str, Any]`\n\n### Transaction\n\nManages batch operations on vectors.\n\n```python\n# Using context manager (recommended)\nwith index.transaction() as txn:\n txn.upsert(vectors)\n\n# Manual transaction management\ntxn = index.create_transaction()\ntxn.upsert(vectors)\ntxn.commit() # or txn.abort()\n```\n\nMethods:\n- `upsert(vectors: List[Dict[str, Any]]) -> Self`\n- `commit() -> Optional[Dict[str, Any]]`\n- `abort() -> Optional[Dict[str, Any]]`\n\n## Best Practices\n\n1. **Connection Management**\n - Reuse the client instance across your application\n - The client automatically handles authentication and token management\n\n2. **Vector Operations**\n - Use transactions for batch operations\n - The context manager (`with` statement) automatically handles commit/abort\n - Maximum batch size is 200 vectors per transaction\n\n3. **Error Handling**\n - All operations raise exceptions on failure\n - Use try/except blocks for error handling\n - Transactions automatically abort on exceptions when using the context manager\n\n4. **Performance**\n - Adjust index parameters based on your use case\n - Use appropriate vector dimensions\n - Consider batch sizes for large operations\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.",
"bugtrack_url": null,
"license": null,
"summary": "A Python SDK for interacting with the Cosdata Vector Database",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/cosdata/cosdata-sdk-python",
"Issues": "https://github.com/cosdata/cosdata-sdk-python/issues",
"Repository": "https://github.com/cosdata/cosdata-sdk-python.git"
},
"split_keywords": [
"cosdata",
" database",
" embeddings",
" similarity-search",
" vector"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "411079c7f70a43781eca5ab123c84a362588f5decd8498fb08883dcb97aaf371",
"md5": "03ef82e95b302fc0798c964ae44391ca",
"sha256": "1676ac8c8fba60c6fbaa97d943dcc0cd69cc709c71f17da19e9e27e107f652e3"
},
"downloads": -1,
"filename": "cosdata_client-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "03ef82e95b302fc0798c964ae44391ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7265,
"upload_time": "2025-03-21T12:58:07",
"upload_time_iso_8601": "2025-03-21T12:58:07.128291Z",
"url": "https://files.pythonhosted.org/packages/41/10/79c7f70a43781eca5ab123c84a362588f5decd8498fb08883dcb97aaf371/cosdata_client-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4c78d55c5c7cd99c3f768fd870caeda098e67930b1e2f3880aa705ff3b5e0125",
"md5": "3a64e8969b7d3941cfec36d7d97d0ed7",
"sha256": "42e8a6b98df5fc9b60ba1c2f451fd49f99622dab8c601a5c2d8309f70f171955"
},
"downloads": -1,
"filename": "cosdata_client-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "3a64e8969b7d3941cfec36d7d97d0ed7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7232,
"upload_time": "2025-03-21T12:58:08",
"upload_time_iso_8601": "2025-03-21T12:58:08.203211Z",
"url": "https://files.pythonhosted.org/packages/4c/78/d55c5c7cd99c3f768fd870caeda098e67930b1e2f3880aa705ff3b5e0125/cosdata_client-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-21 12:58:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cosdata",
"github_project": "cosdata-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cosdata-client"
}
JSON
