qdrant-client


Nameqdrant-client JSON
Version 1.8.2 PyPI version JSON
download
home_pagehttps://github.com/qdrant/qdrant-client
SummaryClient library for the Qdrant vector search engine
upload_time2024-03-27 14:15:54
maintainerNone
docs_urlNone
authorAndrey Vasnetsov
requires_python>=3.8
licenseApache-2.0
keywords vector search neural matching client
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            

<p align="center">
  <img height="100" src="https://github.com/qdrant/qdrant/raw/master/docs/logo.svg" alt="Qdrant">
</p>

<p align="center">
    <b>Python Client library for the <a href="https://github.com/qdrant/qdrant">Qdrant</a> vector search engine.</b>
</p>


<p align=center>
    <a href="https://pypi.org/project/qdrant-client/"><img src="https://badge.fury.io/py/qdrant-client.svg" alt="PyPI version" height="18"></a>
    <a href="https://qdrant.github.io/qdrant/redoc/index.html"><img src="https://img.shields.io/badge/Docs-OpenAPI%203.0-success" alt="OpenAPI Docs"></a>
    <a href="https://github.com/qdrant/qdrant-client/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-success" alt="Apache 2.0 License"></a>
    <a href="https://qdrant.to/discord"><img src="https://img.shields.io/badge/Discord-Qdrant-5865F2.svg?logo=discord" alt="Discord"></a>
    <a href="https://qdrant.to/roadmap"><img src="https://img.shields.io/badge/Roadmap-2023-bc1439.svg" alt="Roadmap 2023"></a>
    <a href="https://python-client.qdrant.tech/"><img src="docs/images/api-icon.svg" width="30px"></a>
</p>

# Python Qdrant Client

