{"id":13486520,"url":"https://github.com/art049/odmantic","last_synced_at":"2026-01-21T23:13:27.897Z","repository":{"id":37796410,"uuid":"260472474","full_name":"art049/odmantic","owner":"art049","description":"Sync and Async ODM (Object Document Mapper) for MongoDB based on python type hints","archived":false,"fork":false,"pushed_at":"2026-01-18T19:33:47.000Z","size":6277,"stargazers_count":1155,"open_issues_count":127,"forks_count":92,"subscribers_count":17,"default_branch":"master","last_synced_at":"2026-01-19T02:51:20.515Z","etag":null,"topics":["async","asyncio","database","fastapi","mongo","mongodb","mongodb-orm","motor","nosql","object-document-mapper","odm","orm","pydantic","pymongo","python","python-types","sync","type-hints"],"latest_commit_sha":null,"homepage":"http://art049.github.io/odmantic","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/art049.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-01T13:59:45.000Z","updated_at":"2026-01-18T23:02:35.000Z","dependencies_parsed_at":"2024-06-18T13:49:28.658Z","dependency_job_id":"aeaf0d7b-4ec0-4347-8716-89eadf56796c","html_url":"https://github.com/art049/odmantic","commit_stats":{"total_commits":559,"total_committers":20,"mean_commits":27.95,"dds":0.3273703041144902,"last_synced_commit":"6095d9dc710a8901a4e0b7be92f59486576a2c81"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/art049/odmantic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/art049%2Fodmantic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/art049%2Fodmantic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/art049%2Fodmantic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/art049%2Fodmantic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/art049","download_url":"https://codeload.github.com/art049/odmantic/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/art049%2Fodmantic/sbom","scorecard":{"id":208780,"data":{"date":"2025-08-11","repo":{"name":"github.com/art049/odmantic","commit":"46572816169fc48e821a8971077b58176897b93e"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.2,"checks":[{"name":"Security-Policy","score":4,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Warn: no linked content found","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":1,"reason":"Found 5/28 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Warn: no topLevel permission defined: .github/workflows/codspeed.yml:1","Warn: no topLevel permission defined: .github/workflows/docs-preview.yml:1","Warn: no topLevel permission defined: .github/workflows/docs.yml:1","Warn: no topLevel permission defined: .github/workflows/latest-changes.yml:1","Warn: no topLevel permission defined: .github/workflows/release.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: ISC License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:16: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:96: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:98: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:105: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:123: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:135: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:138: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:148: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:162: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/ci.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codspeed.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/codspeed.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/codspeed.yml:20: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/codspeed.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/codspeed.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/codspeed.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/codspeed.yml:36: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/codspeed.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs-preview.yml:9: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs-preview.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs-preview.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs-preview.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs-preview.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs-preview.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yml:30: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/docs.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/latest-changes.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/latest-changes.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/latest-changes.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/latest-changes.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/release.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/release.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/art049/odmantic/release.yml/master?enable=pin","Warn: containerImage not pinned by hash: .devcontainer/Dockerfile:1: pin your Docker image by updating mcr.microsoft.com/devcontainers/python:3.8 to mcr.microsoft.com/devcontainers/python:3.8@sha256:13822a0e211e5b99816ce3f44f064ee385f7679eb407f901f19ed5328ad557d0","Warn: downloadThenRun not pinned by hash: .devcontainer/Dockerfile:13","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:62","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:63","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:111","Warn: pipCommand not pinned by hash: .github/workflows/ci.yml:112","Warn: pipCommand not pinned by hash: .github/workflows/codspeed.yml:33","Warn: pipCommand not pinned by hash: .github/workflows/codspeed.yml:34","Warn: pipCommand not pinned by hash: .github/workflows/docs-preview.yml:22","Warn: pipCommand not pinned by hash: .github/workflows/docs-preview.yml:23","Warn: pipCommand not pinned by hash: .github/workflows/docs.yml:25","Warn: pipCommand not pinned by hash: .github/workflows/docs.yml:26","Warn: pipCommand not pinned by hash: .github/workflows/release.yml:22","Info:   0 out of  19 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of  11 third-party GitHubAction dependencies pinned","Info:   0 out of   1 containerImage dependencies pinned","Info:   0 out of   1 downloadThenRun dependencies pinned","Info:   0 out of  11 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 11 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T00:19:47.734Z","repository_id":37796410,"created_at":"2025-08-17T00:19:47.734Z","updated_at":"2025-08-17T00:19:47.734Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28646945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T21:29:11.980Z","status":"ssl_error","status_checked_at":"2026-01-21T21:24:31.872Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["async","asyncio","database","fastapi","mongo","mongodb","mongodb-orm","motor","nosql","object-document-mapper","odm","orm","pydantic","pymongo","python","python-types","sync","type-hints"],"created_at":"2024-07-31T18:00:47.652Z","updated_at":"2026-01-21T23:13:27.881Z","avatar_url":"https://github.com/art049.png","language":"Python","readme":"\u003cb\u003e\u003ch1\u003eODMantic\u003c/h1\u003e\u003c/b\u003e\n\n[![build](https://github.com/art049/odmantic/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/art049/odmantic/actions/workflows/ci.yml)\n[![coverage](https://codecov.io/gh/art049/odmantic/branch/master/graph/badge.svg?token=3NYZK14STZ)](https://codecov.io/gh/art049/odmantic)\n![python-3.8-3.9-3.10-3.11-3.12](https://img.shields.io/badge/python-3.8%20|%203.9%20|%203.10%20|%203.11%20|%203.12-informational.svg)\n[![Package version](https://img.shields.io/pypi/v/odmantic?color=%2334D058\u0026label=pypi)](https://pypi.org/project/odmantic)\n[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/art049/odmantic)\n\n---\n\n**Documentation**: [https://art049.github.io/odmantic/](https://art049.github.io/odmantic/)\n\n---\n\nSync and Async ODM (Object Document Mapper) for \u003ca href=\"https://www.mongodb.com/\"\ntarget=\"_blank\"\u003eMongoDB\u003c/a\u003e based on standard Python type hints. Built on top of \u003ca\nhref=\"https://docs.pydantic.dev/\" target=\"_blank\"\u003ePydantic\u003c/a\u003e for model\ndefinition and validation.\n\nCore features:\n\n- **Simple**: define your model by typing your fields using Python types, build queries\n  using Python comparison operators\n\n- **Developer experience**: field/method autocompletion, type hints, data validation,\n  performing database operations with a functional API\n\n- **Fully typed**: leverage static analysis to reduce runtime issues\n\n- **AsyncIO support**: works well with ASGI frameworks (\u003ca href=\"https://fastapi.tiangolo.com/\"\n  target=\"_blank\"\u003eFastAPI\u003c/a\u003e, \u003ca href=\"https://pgjones.gitlab.io/quart/\"\n  target=\"_blank\"\u003equart\u003c/a\u003e, \u003ca href=\"https://sanicframework.org/\"\n  target=\"_blank\"\u003esanic\u003c/a\u003e, \u003ca href=\"https://www.starlette.io/\"\n  target=\"_blank\"\u003eStarlette\u003c/a\u003e, ...) but works also perfectly in synchronous environments\n\n- **Serialization**: built-in JSON serialization and JSON schema generation\n\n## Requirements\n\n**Python**: 3.8 and later (tested against 3.8, 3.9, 3.10 and 3.11)\n\n**Pydantic**: 2.5 and later\n\n**MongoDB**: 4.0 and later\n\n## Installation\n\n```shell\npip install odmantic\n```\n\n## Example\n\n\u003e To enjoy an async context without any code boilerplate, you can reproduce the\n\u003e following steps using the AsyncIO REPL (only for Python 3.8+).\n\u003e\n\u003e ```\n\u003e python3.8 -m asyncio\n\u003e ```\n\u003e\n\u003e If you are using an earlier version of Python, you can use \u003ca\n\u003e href=\"https://ipython.readthedocs.io/en/stable/install/index.html\"\n\u003e target=\"_blank\"\u003eIPython\u003c/a\u003e which provide an Autoawait feature (starting from Python\n\u003e 3.6).\n\n### Define your first model\n\n```python\nfrom typing import Optional\n\nfrom odmantic import Field, Model\n\n\nclass Publisher(Model):\n    name: str\n    founded: int = Field(ge=1440)\n    location: Optional[str] = None\n```\n\nBy defining the `Publisher` class, we've just created an ODMantic model 🎉. In this\nexample, the model will represent book publishers.\n\nThis model contains three fields:\n\n- `name`: This is the name of the Publisher. This is a simple string field without any\n  specific validation, but it will be required to build a new Publisher.\n\n- `founded`: This is the year of foundation of the Publisher. Since the printing press was invented in 1440, it would be handy to allow only values above 1440. The\n  `ge` keyword argument passed to the Field is exactly doing this. The model will\n  require a founded value greater or equal than 1440.\n\n- `location`: This field will contain the country code of the Publisher. Defining this\n  field as `Optional` with a `None` default value makes it a non required field that\n  will be set automatically when not specified.\n\nThe collection name has been defined by ODMantic as well. In this case it will be\n`publisher`.\n\n### Create some instances\n\n```python\ninstances = [\n    Publisher(name=\"HarperCollins\", founded=1989, location=\"US\"),\n    Publisher(name=\"Hachette Livre\", founded=1826, location=\"FR\"),\n    Publisher(name=\"Lulu\", founded=2002)\n]\n```\n\nWe defined three instances of the Publisher model. They all have a `name` property as it\nwas required. All the foundations years are later than 1440. The last publisher has no\nlocation specified so by default this field is set to `None` (it will be stored as\n`null` in the database).\n\nFor now, those instances only exists locally. We will persist them in a database in the\nnext step.\n\n### Populate the database with your instances\n\n\u003e For the next steps, you'll need to start a local MongoDB server.The easiest way is\n\u003e to use docker. Simply run the next command in a terminal (closing the terminal will\n\u003e terminate the MongoDB instance and remove the container).\n\u003e\n\u003e ```shell\n\u003e docker run --rm -p 27017:27017 mongo\n\u003e ```\n\nFirst, let's connect to the database using the engine. In ODMantic, every database\noperation is performed using the engine object.\n\n```python\nfrom odmantic import AIOEngine\n\nengine = AIOEngine()\n```\n\nBy default, the `AIOEngine` (stands for AsyncIOEngine) automatically tries to connect to a\nMongoDB instance running locally (on port 27017). Since we didn't provide any database name, it will use\nthe database named `test` by default.\n\nThe next step is to persist the instances we created before. We can perform this\noperation using the `AIOEngine.save_all` method.\n\n```python\nawait engine.save_all(instances)\n```\n\nMost of the engine I/O methods are asynchronous, hence the `await` keyword used here.\nOnce the operation is complete, we should be able to see our created documents in the\ndatabase. You can use \u003ca href=\"https://www.mongodb.com/products/compass\"\ntarget=\"_blank\"\u003eCompass\u003c/a\u003e or \u003ca href=\"https://robomongo.org/\"\ntarget=\"_blank\"\u003eRoboMongo\u003c/a\u003e if you'd like to have a graphical interface.\n\nAnother possibility is to use `mongo` CLI directly:\n\n```shell\nmongo --eval \"db.publisher.find({})\"\n```\n\nOutput:\n\n```js\nconnecting to: mongodb://127.0.0.1:27017\n{\n  \"_id\": ObjectId(\"5f67b331514d6855bc5c54c9\"),\n  \"founded\": 1989,\n  \"location\": \"US\",\n  \"name\": \"HarperCollins\"\n},\n{\n  \"_id\": ObjectId(\"5f67b331514d6855bc5c54ca\"),\n  \"founded\":1826,\n  \"location\": \"FR\",\n  \"name\": \"Hachette Livre\"\n},\n{\n  \"_id\": ObjectId(\"5f67b331514d6855bc5c54cb\"),\n  \"founded\": 2002,\n  \"location\": null,\n  \"name\": \"Lulu\"\n}\n```\n\nThe created instances are stored in the `test` database under the `publisher` collection.\n\nWe can see that an `_id` field has been added to each document. MongoDB need this field\nto act as a primary key. Actually, this field is added by ODMantic and you can access it\nunder the name `id`.\n\n```python\nprint(instances[0].id)\n#\u003e ObjectId(\"5f67b331514d6855bc5c54c9\")\n```\n\n### Find instances matching a criteria\n\nSince we now have some documents in the database, we can start building some queries.\n\nFirst, let's find publishers created before the 2000s:\n\n```python\nearly_publishers = await engine.find(Publisher, Publisher.founded \u003c= 2000)\nprint(early_publishers)\n#\u003e [Publisher(name=\"HarperCollins\", founded=1989, location=\"US),\n#\u003e  Publisher(name=\"Hachette Livre\", founded=1826, location=\"FR\")]\n```\n\nHere, we called the `engine.find` method. The first argument we need to specify is the\nModel class we want to query on (in our case `Publisher`). The second argument is the\nactual query. Similarly to \u003ca href=\"https://www.sqlalchemy.org/\"\ntarget=\"_blank\"\u003eSQLAlchemy\u003c/a\u003e, you can build ODMantic queries using the regular python\noperators.\n\nWhen awaited, the `engine.find` method will return the list of matching instances stored\nin the database.\n\nAnother possibility is to query for at most one instance. For example, if we want to\nretrieve a publisher from Canada (CA):\n\n```python\nca_publisher = await engine.find_one(Publisher, Publisher.location == \"CA\")\nprint(ca_publisher)\n#\u003e None\n```\n\nHere the result is `None` because no matching instances have been found in the database.\nThe `engine.find_one` method returns an instance if one exists in the database\notherwise, it will return `None`.\n\n### Modify an instance\n\nFinally, let's edit some instances. For example, we can set the `location` for the\npublisher named `Lulu`.\nFirst, we need to gather the instance from the database:\n\n```python\nlulu = await engine.find_one(Publisher, Publisher.name == \"Lulu\")\nprint(lulu)\n#\u003e Publisher(name=\"Lulu\", founded=2002, location=None)\n```\n\nWe still have the same instance, with no location set. We can change this field:\n\n```python\nlulu.location = \"US\"\nprint(lulu)\n#\u003e Publisher(name=\"Lulu\", founded=2002, location=\"US)\n```\n\nThe location has been changed locally but the last step to persist this change is to\nsave the document:\n\n```python\nawait engine.save(lulu)\n```\n\nWe can now check the database state:\n\n```shell\nmongo --eval \"db.publisher.find({name: 'Lulu'})\"\n```\n\nOutput:\n\n```js hl_lines=\"5\"\nconnecting to: mongodb://127.0.0.1:27017\n{\n  \"_id\": ObjectId(\"5f67b331514d6855bc5c54cb\"),\n  \"founded\": 2002,\n  \"location\": \"US\",\n  \"name\": \"Lulu\"\n}\n```\n\nThe document have been successfully updated !\n\nNow, what if we would like to change the foundation date with an invalid one (before 1440) ?\n\n```python\nlulu.founded = 1000\n#\u003e ValidationError: 1 validation error for Publisher\n#\u003e founded\n#\u003e   ensure this value is greater than 1440\n#\u003e   (type=value_error.number.not_gt; limit_value=1440)\n```\n\nThis will raise an exception as it's not matching the model definition.\n\n### Next steps\n\nIf you already have experience with Pydantic and FastAPI, the [Usage with FastAPI](https://art049.github.io/odmantic/usage_fastapi/) example sould be interesting for you to get kickstarted.\n\nOtherwise, to get started on more advanced practices like relations and building more\nadvanced queries, you can directly check the other sections of the\n[documentation](https://art049.github.io/odmantic/).\n\nIf you wish to contribute to the project (Thank you! :smiley:), you can have a look to the\n[Contributing](https://art049.github.io/odmantic/contributing/) section of the\ndocumentation.\n\n## License\n\nThis project is licensed under the terms of the \u003ca\nhref=\"https://github.com/art049/odmantic/blob/master/LICENSE\" target=\"_blank\"\u003eISC license\u003c/a\u003e.\n","funding_links":[],"categories":["Python","Libraries","ORM","Database Clients","Object Mapping"],"sub_categories":["Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fart049%2Fodmantic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fart049%2Fodmantic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fart049%2Fodmantic/lists"}