{"id":13510722,"url":"https://github.com/jina-ai/annlite","last_synced_at":"2025-07-31T09:39:03.279Z","repository":{"id":37837748,"uuid":"400352346","full_name":"jina-ai/annlite","owner":"jina-ai","description":"⚡ A fast embedded library for approximate nearest neighbor search","archived":false,"fork":false,"pushed_at":"2023-07-21T12:07:51.000Z","size":2826,"stargazers_count":232,"open_issues_count":21,"forks_count":24,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-07-29T03:05:21.708Z","etag":null,"topics":["approximate-nearest-neighbor-search","cython","hnsw","image-search","information-retrieval","neural-search","product-quantization","vector-quantization","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jina-ai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-08-27T01:25:28.000Z","updated_at":"2025-07-22T09:44:14.000Z","dependencies_parsed_at":"2024-02-09T03:43:57.807Z","dependency_job_id":"68bf5a74-9d3f-40f0-a6f6-8b415ff08ff3","html_url":"https://github.com/jina-ai/annlite","commit_stats":{"total_commits":449,"total_committers":15,"mean_commits":"29.933333333333334","dds":"0.36302895322939865","last_synced_commit":"7783b30fd55a10bd2dd0c75dc0451f0fe1834927"},"previous_names":["jina-ai/pqlite"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/jina-ai/annlite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jina-ai%2Fannlite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jina-ai%2Fannlite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jina-ai%2Fannlite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jina-ai%2Fannlite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jina-ai","download_url":"https://codeload.github.com/jina-ai/annlite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jina-ai%2Fannlite/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268017357,"owners_count":24181669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["approximate-nearest-neighbor-search","cython","hnsw","image-search","information-retrieval","neural-search","product-quantization","vector-quantization","vector-search"],"created_at":"2024-08-01T02:01:51.747Z","updated_at":"2025-07-31T09:39:03.250Z","avatar_url":"https://github.com/jina-ai.png","language":"Python","funding_links":[],"categories":["Python","others"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cimg src=\"https://github.com/jina-ai/annlite/blob/main/.github/assets/logo.svg?raw=true\" alt=\"AnnLite logo: A fast and efficient ann libray\" width=\"200px\"\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\u003cb\u003eA fast embedded library for approximate nearest neighbor search\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=center\u003e\n\u003ca href=\"hhttps://github.com/jina-ai/annlite\"\u003e\u003cimg alt=\"GitHub\" src=\"https://img.shields.io/github/license/jina-ai/annlite?style=flat-square\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/annlite/\"\u003e\u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/annlite?label=Release\u0026style=flat-square\"\u003e\u003c/a\u003e\n\u003ca href=\"https://codecov.io/gh/jina-ai/annlite\"\u003e\u003cimg alt=\"Codecov branch\" src=\"https://img.shields.io/codecov/c/github/jina-ai/annlite/main?logo=Codecov\u0026logoColor=white\u0026style=flat-square\"\u003e\u003c/a\u003e\n\u003ca href=\"https://slack.jina.ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Slack-3.1k-blueviolet?logo=slack\u0026amp;logoColor=white\u0026style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c!-- start elevator-pitch --\u003e\n\n\n## What is AnnLite?\n\n`AnnLite` is a *lightweight* and *embeddable* library for **fast** and **filterable** *approximate nearest neighbor search* (ANNS).\nIt allows to search for nearest neighbors in a dataset of millions of points with a Pythonic API.\n\n\n**Highlighted features:**\n\n- 🐥 **Easy-to-use**: a simple API is designed to be used with Python. It is easy to use and intuitive to set up to production.\n\n- 🐎 **Fast**: the library uses a highly optimized approximate nearest neighbor search algorithm (*HNSW*) to search for nearest neighbors.\n\n- 🔎 **Filterable**: the library allows you to search for nearest neighbors within a subset of the dataset.\n\n- 🍱 **Integration**: Smooth integration with neural search ecosystem including [Jina](https://github.com/jina-ai/jina) and [DocArray](https://github.com/jina-ai/docarray),\n    so that users can easily expose search API with **gRPC** and/or **HTTP**.\n\nThe library is easy to install and use. It is designed to be used with Python.\n\n\u003c!---\nRead more on why should you use `AnnLite`: [here](), and compare to alternatives: [here]().\n--\u003e\n\n## Installation\n\nTo use AnnLite, you need to first install it. The easiest way to install AnnLite is using `pip`:\n\n```bash\npip install -U annlite\n```\n\nor install from source:\n\n```bash\npython setup.py install\n```\n\n## Quick start\n\nBefore you start, you need to know some experience about [DocArray](https://github.com/jina-ai/docarray).\n`AnnLite` is designed to be used with [DocArray](https://github.com/jina-ai/docarray), so you need to know how to use `DocArray` first.\n\nFor example, you can create a `DocArray` with `1000` random vectors with `128` dimensions:\n\n```python\nfrom docarray import DocumentArray\nimport numpy as np\n\ndocs = DocumentArray.empty(1000)\ndocs.embeddings = np.random.random([1000, 128]).astype(np.float32)\n```\n\n\n### Index\n\nThen you can create an `AnnIndexer` to index the created `docs` and search for nearest neighbors:\n\n```python\nfrom annlite import AnnLite\n\nann = AnnLite(128, metric='cosine', data_path=\"/tmp/annlite_data\")\nann.index(docs)\n```\n\nNote that this will create a directory `/tmp/annlite_data` to persist the documents indexed.\nIf this directory already exists, the index will be loaded from the directory.\nAnd if you want to create a new index, you can delete the directory first.\n\n### Search\n\nThen you can search for nearest neighbors for some query docs with `ann.search()`:\n\n```python\nquery = DocumentArray.empty(5)\nquery.embeddings = np.random.random([5, 128]).astype(np.float32)\n\nresult = ann.search(query)\n```\n\nThen, you can inspect the retrieved docs for each query doc inside `query` matches:\n```python\nfor q in query:\n    print(f'Query {q.id}')\n    for k, m in enumerate(q.matches):\n        print(f'{k}: {m.id} {m.scores[\"cosine\"]}')\n```\n\n```bash\nQuery ddbae2073416527bad66ff186543eff8\n0: 47dcf7f3fdbe3f0b8d73b87d2a1b266f {'value': 0.17575037}\n1: 7f2cbb8a6c2a3ec7be024b750964f317 {'value': 0.17735684}\n2: 2e7eed87f45a87d3c65c306256566abb {'value': 0.17917466}\nQuery dda90782f6514ebe4be4705054f74452\n0: 6616eecba99bd10d9581d0d5092d59ce {'value': 0.14570713}\n1: d4e3147fc430de1a57c9883615c252c6 {'value': 0.15338594}\n2: 5c7b8b969d4381f405b8f07bc68f8148 {'value': 0.15743542}\n...\n```\n\nOr shorten the loop as one-liner using the element \u0026 attribute selector:\n\n```python\nprint(query['@m', ('id', 'scores__cosine')])\n```\n\n### Query\n\nYou can get specific document by its id:\n\n```python\ndoc = ann.get_doc_by_id('\u003cdoc_id\u003e')\n```\n\nAnd you can also get the documents with `limit` and `offset`, which is useful for pagination:\n\n```python\ndocs = ann.get_docs(limit=10, offset=0)\n```\n\nFurthermore, you can also get the documents ordered by a specific column from the index:\n\n```python\ndocs = ann.get_docs(limit=10, offset=0, order_by='x', ascending=True)\n```\n\n**Note**: the `order_by` column must be one of the `columns` in the index.\n\n### Update\n\nAfter you have indexed the `docs`, you can update the docs in the index by calling `ann.update()`:\n\n```python\nupdated_docs = docs.sample(10)\nupdated_docs.embeddings = np.random.random([10, 128]).astype(np.float32)\n\nann.update(updated_docs)\n```\n\n\n### Delete\n\nAnd finally, you can delete the docs from the index by calling `ann.delete()`:\n\n```python\nto_delete = docs.sample(10)\nann.delete(to_delete)\n```\n\n## Search with filters\n\nTo support search with filters, the annlite must be created with `colums` parameter, which is a series of fields you want to filter by.\nAt the query time, the annlite will filter the dataset by providing `conditions` for certain fields.\n\n```python\nimport annlite\n\n# the column schema: (name:str, dtype:type, create_index: bool)\nann = annlite.AnnLite(128, columns=[('price', float)], data_path=\"/tmp/annlite_data\")\n```\n\nThen you can insert the docs, in which each doc has a field `price` with a float value contained in the `tags`:\n\n\n```python\nimport random\n\ndocs = DocumentArray.empty(1000)\ndocs = DocumentArray(\n    [\n        Document(id=f'{i}', tags={'price': random.random()})\n        for i in range(1000)\n    ]\n)\n\ndocs.embeddings = np.random.random([1000, 128]).astype(np.float32)\n\nann.index(docs)\n```\n\nThen you can search for nearest neighbors with filtering conditions as:\n\n```python\nquery = DocumentArray.empty(5)\nquery.embeddings = np.random.random([5, 128]).astype(np.float32)\n\nann.search(query, filter={\"price\": {\"$lte\": 50}}, limit=10)\nprint(f'the result with filtering:')\nfor i, q in enumerate(query):\n    print(f'query [{i}]:')\n    for m in q.matches:\n        print(f'\\t{m.id} {m.scores[\"euclidean\"].value} (price={m.tags[\"price\"]})')\n```\n\nThe `conditions` parameter is a dictionary of conditions. The key is the field name, and the value is a dictionary of conditions.\nThe query language is the same as  [MongoDB Query Language](https://docs.mongodb.com/manual/reference/operator/query/).\nWe currently support a subset of those selectors.\n\n- `$eq` - Equal to (number, string)\n- `$ne` - Not equal to (number, string)\n- `$gt` - Greater than (number)\n- `$gte` - Greater than or equal to (number)\n- `$lt` - Less than (number)\n- `$lte` - Less than or equal to (number)\n- `$in` - Included in an array\n- `$nin` - Not included in an array\n\n\nThe query will be performed on the field if the condition is satisfied. The following is an example of a query:\n\n1. A Nike shoes with white color\n\n    ```python\n    {\n      \"brand\": {\"$eq\": \"Nike\"},\n      \"category\": {\"$eq\": \"Shoes\"},\n      \"color\": {\"$eq\": \"White\"}\n    }\n    ```\n\n    We also support boolean operators `$or` and `$and`:\n\n    ```python\n    {\n      \"$and\":\n        {\n          \"brand\": {\"$eq\": \"Nike\"},\n          \"category\": {\"$eq\": \"Shoes\"},\n          \"color\": {\"$eq\": \"White\"}\n        }\n    }\n    ```\n\n2. A Nike shoes or price less than `100$`:\n\n    ```python\n    {\n        \"$or\":\n        {\n        \"brand\": {\"$eq\": \"Nike\"},\n        \"price\": {\"$lte\": 100}\n        }\n    }\n    ```\n\n## Dump and Load\n\nBy default, the hnsw index is in memory. You can dump the index to `data_path` by calling `.dump()`:\n\n```python\n\nfrom annlite import AnnLite\n\nann = AnnLite(128, metric='cosine', data_path=\"/path/to/data_path\")\nann.index(docs)\nann.dump()\n```\n\nAnd you can restore the hnsw index from `data_path` if it exists:\n\n```python\nnew_ann = AnnLite(128, metric='cosine', data_path=\"/path/to/data_path\")\n```\n\nIf you didn't dump the hnsw index, the index will be rebuilt from scratch. This will take a while.\n\n## Supported distance metrics\n\nThe annlite supports the following distance metrics:\n\n#### Supported distances:\n\n| Distance                                                             |       parameter |                                                Equation |\n|----------------------------------------------------------------------|----------------:|--------------------------------------------------------:|\n| [Euclidean](https://en.wikipedia.org/wiki/Euclidean_distance)        |     `euclidean` |                                d = sqrt(sum((Ai-Bi)^2)) |\n| [Inner product](https://en.wikipedia.org/wiki/Inner_product_space)   | `inner_product` |                                   d = 1.0 - sum(Ai\\*Bi) |\n| [Cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity) |        `cosine` | d = 1.0 - sum(Ai\\*Bi) / sqrt(sum(Ai\\*Ai) * sum(Bi\\*Bi)) |\n\nNote that inner product is not an actual metric. An element can be closer to some other element than to itself.\nThat allows some speedup if you remove all elements that are not the closest to themselves from the index, e.g.,\n`inner_product([1.0, 1.0], [1.0. 1.0]) \u003c inner_product([1.0, 1.0], [2.0, 2.0])`\n\n\n## HNSW algorithm parameters\n\nThe HNSW algorithm has several parameters that can be tuned to improve the search performance.\n\n### Search parameters\n\n- `ef_search` - The size of the dynamic list for the nearest neighbors during search (default: `50`).\nThe larger the value, the more accurate the search results, but the slower the search speed.\nThe `ef_search` must be larger than `limit` parameter in `search(..., limit)`.\n\n- `limit` - The maximum number of results to return (default: `10`).\n\n## Construction parameters\n\n- `max_connection` - The number of bi-directional links created for every new element during construction (default: `16`).\nReasonable range is from `2` to `100`. Higher values works better for dataset with higher dimensionality and/or high recall.\nThis parameter also affects the memory consumption during construction, which is roughly `max_connection * 8-10` bytes per stored element.\n\n    As an example for `n_dim=4` random vectors optimal `max_connection` for search is somewhere around `6`,\nwhile for high dimensional datasets, higher `max_connection` are required (e.g. `M=48-64`) for optimal performance at high recall.\nThe range `max_connection=12-48` is ok for the most of the use cases.\nWhen `max_connection` is changed one has to update the other parameters.\nNonetheless, `ef_search` and `ef_construction` parameters can be roughly estimated by assuming that `max_connection * ef_{construction}` is a constant.\n\n\n- `ef_construction`: The size of the dynamic list for the nearest neighbors during construction (default: `200`).\nHigher values give better accuracy, but increase construction time and memory consumption.\nAt some point, increasing `ef_construction` does not give any more accuracy.\nTo set `ef_construction` to a reasonable value, one can measure the recall: if the recall is lower than 0.9, then increase `ef_construction` and re-run the search.\n\nTo set the parameters, you can define them when creating the annlite:\n\n```python\nfrom annlite import AnnLite\n\nann = AnnLite(128, columns=[('price', float)], data_path=\"/tmp/annlite_data\", ef_construction=200, max_connection=16)\n```\n\n## Benchmark\n\nOne can run `executor/benchmark.py` to get a quick performance overview.\n\n|Stored data| Indexing time | Query size=1 | Query size=8 | Query size=64|\n|---|---|---|---|---|\n|10000 | 2.970 | 0.002 | 0.013 | 0.100|\n|100000 | 76.474 | 0.011 | 0.078 | 0.649|\n|500000 | 467.936 | 0.046 | 0.356 | 2.823|\n|1000000 | 1025.506 | 0.091 | 0.695 | 5.778|\n\nResults with filtering can be generated from `examples/benchmark_with_filtering.py`. This script should produce a table similar to:\n\n| Stored data |% same filter| Indexing time | Query size=1 | Query size=8 | Query size=64|\n|-----|-----|-----|-----|-----|-----|\n| 10000 | 5  | 2.869 | 0.004 | 0.030 | 0.270 |\n| 10000 | 15 | 2.869 | 0.004 | 0.035 | 0.294 |\n| 10000 | 20 | 3.506 | 0.005 | 0.038 | 0.287 |\n| 10000 | 30 | 3.506 | 0.005 | 0.044 | 0.356 |\n| 10000 | 50 | 3.506 | 0.008 | 0.064 | 0.484 |\n| 10000 | 80 | 2.869 | 0.013 | 0.098 | 0.910 |\n| 100000 | 5 | 75.960 | 0.018 | 0.134 | 1.092 |\n| 100000 | 15 | 75.960 | 0.026 | 0.211 | 1.736 |\n| 100000 | 20 | 78.475 | 0.034 | 0.265 | 2.097 |\n| 100000 | 30 | 78.475 | 0.044 | 0.357 | 2.887 |\n| 100000 | 50 | 78.475 | 0.068 | 0.565 | 4.383 |\n| 100000 | 80 | 75.960 | 0.111 | 0.878 | 6.815 |\n| 500000 | 5 | 497.744 | 0.069 | 0.561 | 4.439 |\n| 500000 | 15 | 497.744 | 0.134 | 1.064 | 8.469 |\n| 500000 | 20 | 440.108 | 0.152 | 1.199 | 9.472 |\n| 500000 | 30 | 440.108 | 0.212 | 1.650 | 13.267 |\n| 500000 | 50 | 440.108 | 0.328 | 2.637 | 21.961 |\n| 500000 | 80 | 497.744 | 0.580 | 4.602 | 36.986 |\n| 1000000 | 5 | 1052.388 | 0.131 | 1.031 | 8.212 |\n| 1000000 | 15 | 1052.388 | 0.263 | 2.191 | 16.643 |\n| 1000000 | 20 | 980.598 | 0.351 | 2.659 | 21.193 |\n| 1000000 | 30 | 980.598 | 0.461 | 3.713 | 29.794 |\n| 1000000 | 50 | 980.598 | 0.732 | 5.975 | 47.356 |\n| 1000000 | 80 | 1052.388 | 1.151 | 9.255 | 73.552 |\n\n\nNote that:\n- query times presented are represented in seconds.\n- `% same filter`  indicates the amount of data that verifies a filter in the database.\n    - For example, if `% same filter = 10` and `Stored data = 1_000_000` then it means `100_000` example verify the filter.\n\n\n## Next steps\n\nIf you already have experience with Jina and DocArray, you can start using `AnnLite` right away.\n\nOtherwise, you can check out this advanced tutorial to learn how to use `AnnLite`: [here]() in practice.\n\n\n## 🙋 FAQ\n\n**1. Why should I use `AnnLite`?**\n\n`AnnLite` is easy to use and intuitive to set up in production. It is also very fast and memory efficient, making it a great choice for approximate nearest neighbor search.\n\n**2. How do I use `AnnLite` with Jina?**\n\nWe have implemented an executor for `AnnLite` that can be used with Jina.\n\n```python\nfrom jina import Flow\n\nwith Flow().add(uses='jinahub://AnnLiteIndexer', uses_with={'n_dim': 128}) as f:\n    f.post('/index', inputs=docs)\n```\n\n3. Does `AnnLite` support search with filters?\n\n```text\nYes.\n```\n\n\n## Documentation\n\nYou can find the documentation on [Github]() and [ReadTheDocs]()\n\n## 🤝 Contribute and spread the word\n\nWe are also looking for contributors who want to help us improve: code, documentation, issues, feedback! Here is how you can get started:\n\n- Have a look through GitHub issues labeled \"Good first issue\".\n- Read our Contributor Covenant Code of Conduct\n- Open an issue or submit your pull request!\n\n\n## License\n\n`AnnLite` is licensed under the [Apache License 2.0]().\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjina-ai%2Fannlite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjina-ai%2Fannlite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjina-ai%2Fannlite/lists"}