# TopK SDK
**Full documentation is available on [docs.topk.io](https://docs.topk.io).**
TopK SDK provides a Python API for managing collections, querying data, and performing advanced search operations, including keyword and vector-based searches. It is designed for scalability and flexibility in building search applications.
## Features
- Create and manage collections with custom schemas.
- Perform keyword and vector-based searches with scoring and ranking.
- Upsert and delete documents in collections.
- Support for schema validation and collection listing.
- Pythonic API for seamless integration.
## Installation
Install the SDK using `pip`:
```bash
pip install topk-sdk
```
## Usage Examples
Create a client:
```python
from topk_sdk import Client
client = Client(api_key="your_api_key", region="aws-us-east-1-thunderbird")
```
### 1. Create a Collection
Define a schema and create a collection.
```python
from topk_sdk.schema import text, vector, vector_index, keyword_index
schema = {
"title": text().required().index(keyword_index()),
"embedding": vector(3).required().index(vector_index(metric="cosine")),
}
client.collections().create("books", schema=schema)
```
### 2. Upsert Documents
Add or update documents in a collection.
```python
client.collection("books").upsert(
[
{"_id": "doc1", "title": "Hello World", "embedding": [1.0, 2.0, 3.0]},
{"_id": "doc2", "title": "Rust Programming", "embedding": [4.0, 5.0, 6.0]},
]
)
```
### 3. Query for Keyword Search
Perform a keyword search with token matching and scoring.
```python
from topk_sdk.query import match, fn, select
results = client.collection("books").query(
select(
text_score=fn.keyword_score(),
).filter(
match("title", token="Rust", weight=10.0)
).top_k("text_score", k=3)
)
```
### 4. Query for Vector Search
Perform a nearest-neighbor search with vector distances.
```python
results = client.collection("books").query(
select(
vector_distance=fn.vector_distance("embedding", [1.0, 2.0, 3.0]),
).top_k("vector_distance", k=3, asc=True)
)
```
### 5. Delete Documents
Remove documents from a collection.
```python
client.collection("books").delete(["doc1"])
```
### 6. List and Delete Collections
Manage collections in your workspace.
```python
# List collections
collections = client.collections().list()
# Delete a collection
client.collections().delete("books")
```
## Testing
Run the test suite with `pytest`:
```bash
pytest
```
Raw data
{
"_id": null,
"home_page": null,
"name": "topk-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "topk, search, vector, search, keyword, bm25",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "\n# TopK SDK\n\n**Full documentation is available on [docs.topk.io](https://docs.topk.io).**\n\nTopK SDK provides a Python API for managing collections, querying data, and performing advanced search operations, including keyword and vector-based searches. It is designed for scalability and flexibility in building search applications.\n\n## Features\n\n- Create and manage collections with custom schemas.\n- Perform keyword and vector-based searches with scoring and ranking.\n- Upsert and delete documents in collections.\n- Support for schema validation and collection listing.\n- Pythonic API for seamless integration.\n\n## Installation\n\nInstall the SDK using `pip`:\n\n```bash\npip install topk-sdk\n```\n\n## Usage Examples\n\nCreate a client:\n\n```python\nfrom topk_sdk import Client\n\nclient = Client(api_key=\"your_api_key\", region=\"aws-us-east-1-thunderbird\")\n```\n\n### 1. Create a Collection\n\nDefine a schema and create a collection.\n\n```python\nfrom topk_sdk.schema import text, vector, vector_index, keyword_index\n\nschema = {\n \"title\": text().required().index(keyword_index()),\n \"embedding\": vector(3).required().index(vector_index(metric=\"cosine\")),\n}\n\nclient.collections().create(\"books\", schema=schema)\n```\n\n### 2. Upsert Documents\n\nAdd or update documents in a collection.\n\n```python\nclient.collection(\"books\").upsert(\n [\n {\"_id\": \"doc1\", \"title\": \"Hello World\", \"embedding\": [1.0, 2.0, 3.0]},\n {\"_id\": \"doc2\", \"title\": \"Rust Programming\", \"embedding\": [4.0, 5.0, 6.0]},\n ]\n)\n```\n\n### 3. Query for Keyword Search\n\nPerform a keyword search with token matching and scoring.\n\n```python\nfrom topk_sdk.query import match, fn, select\n\nresults = client.collection(\"books\").query(\n select(\n text_score=fn.keyword_score(),\n ).filter(\n match(\"title\", token=\"Rust\", weight=10.0)\n ).top_k(\"text_score\", k=3)\n)\n```\n\n### 4. Query for Vector Search\n\nPerform a nearest-neighbor search with vector distances.\n\n```python\nresults = client.collection(\"books\").query(\n select(\n vector_distance=fn.vector_distance(\"embedding\", [1.0, 2.0, 3.0]),\n ).top_k(\"vector_distance\", k=3, asc=True)\n)\n```\n\n### 5. Delete Documents\n\nRemove documents from a collection.\n\n```python\nclient.collection(\"books\").delete([\"doc1\"])\n```\n\n### 6. List and Delete Collections\n\nManage collections in your workspace.\n\n```python\n# List collections\ncollections = client.collections().list()\n\n# Delete a collection\nclient.collections().delete(\"books\")\n```\n\n## Testing\n\nRun the test suite with `pytest`:\n\n```bash\npytest\n```\n\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.1.6",
"project_urls": {
"documentation": "https://docs.topk.io",
"homepage": "https://topk.io",
"repository": "https://github.com/fafolabs/topk-sdk"
},
"split_keywords": [
"topk",
" search",
" vector",
" search",
" keyword",
" bm25"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b699c98e204d8d11b69525bd9017722508c45122d9c81359280c58b107742979",
"md5": "be8e1f6eaaf6a853f73ab1d031512db1",
"sha256": "6e9907aeb0c2d0b9af51976b194a9121c92e8ec087654f9a17168fb751969741"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp310-cp310-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "be8e1f6eaaf6a853f73ab1d031512db1",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 1510690,
"upload_time": "2025-01-27T03:08:58",
"upload_time_iso_8601": "2025-01-27T03:08:58.631793Z",
"url": "https://files.pythonhosted.org/packages/b6/99/c98e204d8d11b69525bd9017722508c45122d9c81359280c58b107742979/topk_sdk-0.1.6-cp310-cp310-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d1c83c28170175445c4813b7012859cac175f3900e273d883205f84897b21c00",
"md5": "05df01f07ca0c482505c371939ea616f",
"sha256": "b3bd1b4681385ee5dab458f129406578f0a36948b7e276375d07f2efcb5fe026"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp310-cp310-manylinux_2_34_aarch64.whl",
"has_sig": false,
"md5_digest": "05df01f07ca0c482505c371939ea616f",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.9",
"size": 1605921,
"upload_time": "2025-01-27T03:12:34",
"upload_time_iso_8601": "2025-01-27T03:12:34.178340Z",
"url": "https://files.pythonhosted.org/packages/d1/c8/3c28170175445c4813b7012859cac175f3900e273d883205f84897b21c00/topk_sdk-0.1.6-cp310-cp310-manylinux_2_34_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e62ad446b841614c44dee90565946e06a908d5897fcf7dea491c542ae913d906",
"md5": "f5531cab299829fae3315887816d5663",
"sha256": "31b777f902424e56671d45644c22e4a947a414832be4460bed5405d252904099"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp311-cp311-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "f5531cab299829fae3315887816d5663",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 1510946,
"upload_time": "2025-01-27T03:09:03",
"upload_time_iso_8601": "2025-01-27T03:09:03.113918Z",
"url": "https://files.pythonhosted.org/packages/e6/2a/d446b841614c44dee90565946e06a908d5897fcf7dea491c542ae913d906/topk_sdk-0.1.6-cp311-cp311-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ce913f3e024dce647fb82e82ea1223535bc1b2a85bad37774e52910db1cf53fd",
"md5": "4e5bb262d92adb150918e69e4b63c11a",
"sha256": "27bac31e5b8530a7a65d1c4fe8b09ecdc75b1d0e0935e0d7d1d765867220c494"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp311-cp311-manylinux_2_34_aarch64.whl",
"has_sig": false,
"md5_digest": "4e5bb262d92adb150918e69e4b63c11a",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.9",
"size": 1606368,
"upload_time": "2025-01-27T03:12:38",
"upload_time_iso_8601": "2025-01-27T03:12:38.195357Z",
"url": "https://files.pythonhosted.org/packages/ce/91/3f3e024dce647fb82e82ea1223535bc1b2a85bad37774e52910db1cf53fd/topk_sdk-0.1.6-cp311-cp311-manylinux_2_34_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "69ee0456cd4f7025ce29dbf644ba0f3b3bf0c4166829b1eebd4ec23c71b1b7f6",
"md5": "18c8503d726736645d6b624214fe5b66",
"sha256": "bf183ab2be0514c4e92c7304b8790029e983fdc57564a6d59c9fa7f042ced255"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp312-cp312-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "18c8503d726736645d6b624214fe5b66",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 1499598,
"upload_time": "2025-01-27T03:09:08",
"upload_time_iso_8601": "2025-01-27T03:09:08.322424Z",
"url": "https://files.pythonhosted.org/packages/69/ee/0456cd4f7025ce29dbf644ba0f3b3bf0c4166829b1eebd4ec23c71b1b7f6/topk_sdk-0.1.6-cp312-cp312-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fed86f9ff0a8ebb3111faeb618d157d54f8967bae3a63761a640651e76d2937e",
"md5": "7d546f19931cf0769e620e26a0067d6e",
"sha256": "eca7bfbd0faaef406ec2dbeb475638030ec7d123cdc3d3ec5a8b26dd30dbf271"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp312-cp312-manylinux_2_34_aarch64.whl",
"has_sig": false,
"md5_digest": "7d546f19931cf0769e620e26a0067d6e",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.9",
"size": 1610652,
"upload_time": "2025-01-27T03:12:42",
"upload_time_iso_8601": "2025-01-27T03:12:42.141754Z",
"url": "https://files.pythonhosted.org/packages/fe/d8/6f9ff0a8ebb3111faeb618d157d54f8967bae3a63761a640651e76d2937e/topk_sdk-0.1.6-cp312-cp312-manylinux_2_34_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ef69f3a15369f78fd0718ba92aa07b062001094901253b790a254a1b87159032",
"md5": "0b2f1253740c6a39989221f3ba14ecc6",
"sha256": "21b65eddaf93d41c4ae97799cc81ca21367778d2a3b8053561d140107c3c74ad"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp313-cp313-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "0b2f1253740c6a39989221f3ba14ecc6",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.9",
"size": 1499000,
"upload_time": "2025-01-27T03:09:12",
"upload_time_iso_8601": "2025-01-27T03:09:12.763118Z",
"url": "https://files.pythonhosted.org/packages/ef/69/f3a15369f78fd0718ba92aa07b062001094901253b790a254a1b87159032/topk_sdk-0.1.6-cp313-cp313-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7dc7972770f6c11dae791193a674585642ce35e3ea6440373eb7ee122317083f",
"md5": "4b3855dcf599e294177e6c826c29e5a3",
"sha256": "9b4c1cdeac03fde09a61b866bf87b8ab18dced0fef34ff3c6670f8db99cd9d2a"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp313-cp313-manylinux_2_34_aarch64.whl",
"has_sig": false,
"md5_digest": "4b3855dcf599e294177e6c826c29e5a3",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.9",
"size": 1610812,
"upload_time": "2025-01-27T03:12:46",
"upload_time_iso_8601": "2025-01-27T03:12:46.078329Z",
"url": "https://files.pythonhosted.org/packages/7d/c7/972770f6c11dae791193a674585642ce35e3ea6440373eb7ee122317083f/topk_sdk-0.1.6-cp313-cp313-manylinux_2_34_aarch64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b12a1320af787152eb89c55b41749fb964b0220470dbb27504dbd11c26f2938d",
"md5": "f152781b850b5b0b1ba1cfd55521db4b",
"sha256": "3e2dfd8e5b4e715d3a1dce517518d0fa7806c84ae0c732affa946f0e5e41dd4f"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp39-cp39-macosx_11_0_arm64.whl",
"has_sig": false,
"md5_digest": "f152781b850b5b0b1ba1cfd55521db4b",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 1511088,
"upload_time": "2025-01-27T03:09:17",
"upload_time_iso_8601": "2025-01-27T03:09:17.213529Z",
"url": "https://files.pythonhosted.org/packages/b1/2a/1320af787152eb89c55b41749fb964b0220470dbb27504dbd11c26f2938d/topk_sdk-0.1.6-cp39-cp39-macosx_11_0_arm64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e90c588516dd1b1c7f45f354642c878c71f4f2cea592dcaa5edc1172b1e1e8fa",
"md5": "5463a999239d405a4be0080f07478d94",
"sha256": "a2d34d349095555fb2cc735bbe604dd930d8c64b23e67879619b0664bf1ccf51"
},
"downloads": -1,
"filename": "topk_sdk-0.1.6-cp39-cp39-manylinux_2_34_aarch64.whl",
"has_sig": false,
"md5_digest": "5463a999239d405a4be0080f07478d94",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.9",
"size": 1606830,
"upload_time": "2025-01-27T03:12:50",
"upload_time_iso_8601": "2025-01-27T03:12:50.726997Z",
"url": "https://files.pythonhosted.org/packages/e9/0c/588516dd1b1c7f45f354642c878c71f4f2cea592dcaa5edc1172b1e1e8fa/topk_sdk-0.1.6-cp39-cp39-manylinux_2_34_aarch64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-27 03:08:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fafolabs",
"github_project": "topk-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "topk-sdk"
}
JSON
