{"id":50287396,"url":"https://github.com/lexxai/django-mariadb-vector","last_synced_at":"2026-05-28T03:30:33.243Z","repository":{"id":347459755,"uuid":"1192832815","full_name":"lexxai/django-mariadb-vector","owner":"lexxai","description":"Django ORM support for the MariaDB Vector field (introduced in MariaDB 11.7+).","archived":false,"fork":false,"pushed_at":"2026-03-28T00:33:48.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T07:38:44.958Z","etag":null,"topics":["django","django-orm","mariadb","vector","vector-search"],"latest_commit_sha":null,"homepage":"https://github.com/lexxai/django-mariadb-vector","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lexxai.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-26T15:52:48.000Z","updated_at":"2026-03-28T00:33:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lexxai/django-mariadb-vector","commit_stats":null,"previous_names":["lexxai/django-mariadb-vector"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/lexxai/django-mariadb-vector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexxai%2Fdjango-mariadb-vector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexxai%2Fdjango-mariadb-vector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexxai%2Fdjango-mariadb-vector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexxai%2Fdjango-mariadb-vector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lexxai","download_url":"https://codeload.github.com/lexxai/django-mariadb-vector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lexxai%2Fdjango-mariadb-vector/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33593400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"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":["django","django-orm","mariadb","vector","vector-search"],"created_at":"2026-05-28T03:30:32.576Z","updated_at":"2026-05-28T03:30:33.228Z","avatar_url":"https://github.com/lexxai.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django MariaDB Vector\n\nDjango ORM support for the MariaDB Vector field (introduced in MariaDB 11.7+).\n\n## Why this project exists\n\nMariaDB introduced **native vector support**, allowing you to store embeddings and perform similarity search directly in the database.\n\nHowever, Django currently lacks:\n- a native `VECTOR` model field\n- ORM support for vector queries\n- automatic migration support for vector indexes\n\nThis project fills that gap by providing a clean, Django-native way to work with MariaDB vectors.\n\n## Features\n\n- Django `MariaDBVectorField` for `VECTOR(n)`\n- Automatic Django migrations\n- Automatic `VECTOR INDEX` creation\n- ORM-friendly similarity queries\n- Recommendation Manager for Django models\n- No raw SQL required\n- Works with MariaDB 11.8.2+\n- Optionally [optimization for better performance](assets/images/perf_v0.2.0_sm.png) when working with vectors with use package `orjson` and `binary_responce` option\n\n\n## Why use this\n\nWithout this package, using MariaDB vectors in Django requires:\n\n- manual SQL migrations\n- custom query expressions\n- fragile schema management\n\nWith this package, you get:\n\n- clean Django models\n- automatic schema generation\n- reusable and maintainable code\n\n## Use cases\n\nThis package is useful for:\n\n- Retrieval-Augmented Generation (RAG)\n- semantic search\n- recommendation systems\n- document / code similarity search\n\nTypical workflow: text → embedding → store → similarity search\n\n## How it works\n- Maps Django field → VECTOR(n)\n- Extends Django migration system\n- Injects MariaDB-specific SQL for:\n- vector columns\n- vector indexes\n- Wraps vector distance functions like:\n  - VEC_DISTANCE\n  - VEC_DISTANCE_COSINE\n  - VEC_DISTANCE_EUCLIDEAN\n- Recommendation Manager (bonus)\n\n## Requirements\n\n- Python 3.12+\n- Django 5.2+, or 6.0+\n- MariaDB 11.8.2 or newer\n\n## Installation\n\n```bash\npip install django-mariadb-vector\n```\n\n### Optional: faster JSON serialization\nFor better performance when working with vectors, install with the orjson extra:\n```bash\npip install django-mariadb-vector[orjson]\n```\n\n## Usage\n\nmodels.py:\n```python\nfrom django.db import models\nfrom django_mariadb_vector import MariaDBVectorField, MariaDBVectorIndex\n\n\nclass MyModel(models.Model):\n    embedding = MariaDBVectorField(dimensions=3)\n\n    class Meta:\n        indexes = [\n            # Vector index (MariaDB 11.8.2+)\n            MariaDBVectorIndex(fields=[\"embedding\"], dimensions=3)\n        ]\n```\n\n### Querying with Vector Functions\n\nYou can use `VecDistance` to perform similarity searches.\n\n```python\nfrom django_mariadb_vector import VecDistance\n\nfrom .models import MyModel\n\n# Find 5 most similar records to a reference vector\nreference_vector = [0.1, 0.2, 0.3]\nresults = MyModel.objects.annotate(\n    distance=VecDistance(\"embedding\", reference_vector)\n).order_by(\"distance\")[:5]\n```\n\n### Optimization: `orlson` for better performance\nin case of installation `django-mariadb-vector` library with extra `orjson` depencedcy\n```bash\npip install django-mariadb-vector[orjson]\n```\nor \n```bash\nuv add django-mariadb-vector[orjson]\n```\n#### Benefits orlson vs json (batch mode)\n- Up to **~20× faster** compared to the standard `json` library on generate vector data\n- Up to **~8× faster** compared to the standard `json` library on response vector data\n\n\u003e **Note:** Performance was measured using 20,000 iterations (3 runs) in  \n\u003e `tests/test_performance.py`, with randomly generated vectors of dimension 3072.\n\n\n### Optimization: `binary_response` for better performance\n\nThe `binary_response` option improves performance when working with vectors by returning data in a compact binary format instead of JSON.\n\n- Vectors are returned as a sequence of **little-endian IEEE 754 float32 bytes** (4 bytes per value)  \n  ([MariaDB reference](https://mariadb.com/docs/server/reference/sql-functions/vector-functions/vec_fromtext))\n- Reduces network traffic between MariaDB and your application\n- Eliminates JSON parsing overhead on the Python side\n\n#### Benefits of binary response (batch mode)\n\n- Up to **~16× faster** compared to the standard `json` library\n- About **~2× faster** compared to `orjson`\n- Lower bandwidth usage for large vector payloads\n\n\u003e **Note:** Performance was measured using 20,000 iterations (3 runs) in  \n\u003e `tests/test_performance.py`, with randomly generated vectors of dimension 3072.\n\n#### Usage of `binary_response`\n\n```python\nfrom django.db import models\nfrom django_mariadb_vector import MariaDBVectorField\n\nclass MyModel(models.Model):\n    embedding = MariaDBVectorField(dimensions=3, binary_response=True)\n```\n\n\n### Recommendation Manager for Django models\n\nUsing a `RecommendationManager` can simplify vector searches in your application:\n\nmodels.py:\n```python\nfrom django.db import models\n\nfrom django_mariadb_vector import MariaDBVectorField, MariaDBVectorIndex\nfrom django_mariadb_vector.managers import RecommendationManager\n\n\nclass MyModel(models.Model):\n    embedding = MariaDBVectorField(dimensions=3)\n    \n    objects = RecommendationManager(vector_field=\"embedding\")\n    \n    class Meta:\n        indexes = [\n            # Vector index (MariaDB 11.8.2+)\n            MariaDBVectorIndex(fields=[\"embedding\"], dimensions=3, m=16),\n        ]\n```\n\n\n#### Example of usage Manager\n```python\nfrom .models import MyModel\n\nreference_vector:list[float] = [0.1, 0.2, 0.3]\n\n# Find 5 most similar records to a reference vector\nresults = MyModel.objects.similar_to_vector(reference_vector, limit=5)\n\nfor item in results:\n    print(f\"{item.name} - Distance: {item.distance}\")\n```\n\n```python\nfrom .models import MyModel\n\nreference_id:int = 1\n# Find 5 most similar records to a reference object by id\nresults = MyModel.objects.similar_to(reference_id, limit=5)\n\nfor item in results:\n    print(f\"{item.name} - Distance: {item.distance}\")\n```\n\n### Advanced Functions\n\nThe following functions are available in `django_mariadb_vector.functions`:\n\n- `Search(expression, vector)`: Convenient wrapper for COSINE distance search.\n- `VecDistance(expression, vector)`: Generic `VEC_DISTANCE` function.\n- `VecDistanceCosine(expression, vector)`: Native MariaDB `VEC_DISTANCE_COSINE`.\n- `VecDistanceEuclidean(expression, vector)`: Native MariaDB `VEC_DISTANCE_EUCLIDEAN`.\n- `VecFromText(text)`: Converts JSON string to MariaDB VECTOR format.\n- `VecToText(expression)`: Converts MariaDB VECTOR format to JSON string.\n\n## Reference\n- https://mariadb.com/docs/server/reference/sql-functions/vector-functions\n\n## Demo \nA minimal demo project showing how to build article recommendations using vector similarity in Django with MariaDB as the database using the `django-mariadb-vector` library.\n\n- Demo repo: https://github.com/lexxai/django-mariadb-vector-demo\n- Example: https://github.com/lexxai/django-mariadb-vector-demo/tree/main/docs\n\n\n## Docker Testing\n\nYou can test the build and run tests in Docker for different Python versions and OS images.\nThe Dockerfile is located in `tests/docker/Dockerfile`.\n\n### Using the helper script (Linux/macOS)\n```bash\nbash tests/docker/run_docker_tests.sh\n```\n\n### Manual build example\n```bash\ndocker build --build-arg PYTHON_VERSION=3.13 -f tests/docker/Dockerfile -t django-mariadb-vector:test-3.13 .\ndocker run --rm django-mariadb-vector:test-3.13\n```\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flexxai%2Fdjango-mariadb-vector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flexxai%2Fdjango-mariadb-vector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flexxai%2Fdjango-mariadb-vector/lists"}