# Upstash AI Search Python Client
> [!NOTE]
> **This project is in GA Stage.**
>
> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes.
> The Upstash team is committed to maintaining and improving its functionality.
It is a connectionless (HTTP based) AI Search client and designed for:
- Serverless functions (AWS Lambda ...)
- Cloudflare Workers
- Next.js, Jamstack ...
- Client side web/mobile applications
- WebAssembly
- and other environments where HTTP is preferred over TCP.
## Quick Start
### Install
#### Python
```bash
pip install upstash-search
```
### Create Database
Create a new database on [Upstash](https://console.upstash.com/search)
## Basic Usage:
```py
from upstash_search import Search
client = Search(
url="<UPSTASH_SEARCH_REST_URL>",
token="<UPSTASH_SEARCH_REST_TOKEN>",
)
# Access the index of a database
index = client.index("movies")
# Upsert documents into index
index.upsert(
documents=[
{
"id": "movie-0",
"content": {
"title": "Star Wars",
"overview": "Sci-fi space opera",
"genre": "sci-fi",
"category": "classic",
},
"metadata": {
"poster": "https://poster.link/starwars.jpg",
},
},
{
"id": "movie-1",
"content": {
"title": "Inception",
"overview": "Mind-bending thriller",
"genre": "sci-fi",
"category": "modern",
},
"metadata": {
"poster": "https://poster.link/inception.jpg",
},
},
],
)
# Fetch documents by ids
documents = index.fetch(
ids=["movie-0", "movie-1"],
)
print(documents)
# AI search
scores = index.search(
query="space opera",
limit=2,
)
print(scores)
# AI search with reranking
scores = index.search(
query="space opera",
limit=2,
reranking=True
)
print(scores)
# AI search with only semantic search
scores = index.search(
query="space opera",
limit=2,
semantic_weight=1
)
# AI search with only full-text search
scores = index.search(
query="space opera",
limit=2,
semantic_weight=0
)
# AI search with full-text search and sematic search
# combined with equal weights
scores = index.search(
query="space opera",
limit=2,
semantic_weight=0.5
)
# AI search without input enrichment
scores = index.search(
query="space opera",
limit=2,
input_enrichment=False
)
# AI search with filtering
scores = index.search(
query="space opera",
limit=2,
filter="category = 'classic'",
)
print(scores)
# Range over documents
range_documents = index.range(
cursor="",
limit=1,
)
print(range_documents.documents)
# Range over the next page of documents
range_documents = index.range(
cursor=range_documents.next_cursor,
limit=3,
)
# Delete a document by id
index.delete(
ids=["movie-0"],
)
# Reset the index (delete all documents)
index.reset()
# Get database and index info
info = client.info()
print(info)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/upstash/search-py",
"name": "upstash-search",
"maintainer": "Upstash",
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": "support@upstash.com",
"keywords": "Search, Upstash Search, Serverless Search",
"author": "Upstash",
"author_email": "support@upstash.com",
"download_url": "https://files.pythonhosted.org/packages/36/4c/fbc25cb531ac5566a533347d83ab691cd125455e5801cc8045fd6641552c/upstash_search-0.1.1.tar.gz",
"platform": null,
"description": "# Upstash AI Search Python Client\n\n> [!NOTE]\n> **This project is in GA Stage.**\n>\n> The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes.\n> The Upstash team is committed to maintaining and improving its functionality.\n\nIt is a connectionless (HTTP based) AI Search client and designed for:\n\n- Serverless functions (AWS Lambda ...)\n- Cloudflare Workers\n- Next.js, Jamstack ...\n- Client side web/mobile applications\n- WebAssembly\n- and other environments where HTTP is preferred over TCP.\n\n## Quick Start\n\n### Install\n\n#### Python\n\n```bash\npip install upstash-search\n```\n\n### Create Database\n\nCreate a new database on [Upstash](https://console.upstash.com/search)\n\n## Basic Usage:\n\n```py\nfrom upstash_search import Search\n\nclient = Search(\n url=\"<UPSTASH_SEARCH_REST_URL>\",\n token=\"<UPSTASH_SEARCH_REST_TOKEN>\",\n)\n\n# Access the index of a database\nindex = client.index(\"movies\")\n\n# Upsert documents into index\nindex.upsert(\n documents=[\n {\n \"id\": \"movie-0\",\n \"content\": {\n \"title\": \"Star Wars\",\n \"overview\": \"Sci-fi space opera\",\n \"genre\": \"sci-fi\",\n \"category\": \"classic\",\n },\n \"metadata\": {\n \"poster\": \"https://poster.link/starwars.jpg\",\n },\n },\n {\n \"id\": \"movie-1\",\n \"content\": {\n \"title\": \"Inception\",\n \"overview\": \"Mind-bending thriller\",\n \"genre\": \"sci-fi\",\n \"category\": \"modern\",\n },\n \"metadata\": {\n \"poster\": \"https://poster.link/inception.jpg\",\n },\n },\n ],\n)\n\n# Fetch documents by ids\ndocuments = index.fetch(\n ids=[\"movie-0\", \"movie-1\"],\n)\nprint(documents)\n\n# AI search\nscores = index.search(\n query=\"space opera\",\n limit=2,\n)\nprint(scores)\n\n# AI search with reranking\nscores = index.search(\n query=\"space opera\",\n limit=2,\n reranking=True\n)\nprint(scores)\n\n# AI search with only semantic search\nscores = index.search(\n query=\"space opera\",\n limit=2,\n semantic_weight=1\n)\n\n# AI search with only full-text search\nscores = index.search(\n query=\"space opera\",\n limit=2,\n semantic_weight=0\n)\n\n# AI search with full-text search and sematic search\n# combined with equal weights\nscores = index.search(\n query=\"space opera\",\n limit=2,\n semantic_weight=0.5\n)\n\n# AI search without input enrichment\nscores = index.search(\n query=\"space opera\",\n limit=2,\n input_enrichment=False\n)\n\n# AI search with filtering\nscores = index.search(\n query=\"space opera\",\n limit=2,\n filter=\"category = 'classic'\",\n)\nprint(scores)\n\n# Range over documents\nrange_documents = index.range(\n cursor=\"\",\n limit=1,\n)\nprint(range_documents.documents)\n\n# Range over the next page of documents\nrange_documents = index.range(\n cursor=range_documents.next_cursor,\n limit=3,\n)\n\n# Delete a document by id\nindex.delete(\n ids=[\"movie-0\"],\n)\n\n# Reset the index (delete all documents)\nindex.reset()\n\n# Get database and index info\ninfo = client.info()\nprint(info)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An HTTP/REST based AI Search client built on top of Upstash REST API.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/upstash/search-py",
"Repository": "https://github.com/upstash/search-py"
},
"split_keywords": [
"search",
" upstash search",
" serverless search"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7a44aa151c17ea1e76eaf7ee215ade8a0308388330f55fd615fa92bfcc49bdaf",
"md5": "27402c709d5eafd26be2a3c0fae0c22c",
"sha256": "bd7126ff6e2d852eb0a2cc6d24825521bf883d9c74784ac27dd5f4d6bf9e249b"
},
"downloads": -1,
"filename": "upstash_search-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27402c709d5eafd26be2a3c0fae0c22c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 13309,
"upload_time": "2025-07-25T08:36:28",
"upload_time_iso_8601": "2025-07-25T08:36:28.345855Z",
"url": "https://files.pythonhosted.org/packages/7a/44/aa151c17ea1e76eaf7ee215ade8a0308388330f55fd615fa92bfcc49bdaf/upstash_search-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "364cfbc25cb531ac5566a533347d83ab691cd125455e5801cc8045fd6641552c",
"md5": "9b29e4919e92c48af4dda76a273b3e0f",
"sha256": "83251e642188a26150b0bb2ac0fdfb72420064404e04ff539cc3b797561ac806"
},
"downloads": -1,
"filename": "upstash_search-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "9b29e4919e92c48af4dda76a273b3e0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8455,
"upload_time": "2025-07-25T08:36:29",
"upload_time_iso_8601": "2025-07-25T08:36:29.887120Z",
"url": "https://files.pythonhosted.org/packages/36/4c/fbc25cb531ac5566a533347d83ab691cd125455e5801cc8045fd6641552c/upstash_search-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 08:36:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "upstash",
"github_project": "search-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "upstash-search"
}
JSON
