cosdata-client


Namecosdata-client JSON
Version 0.1.3 PyPI version JSON
download
home_pageNone
SummaryA Python SDK for interacting with the Cosdata Vector Database
upload_time2025-03-21 12:58:08
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseNone
keywords cosdata database embeddings similarity-search vector
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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"
}
        
Elapsed time: 1.44831s