Client library and SDK for the [Qdrant](https://github.com/qdrant/qdrant) vector search engine. Python Client API Documentation is available [here](https://python-client.qdrant.tech/).

Library contains type definitions for all Qdrant API and allows to make both Sync and Async requests.

Client allows calls for all [Qdrant API methods](https://qdrant.github.io/qdrant/redoc/index.html) directly.
It also provides some additional helper methods for frequently required operations, e.g. initial collection uploading.

See [QuickStart](https://qdrant.tech/documentation/quick-start/#create-collection) for more details!

## Installation

```
pip install qdrant-client
```

## Features

- Type hints for all API methods
- Local mode - use same API without running server
- REST and gRPC support
- Minimal dependencies
- Extensive Test Coverage

## Local mode

<p align="center">
  <!--- https://github.com/qdrant/qdrant-client/raw/master -->
  <img max-height="180" src="https://github.com/qdrant/qdrant-client/raw/master/docs/images/try-develop-deploy.png" alt="Qdrant">
</p>

Python client allows you to run same code in local mode without running Qdrant server.

Simply initialize client like this:

```python
from qdrant_client import QdrantClient

client = QdrantClient(":memory:")
# or
client = QdrantClient(path="path/to/db")  # Persists changes to disk
```

Local mode is useful for development, prototyping and testing.

- You can use it to run tests in your CI/CD pipeline.
- Run it in Colab or Jupyter Notebook, no extra dependencies required. See an [example](https://colab.research.google.com/drive/1Bz8RSVHwnNDaNtDwotfPj0w7AYzsdXZ-?usp=sharing)
- When you need to scale, simply switch to server mode.

## Fast Embeddings + Simpler API

```
pip install qdrant-client[fastembed]
```

FastEmbed is a library for creating fast vector embeddings on CPU. It is based on ONNX Runtime and allows to run inference on CPU with GPU-like performance.

Qdrant Client can use FastEmbed to create embeddings and upload them to Qdrant. This allows to simplify API and make it more intuitive.

```python
from qdrant_client import QdrantClient

# Initialize the client
client = QdrantClient(":memory:")  # or QdrantClient(path="path/to/db")

# Prepare your documents, metadata, and IDs
docs = ["Qdrant has Langchain integrations", "Qdrant also has Llama Index integrations"]
metadata = [
    {"source": "Langchain-docs"},
    {"source": "Linkedin-docs"},
]
ids = [42, 2]

# Use the new add method
client.add(
    collection_name="demo_collection",
    documents=docs,
    metadata=metadata,
    ids=ids
)

search_result = client.query(
    collection_name="demo_collection",
    query_text="This is a query document"
)
print(search_result)
```

## Connect to Qdrant server

To connect to Qdrant server, simply specify host and port:

```python
from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", port=6333)
# or
client = QdrantClient(url="http://localhost:6333")
```

You can run Qdrant server locally with docker:

```bash
docker run -p 6333:6333 qdrant/qdrant:latest
```

See more launch options in [Qdrant repository](https://github.com/qdrant/qdrant#usage).


## Connect to Qdrant cloud

You can register and use [Qdrant Cloud](https://cloud.qdrant.io/) to get a free tier account with 1GB RAM.

Once you have your cluster and API key, you can connect to it like this:

```python
from qdrant_client import QdrantClient

qdrant_client = QdrantClient(
    url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
    api_key="<your-api-key>",
)
```

## Examples


Create a new collection
```python
from qdrant_client.models import Distance, VectorParams

client.recreate_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(size=100, distance=Distance.COSINE),
)
```

Insert vectors into a collection

```python
import numpy as np
from qdrant_client.models import PointStruct

vectors = np.random.rand(100, 100)
# NOTE: consider splitting the data into chunks to avoid hitting the server's payload size limit
# or use `upload_collection` or `upload_points` methods which handle this for you
# WARNING: uploading points one-by-one is not recommended due to requests overhead
client.upsert(
    collection_name="my_collection",
    points=[
        PointStruct(
            id=idx,
            vector=vector.tolist(),
            payload={"color": "red", "rand_number": idx % 10}
        )
        for idx, vector in enumerate(vectors)
    ]
)
```

Search for similar vectors

```python
query_vector = np.random.rand(100)
hits = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    limit=5  # Return 5 closest points
)
```

Search for similar vectors with filtering condition

```python
from qdrant_client.models import Filter, FieldCondition, Range

hits = client.search(
    collection_name="my_collection",
    query_vector=query_vector,
    query_filter=Filter(
        must=[  # These conditions are required for search results
            FieldCondition(
                key='rand_number',  # Condition based on values of `rand_number` field.
                range=Range(
                    gte=3  # Select only those results where `rand_number` >= 3
                )
            )
        ]
    ),
    limit=5  # Return 5 closest points
)
```

See more examples in our [Documentation](https://qdrant.tech/documentation/)!

### gRPC

To enable (typically, much faster) collection uploading with gRPC, use the following initialization:

```python
from qdrant_client import QdrantClient

client = QdrantClient(host="localhost", grpc_port=6334, prefer_grpc=True)
```


## Async client

Starting from version 1.6.1, all python client methods are available in async version.

To use it, just import `AsyncQdrantClient` instead of `QdrantClient`:

```python
from qdrant_client import AsyncQdrantClient, models
import numpy as np
import asyncio

async def main():
    # Your async code using QdrantClient might be put here
    client = AsyncQdrantClient(url="http://localhost:6333")

    await client.create_collection(
        collection_name="my_collection",
        vectors_config=models.VectorParams(size=10, distance=models.Distance.COSINE),
    )

    await client.upsert(
        collection_name="my_collection",
        points=[
            models.PointStruct(
                id=i,
                vector=np.random.rand(10).tolist(),
            )
            for i in range(100)
        ],
    )

    res = await client.search(
        collection_name="my_collection",
        query_vector=np.random.rand(10).tolist(),  # type: ignore
        limit=10,
    )

    print(res)

asyncio.run(main())
```

Both, gRPC and REST API are supported in async mode.
More examples can be found [here](./tests/test_async_qdrant_client.py).

### Development

This project uses git hooks to run code formatters.

Install `pre-commit` with `pip3 install pre-commit` and set up hooks with `pre-commit install`.

> pre-commit requires python>=3.8


            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/qdrant/qdrant-client",
    "name": "qdrant-client",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "vector, search, neural, matching, client",
    "author": "Andrey Vasnetsov",
    "author_email": "andrey@qdrant.tech",
    "download_url": "https://files.pythonhosted.org/packages/cb/d8/69578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba/qdrant_client-1.8.2.tar.gz",
    "platform": null,
    "description": "\n\n<p align=\"center\">\n  <img height=\"100\" src=\"https://github.com/qdrant/qdrant/raw/master/docs/logo.svg\" alt=\"Qdrant\">\n</p>\n\n<p align=\"center\">\n    <b>Python Client library for the <a href=\"https://github.com/qdrant/qdrant\">Qdrant</a> vector search engine.</b>\n</p>\n\n\n<p align=center>\n    <a href=\"https://pypi.org/project/qdrant-client/\"><img src=\"https://badge.fury.io/py/qdrant-client.svg\" alt=\"PyPI version\" height=\"18\"></a>\n    <a href=\"https://qdrant.github.io/qdrant/redoc/index.html\"><img src=\"https://img.shields.io/badge/Docs-OpenAPI%203.0-success\" alt=\"OpenAPI Docs\"></a>\n    <a href=\"https://github.com/qdrant/qdrant-client/blob/master/LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-success\" alt=\"Apache 2.0 License\"></a>\n    <a href=\"https://qdrant.to/discord\"><img src=\"https://img.shields.io/badge/Discord-Qdrant-5865F2.svg?logo=discord\" alt=\"Discord\"></a>\n    <a href=\"https://qdrant.to/roadmap\"><img src=\"https://img.shields.io/badge/Roadmap-2023-bc1439.svg\" alt=\"Roadmap 2023\"></a>\n    <a href=\"https://python-client.qdrant.tech/\"><img src=\"docs/images/api-icon.svg\" width=\"30px\"></a>\n</p>\n\n# Python Qdrant Client\n\nClient library and SDK for the [Qdrant](https://github.com/qdrant/qdrant) vector search engine. Python Client API Documentation is available [here](https://python-client.qdrant.tech/).\n\nLibrary contains type definitions for all Qdrant API and allows to make both Sync and Async requests.\n\nClient allows calls for all [Qdrant API methods](https://qdrant.github.io/qdrant/redoc/index.html) directly.\nIt also provides some additional helper methods for frequently required operations, e.g. initial collection uploading.\n\nSee [QuickStart](https://qdrant.tech/documentation/quick-start/#create-collection) for more details!\n\n## Installation\n\n```\npip install qdrant-client\n```\n\n## Features\n\n- Type hints for all API methods\n- Local mode - use same API without running server\n- REST and gRPC support\n- Minimal dependencies\n- Extensive Test Coverage\n\n## Local mode\n\n<p align=\"center\">\n  <!--- https://github.com/qdrant/qdrant-client/raw/master -->\n  <img max-height=\"180\" src=\"https://github.com/qdrant/qdrant-client/raw/master/docs/images/try-develop-deploy.png\" alt=\"Qdrant\">\n</p>\n\nPython client allows you to run same code in local mode without running Qdrant server.\n\nSimply initialize client like this:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(\":memory:\")\n# or\nclient = QdrantClient(path=\"path/to/db\")  # Persists changes to disk\n```\n\nLocal mode is useful for development, prototyping and testing.\n\n- You can use it to run tests in your CI/CD pipeline.\n- Run it in Colab or Jupyter Notebook, no extra dependencies required. See an [example](https://colab.research.google.com/drive/1Bz8RSVHwnNDaNtDwotfPj0w7AYzsdXZ-?usp=sharing)\n- When you need to scale, simply switch to server mode.\n\n## Fast Embeddings + Simpler API\n\n```\npip install qdrant-client[fastembed]\n```\n\nFastEmbed is a library for creating fast vector embeddings on CPU. It is based on ONNX Runtime and allows to run inference on CPU with GPU-like performance.\n\nQdrant Client can use FastEmbed to create embeddings and upload them to Qdrant. This allows to simplify API and make it more intuitive.\n\n```python\nfrom qdrant_client import QdrantClient\n\n# Initialize the client\nclient = QdrantClient(\":memory:\")  # or QdrantClient(path=\"path/to/db\")\n\n# Prepare your documents, metadata, and IDs\ndocs = [\"Qdrant has Langchain integrations\", \"Qdrant also has Llama Index integrations\"]\nmetadata = [\n    {\"source\": \"Langchain-docs\"},\n    {\"source\": \"Linkedin-docs\"},\n]\nids = [42, 2]\n\n# Use the new add method\nclient.add(\n    collection_name=\"demo_collection\",\n    documents=docs,\n    metadata=metadata,\n    ids=ids\n)\n\nsearch_result = client.query(\n    collection_name=\"demo_collection\",\n    query_text=\"This is a query document\"\n)\nprint(search_result)\n```\n\n## Connect to Qdrant server\n\nTo connect to Qdrant server, simply specify host and port:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(host=\"localhost\", port=6333)\n# or\nclient = QdrantClient(url=\"http://localhost:6333\")\n```\n\nYou can run Qdrant server locally with docker:\n\n```bash\ndocker run -p 6333:6333 qdrant/qdrant:latest\n```\n\nSee more launch options in [Qdrant repository](https://github.com/qdrant/qdrant#usage).\n\n\n## Connect to Qdrant cloud\n\nYou can register and use [Qdrant Cloud](https://cloud.qdrant.io/) to get a free tier account with 1GB RAM.\n\nOnce you have your cluster and API key, you can connect to it like this:\n\n```python\nfrom qdrant_client import QdrantClient\n\nqdrant_client = QdrantClient(\n    url=\"https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333\",\n    api_key=\"<your-api-key>\",\n)\n```\n\n## Examples\n\n\nCreate a new collection\n```python\nfrom qdrant_client.models import Distance, VectorParams\n\nclient.recreate_collection(\n    collection_name=\"my_collection\",\n    vectors_config=VectorParams(size=100, distance=Distance.COSINE),\n)\n```\n\nInsert vectors into a collection\n\n```python\nimport numpy as np\nfrom qdrant_client.models import PointStruct\n\nvectors = np.random.rand(100, 100)\n# NOTE: consider splitting the data into chunks to avoid hitting the server's payload size limit\n# or use `upload_collection` or `upload_points` methods which handle this for you\n# WARNING: uploading points one-by-one is not recommended due to requests overhead\nclient.upsert(\n    collection_name=\"my_collection\",\n    points=[\n        PointStruct(\n            id=idx,\n            vector=vector.tolist(),\n            payload={\"color\": \"red\", \"rand_number\": idx % 10}\n        )\n        for idx, vector in enumerate(vectors)\n    ]\n)\n```\n\nSearch for similar vectors\n\n```python\nquery_vector = np.random.rand(100)\nhits = client.search(\n    collection_name=\"my_collection\",\n    query_vector=query_vector,\n    limit=5  # Return 5 closest points\n)\n```\n\nSearch for similar vectors with filtering condition\n\n```python\nfrom qdrant_client.models import Filter, FieldCondition, Range\n\nhits = client.search(\n    collection_name=\"my_collection\",\n    query_vector=query_vector,\n    query_filter=Filter(\n        must=[  # These conditions are required for search results\n            FieldCondition(\n                key='rand_number',  # Condition based on values of `rand_number` field.\n                range=Range(\n                    gte=3  # Select only those results where `rand_number` >= 3\n                )\n            )\n        ]\n    ),\n    limit=5  # Return 5 closest points\n)\n```\n\nSee more examples in our [Documentation](https://qdrant.tech/documentation/)!\n\n### gRPC\n\nTo enable (typically, much faster) collection uploading with gRPC, use the following initialization:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(host=\"localhost\", grpc_port=6334, prefer_grpc=True)\n```\n\n\n## Async client\n\nStarting from version 1.6.1, all python client methods are available in async version.\n\nTo use it, just import `AsyncQdrantClient` instead of `QdrantClient`:\n\n```python\nfrom qdrant_client import AsyncQdrantClient, models\nimport numpy as np\nimport asyncio\n\nasync def main():\n    # Your async code using QdrantClient might be put here\n    client = AsyncQdrantClient(url=\"http://localhost:6333\")\n\n    await client.create_collection(\n        collection_name=\"my_collection\",\n        vectors_config=models.VectorParams(size=10, distance=models.Distance.COSINE),\n    )\n\n    await client.upsert(\n        collection_name=\"my_collection\",\n        points=[\n            models.PointStruct(\n                id=i,\n                vector=np.random.rand(10).tolist(),\n            )\n            for i in range(100)\n        ],\n    )\n\n    res = await client.search(\n        collection_name=\"my_collection\",\n        query_vector=np.random.rand(10).tolist(),  # type: ignore\n        limit=10,\n    )\n\n    print(res)\n\nasyncio.run(main())\n```\n\nBoth, gRPC and REST API are supported in async mode.\nMore examples can be found [here](./tests/test_async_qdrant_client.py).\n\n### Development\n\nThis project uses git hooks to run code formatters.\n\nInstall `pre-commit` with `pip3 install pre-commit` and set up hooks with `pre-commit install`.\n\n> pre-commit requires python>=3.8\n\n",
    "bugtrack_url": null,
    "license": "Apache-2.0",
    "summary": "Client library for the Qdrant vector search engine",
    "version": "1.8.2",
    "project_urls": {
        "Homepage": "https://github.com/qdrant/qdrant-client",
        "Repository": "https://github.com/qdrant/qdrant-client"
    },
    "split_keywords": [
        "vector",
        " search",
        " neural",
        " matching",
        " client"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cf07b5ad4d11ed64e61aec3f7ab13a5f372b845e0d40363c0da67091c0552b40",
                "md5": "457df0d28936d84205bef33f412d0a7a",
                "sha256": "ee5341c0486d09e4346b0f5ef7781436e6d8cdbf1d5ecddfde7adb3647d353a8"
            },
            "downloads": -1,
            "filename": "qdrant_client-1.8.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "457df0d28936d84205bef33f412d0a7a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 223222,
            "upload_time": "2024-03-27T14:15:51",
            "upload_time_iso_8601": "2024-03-27T14:15:51.771149Z",
            "url": "https://files.pythonhosted.org/packages/cf/07/b5ad4d11ed64e61aec3f7ab13a5f372b845e0d40363c0da67091c0552b40/qdrant_client-1.8.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cbd869578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba",
                "md5": "b4cb979e9d914d247742f0017a4b0b5e",
                "sha256": "65078d5328bc0393f42a46a31cd319a989b8285bf3958360acf1dffffdf4cc4e"
            },
            "downloads": -1,
            "filename": "qdrant_client-1.8.2.tar.gz",
            "has_sig": false,
            "md5_digest": "b4cb979e9d914d247742f0017a4b0b5e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 195225,
            "upload_time": "2024-03-27T14:15:54",
            "upload_time_iso_8601": "2024-03-27T14:15:54.575569Z",
            "url": "https://files.pythonhosted.org/packages/cb/d8/69578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba/qdrant_client-1.8.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-27 14:15:54",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "qdrant",
    "github_project": "qdrant-client",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "qdrant-client"
}
        
Elapsed time: 0.38124s