From 12ca2a021b1b810bfea701a4e4259aeb62be12ab Mon Sep 17 00:00:00 2001
From: OPTIMADE Developers <dev@optimade.org>
Date: Mon, 12 Aug 2024 22:33:01 +0000
Subject: [PATCH] Deployed b6fc4ad to latest with MkDocs 1.6.0 and mike 2.1.2

---
 latest/CHANGELOG/index.html     |  11 ++---
 latest/search/search_index.json |   2 +-
 latest/sitemap.xml              |  76 ++++++++++++++++----------------
 latest/sitemap.xml.gz           | Bin 483 -> 484 bytes
 4 files changed, 45 insertions(+), 44 deletions(-)

diff --git a/latest/CHANGELOG/index.html b/latest/CHANGELOG/index.html
index c646b432..31d477c0 100644
--- a/latest/CHANGELOG/index.html
+++ b/latest/CHANGELOG/index.html
@@ -319,9 +319,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#unreleased-changes-2024-08-06" class="md-nav__link">
+  <a href="#unreleased-changes-2024-08-12" class="md-nav__link">
     <span class="md-ellipsis">
-      Unreleased changes (2024-08-06)
+      Unreleased changes (2024-08-12)
     </span>
   </a>
   
@@ -1468,9 +1468,9 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
       
         <li class="md-nav__item">
-  <a href="#unreleased-changes-2024-08-06" class="md-nav__link">
+  <a href="#unreleased-changes-2024-08-12" class="md-nav__link">
     <span class="md-ellipsis">
-      Unreleased changes (2024-08-06)
+      Unreleased changes (2024-08-12)
     </span>
   </a>
   
@@ -1564,7 +1564,7 @@
 
 
 <h1 id="changelog">Changelog<a class="headerlink" href="#changelog" title="Permanent link">&para;</a></h1>
-<h2 id="unreleased-changes-2024-08-06"><a href="https://github.com/Materials-Consortia/optimade-gateway/tree/Unreleased changes">Unreleased changes</a> (2024-08-06)<a class="headerlink" href="#unreleased-changes-2024-08-06" title="Permanent link">&para;</a></h2>
+<h2 id="unreleased-changes-2024-08-12"><a href="https://github.com/Materials-Consortia/optimade-gateway/tree/Unreleased changes">Unreleased changes</a> (2024-08-12)<a class="headerlink" href="#unreleased-changes-2024-08-12" title="Permanent link">&para;</a></h2>
 <p><a href="https://github.com/Materials-Consortia/optimade-gateway/compare/v0.4.0...Unreleased changes">Full Changelog</a></p>
 <p><strong>Implemented enhancements:</strong></p>
 <ul>
@@ -1589,6 +1589,7 @@ <h2 id="unreleased-changes-2024-08-06"><a href="https://github.com/Materials-Con
 </ul>
 <p><strong>Merged pull requests:</strong></p>
 <ul>
+<li>[pre-commit.ci] pre-commit autoupdate <a href="https://github.com/Materials-Consortia/optimade-gateway/pull/511">#511</a> (<a href="https://github.com/apps/pre-commit-ci">pre-commit-ci[bot]</a>)</li>
 <li>[pre-commit.ci] pre-commit autoupdate <a href="https://github.com/Materials-Consortia/optimade-gateway/pull/510">#510</a> (<a href="https://github.com/apps/pre-commit-ci">pre-commit-ci[bot]</a>)</li>
 <li>Bump SINTEF/ci-cd from 2.7.4 to 2.8.0 in the actions group <a href="https://github.com/Materials-Consortia/optimade-gateway/pull/509">#509</a> (<a href="https://github.com/apps/dependabot">dependabot[bot]</a>)</li>
 <li>[pre-commit.ci] pre-commit autoupdate <a href="https://github.com/Materials-Consortia/optimade-gateway/pull/508">#508</a> (<a href="https://github.com/apps/pre-commit-ci">pre-commit-ci[bot]</a>)</li>
diff --git a/latest/search/search_index.json b/latest/search/search_index.json
index 93e82b1d..7feee87c 100644
--- a/latest/search/search_index.json
+++ b/latest/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"OPTIMADE Gateway","text":"<p>A REST API server acting as a gateway for databases with an OPTIMADE API, handling the distribution and collection of a single query to several different OPTIMADE databases.</p> <p>The design outline is available here.</p>"},{"location":"#known-limitations","title":"Known limitations","text":"<p>Here follows a list of known limitations and oddities of the current OPTIMADE gateway code.</p>"},{"location":"#pagination","title":"Pagination","text":"<p>Pagination is a bit awkward in its current implementation state.</p> <p>When using the <code>page_limit</code> query parameter for a gateway query for gateways with multiple databases, i.e., for <code>GET /gateways/{gateway ID}/structures</code> and <code>GET /queries/{query ID}</code>, the resulting entry-resource number is the product of the <code>page_limit</code> value and the number of databases in the gateway (maximum). This is because the <code>page_limit</code> query parameter is passed straight through to the external database requests, and the returned entries are stitched together for the gateway response.</p> <p>So effectively, when querying <code>GET /gateways/{gateway with N databases}/structures?page_limit=5</code> the resulting (maximum) number of entries returned in the response (the size of the <code>data</code> array in the response) will be N x 5, and not 5 as would otherwise be expected.</p> <p>The intention is to fix this in the future, either through short-time caching of external database responses, or figuring out if there is a usable algorithm that doesn't extend the number of external requests (and therefore the gateway response times) by too much.</p>"},{"location":"#sorting","title":"Sorting","text":"<p>Sorting is supported for all the gateway's own resources, i.e., in the <code>/gateways</code>, <code>/databases</code>, and <code>/queries</code> endpoints. But sorting is not supported for the results from external OPTIMADE databases. This means the <code>sort</code> query parameter has no effect in the <code>GET /gateways/{gateway ID}/structures</code> and <code>GET /queries/{query ID}</code> endpoints.</p> <p>This shortcoming is a direct result of the current <code>page_limit</code> query parameter handling, and the limitation of the same.</p>"},{"location":"#license-copyright-funding-support","title":"License, copyright &amp; funding support","text":"<p>All code in this repository was originally written by Casper Welzel Andersen (@CasperWA). The design for the gateway as outlined in design.md was a joint effort between Casper Welzel Andersen &amp; Carl Simon Adorf (@csadorf).</p> <p>All files in this repository are licensed under the MIT license with copyright \u00a9 2021 Casper Welzel Andersen &amp; THEOS, EPFL.</p>"},{"location":"#funding-support","title":"Funding support","text":"<p>This work was funded by THEOS, EPFL and the MarketPlace project.</p> <p>The MarketPlace project is funded by Horizon 2020 under H2020-NMBP-25-2017 call with Grant agreement number: 760173.</p>"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#unreleased-changes-2024-08-06","title":"Unreleased changes (2024-08-06)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Migrate to pydantic v2 #433</li> <li>Move to use flit build system #418</li> <li>Use callable workflows for CI/CD #391</li> </ul> <p>Fixed bugs:</p> <ul> <li>Support latest <code>pytest-asyncio</code> #447</li> <li>Wrong key used for ignore rules in CI job #423</li> <li>Revert update of codecov-action from v4 to v3 #405</li> <li><code>pre-commit</code> issue for the mypy hook #385</li> <li>Update docs config #366</li> </ul> <p>Closed issues:</p> <ul> <li>Upgrade to ruff #417</li> <li>Remove usage of permanent dependencies branch #411</li> <li>Python 3.8 support is being dropped in dependencies #387</li> <li>Don't use GITHUB_TOKEN for changelog CI steps #368</li> </ul> <p>Merged pull requests:</p> <ul> <li>[pre-commit.ci] pre-commit autoupdate #510 (pre-commit-ci[bot])</li> <li>Bump SINTEF/ci-cd from 2.7.4 to 2.8.0 in the actions group #509 (dependabot[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #508 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #507 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #506 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #505 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #504 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #503 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #502 (pre-commit-ci[bot])</li> <li>Set port as an env var #501 (CasperWA)</li> <li>Rejig Dockerfiles's CMD #500 (CasperWA)</li> <li>Deploy on fly.io #499 (CasperWA)</li> <li>[pre-commit.ci] pre-commit autoupdate #498 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #497 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #496 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #495 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #494 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #493 (pre-commit-ci[bot])</li> <li>Remove all CI/CD to do with the permanent dep branch #491 (CasperWA)</li> <li>Update to pytest-asyncio v0.23 #490 (CasperWA)</li> <li>Update mkdocstrings[python] requirement from ~=0.24.3 to ~=0.25.0 #488 (dependabot[bot])</li> <li>[Auto-generated] Update dependencies #487 (CasperWA)</li> <li>[Auto-generated] Update dependencies #485 (CasperWA)</li> <li>[Auto-generated] Update dependencies #484 (CasperWA)</li> <li>[Auto-generated] Update dependencies #482 (CasperWA)</li> <li>[Auto-generated] Update dependencies #480 (CasperWA)</li> <li>[Auto-generated] Update dependencies #478 (CasperWA)</li> <li>[Auto-generated] Update dependencies #476 (CasperWA)</li> <li>[Auto-generated] Update dependencies #475 (CasperWA)</li> <li>[Auto-generated] Update dependencies #472 (CasperWA)</li> <li>[Auto-generated] Update dependencies #469 (CasperWA)</li> <li>[Auto-generated] Update dependencies #466 (CasperWA)</li> <li>[Auto-generated] Update dependencies #464 (CasperWA)</li> <li>[Auto-generated] Update dependencies #463 (CasperWA)</li> <li>[Auto-generated] Update dependencies #459 (CasperWA)</li> <li>[Auto-generated] Update dependencies #456 (CasperWA)</li> <li>[Auto-generated] Update dependencies #455 (CasperWA)</li> <li>[Auto-generated] Update dependencies #451 (CasperWA)</li> <li>[Auto-generated] Update dependencies #449 (CasperWA)</li> <li>[Auto-generated] Update dependencies #448 (CasperWA)</li> <li>Migrate to pydantic v2 #446 (CasperWA)</li> <li>[Auto-generated] Update dependencies #441 (CasperWA)</li> <li>[Auto-generated] Update dependencies #439 (CasperWA)</li> <li>[Auto-generated] Update dependencies #438 (CasperWA)</li> <li>Bump SINTEF/ci-cd from 2.5.3 to 2.6.0 #437 (dependabot[bot])</li> <li>Update pytest-httpx requirement from ~=0.26.0 to ~=0.27.0 #436 (dependabot[bot])</li> <li>Update mkdocstrings[python-legacy] requirement from ~=0.23.0 to ~=0.24.0 #435 (dependabot[bot])</li> <li>[Auto-generated] Update dependencies #434 (CasperWA)</li> <li>[Auto-generated] Update dependencies #431 (CasperWA)</li> <li>[Auto-generated] Check &amp; update dependencies (<code>pyproject.toml</code>) #430 (CasperWA)</li> <li>[Auto-generated] Update dependencies #428 (CasperWA)</li> <li>[Auto-generated] Update dependencies #426 (CasperWA)</li> <li>Fix key in ignore rule for CI Check deps #424 (CasperWA)</li> <li>[Auto-generated] Update dependencies #422 (CasperWA)</li> <li>Use ruff as the Python linter #420 (CasperWA)</li> <li>Update build system to flit #419 (CasperWA)</li> <li>[Auto-generated] Update dependencies #416 (CasperWA)</li> <li>[Auto-generated] Update dependencies #413 (CasperWA)</li> <li>[Auto-generated] Update dependencies #410 (CasperWA)</li> <li>[Auto-generated] Update dependencies #407 (CasperWA)</li> <li>[Auto-generated] Update dependencies #399 (CasperWA)</li> <li>[Auto-generated] Update dependencies #397 (CasperWA)</li> <li>[Auto-generated] Update dependencies #393 (CasperWA)</li> <li>Use callable workflows for CI/CD #392 (CasperWA)</li> <li>Split dependency version ranges according to Py3.8 support #388 (CasperWA)</li> <li>Update hooks and use pydantic\\&lt;2 for mypy #386 (CasperWA)</li> <li>Update dependencies #378 (CasperWA)</li> <li>Update dependencies #372 (CasperWA)</li> <li>Use PAT instead of GITHUB_TOKEN for changelog steps #369 (CasperWA)</li> <li>Update mkdocs config #367 (CasperWA)</li> <li>Update dependencies #365 (CasperWA)</li> <li>Update dependencies #361 (CasperWA)</li> <li>Update dependencies #359 (CasperWA)</li> <li>Update dependencies #354 (CasperWA)</li> <li>Update dependencies #351 (CasperWA)</li> <li>Update dependencies #348 (CasperWA)</li> <li>Update dependencies #347 (CasperWA)</li> <li>Update dependencies #342 (CasperWA)</li> <li>Update dependencies #339 (CasperWA)</li> <li>Update dependencies #336 (CasperWA)</li> <li>Update dependencies #335 (CasperWA)</li> <li>Update dependencies #333 (CasperWA)</li> <li>Update dependencies #321 (CasperWA)</li> <li>Update dependencies #319 (CasperWA)</li> <li>Update dependencies #318 (CasperWA)</li> <li>Update dependencies #314 (CasperWA)</li> <li>Update dependencies #311 (CasperWA)</li> <li>Update dependencies #307 (CasperWA)</li> <li>Update dependencies #306 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v040-2022-09-28","title":"v0.4.0 (2022-09-28)","text":"<p>Full Changelog</p> <p>Merged pull requests:</p> <ul> <li>Update dependencies #301 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v030-2022-09-19","title":"v0.3.0 (2022-09-19)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>FastAPI safety issues #281</li> <li>pylint rules seems to be stricter #253</li> <li>Fix type for auto-merge workflow #238</li> <li>Pushing in automerge CI workflow not working #179</li> <li>Auto-merge CD workflow not working #177</li> <li>Resetting <code>ci/dependabot-updates</code> branch failing #174</li> <li>Single dependabot PR workflow failing #167</li> <li>Update mcdb name #296 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>More verbose in <code>main</code> push CI job #184</li> <li>Add <code>pre-commit</code> hooks autoupdate to CI #183</li> </ul> <p>Merged pull requests:</p> <ul> <li>Update dependencies #300 (CasperWA)</li> <li>Update dependencies #298 (CasperWA)</li> <li>Update dependencies #293 (CasperWA)</li> <li>Update dependencies #290 (CasperWA)</li> <li>Update dependencies #288 (CasperWA)</li> <li>Update dependencies #286 (CasperWA)</li> <li>Update dependencies #285 (CasperWA)</li> <li>Update dependencies #282 (CasperWA)</li> <li>Remove no-self-use disables #280 (CasperWA)</li> <li>Update dependencies #277 (CasperWA)</li> <li>Update dependencies #271 (CasperWA)</li> <li>Update dependencies #269 (CasperWA)</li> <li>Update dependencies #267 (CasperWA)</li> <li>Update dependencies #264 (CasperWA)</li> <li>Update dependencies #262 (CasperWA)</li> <li>Update dependencies #261 (CasperWA)</li> <li>Update dependencies #258 (CasperWA)</li> <li>Update dependencies #250 (CasperWA)</li> <li>Update dependencies #248 (CasperWA)</li> <li>Update dependencies #246 (CasperWA)</li> <li>Update dependencies #242 (CasperWA)</li> <li>Use <code>ID!</code> type instead of <code>String!</code> #239 (CasperWA)</li> <li>Update dependencies #237 (CasperWA)</li> <li>Update dependencies #235 (CasperWA)</li> <li>Update dependencies #232 (CasperWA)</li> <li>Update dependencies #227 (CasperWA)</li> <li>Update dependencies #223 (CasperWA)</li> <li>Update dependencies #219 (CasperWA)</li> <li>Update dependencies #217 (CasperWA)</li> <li>Update dependencies #210 (CasperWA)</li> <li>Update dependencies #209 (CasperWA)</li> <li>Update dependencies #207 (CasperWA)</li> <li>Update dependencies #205 (CasperWA)</li> <li>Update dependencies #202 (CasperWA)</li> <li>Update dependencies #198 (CasperWA)</li> <li>Update dependencies #197 (CasperWA)</li> <li>Update dependencies #196 (CasperWA)</li> <li>Be more verbose in CI/CD workflows #191 (CasperWA)</li> <li>Update <code>pre-commit</code> hooks in dependabot CI #186 (CasperWA)</li> <li>Update dependencies #182 (CasperWA)</li> <li>Use PAT for pushing to activate CI jobs #181 (CasperWA)</li> <li>Use push action for pushing to dependabot branch #180 (CasperWA)</li> <li>Use <code>ref</code> instead of <code>sha</code> #178 (CasperWA)</li> <li>Update dependencies #173 (CasperWA)</li> <li>Wrap def in quotations and change to single quote #168 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v022-2021-10-05","title":"v0.2.2 (2021-10-05)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>Fix auto-merge workflow to actually run #165</li> <li>Reset <code>ci/dependabot-updates</code> after merging <code>ci/update-dependencies</code> #131</li> </ul> <p>Closed issues:</p> <ul> <li>Activate auto-merge for Dependabot PRs #162</li> <li>Move automatic <code>ci/update-dependencies</code> PR to Tuesday or Friday #160</li> </ul> <p>Merged pull requests:</p> <ul> <li>Move check for dependabot head branch to job #166 (CasperWA)</li> <li>New auto-merge CI for dependabot PRs #163 (CasperWA)</li> <li>Reset <code>ci/dependabot-updates</code> branch upon merge to <code>main</code> #161 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v021-2021-10-04","title":"v0.2.1 (2021-10-04)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Run keep-up-to-date workflow immediately with push #140</li> <li>Update to versioned documentation #132</li> <li>Use <code>bandit</code>, <code>pylint</code>, <code>safety</code>, and <code>mypy</code> #119 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>GH Release action overwrites release description #155</li> <li>Fix condition in <code>main</code> docs deployment #152</li> <li>Properly authenticate the use of <code>gh api</code> in workflow #150</li> <li>Double documentation deploy during release #145</li> <li>Allow beta/alpha releases #143</li> <li>Use protected-push action for keep-up-to-date workflow #138</li> <li>Workflow not working #133</li> <li>Attempt with fetch-depth 0 #154 (CasperWA)</li> <li>Set git config before <code>mike deploy</code> #144 (CasperWA)</li> <li>Use <code>git push</code> instead of action #136 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>Update cron timings for dependency workflows #147</li> <li>Use <code>gh-pages</code> in documentation deploy workflows #142</li> </ul> <p>Merged pull requests:</p> <ul> <li>Update dependencies #159 (CasperWA)</li> <li>Deploy docs to <code>gh-pages</code> branch #157 (CasperWA)</li> <li>Use GH CLI instead of release action #156 (CasperWA)</li> <li>Fix conditional docs <code>main</code> build #153 (CasperWA)</li> <li>Add GITHUB_TOKEN env var to authenticate gh CLI #151 (CasperWA)</li> <li>Fix double docs deployment on release #149 (CasperWA)</li> <li>Update cron times #148 (CasperWA)</li> <li>Update dependencies #146 (CasperWA)</li> <li>Run up-to-date workflow immediately upon push #141 (CasperWA)</li> <li>Push via CasperWA/push-protected action #139 (CasperWA)</li> <li>Use versioned documentation #137 (CasperWA)</li> <li>Fetch everything and ensure correct checkout #135 (CasperWA)</li> <li>Attempt to fix workflow #134 (CasperWA)</li> <li>Run dependabot workflow more often #130 (CasperWA)</li> <li>Only update permanent dependabot branch after CI #127 (CasperWA)</li> <li>Don't use <code>env</code> outside of usable scope #126 (CasperWA)</li> <li>Setup dependabot automation #125 (CasperWA)</li> <li>Don't load providers on startup by default #121 (CasperWA)</li> <li>Update pylint requirement from ~=2.10 to ~=2.11 #120 (dependabot[bot])</li> </ul>"},{"location":"CHANGELOG/#v020-2021-09-07","title":"v0.2.0 (2021-09-07)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Minor re-design #82 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>Fix CD - remnants from #82 #117</li> </ul> <p>Merged pull requests:</p> <ul> <li>Remove references to docker_config.json #118 (CasperWA)</li> <li>Return to major version tags (where available) for GH Actions #114 (CasperWA)</li> <li>Update dependencies #112 (CasperWA)</li> <li>Update pytest-httpx requirement from ~=0.12.0 to ~=0.12.1 #108 (dependabot[bot])</li> <li>Update dependencies #107 (CasperWA)</li> <li>Update dependencies &amp; GH Actions #104 (CasperWA)</li> <li>Update dependencies and GH Actions #99 (CasperWA)</li> <li>Update dependencies #96 (CasperWA)</li> <li>Bump codecov/codecov-action from 1.5.0 to 1.5.2 #83 (dependabot[bot])</li> <li>Update dependencies + GH Actions #81 (CasperWA)</li> <li>Update optimade[server] requirement from ~=0.14.0 to ~=0.15.0 #79 (dependabot[bot])</li> <li>Bump mkdocs-material from 7.1.3 to 7.1.4 #67 (dependabot[bot])</li> <li>Update auto-changelog-action to v1.4 #65 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v012-2021-05-01","title":"v0.1.2 (2021-05-01)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>CD is still wrong #63</li> </ul> <p>Merged pull requests:</p> <ul> <li>Fix tag version retrieval #64 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v011-2021-05-01","title":"v0.1.1 (2021-05-01)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>CD workflow not releasing latest documentation build #61</li> </ul> <p>Merged pull requests:</p> <ul> <li>Use ref variable for actions/checkout #62 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v010-2021-05-01","title":"v0.1.0 (2021-05-01)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Create a /search endpoint #40</li> <li>Sorting #20</li> <li>Add test and update code for creating queries accordingly #38 (CasperWA)</li> <li>Asynchronous queued queries #34 (CasperWA)</li> <li>Add extra endpoints #27 (CasperWA)</li> <li>Versioned base URLs #12 (CasperWA)</li> <li>Dockerfile and docker-compose #11 (CasperWA)</li> <li>Establish /gateways/{id}/structures endpoint #10 (CasperWA)</li> <li>Tests and GET /gateways #7 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>Make tests more loose for model assertion #24 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>Documentation #53</li> <li>Setup mock implementations for testing the gateway #32</li> <li>Finalize the APIs - Determine fate of CLI #16</li> <li>Further abstract and modularize the code #15</li> <li>Update docker CI job #13</li> <li>Don't use GH version of optimade package #8</li> </ul> <p>Merged pull requests:</p> <ul> <li>Change to v0.1.0-rc.1 #60 (CasperWA)</li> <li>Don't sort for external DB requests #59 (CasperWA)</li> <li>Update dependencies #58 (CasperWA)</li> <li>Create documentation site #54 (CasperWA)</li> <li>Update dependencies #52 (CasperWA)</li> <li>Implement /databases for registering and handling known OPTIMADE databases #49 (CasperWA)</li> <li>Change epfl-theos -&gt; Materials-Consortia &amp; update codecov CI step #48 (CasperWA)</li> <li>Update pytest-asyncio requirement from ~=0.14.0 to ~=0.15.0 #47 (dependabot[bot])</li> <li>Add license, copyright and funding information #46 (CasperWA)</li> <li>Update dependencies #45 (CasperWA)</li> <li>Set up the /search endpoint #41 (CasperWA)</li> <li>Use pytest-httpx to mock external responses #39 (CasperWA)</li> <li>Update optimade requirement from ~=0.13.3 to ~=0.14.0 #37 (dependabot[bot])</li> <li>Update httpx requirement from ~=0.17.0 to ~=0.17.1 #36 (dependabot[bot])</li> <li>Use latest MongoDB v4 (v4.4) #33 (CasperWA)</li> <li>Update dependencies #31 (CasperWA)</li> <li>Update httpx requirement from ~=0.16.1 to ~=0.17.0 #28 (dependabot[bot])</li> <li>Update dependencies #26 (CasperWA)</li> <li>Update optimade and docker CI job #14 (CasperWA)</li> <li>Various updates #9 (CasperWA)</li> <li>Update dependencies #6 (CasperWA)</li> </ul> <p>* This Changelog was automatically generated by github_changelog_generator</p>"},{"location":"LICENSE/","title":"License","text":"<p>MIT License</p> <p>Copyright (c) 2021 Casper Welzel Andersen &amp; THEOS, EPFL</p> <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> <p>THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>"},{"location":"design/","title":"Design of the OPTIMADE gateway","text":"<p>The OPTIMADE gateway is intended to be implemented into the MarketPlace platform. Therefore, it should implement the MarketPlace Data Source API, as well as endpoints needed for the gateway capabilities themselves. To this end, the following sections defines/recaps these APIs and capabilities.</p>"},{"location":"design/#marketplace-data-source-api","title":"MarketPlace Data Source API","text":"<p>The MarketPlace Data Source API developed in T2.2 of the MarketPlace project. It can be found on the Fraunhofer GitLab here.</p> <p>Outline of the currently defined endpoints. Note, if there is no HTTP method next to the endpoint, it is not an available and reachable endpoint.</p> <p><code>/marketplace/</code></p> <ul> <li> <p><code>/schemas/</code> (<code>GET</code>)</p> </li> <li> <p><code>/{schema_id}/</code></p> <ul> <li><code>/attributes</code> (<code>GET</code>)</li> <li><code>/export</code> (<code>POST</code>)</li> <li><code>/search</code> (<code>POST</code>)</li> </ul> </li> </ul>"},{"location":"design/#optimade-gateway-api","title":"OPTIMADE gateway API","text":"<p>The suggested OPTIMADE gateway API.</p> <p>This API is based on the expected capabilities outlined below.</p> <p><code>/optimade/</code> Methods: <code>GET</code> Behavior: Introspective/static metadata overview of server.</p> <ul> <li> <p><code>/query/</code> Methods: <code>POST</code> or <code>GET</code> Behavior: Orchestrate an OPTIMADE query.</p> </li> <li> <p><code>/gateways/</code> Methods: <code>GET</code> Behavior: Standard reponse: Introspective/static metadata overview of all gateways. Using special query parameter: Create/retrieve and return unique gateway ID.</p> </li> <li> <p><code>/{gateway_id}/</code> Methods: <code>POST</code> or <code>GET</code> Behavior: Create/retrieve search ID and return unique search ID.     Start asynchronous search task.</p> <p>Either:</p> <ul> <li> <p><code>/queries/</code> Methods: None Behavior: Disallowed. Note: This endpoint could support <code>GET</code> requests with similar functionality and behavior as for <code>/gateways/</code>?   This would move some functionality away from <code>/{gateway_id}/</code> to this endpoint.   Making <code>/{gateway_id}/</code> act as a mix of <code>/query/</code> and <code>/gateways/</code> in terms of orchestrating the search and returning introspective/static metadata about the gateway.</p> </li> <li> <p><code>/{search_id}/</code> Methods: <code>GET</code> Behavior: Return current results according to state of asynchronous search task.</p> </li> </ul> <p>or:</p> <ul> <li><code>/{search_id}/</code> Methods: <code>GET</code> Behavior: Return current results according to state of asynchronous search task.</li> </ul> </li> </ul>"},{"location":"design/#optimade-gateway-capabilities","title":"OPTIMADE gateway capabilities","text":"<ul> <li>Searching in multiple OPTIMADE databases.</li> <li>Utilize the OPTIMADE filter language.</li> <li>Retrieve entries (OPTIMADE structures) as JSON-serialized CUDS.   Not a required capability for the base gateway API.</li> </ul>"},{"location":"design/#design-ideas-and-comments-by-simon-adorf-csadorf","title":"Design ideas and comments by Simon Adorf (@csadorf)","text":"<p>I think the way you would achieve the \u201cselection\u201d of databases is by creating provider-specific endpoints like this:</p> <pre><code>GET\n/gateway?providers=abc,def,xyz\n</code></pre> <p>This will return a deterministic gateway id related to specific set of providers, which you will then use for further queries like this:</p> <pre><code>GET\n/gateway/{gateway_id}/structures/\n</code></pre> <p>etc.</p> <p>The gateway id would provide introspection, so <code>/gateway/{gateway_id}</code> returns some information about the gateway (supported OPTIMADE API, list of providers) etc. You would cache the gateway id in the client, so you don\u2019t have to make two requests for each query. If you don\u2019t provide a list of providers, the current default set is used. But this ensures that the REST API is actually stateless, because one gateway is always tied to a specific set of providers even if the default list is changed. Obviously, if you use a gateway that includes providers that are no longer available you would respond with code 503 or so.</p> <p>This design solves the issue of how to provide a gateway that implements the OPTIMADE API and allows for the selection of providers. I assume your results are paginated, so IMO \u2014 unless you request a specific order \u2014 you should just return results as they come in. You need to implement this gateway asynchronously anyways so it really does not matter whether you include slow providers or not.</p> <p>Of course, this changes if the user requests a specific order, but that\u2019s just how it is. From a user perspective it would make sense to me that such a query across multiple providers may take a while.</p> <p>You should definitely define a timeout for each gateway where if a provider does not respond by then, the result is returned regardless of whether the provider has responded. Or you respond with a time out code.</p>"},{"location":"design/#searching","title":"Searching","text":"<p>Taking Simon's comments into account, the search capability should be:</p> <ul> <li>Asynchronous; and</li> <li>Dynamic.</li> </ul> <p>The asynchronicity comes from creating web calls (possibly using CORS) to each (chosen) database asynchronously, collating the results in a single (gateway) endpoint.</p> <p>The dynamics here relate to the suggested dynamic creation (and possible deletion) of gateway IDs under a <code>/gateway</code>-endpoint.</p>"},{"location":"design/#get-requests","title":"GET requests","text":"<p>Essentially, for each search, a new gateway will be created (if needed) with a unique ID. This unique ID will constitue the content of the initial response after performing a search, so that the user can go to the new gateway ID-specific endpoint to retrieve the results. To make this easier for the user, the server could automatically redirect the user after creating the endpoint. Here the response will contain the currently retrieved results as well as som metadata information about how the search is going and a general overview.</p> <p>This would ideally result in the following search sequence:</p> <p></p> <p>The final <code>GET</code> request can be repeated to retrieve more results during the timeline of the search happening, and to retrieve the final list of results in a set time period after the search has finished.</p>"},{"location":"design/#post-requests","title":"POST requests","text":"<p>One could also think of using <code>POST</code> requests instead, containing the OPTIMADE query parameters alongside with other information, mainly utilized for the <code>/gateway/{unique ID}</code>-endpoints. The response could contain a link or simply redirect to a <code>/gateway/{unique ID}/{search unique ID}</code>-endpoint. The latter part could also be done for the <code>GET</code> approach, since a specific gateway should support multiple unique simultaneous searched. Since the searches are asynchronous, the results don't come back from all resources simultaneously, thus demanding an extra endpoint, where the continuously updating results can be found - as well as the final list of results for a specific search.</p> <p>This differs from the section above, where a <code>GET</code> request should contain query parameters in the URL and this will be correlated with an ongoing (unique) search in the backend, which would potentially allow different users to experience the same loading of results if they performed the same search in the same gateway, even at slightly different times during the searching period.</p> <p>A sequence would ideally look this:</p> <p></p>"},{"location":"design/#conclusion","title":"Conclusion","text":"<p>The best approach here would be to create unique search IDs under each unique gateway, pertaining to a specific search. In the same way that gateways may be reused, search results may be reused. However, to ensure the \"freshness\" of the data, the \"live\"-period for any unique search should be significantly smaller than that of any unique gateway.</p> <p><code>POST</code> requests may be preferred due to the ability of combining OPTIMADE-specific query data and gateway-specific data.</p> <p>Suggested search sequence diagram:</p> <p></p>"},{"location":"design/#design-discussions-17122020","title":"Design discussions (17.12.2020)","text":"<p>To be backwards compatible (where each gateway may represent a fully fledged OPTIMADE database), make <code>/gateways/{unique ID}/</code> redirect to <code>/gateways/{unique ID}/structures/</code>.</p> <p>Note, remove CUDS as a required capability, content negotiation might be with different means than a URL query parameter.</p>"},{"location":"design/#caching","title":"Caching","text":"<p>Caching should be segmented for each database. For each new user query that retrieves and caches individual resources from a database, the lifetime of the cached resource should be updated to the set default (or what is determined by caching headers from the side of the database). Either the CacheControl or requests-cache packages will be utilized for caching.</p> <p>Since the time it takes for an OPTIMADE database to change its content varies, but is mainly quite long, individual search life times (<code>/gateways/{gateway ID}(/queries)/{search ID}/</code>) can be \"long\", e.g., a couple of hours. However, these two ways of \"caching\" should be separate.</p> <p>It should always be possible to forcefully ensure a \"fresh\" search.</p>"},{"location":"design/#optimade-filter-language","title":"OPTIMADE filter language","text":"<p>The filter language will be reused as the filter language for any search in any gateway.</p> <p>The filter language is defined in the OPTIMADE specification.</p>"},{"location":"design/#retrieval-formats","title":"Retrieval formats","text":"<p>All responses will be in JSON (for now).</p> <p>To choose the retrieval format of the structure, a query parameter will be dedicated for the <code>/{search unique ID}</code> endpoint.</p>"},{"location":"design/#optimade","title":"OPTIMADE","text":"<p>The standard OPTIMADE format for defining structures will be reused for listing the structure entries.</p> <p>See the OPTIMADE specification for a list of properties defining the structures entry.</p> <p>When returning the results in this format, the whole response should be compliant with a standard OPTIMADE response as is expected in the <code>/structures</code>-endpoint.</p>"},{"location":"design/#cuds","title":"CUDS","text":"<p>Utilizing the <code>optimade2cuds</code> Python package in the SimOPTIMADE repository on the Fraunhofer GitLab for the MarketPlace project, the resulting OPTIMADE structure can be converted to Python CUDS objects. From there they can be serialized to JSON representations (using the OSP-Core package) and returned as a search result response.</p>"},{"location":"design/#external-api-calls","title":"External API calls","text":"<p>When making external API calls, i.e., requesting the various OPTIMADE databases, this is technically done in a <code>concurrent.futures.ThreadPoolExecutor</code>. This is mainly done to not block the main OS thread, where the asyncio event loop is running. This is the event loop that handles incoming gateway requests. While the number of databases may not be significant, the response times can still vary and by using a <code>ThreadPoolExecutor</code>, the gateway is ready for more heavy use out-of-the-box.</p> <p>Another key reason to use a <code>ThreadPoolExecutor</code> (instead of Starlette's - and therefore FastAPI's - <code>BackgroundTask</code>) is for testing with the <code>pytest</code> framework. When using <code>BackgroundTask</code> the response cannot be properly mocked and instead blocks the main OS thread. Perhaps this could be solved by implementing the same solution as has been done for now, namely running a <code>time.sleep</code> function call in a <code>ThreadPoolExecutor</code>, in the mocked response callback, but the benefits of using a <code>ThreadPoolExecutor</code> also for the actual queries outweigh this in the long run.</p> <p>For further considerations a <code>ProcessPoolExecutor</code> might even be considered, but it shouldn't be necessary as the work done is IO blocking, not CPU blocking. The possible speed-up should not be significant.</p> <p>Further reading and considerations on this subject Multithreading vs. Multiprocessing in Python by Amine Baatout is a good read. Another source of inspiration was found in this StackOverflow post response.</p>"},{"location":"design/#other-ideas-a-queue","title":"Other ideas - a queue","text":"<p>Throughout the process of figuring this out, other ideas were on the table. One was to setup an <code>asyncio.Queue</code> - either a single \"unbuffered channel\" queue for the whole lifetime of the server, or one each per request. This would effectively split up the <code>perform_query</code> in producer/worker functions.</p> <p>For some nice reading on this, check out Latency in Asynchronous Python by Chris Wellons (null program).</p> <p>Since the <code>ThreadPoolExecutor</code> solution solves the issue of the analogous \"heartbeat\" function not losing its responsivenes, i.e., the asyncio event loop not being blocked, and it would work with the current code implementation, I opted for this solution instead. But I recon a queue solution would work similarly, but perhaps with slightly less gateway API responsiveness during heavy load, since it all still runs in the same event loop.</p>"},{"location":"api_reference/events/","title":"events","text":"<p>ASGI app events.</p> <p>These events can be run at application startup or shutdown. The specific events are listed in <code>EVENTS</code> along with their respected proper invocation time.</p>"},{"location":"api_reference/events/#optimade_gateway.events.EVENTS","title":"<code>EVENTS: Sequence[tuple[str, Callable[[], Coroutine[Any, Any, None]]]] = (('startup', ci_dev_startup), ('startup', load_optimade_providers_databases))</code>  <code>module-attribute</code>","text":"<p>A tuple of all pairs of events and event functions.</p> <p>To use this tuple of tuples:</p> <pre><code>from fastapi import FastAPI\nAPP = FastAPI()\nfor event, func in EVENTS:\n    APP.add_event_handler(event, func)\n</code></pre>"},{"location":"api_reference/events/#optimade_gateway.events.ci_dev_startup","title":"<code>ci_dev_startup()</code>  <code>async</code>","text":"<p>Function to run at app startup - only relevant for CI or development to add test data.</p> Source code in <code>optimade_gateway/events.py</code> <pre><code>async def ci_dev_startup() -&gt; None:\n    \"\"\"Function to run at app startup - only relevant for CI or development to add test\n    data.\"\"\"\n    if bool(os.getenv(\"CI\", \"\")):\n        LOGGER.info(\n            \"CI detected - Will load test gateways (after dropping the collection)!\"\n        )\n    elif os.getenv(\"OPTIMADE_MONGO_DATABASE\", \"\") == \"optimade_gateway_dev\":\n        LOGGER.info(\n            \"Running in development mode - Will load test gateways (after dropping the\"\n            \" collection)!\"\n        )\n    else:\n        LOGGER.debug(\"Not in CI or development mode - will start normally.\")\n        return\n\n    # Add test gateways\n    import json\n    from pathlib import Path\n\n    from optimade_gateway.mongo.database import MONGO_DB\n\n    test_data = (\n        Path(__file__).parent.parent.joinpath(\".ci/test_gateways.json\").resolve()\n    )\n\n    await MONGO_DB[CONFIG.gateways_collection].drop()\n\n    if await MONGO_DB[CONFIG.gateways_collection].count_documents({}) != 0:\n        raise RuntimeError(\n            f\"Unexpectedly found documents in the {CONFIG.gateways_collection!r} Mongo\"\n            \" collection after dropping it ! Found number of documents: \"\n            f\"{await MONGO_DB[CONFIG.gateways_collection].count_documents({})}\"\n        )\n\n    if not test_data.exists():\n        raise FileNotFoundError(\n            f\"Could not find test data file with test gateways at {test_data} !\"\n        )\n\n    data = json.loads(test_data.read_bytes())\n\n    await MONGO_DB[CONFIG.gateways_collection].insert_many(data)\n</code></pre>"},{"location":"api_reference/events/#optimade_gateway.events.load_optimade_providers_databases","title":"<code>load_optimade_providers_databases()</code>  <code>async</code>","text":"<p>Load in the providers' OPTIMADE databases from Materials-Consortia</p> <p>Utilize the Materials-Consortia list of OPTIMADE providers at https://providers.optimade.org. Load in all databases with a valid base URL.</p> Source code in <code>optimade_gateway/events.py</code> <pre><code>async def load_optimade_providers_databases() -&gt; None:\n    \"\"\"Load in the providers' OPTIMADE databases from Materials-Consortia\n\n    Utilize the Materials-Consortia list of OPTIMADE providers at\n    [https://providers.optimade.org](https://providers.optimade.org).\n    Load in all databases with a valid base URL.\n    \"\"\"\n    import asyncio\n\n    import httpx\n    from optimade import __api_version__\n    from optimade.models import LinksResponse\n    from optimade.models.links import LinkType\n    from optimade.server.routers.utils import BASE_URL_PREFIXES\n\n    from optimade_gateway.common.utils import clean_python_types, get_resource_attribute\n    from optimade_gateway.models.databases import DatabaseCreate\n    from optimade_gateway.queries.perform import db_get_all_resources\n    from optimade_gateway.routers.utils import resource_factory\n\n    if not CONFIG.load_optimade_providers_databases:\n        LOGGER.debug(\n            \"Will not load databases from Materials-Consortia list of providers.\"\n        )\n        return\n\n    if TYPE_CHECKING or bool(os.getenv(\"MKDOCS_BUILD\", \"\")):  # pragma: no cover\n        providers: httpx.Response | LinksResponse\n\n    async with httpx.AsyncClient() as client:\n        providers = await client.get(\n            \"https://providers.optimade.org/v\"\n            f\"{__api_version__.split('.', maxsplit=1)[0]}/links\"\n        )\n\n    if providers.is_error:\n        LOGGER.warning(\n            \"Response from Materials-Consortia's list of OPTIMADE providers was not \"\n            \"successful (status code != 200). No databases will therefore be added at \"\n            \"server startup.\"\n        )\n        return\n\n    LOGGER.info(\n        \"Registering Materials-Consortia list of OPTIMADE providers' databases.\"\n    )\n\n    providers = LinksResponse(**providers.json())\n\n    valid_providers = []\n    for provider in providers.data:\n        if get_resource_attribute(provider, \"id\") in (\"exmpl\", \"optimade\"):\n            LOGGER.info(\n                \"- %s (id=%r) - Skipping: Not a real provider.\",\n                get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(provider, \"id\"),\n            )\n            continue\n\n        if not get_resource_attribute(provider, \"attributes.base_url\"):\n            LOGGER.info(\n                \"- %s (id=%r) - Skipping: No base URL information.\",\n                get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(provider, \"id\"),\n            )\n            continue\n\n        valid_providers.append(provider)\n\n    # Run queries to each database using the supported major versioned base URL to get a\n    # list of the provider's databases.\n    # There is no need to use ThreadPoolExecutor here, since we want this to block\n    # everything and then finish, before the server actually starts up.\n    provider_queries = [\n        asyncio.create_task(\n            db_get_all_resources(\n                database=provider,\n                endpoint=\"links\",\n                response_model=LinksResponse,\n            )\n        )\n        for provider in valid_providers\n    ]\n\n    for query in asyncio.as_completed(provider_queries):\n        provider_databases, provider = await query\n\n        LOGGER.info(\n            \"- %s (id=%r) - Processing\",\n            get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n            get_resource_attribute(provider, \"id\"),\n        )\n        if not provider_databases:\n            LOGGER.info(\"  - No OPTIMADE databases found.\")\n            continue\n\n        provider_databases = [\n            db\n            for db in provider_databases\n            if await clean_python_types(\n                get_resource_attribute(db, \"attributes.link_type\", \"\")\n            )\n            == LinkType.CHILD.value\n        ]\n\n        if not provider_databases:\n            LOGGER.info(\"  - No OPTIMADE databases found.\")\n            continue\n\n        for database in provider_databases:\n            if not get_resource_attribute(database, \"attributes.base_url\"):\n                LOGGER.info(\n                    \"  - %s (id=%r) - Skipping: No base URL information.\",\n                    get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                    get_resource_attribute(database, \"id\"),\n                )\n                continue\n\n            LOGGER.info(\n                \"  - %s (id=%r) - Checking versioned base URL and /structures\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n            )\n\n            async with httpx.AsyncClient() as client:\n                try:\n                    db_response = await client.get(\n                        f\"{str(get_resource_attribute(database, 'attributes.base_url')).rstrip('/')}\"  # noqa: E501\n                        f\"{BASE_URL_PREFIXES['major']}/structures\",\n                    )\n                except httpx.ReadTimeout:\n                    LOGGER.info(\n                        \"  - %s (id=%r) - Skipping: Timeout while requesting \"\n                        \"%s/structures.\",\n                        get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                        get_resource_attribute(database, \"id\"),\n                        BASE_URL_PREFIXES[\"major\"],\n                    )\n                    continue\n            if db_response.status_code != 200:\n                LOGGER.info(\n                    \"  - %s (id=%r) - Skipping: Response from %s/structures is not \"\n                    \"200 OK.\",\n                    get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                    get_resource_attribute(database, \"id\"),\n                    BASE_URL_PREFIXES[\"major\"],\n                )\n                continue\n\n            new_id = (\n                f\"{get_resource_attribute(provider, 'id')}\"\n                f\"/{get_resource_attribute(database, 'id')}\"\n                if len(provider_databases) &gt; 1\n                else get_resource_attribute(database, \"id\")\n            )\n            registered_database, _ = await resource_factory(\n                DatabaseCreate(\n                    id=new_id,\n                    **await clean_python_types(\n                        get_resource_attribute(database, \"attributes\", {})\n                    ),\n                )\n            )\n            LOGGER.info(\n                \"  - %s (id=%r) - Registered database with id=%r\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n                registered_database.id,\n            )\n</code></pre>"},{"location":"api_reference/exception_handlers/","title":"exception_handlers","text":"<p>ASGI app exception handlers.</p> <p>These are in addition to the exception handlers available in OPTIMADE Python tools. For more information see https://www.optimade.org/optimade-python-tools/api_reference/server/exception_handlers/.</p>"},{"location":"api_reference/exception_handlers/#optimade_gateway.exception_handlers.request_validation_exception_handler","title":"<code>request_validation_exception_handler(request, exc)</code>  <code>async</code>","text":"<p>Special handler if a <code>RequestValidationError</code> comes from wrong <code>POST</code> data</p> Source code in <code>optimade_gateway/exception_handlers.py</code> <pre><code>async def request_validation_exception_handler(\n    request: Request, exc: RequestValidationError\n) -&gt; JSONResponse:\n    \"\"\"Special handler if a `RequestValidationError` comes from wrong `POST` data\"\"\"\n    status_code = 500\n    if request.method in (\"POST\", \"post\"):\n        status_code = 400\n\n    errors = set()\n    for error in exc.errors():\n        pointer = \"/\" + \"/\".join([str(_) for _ in error[\"loc\"]])\n        source = ErrorSource(pointer=pointer)\n        code = error[\"type\"]\n        detail = error[\"msg\"]\n        errors.add(\n            OptimadeError(\n                detail=detail,\n                status=status_code,\n                title=str(exc.__class__.__name__),\n                source=source,\n                code=code,\n            )\n        )\n\n    return general_exception(request, exc, status_code=status_code, errors=list(errors))\n</code></pre>"},{"location":"api_reference/main/","title":"main","text":"<p>The initialization of the ASGI FastAPI application.</p>"},{"location":"api_reference/main/#optimade_gateway.main.APP","title":"<code>APP = FastAPI(title='OPTIMADE Gateway', description='A gateway server to query multiple OPTIMADE databases.', version=__version__)</code>  <code>module-attribute</code>","text":"<p>The FastAPI ASGI application.</p>"},{"location":"api_reference/main/#optimade_gateway.main.get_root","title":"<code>get_root(request)</code>  <code>async</code>","text":"<p><code>GET /</code></p> <p>Introspective overview of gateway server.</p> <p>Note</p> <p>Temporarily redirecting to <code>GET /docs</code>.</p> Source code in <code>optimade_gateway/main.py</code> <pre><code>@APP.get(\"/\", include_in_schema=False)\nasync def get_root(request: Request) -&gt; RedirectResponse:\n    \"\"\"`GET /`\n\n    Introspective overview of gateway server.\n\n    !!! note\n        Temporarily redirecting to `GET /docs`.\n    \"\"\"\n    return RedirectResponse(\n        request.url.replace(path=f\"{request.url.path.strip('/')}/docs\")\n    )\n</code></pre>"},{"location":"api_reference/middleware/","title":"middleware","text":"<p>ASGI app middleware.</p> <p>These are in addition to the middleware available in OPTIMADE Python tools. For more information see https://www.optimade.org/optimade-python-tools/api_reference/server/middleware/.</p>"},{"location":"api_reference/middleware/#optimade_gateway.middleware.CheckWronglyVersionedBaseUrlsGateways","title":"<code>CheckWronglyVersionedBaseUrlsGateways</code>","text":"<p>               Bases: <code>BaseHTTPMiddleware</code></p> <p>If a non-supported versioned base URL is supplied to a gateway return <code>553 Version Not Supported</code>.</p> Source code in <code>optimade_gateway/middleware.py</code> <pre><code>class CheckWronglyVersionedBaseUrlsGateways(BaseHTTPMiddleware):\n    \"\"\"If a non-supported versioned base URL is supplied to a gateway\n    return `553 Version Not Supported`.\"\"\"\n\n    @staticmethod\n    async def check_url(url: URL):\n        \"\"\"Check URL path for versioned part.\n\n        Parameters:\n            url: A complete `urllib`-parsed raw URL.\n\n        Raises:\n            VersionNotSupported: If the URL represents an OPTIMADE versioned base URL\n                and the version part is not supported by the implementation.\n\n        \"\"\"\n        base_url = get_base_url(url)\n        optimade_path = f\"{url.scheme}://{url.netloc}{url.path}\"[len(base_url) :]\n        match = re.match(\n            r\"^/gateways/[^/\\s]+(?P&lt;version&gt;/v[0-9]+(\\.[0-9]+){0,2}).*\", optimade_path\n        )\n        if (\n            match is not None\n            and match.group(\"version\") not in BASE_URL_PREFIXES.values()\n        ):\n            raise VersionNotSupported(\n                detail=(\n                    f\"The parsed versioned base URL {match.group('version')!r} \"\n                    f\"from {url} is not supported by this implementation. \"\n                    \"Supported versioned base URLs are: \"\n                    f\"{', '.join(BASE_URL_PREFIXES.values())}\"\n                )\n            )\n\n    async def dispatch(self, request: Request, call_next):\n        if request.url.path:\n            await self.check_url(request.url)\n        return await call_next(request)\n</code></pre>"},{"location":"api_reference/middleware/#optimade_gateway.middleware.CheckWronglyVersionedBaseUrlsGateways.check_url","title":"<code>check_url(url)</code>  <code>async</code> <code>staticmethod</code>","text":"<p>Check URL path for versioned part.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>URL</code> <p>A complete <code>urllib</code>-parsed raw URL.</p> required <p>Raises:</p> Type Description <code>VersionNotSupported</code> <p>If the URL represents an OPTIMADE versioned base URL and the version part is not supported by the implementation.</p> Source code in <code>optimade_gateway/middleware.py</code> <pre><code>@staticmethod\nasync def check_url(url: URL):\n    \"\"\"Check URL path for versioned part.\n\n    Parameters:\n        url: A complete `urllib`-parsed raw URL.\n\n    Raises:\n        VersionNotSupported: If the URL represents an OPTIMADE versioned base URL\n            and the version part is not supported by the implementation.\n\n    \"\"\"\n    base_url = get_base_url(url)\n    optimade_path = f\"{url.scheme}://{url.netloc}{url.path}\"[len(base_url) :]\n    match = re.match(\n        r\"^/gateways/[^/\\s]+(?P&lt;version&gt;/v[0-9]+(\\.[0-9]+){0,2}).*\", optimade_path\n    )\n    if (\n        match is not None\n        and match.group(\"version\") not in BASE_URL_PREFIXES.values()\n    ):\n        raise VersionNotSupported(\n            detail=(\n                f\"The parsed versioned base URL {match.group('version')!r} \"\n                f\"from {url} is not supported by this implementation. \"\n                \"Supported versioned base URLs are: \"\n                f\"{', '.join(BASE_URL_PREFIXES.values())}\"\n            )\n        )\n</code></pre>"},{"location":"api_reference/warnings/","title":"warnings","text":"<p>Server warnings.</p> <p>The warnings in this module will all be caught by middleware and added to the response under <code>meta.warnings</code>.</p>"},{"location":"api_reference/warnings/#optimade_gateway.warnings.OptimadeGatewayWarning","title":"<code>OptimadeGatewayWarning</code>","text":"<p>               Bases: <code>OptimadeWarning</code></p> <p>Base Warning for the <code>optimade-gateway</code> package.</p> Source code in <code>optimade_gateway/warnings.py</code> <pre><code>class OptimadeGatewayWarning(OptimadeWarning):\n    \"\"\"Base Warning for the `optimade-gateway` package.\"\"\"\n</code></pre>"},{"location":"api_reference/warnings/#optimade_gateway.warnings.SortNotSupported","title":"<code>SortNotSupported</code>","text":"<p>               Bases: <code>OptimadeGatewayWarning</code></p> <p>Sorting (the <code>sort</code> query parameter) is currently not supported for gateway queries to external OPTIMADE databases. See https://optimade.org/optimade-gateway#sorting for more information.</p> Source code in <code>optimade_gateway/warnings.py</code> <pre><code>class SortNotSupported(OptimadeGatewayWarning):\n    \"\"\"Sorting (the `sort` query parameter) is currently not supported for gateway\n    queries to external OPTIMADE databases. See\n    https://optimade.org/optimade-gateway#sorting for more information.\"\"\"\n</code></pre>"},{"location":"api_reference/common/config/","title":"config","text":"<p>Configuration of the FastAPI server.</p>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig","title":"<code>ServerConfig</code>","text":"<p>               Bases: <code>ServerConfig</code></p> <p>This class stores server config parameters in a way that can be easily extended for new config file types.</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>class ServerConfig(OptimadeServerConfig):\n    \"\"\"This class stores server config parameters in a way that\n    can be easily extended for new config file types.\n\n    \"\"\"\n\n    databases_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/databases` endpoint resources.\",\n        ),\n    ] = \"databases\"\n\n    gateways_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/gateways` endpoint resources.\",\n        ),\n    ] = \"gateways\"\n\n    queries_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/queries` endpoint resources.\",\n        ),\n    ] = \"queries\"\n\n    load_optimade_providers_databases: Annotated[\n        bool,\n        Field(\n            description=(\n                \"Whether or not to load all valid OPTIMADE providers' databases from \"\n                \"the [Materials-Consortia list of OPTIMADE providers]\"\n                \"(https://providers.optimade.org) on server startup.\"\n            ),\n        ),\n    ] = True\n\n    mongo_certfile: Annotated[\n        Path,\n        Field(\n            description=\"Path to the MongoDB certificate file.\",\n        ),\n    ] = Path(\"/certs/mongodb.pem\")\n\n    mongo_atlas_pem_content: Annotated[\n        SecretStr | None,\n        Field(\n            description=\"PEM content for MongoDB Atlas certificate.\",\n        ),\n    ] = None\n\n    @field_validator(\"mongo_uri\", mode=\"after\")\n    @classmethod\n    def replace_with_env_vars(cls, value: str) -&gt; str:\n        \"\"\"Replace string variables with environment variables, if possible\"\"\"\n        res = value\n        for match in re.finditer(r\"\\{[^{}]+\\}\", value):\n            string_var = match.group()[1:-1]\n            env_var = os.getenv(\n                string_var, os.getenv(string_var.upper(), os.getenv(string_var.lower()))\n            )\n            if env_var is not None:\n                res = res.replace(match.group(), env_var)\n            else:\n                warn(\n                    OptimadeGatewayWarning(\n                        detail=(\n                            \"Could not find an environment variable for \"\n                            f\"{match.group()!r} from mongo_uri: {value}\"\n                        )\n                    )\n                )\n        return res\n\n    @model_validator(mode=\"after\")\n    def write_pem_content_to_file(self) -&gt; ServerConfig:\n        \"\"\"Write the MongoDB Atlas PEM content to a file\"\"\"\n        if self.mongo_atlas_pem_content:\n            self.mongo_certfile.parent.mkdir(parents=True, exist_ok=True)\n            self.mongo_certfile.write_text(\n                self.mongo_atlas_pem_content.get_secret_value()\n            )\n\n        return self\n</code></pre>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig.replace_with_env_vars","title":"<code>replace_with_env_vars(value)</code>  <code>classmethod</code>","text":"<p>Replace string variables with environment variables, if possible</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>@field_validator(\"mongo_uri\", mode=\"after\")\n@classmethod\ndef replace_with_env_vars(cls, value: str) -&gt; str:\n    \"\"\"Replace string variables with environment variables, if possible\"\"\"\n    res = value\n    for match in re.finditer(r\"\\{[^{}]+\\}\", value):\n        string_var = match.group()[1:-1]\n        env_var = os.getenv(\n            string_var, os.getenv(string_var.upper(), os.getenv(string_var.lower()))\n        )\n        if env_var is not None:\n            res = res.replace(match.group(), env_var)\n        else:\n            warn(\n                OptimadeGatewayWarning(\n                    detail=(\n                        \"Could not find an environment variable for \"\n                        f\"{match.group()!r} from mongo_uri: {value}\"\n                    )\n                )\n            )\n    return res\n</code></pre>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig.write_pem_content_to_file","title":"<code>write_pem_content_to_file()</code>","text":"<p>Write the MongoDB Atlas PEM content to a file</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>@model_validator(mode=\"after\")\ndef write_pem_content_to_file(self) -&gt; ServerConfig:\n    \"\"\"Write the MongoDB Atlas PEM content to a file\"\"\"\n    if self.mongo_atlas_pem_content:\n        self.mongo_certfile.parent.mkdir(parents=True, exist_ok=True)\n        self.mongo_certfile.write_text(\n            self.mongo_atlas_pem_content.get_secret_value()\n        )\n\n    return self\n</code></pre>"},{"location":"api_reference/common/exceptions/","title":"exceptions","text":"<p>Specific OPTIMADE Gateway Python exceptions.</p>"},{"location":"api_reference/common/exceptions/#optimade_gateway.common.exceptions.OptimadeGatewayError","title":"<code>OptimadeGatewayError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>General OPTIMADE Gateway exception.</p> Source code in <code>optimade_gateway/common/exceptions.py</code> <pre><code>class OptimadeGatewayError(Exception):\n    \"\"\"General OPTIMADE Gateway exception.\"\"\"\n</code></pre>"},{"location":"api_reference/common/logger/","title":"logger","text":"<p>Logging to both file and console</p>"},{"location":"api_reference/common/logger/#optimade_gateway.common.logger.disable_logging","title":"<code>disable_logging()</code>","text":"<p>Temporarily disable logging.</p> <p>Usage:</p> <pre><code>from optimade_gateway.common.logger import disable_logging\n\n# Do stuff, logging to all handlers.\n# ...\nwith disable_logging():\n    # Do stuff, without logging to any handlers.\n    # ...\n# Do stuff, logging to all handlers now re-enabled.\n# ...\n</code></pre> Source code in <code>optimade_gateway/common/logger.py</code> <pre><code>@contextmanager\ndef disable_logging():\n    \"\"\"Temporarily disable logging.\n\n    Usage:\n\n    ```python\n    from optimade_gateway.common.logger import disable_logging\n\n    # Do stuff, logging to all handlers.\n    # ...\n    with disable_logging():\n        # Do stuff, without logging to any handlers.\n        # ...\n    # Do stuff, logging to all handlers now re-enabled.\n    # ...\n    ```\n\n    \"\"\"\n    try:\n        # Disable logging lower than CRITICAL level\n        logging.disable(logging.CRITICAL)\n        yield\n    finally:\n        # Re-enable logging to desired levels\n        logging.disable(logging.NOTSET)\n</code></pre>"},{"location":"api_reference/common/utils/","title":"utils","text":"<p>Common utility functions.</p> <p>These functions may be used in general throughout the OPTIMADE Gateway Python code.</p>"},{"location":"api_reference/common/utils/#optimade_gateway.common.utils.clean_python_types","title":"<code>clean_python_types(data, **dump_kwargs)</code>  <code>async</code>","text":"<p>Turn any types into MongoDB-friendly Python types.</p> <p>Use <code>model_dump()</code> method for Pydantic models. Use <code>value</code> property for Enums. Turn tuples and sets into lists.</p> Source code in <code>optimade_gateway/common/utils.py</code> <pre><code>async def clean_python_types(data: Any, **dump_kwargs: Any) -&gt; Any:\n    \"\"\"Turn any types into MongoDB-friendly Python types.\n\n    Use `model_dump()` method for Pydantic models.\n    Use `value` property for Enums.\n    Turn tuples and sets into lists.\n    \"\"\"\n    if isinstance(data, (list, tuple, set)):\n        res_list = []\n        for datum in data:\n            res_list.append(await clean_python_types(datum, **dump_kwargs))\n        return res_list\n\n    if isinstance(data, dict):\n        res_dict = {}\n        for key in list(data.keys()):\n            res_dict[key] = await clean_python_types(data[key], **dump_kwargs)\n        return res_dict\n\n    if isinstance(data, BaseModel):\n        # Pydantic model\n        return await clean_python_types(data.model_dump(**dump_kwargs))\n\n    if isinstance(data, Enum):\n        return await clean_python_types(data.value, **dump_kwargs)\n\n    if isinstance(data, type):\n        return await clean_python_types(\n            f\"{data.__module__}.{data.__name__}\", **dump_kwargs\n        )\n\n    if isinstance(data, AnyUrl):\n        return await clean_python_types(str(data), **dump_kwargs)\n\n    # Unknown or other basic type, e.g., str, int, etc.\n    return data\n</code></pre>"},{"location":"api_reference/common/utils/#optimade_gateway.common.utils.get_resource_attribute","title":"<code>get_resource_attribute(resource, field, default=None, disambiguate=True)</code>","text":"<p>Return a resource's field's value</p> <p>Get the field value no matter if the resource is a pydantic model or a Python dictionary.</p> <p>Determine ambiguous field values and return them if desired (<code>disambiguate</code>). For example, if <code>\"attributes.base_url\"</code> is requested for a <code>LinksResource</code> it can be either a string, a <code>Link</code> model or a dictionary resembling the <code>Link</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>resource</code> <code>BaseModel | dict[str, Any] | None</code> <p>The resource, from which to get the field value.</p> required <code>field</code> <code>str</code> <p>The resource field. This can be a dot-separated nested field, e.g., <code>\"attributes.base_url\"</code>.</p> required <code>default</code> <code>Any</code> <p>The default value to return if <code>field</code> does not exist.</p> <code>None</code> <code>disambiguate</code> <code>bool</code> <p>Whether or not to \"shortcut\" a field value. For example, for <code>attributes.base_url</code>, if <code>True</code>, this would return the string value or the value of it's <code>\"href\"</code> key.</p> <code>True</code> <p>Returns:</p> Type Description <code>Any</code> <p>The resource's field's value.</p> Source code in <code>optimade_gateway/common/utils.py</code> <pre><code>def get_resource_attribute(\n    resource: BaseModel | dict[str, Any] | None,\n    field: str,\n    default: Any = None,\n    disambiguate: bool = True,\n) -&gt; Any:\n    \"\"\"Return a resource's field's value\n\n    Get the field value no matter if the resource is a pydantic model or a Python\n    dictionary.\n\n    Determine ambiguous field values and return them if desired (`disambiguate`).\n    For example, if\n    [`\"attributes.base_url\"`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes.base_url)\n    is requested for a\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n    it can be either a string, a\n    [`Link`](https://www.optimade.org/optimade-python-tools/api_reference/models/jsonapi/#optimade.models.jsonapi.Link)\n    model or a dictionary resembling the `Link` model.\n\n    Parameters:\n        resource: The resource, from which to get the field value.\n        field: The resource field. This can be a dot-separated nested field, e.g.,\n            `\"attributes.base_url\"`.\n        default: The default value to return if `field` does not exist.\n        disambiguate: Whether or not to \"shortcut\" a field value.\n            For example, for `attributes.base_url`, if `True`, this would return the\n            string value or the value of it's `\"href\"` key.\n\n    Returns:\n        The resource's field's value.\n\n    \"\"\"\n    if isinstance(resource, BaseModel):\n        _get_attr = getattr\n    elif isinstance(resource, dict):\n\n        def _get_attr(mapping: dict, key: str, default: Any) -&gt; Any:  # type: ignore[misc]\n            return mapping.get(key, default)\n\n    elif resource is None:\n        # Allow passing `None`, but simply return `default`\n        return default\n    else:\n        raise TypeError(\n            \"resource must be either a pydantic model or a Python dictionary, it was \"\n            f\"of type {type(resource)!r}\"\n        )\n\n    fields = field.split(\".\")\n    for _ in fields[:-1]:\n        resource = _get_attr(resource, _, {})\n    field = fields[-1]\n    value = _get_attr(resource, field, default)\n\n    if (\n        disambiguate\n        and field in (\"base_url\", \"next\", \"prev\", \"last\", \"first\")\n        and not isinstance(value, (str, AnyUrl))\n    ):\n        value = _get_attr(value, \"href\", default)\n\n    return value\n</code></pre>"},{"location":"api_reference/mappers/base/","title":"base","text":"<p>Base resource mapper.</p> <p>Based on the <code>BaseResourceMapper</code> in OPTIMADE Python tools.</p>"},{"location":"api_reference/mappers/base/#optimade_gateway.mappers.base.BaseResourceMapper","title":"<code>BaseResourceMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p>Generic Resource Mapper that defines and performs the mapping between objects in the database and the resource objects defined by the specification.</p> Note <p>This is a \"wrapped\" sub-class to make certain methods asynchronous.</p> <p>Attributes:</p> Name Type Description <code>ALIASES</code> <p>a tuple of aliases between OPTIMADE field names and the field names in the database , e.g. <code>((\"elements\", \"custom_elements_field\"))</code>.</p> <code>LENGTH_ALIASES</code> <p>a tuple of aliases between a field name and another field that defines its length, to be used when querying, e.g. <code>((\"elements\", \"nelements\"))</code>. e.g. <code>((\"elements\", \"custom_elements_field\"))</code>.</p> <code>ENTRY_RESOURCE_CLASS</code> <p>The entry type that this mapper corresponds to.</p> <code>PROVIDER_FIELDS</code> <p>a tuple of extra field names that this mapper should support when querying with the database prefix.</p> <code>TOP_LEVEL_NON_ATTRIBUTES_FIELDS</code> <p>the set of top-level field names common to all endpoints.</p> <code>SUPPORTED_PREFIXES</code> <p>The set of prefixes registered by this mapper.</p> <code>ALL_ATTRIBUTES</code> <p>The set of attributes defined across the entry resource class and the server configuration.</p> <code>ENTRY_RESOURCE_ATTRIBUTES</code> <p>A dictionary of attributes and their definitions defined by the schema of the entry resource class.</p> <code>ENDPOINT</code> <p>The expected endpoint name for this resource, as defined by the <code>type</code> in the schema of the entry resource class.</p> Source code in <code>optimade_gateway/mappers/base.py</code> <pre><code>class BaseResourceMapper(OptimadeBaseResourceMapper):\n    \"\"\"\n    Generic Resource Mapper that defines and performs the mapping\n    between objects in the database and the resource objects defined by\n    the specification.\n\n    Note:\n        This is a \"wrapped\" sub-class to make certain methods asynchronous.\n\n    Attributes:\n        ALIASES: a tuple of aliases between\n            OPTIMADE field names and the field names in the database ,\n            e.g. `((\"elements\", \"custom_elements_field\"))`.\n        LENGTH_ALIASES: a tuple of aliases between\n            a field name and another field that defines its length, to be used\n            when querying, e.g. `((\"elements\", \"nelements\"))`.\n            e.g. `((\"elements\", \"custom_elements_field\"))`.\n        ENTRY_RESOURCE_CLASS: The entry type that this mapper corresponds to.\n        PROVIDER_FIELDS: a tuple of extra field names that this\n            mapper should support when querying with the database prefix.\n        TOP_LEVEL_NON_ATTRIBUTES_FIELDS: the set of top-level\n            field names common to all endpoints.\n        SUPPORTED_PREFIXES: The set of prefixes registered by this mapper.\n        ALL_ATTRIBUTES: The set of attributes defined across the entry\n            resource class and the server configuration.\n        ENTRY_RESOURCE_ATTRIBUTES: A dictionary of attributes and their definitions\n            defined by the schema of the entry resource class.\n        ENDPOINT: The expected endpoint name for this resource, as defined by\n            the `type` in the schema of the entry resource class.\n\n    \"\"\"\n\n    @classmethod\n    async def adeserialize(\n        cls, results: dict | Iterable[dict]\n    ) -&gt; list[EntryResource] | EntryResource:\n        \"\"\"Asynchronous version of the `deserialize()` class method.\n\n        Parameters:\n            results: A list of or a single dictionary, representing an entry-endpoint\n                resource.\n\n        Returns:\n            The deserialized list of or single pydantic resource model for the input\n            `results`.\n\n        \"\"\"\n        return super().deserialize(results)\n\n    @classmethod\n    def map_back(cls, doc: dict) -&gt; dict:\n        from optimade.server.routers.utils import BASE_URL_PREFIXES\n\n        if \"_id\" in doc:\n            _id = str(doc.pop(\"_id\"))\n            if \"id\" not in doc:\n                doc[\"id\"] = _id\n\n        doc[\"links\"] = {\n            \"self\": AnyUrl(\n                url=(\n                    f\"{CONFIG.base_url.strip('/')}{BASE_URL_PREFIXES['major']}\"\n                    f\"/{cls.ENDPOINT}/{doc['id']}\"\n                ),\n            )\n        }\n        return super().map_back(doc)\n</code></pre>"},{"location":"api_reference/mappers/base/#optimade_gateway.mappers.base.BaseResourceMapper.adeserialize","title":"<code>adeserialize(results)</code>  <code>async</code> <code>classmethod</code>","text":"<p>Asynchronous version of the <code>deserialize()</code> class method.</p> <p>Parameters:</p> Name Type Description Default <code>results</code> <code>dict | Iterable[dict]</code> <p>A list of or a single dictionary, representing an entry-endpoint resource.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource</code> <p>The deserialized list of or single pydantic resource model for the input</p> <code>list[EntryResource] | EntryResource</code> <p><code>results</code>.</p> Source code in <code>optimade_gateway/mappers/base.py</code> <pre><code>@classmethod\nasync def adeserialize(\n    cls, results: dict | Iterable[dict]\n) -&gt; list[EntryResource] | EntryResource:\n    \"\"\"Asynchronous version of the `deserialize()` class method.\n\n    Parameters:\n        results: A list of or a single dictionary, representing an entry-endpoint\n            resource.\n\n    Returns:\n        The deserialized list of or single pydantic resource model for the input\n        `results`.\n\n    \"\"\"\n    return super().deserialize(results)\n</code></pre>"},{"location":"api_reference/mappers/databases/","title":"databases","text":"<p>Resource mapper for resources under <code>/databases</code>.</p> <p>These resources are <code>LinksResource</code>s.</p>"},{"location":"api_reference/mappers/databases/#optimade_gateway.mappers.databases.DatabasesMapper","title":"<code>DatabasesMapper</code>","text":"<p>               Bases: <code>LinksMapper</code></p> <p><code>/databases</code>-endpoint resources mapper.</p> Source code in <code>optimade_gateway/mappers/databases.py</code> <pre><code>class DatabasesMapper(LinksMapper):\n    \"\"\"`/databases`-endpoint resources mapper.\"\"\"\n\n    ENDPOINT = \"databases\"\n</code></pre>"},{"location":"api_reference/mappers/gateways/","title":"gateways","text":"<p>Resource mapper for <code>GatewayResource</code>.</p>"},{"location":"api_reference/mappers/gateways/#optimade_gateway.mappers.gateways.GatewaysMapper","title":"<code>GatewaysMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p><code>GatewayResource</code> mapper.</p> Source code in <code>optimade_gateway/mappers/gateways.py</code> <pre><code>class GatewaysMapper(BaseResourceMapper):\n    \"\"\"[`GatewayResource`][optimade_gateway.models.gateways.GatewayResource] mapper.\"\"\"\n\n    ENDPOINT = \"gateways\"\n    ENTRY_RESOURCE_CLASS = GatewayResource\n</code></pre>"},{"location":"api_reference/mappers/links/","title":"links","text":"<p>Replicate of <code>LinksMapper</code> in OPTIMADE Python tools.</p>"},{"location":"api_reference/mappers/links/#optimade_gateway.mappers.links.LinksMapper","title":"<code>LinksMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p>Replicate of <code>LinksMapper</code> in OPTIMADE Python tools.</p> <p>This is based on the OPTIMADE Gateway <code>BaseResourceMapper</code> however.</p> Source code in <code>optimade_gateway/mappers/links.py</code> <pre><code>class LinksMapper(BaseResourceMapper):\n    \"\"\"Replicate of\n    [`LinksMapper`](https://www.optimade.org/optimade-python-tools/api_reference/server/mappers/links/#optimade.server.mappers.links.LinksMapper)\n    in OPTIMADE Python tools.\n\n    This is based on the OPTIMADE Gateway\n    [`BaseResourceMapper`][optimade_gateway.mappers.base.BaseResourceMapper] however.\n    \"\"\"\n\n    ENDPOINT = \"links\"\n    ENTRY_RESOURCE_CLASS = LinksResource\n\n    @classmethod\n    def map_back(cls, doc: dict) -&gt; dict:\n        type_ = doc.get(\"type\") or \"links\"\n        newdoc = super().map_back(doc)\n        newdoc[\"type\"] = type_\n        return newdoc\n</code></pre>"},{"location":"api_reference/mappers/queries/","title":"queries","text":"<p>Resource mapper for <code>QueryResource</code>.</p>"},{"location":"api_reference/mappers/queries/#optimade_gateway.mappers.queries.QueryMapper","title":"<code>QueryMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p><code>QueryResource</code> mapper.</p> Source code in <code>optimade_gateway/mappers/queries.py</code> <pre><code>class QueryMapper(BaseResourceMapper):\n    \"\"\"[`QueryResource`][optimade_gateway.models.queries.QueryResource] mapper.\"\"\"\n\n    ENDPOINT = \"queries\"\n    ENTRY_RESOURCE_CLASS = QueryResource\n</code></pre>"},{"location":"api_reference/models/databases/","title":"databases","text":"<p>Pydantic models/schemas for the LinksResource used in /databases</p>"},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate","title":"<code>DatabaseCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>LinksResourceAttributes</code></p> <p>Model for creating new LinksResources representing <code>/databases</code> resources in the MongoDB.</p> <p>Required fields:</p> <ul> <li><code>name</code></li> <li><code>base_url</code></li> </ul> <p>Original required fields for a <code>LinksResourceAttributes</code> model:</p> <ul> <li><code>name</code></li> <li><code>description</code></li> <li><code>link_type</code></li> </ul> Source code in <code>optimade_gateway/models/databases.py</code> <pre><code>class DatabaseCreate(EntryResourceCreate, LinksResourceAttributes):\n    \"\"\"Model for creating new LinksResources representing `/databases` resources in the\n    MongoDB.\n\n    Required fields:\n\n    - `name`\n    - `base_url`\n\n    Original required fields for a\n    [`LinksResourceAttributes`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes)\n    model:\n\n    - `name`\n    - `description`\n    - `link_type`\n\n    \"\"\"\n\n    description: Annotated[\n        str | None,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"description\"].description\n        ),\n    ] = None\n\n    base_url: Annotated[\n        JsonLinkType,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"base_url\"].description\n        ),\n    ]\n\n    homepage: Annotated[\n        JsonLinkType | None,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"homepage\"].description,\n        ),\n    ] = None\n\n    link_type: Annotated[\n        LinkType | None,\n        StrictField(\n            title=LinksResourceAttributes.model_fields[\"link_type\"].title,\n            description=LinksResourceAttributes.model_fields[\"link_type\"].description,\n        ),\n    ] = None\n\n    @field_validator(\"link_type\", mode=\"after\")\n    @classmethod\n    def ensure_database_link_type(cls, value: LinkType) -&gt; LinkType:\n        \"\"\"Ensure databases are not index meta-database-only types\n\n        I.e., ensure they're not of type `\"root\"` or `\"providers\"`.\n\n        !!! note\n            Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n            but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n        \"\"\"\n        if value in (LinkType.ROOT, LinkType.PROVIDERS):\n            raise ValueError(\n                \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                f\"gateway-usable database resources. Given link_type: {value}\"\n            )\n        return value\n</code></pre>"},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.base_url","title":"<code>base_url: Annotated[JsonLinkType, StrictField(description=LinksResourceAttributes.model_fields['base_url'].description)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.description","title":"<code>description: Annotated[str | None, StrictField(description=LinksResourceAttributes.model_fields['description'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.homepage","title":"<code>homepage: Annotated[JsonLinkType | None, StrictField(description=LinksResourceAttributes.model_fields['homepage'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.link_type","title":"<code>link_type: Annotated[LinkType | None, StrictField(title=LinksResourceAttributes.model_fields['link_type'].title, description=LinksResourceAttributes.model_fields['link_type'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.ensure_database_link_type","title":"<code>ensure_database_link_type(value)</code>  <code>classmethod</code>","text":"<p>Ensure databases are not index meta-database-only types</p> <p>I.e., ensure they're not of type <code>\"root\"</code> or <code>\"providers\"</code>.</p> <p>Note</p> <p>Both <code>\"external\"</code> and <code>\"child\"</code> can still represent index meta-dbs, but <code>\"root\"</code> and <code>\"providers\"</code> can not represent \"regular\" dbs.</p> Source code in <code>optimade_gateway/models/databases.py</code> <pre><code>@field_validator(\"link_type\", mode=\"after\")\n@classmethod\ndef ensure_database_link_type(cls, value: LinkType) -&gt; LinkType:\n    \"\"\"Ensure databases are not index meta-database-only types\n\n    I.e., ensure they're not of type `\"root\"` or `\"providers\"`.\n\n    !!! note\n        Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n        but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n    \"\"\"\n    if value in (LinkType.ROOT, LinkType.PROVIDERS):\n        raise ValueError(\n            \"Databases with 'root' or 'providers' link_type is not allowed for \"\n            f\"gateway-usable database resources. Given link_type: {value}\"\n        )\n    return value\n</code></pre>"},{"location":"api_reference/models/gateways/","title":"gateways","text":"<p>Pydantic models/schemas for the Gateways resource.</p>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate","title":"<code>GatewayCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>GatewayResourceAttributes</code></p> <p>Model for creating new Gateway resources in the MongoDB</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayCreate(EntryResourceCreate, GatewayResourceAttributes):\n    \"\"\"Model for creating new Gateway resources in the MongoDB\"\"\"\n\n    id: Annotated[\n        str | None,\n        OptimadeField(\n            description=EntryResource.model_fields[\"id\"].description,\n            support=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-support\"\n            ],\n            queryable=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-queryable\"\n            ],\n            pattern=r\"^[^/]*$\",  # This pattern is the special addition\n        ),\n    ] = None\n\n    database_ids: Annotated[\n        set[str] | None,\n        Field(description=\"A unique list of database IDs for registered databases.\"),\n    ] = None\n\n    databases: Annotated[\n        list[LinksResource] | None,\n        Field(\n            description=GatewayResourceAttributes.model_fields[\"databases\"].description\n        ),\n    ] = None  # type: ignore[assignment]\n\n    @model_validator(mode=\"after\")\n    def specify_databases(self) -&gt; GatewayCreate:\n        \"\"\"Either `database_ids` or `databases` must be non-empty.\n        Both together is also fine.\n        \"\"\"\n        if not any(getattr(self, field) for field in (\"database_ids\", \"databases\")):\n            raise ValueError(\"Either 'database_ids' or 'databases' MUST be specified\")\n        return self\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.database_ids","title":"<code>database_ids: Annotated[set[str] | None, Field(description='A unique list of database IDs for registered databases.')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.databases","title":"<code>databases: Annotated[list[LinksResource] | None, Field(description=GatewayResourceAttributes.model_fields['databases'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.id","title":"<code>id: Annotated[str | None, OptimadeField(description=EntryResource.model_fields['id'].description, support=EntryResource.model_fields['id'].json_schema_extra['x-optimade-support'], queryable=EntryResource.model_fields['id'].json_schema_extra['x-optimade-queryable'], pattern='^[^/]*$')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.specify_databases","title":"<code>specify_databases()</code>","text":"<p>Either <code>database_ids</code> or <code>databases</code> must be non-empty. Both together is also fine.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>@model_validator(mode=\"after\")\ndef specify_databases(self) -&gt; GatewayCreate:\n    \"\"\"Either `database_ids` or `databases` must be non-empty.\n    Both together is also fine.\n    \"\"\"\n    if not any(getattr(self, field) for field in (\"database_ids\", \"databases\")):\n        raise ValueError(\"Either 'database_ids' or 'databases' MUST be specified\")\n    return self\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource","title":"<code>GatewayResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>OPTIMADE gateway</p> <p>A resource representing a dynamic collection of OPTIMADE databases. The gateway can be treated as any other OPTIMADE gateway, but the entries are an aggregate of multiple databases. The <code>id</code> of each aggregated resource will reflect the originating database.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayResource(EntryResource):\n    \"\"\"OPTIMADE gateway\n\n    A resource representing a dynamic collection of OPTIMADE databases.\n    The gateway can be treated as any other OPTIMADE gateway, but the entries are an\n    aggregate of multiple databases. The `id` of each aggregated resource will reflect\n    the originating database.\n    \"\"\"\n\n    id: Annotated[\n        str,\n        OptimadeField(\n            description=EntryResource.model_fields[\"id\"].description,\n            support=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-support\"\n            ],\n            queryable=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-queryable\"\n            ],\n            pattern=r\"^[^/]*$\",\n        ),\n    ]\n\n    type: Annotated[\n        Literal[\"gateways\"],\n        Field(description=\"The name of the type of an entry.\"),\n    ] = \"gateways\"\n\n    attributes: Annotated[\n        GatewayResourceAttributes,\n        Field(description=EntryResource.model_fields[\"attributes\"].description),\n    ]\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.attributes","title":"<code>attributes: Annotated[GatewayResourceAttributes, Field(description=EntryResource.model_fields['attributes'].description)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.id","title":"<code>id: Annotated[str, OptimadeField(description=EntryResource.model_fields['id'].description, support=EntryResource.model_fields['id'].json_schema_extra['x-optimade-support'], queryable=EntryResource.model_fields['id'].json_schema_extra['x-optimade-queryable'], pattern='^[^/]*$')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.type","title":"<code>type: Annotated[Literal['gateways'], Field(description='The name of the type of an entry.')] = 'gateways'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes","title":"<code>GatewayResourceAttributes</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Attributes for an OPTIMADE gateway</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayResourceAttributes(EntryResourceAttributes):\n    \"\"\"Attributes for an OPTIMADE gateway\"\"\"\n\n    databases: Annotated[\n        list[LinksResource],\n        Field(\n            description=(\n                \"List of databases (OPTIMADE 'links') to be queried in this gateway.\"\n            ),\n        ),\n    ]\n\n    @field_validator(\"databases\", mode=\"after\")\n    @classmethod\n    def unique_base_urls(cls, value: list[LinksResource]) -&gt; list[LinksResource]:\n        \"\"\"Remove extra entries with repeated base_urls.\n\n        Also, ensure databases are not of type `\"root\"` or `\"providers\"`\n\n        !!! note\n            Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n            but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n        \"\"\"\n        for resource in value:\n            if resource.attributes.link_type in (LinkType.ROOT, LinkType.PROVIDERS):\n                raise ValueError(\n                    \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                    f\"gateway resources. Given database: {resource}\"\n                )\n\n        db_base_urls = [_.attributes.base_url for _ in value]\n        unique_base_urls = set(db_base_urls)\n        if len(db_base_urls) == len(unique_base_urls):\n            return value\n\n        repeated_base_urls = [_ for _ in unique_base_urls if db_base_urls.count(_) &gt; 1]\n        new_databases = [\n            _ for _ in value if _.attributes.base_url not in repeated_base_urls\n        ]\n        for base_url in repeated_base_urls:\n            new_databases.append(\n                next(_ for _ in value if _.attributes.base_url == base_url)\n            )\n        warnings.warn(\n            \"Removed extra database entries for a gateway, because the base_url was \"\n            \"repeated. The first found database entry was kept, while the others were \"\n            f\"removed. Original number of databases: {len(value)}. New number of \"\n            f\"databases: {len(new_databases)} Repeated base_urls (number of repeats): \"\n            \"{}\".format(\n                [\n                    f\"{base_url} ({db_base_urls.count(base_url)})\"\n                    for base_url in repeated_base_urls\n                ]\n            ),\n            OptimadeGatewayWarning,\n        )\n        return new_databases\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes.databases","title":"<code>databases: Annotated[list[LinksResource], Field(description=\"List of databases (OPTIMADE 'links') to be queried in this gateway.\")]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes.unique_base_urls","title":"<code>unique_base_urls(value)</code>  <code>classmethod</code>","text":"<p>Remove extra entries with repeated base_urls.</p> <p>Also, ensure databases are not of type <code>\"root\"</code> or <code>\"providers\"</code></p> <p>Note</p> <p>Both <code>\"external\"</code> and <code>\"child\"</code> can still represent index meta-dbs, but <code>\"root\"</code> and <code>\"providers\"</code> can not represent \"regular\" dbs.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>@field_validator(\"databases\", mode=\"after\")\n@classmethod\ndef unique_base_urls(cls, value: list[LinksResource]) -&gt; list[LinksResource]:\n    \"\"\"Remove extra entries with repeated base_urls.\n\n    Also, ensure databases are not of type `\"root\"` or `\"providers\"`\n\n    !!! note\n        Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n        but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n    \"\"\"\n    for resource in value:\n        if resource.attributes.link_type in (LinkType.ROOT, LinkType.PROVIDERS):\n            raise ValueError(\n                \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                f\"gateway resources. Given database: {resource}\"\n            )\n\n    db_base_urls = [_.attributes.base_url for _ in value]\n    unique_base_urls = set(db_base_urls)\n    if len(db_base_urls) == len(unique_base_urls):\n        return value\n\n    repeated_base_urls = [_ for _ in unique_base_urls if db_base_urls.count(_) &gt; 1]\n    new_databases = [\n        _ for _ in value if _.attributes.base_url not in repeated_base_urls\n    ]\n    for base_url in repeated_base_urls:\n        new_databases.append(\n            next(_ for _ in value if _.attributes.base_url == base_url)\n        )\n    warnings.warn(\n        \"Removed extra database entries for a gateway, because the base_url was \"\n        \"repeated. The first found database entry was kept, while the others were \"\n        f\"removed. Original number of databases: {len(value)}. New number of \"\n        f\"databases: {len(new_databases)} Repeated base_urls (number of repeats): \"\n        \"{}\".format(\n            [\n                f\"{base_url} ({db_base_urls.count(base_url)})\"\n                for base_url in repeated_base_urls\n            ]\n        ),\n        OptimadeGatewayWarning,\n    )\n    return new_databases\n</code></pre>"},{"location":"api_reference/models/queries/","title":"queries","text":"<p>Pydantic models/schemas for the Queries resource.</p>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QUERY_PARAMETERS","title":"<code>QUERY_PARAMETERS: QueryParameters = {'annotations': {name: FieldInfo.from_annotation(parameter.annotation)for (name, parameter) in inspect.signature(EntryListingQueryParams).parameters.items()}, 'defaults': EntryListingQueryParams()}</code>  <code>module-attribute</code>","text":"<p>Entry listing URL query parameters from the <code>optimade</code> package (<code>EntryListingQueryParams</code>).</p>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType","title":"<code>EndpointEntryType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Entry endpoint resource types, mapping to their pydantic models from the <code>optimade</code> package.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class EndpointEntryType(Enum):\n    \"\"\"Entry endpoint resource types, mapping to their pydantic models from the\n    `optimade` package.\"\"\"\n\n    REFERENCES = \"references\"\n    STRUCTURES = \"structures\"\n\n    def get_resource_model(self) -&gt; ReferenceResource | StructureResource:\n        \"\"\"Get the matching pydantic model for a resource.\"\"\"\n        return {\n            \"references\": ReferenceResource,\n            \"structures\": StructureResource,\n        }[self.value]\n\n    def get_response_model(\n        self, single: bool = False\n    ) -&gt; (\n        ReferenceResponseMany\n        | ReferenceResponseOne\n        | StructureResponseMany\n        | StructureResponseOne\n    ):\n        \"\"\"Get the matching pydantic model for a successful response.\"\"\"\n        if single:\n            return {\n                \"references\": ReferenceResponseOne,\n                \"structures\": StructureResponseOne,\n            }[self.value]\n        return {\n            \"references\": ReferenceResponseMany,\n            \"structures\": StructureResponseMany,\n        }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.REFERENCES","title":"<code>REFERENCES = 'references'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.STRUCTURES","title":"<code>STRUCTURES = 'structures'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.get_resource_model","title":"<code>get_resource_model()</code>","text":"<p>Get the matching pydantic model for a resource.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>def get_resource_model(self) -&gt; ReferenceResource | StructureResource:\n    \"\"\"Get the matching pydantic model for a resource.\"\"\"\n    return {\n        \"references\": ReferenceResource,\n        \"structures\": StructureResource,\n    }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.get_response_model","title":"<code>get_response_model(single=False)</code>","text":"<p>Get the matching pydantic model for a successful response.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>def get_response_model(\n    self, single: bool = False\n) -&gt; (\n    ReferenceResponseMany\n    | ReferenceResponseOne\n    | StructureResponseMany\n    | StructureResponseOne\n):\n    \"\"\"Get the matching pydantic model for a successful response.\"\"\"\n    if single:\n        return {\n            \"references\": ReferenceResponseOne,\n            \"structures\": StructureResponseOne,\n        }[self.value]\n    return {\n        \"references\": ReferenceResponseMany,\n        \"structures\": StructureResponseMany,\n    }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EntryResource","title":"<code>EntryResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>Entry Resource ensuring datetimes are not naive.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class EntryResource(OptimadeEntryResource):\n    \"\"\"Entry Resource ensuring datetimes are not naive.\"\"\"\n\n    @field_validator(\"attributes\", mode=\"after\")\n    @classmethod\n    def ensure_non_naive_datetime(\n        cls, value: EntryResourceAttributes\n    ) -&gt; EntryResourceAttributes:\n        \"\"\"Set timezone to UTC if datetime is naive.\"\"\"\n        if value.last_modified and value.last_modified.tzinfo is None:\n            value.last_modified = value.last_modified.replace(tzinfo=timezone.utc)\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EntryResource.ensure_non_naive_datetime","title":"<code>ensure_non_naive_datetime(value)</code>  <code>classmethod</code>","text":"<p>Set timezone to UTC if datetime is naive.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"attributes\", mode=\"after\")\n@classmethod\ndef ensure_non_naive_datetime(\n    cls, value: EntryResourceAttributes\n) -&gt; EntryResourceAttributes:\n    \"\"\"Set timezone to UTC if datetime is naive.\"\"\"\n    if value.last_modified and value.last_modified.tzinfo is None:\n        value.last_modified = value.last_modified.replace(tzinfo=timezone.utc)\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse","title":"<code>GatewayQueryResponse</code>","text":"<p>               Bases: <code>Response</code></p> <p>Response from a Gateway Query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class GatewayQueryResponse(Response):\n    \"\"\"Response from a Gateway Query.\"\"\"\n\n    data: Annotated[\n        dict[str, list[EntryResource] | list[dict[str, Any]]],\n        StrictField(uniqueItems=True, description=\"Outputted Data.\"),\n    ]\n\n    meta: Annotated[\n        ResponseMeta,\n        StrictField(description=\"A meta object containing non-standard information.\"),\n    ]\n\n    errors: Annotated[\n        list[OptimadeError] | None,\n        StrictField(\n            description=(\n                \"A list of OPTIMADE-specific JSON API error objects, where the field \"\n                \"detail MUST be present.\"\n            ),\n            uniqueItems=True,\n        ),\n    ] = []  # noqa: RUF012\n\n    included: Annotated[\n        list[EntryResource] | list[dict[str, Any]] | None,\n        StrictField(\n            description=\"A list of unique included OPTIMADE entry resources.\",\n            uniqueItems=True,\n            union_mode=\"left_to_right\",\n        ),\n    ] = None\n\n    @model_validator(mode=\"after\")\n    def either_data_meta_or_errors_must_be_set(self) -&gt; GatewayQueryResponse:\n        \"\"\"Overwrite `either_data_meta_or_errors_must_be_set`.\n\n        `errors` should be allowed to be present always for this special response.\n        \"\"\"\n        return self\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.data","title":"<code>data: Annotated[dict[str, list[EntryResource] | list[dict[str, Any]]], StrictField(uniqueItems=True, description='Outputted Data.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.errors","title":"<code>errors: Annotated[list[OptimadeError] | None, StrictField(description='A list of OPTIMADE-specific JSON API error objects, where the field detail MUST be present.', uniqueItems=True)] = []</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.included","title":"<code>included: Annotated[list[EntryResource] | list[dict[str, Any]] | None, StrictField(description='A list of unique included OPTIMADE entry resources.', uniqueItems=True, union_mode='left_to_right')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.meta","title":"<code>meta: Annotated[ResponseMeta, StrictField(description='A meta object containing non-standard information.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.either_data_meta_or_errors_must_be_set","title":"<code>either_data_meta_or_errors_must_be_set()</code>","text":"<p>Overwrite <code>either_data_meta_or_errors_must_be_set</code>.</p> <p><code>errors</code> should be allowed to be present always for this special response.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@model_validator(mode=\"after\")\ndef either_data_meta_or_errors_must_be_set(self) -&gt; GatewayQueryResponse:\n    \"\"\"Overwrite `either_data_meta_or_errors_must_be_set`.\n\n    `errors` should be allowed to be present always for this special response.\n    \"\"\"\n    return self\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters","title":"<code>OptimadeQueryParameters</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Common OPTIMADE entry listing endpoint query parameters.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class OptimadeQueryParameters(BaseModel):\n    \"\"\"Common OPTIMADE entry listing endpoint query parameters.\"\"\"\n\n    filter: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"filter\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].filter\n\n    response_format: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"response_format\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].response_format\n\n    email_address: Annotated[\n        EmailStr | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"email_address\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].email_address\n\n    response_fields: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"response_fields\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"response_fields\"]\n            .metadata[0]\n            .pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].response_fields\n\n    sort: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"sort\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"sort\"].metadata[0].pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].sort\n\n    page_limit: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_limit\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_limit\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_limit\n\n    page_offset: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_offset\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_offset\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_offset\n\n    page_number: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_number\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_number\n\n    page_cursor: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_cursor\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_cursor\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_cursor\n\n    page_above: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_above\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_above\n\n    page_below: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_below\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_below\n\n    include: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"include\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].include\n\n    api_hint: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"api_hint\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"api_hint\"].metadata[0].pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].api_hint\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.api_hint","title":"<code>api_hint: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['api_hint'].description, pattern=QUERY_PARAMETERS['annotations']['api_hint'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].api_hint</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.email_address","title":"<code>email_address: Annotated[EmailStr | None, Field(description=QUERY_PARAMETERS['annotations']['email_address'].description)] = QUERY_PARAMETERS['defaults'].email_address</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.filter","title":"<code>filter: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['filter'].description)] = QUERY_PARAMETERS['defaults'].filter</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.include","title":"<code>include: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['include'].description)] = QUERY_PARAMETERS['defaults'].include</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_above","title":"<code>page_above: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_above'].description)] = QUERY_PARAMETERS['defaults'].page_above</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_below","title":"<code>page_below: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_below'].description)] = QUERY_PARAMETERS['defaults'].page_below</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_cursor","title":"<code>page_cursor: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_cursor'].description, ge=QUERY_PARAMETERS['annotations']['page_cursor'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_cursor</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_limit","title":"<code>page_limit: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_limit'].description, ge=QUERY_PARAMETERS['annotations']['page_limit'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_limit</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_number","title":"<code>page_number: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_number'].description)] = QUERY_PARAMETERS['defaults'].page_number</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_offset","title":"<code>page_offset: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_offset'].description, ge=QUERY_PARAMETERS['annotations']['page_offset'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_offset</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.response_fields","title":"<code>response_fields: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['response_fields'].description, pattern=QUERY_PARAMETERS['annotations']['response_fields'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].response_fields</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.response_format","title":"<code>response_format: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['response_format'].description)] = QUERY_PARAMETERS['defaults'].response_format</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.sort","title":"<code>sort: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['sort'].description, pattern=QUERY_PARAMETERS['annotations']['sort'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].sort</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate","title":"<code>QueryCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>QueryResourceAttributes</code></p> <p>Model for creating new Query resources in the MongoDB</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryCreate(EntryResourceCreate, QueryResourceAttributes):\n    \"\"\"Model for creating new Query resources in the MongoDB\"\"\"\n\n    state: Annotated[\n        QueryState | None,\n        Field(\n            title=QueryResourceAttributes.model_fields[\"state\"].title,\n            description=QueryResourceAttributes.model_fields[\"state\"].description,\n            json_schema_extra=QueryResourceAttributes.model_fields[\n                \"state\"\n            ].json_schema_extra,\n        ),\n    ] = None  # type: ignore[assignment]\n    endpoint: Annotated[\n        EndpointEntryType | None,\n        Field(\n            title=QueryResourceAttributes.model_fields[\"endpoint\"].title,\n            description=QueryResourceAttributes.model_fields[\"endpoint\"].description,\n            json_schema_extra=QueryResourceAttributes.model_fields[\n                \"endpoint\"\n            ].json_schema_extra,\n        ),\n    ] = None  # type: ignore[assignment]\n\n    @field_validator(\"query_parameters\", mode=\"after\")\n    @classmethod\n    def sort_not_supported(\n        cls, value: OptimadeQueryParameters\n    ) -&gt; OptimadeQueryParameters:\n        \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n        if value.sort:\n            warnings.warn(SortNotSupported())\n            value.sort = None\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.endpoint","title":"<code>endpoint: Annotated[EndpointEntryType | None, Field(title=QueryResourceAttributes.model_fields['endpoint'].title, description=QueryResourceAttributes.model_fields['endpoint'].description, json_schema_extra=QueryResourceAttributes.model_fields['endpoint'].json_schema_extra)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.state","title":"<code>state: Annotated[QueryState | None, Field(title=QueryResourceAttributes.model_fields['state'].title, description=QueryResourceAttributes.model_fields['state'].description, json_schema_extra=QueryResourceAttributes.model_fields['state'].json_schema_extra)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.sort_not_supported","title":"<code>sort_not_supported(value)</code>  <code>classmethod</code>","text":"<p>Warn and reset value if <code>sort</code> is supplied.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"query_parameters\", mode=\"after\")\n@classmethod\ndef sort_not_supported(\n    cls, value: OptimadeQueryParameters\n) -&gt; OptimadeQueryParameters:\n    \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n    if value.sort:\n        warnings.warn(SortNotSupported())\n        value.sort = None\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters","title":"<code>QueryParameters</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>Type definition for <code>QUERY_PARAMETERS</code>.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryParameters(TypedDict):\n    \"\"\"Type definition for `QUERY_PARAMETERS`.\"\"\"\n\n    annotations: dict[str, FieldInfo]\n    defaults: EntryListingQueryParams\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters.annotations","title":"<code>annotations: dict[str, FieldInfo]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters.defaults","title":"<code>defaults: EntryListingQueryParams</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource","title":"<code>QueryResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>OPTIMADE query resource for a gateway</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryResource(EntryResource):\n    \"\"\"OPTIMADE query resource for a gateway\"\"\"\n\n    type: Annotated[\n        Literal[\"queries\"],\n        Field(\n            description=\"The name of the type of an entry.\",\n        ),\n    ] = \"queries\"\n\n    attributes: QueryResourceAttributes\n\n    async def response_as_optimade(\n        self,\n        url: None | (\n            urllib.parse.ParseResult | urllib.parse.SplitResult | StarletteURL | str\n        ) = None,\n    ) -&gt; EntryResponseMany | ErrorResponse:\n        \"\"\"Return `attributes.response` as a valid OPTIMADE entry listing response.\n\n        Note, this method disregards the state of the query and will simply return the\n        query results as they currently are (if there are any at all).\n\n        Parameters:\n            url: Optionally, update the `meta.query.representation` value with this.\n\n        Returns:\n            A valid OPTIMADE entry-listing response according to the\n            [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints)\n            or an error response, if errors were returned or occurred during the query.\n\n        \"\"\"\n        from optimade.server.routers.utils import (\n            meta_values,\n        )\n\n        async def _update_id(\n            entry_: EntryResource | dict[str, Any], database_provider_: str\n        ) -&gt; EntryResource | dict[str, Any]:\n            \"\"\"Internal utility function to prepend the entries' `id` with\n            `provider/database/`.\n\n            Parameters:\n                entry_: The entry as a model or a dictionary.\n                database_provider_: `provider/database` string.\n\n            Returns:\n                The entry with an updated `id` value.\n\n            \"\"\"\n            if isinstance(entry_, dict):\n                _entry = deepcopy(entry_)\n                _entry[\"id\"] = f\"{database_provider_}/{entry_['id']}\"\n                return _entry\n\n            return entry_.model_copy(\n                update={\"id\": f\"{database_provider_}/{entry_.id}\"},\n                deep=True,\n            ).model_dump(exclude_unset=True, exclude_none=True)\n\n        if not self.attributes.response:\n            # The query has not yet been initiated\n            return ErrorResponse(\n                errors=[\n                    {\n                        \"detail\": (\n                            \"Can not return as a valid OPTIMADE response as the query \"\n                            \"has not yet been initialized.\"\n                        ),\n                        \"id\": \"OPTIMADE_GATEWAY_QUERY_NOT_INITIALIZED\",\n                    }\n                ],\n                meta=meta_values(\n                    url=url or f\"/queries/{self.id}?\",\n                    data_returned=0,\n                    data_available=0,\n                    more_data_available=False,\n                    schema=CONFIG.schema_url,\n                ),\n            )\n\n        meta_ = self.attributes.response.meta\n\n        if url:\n            meta_ = meta_.model_dump(exclude_unset=True)\n            for repeated_key in (\n                \"query\",\n                \"api_version\",\n                \"time_stamp\",\n                \"provider\",\n                \"implementation\",\n            ):\n                meta_.pop(repeated_key, None)\n            meta_ = meta_values(url=url, **meta_)\n\n        # Error response\n        if self.attributes.response.errors:\n            return ErrorResponse(\n                errors=self.attributes.response.errors,\n                meta=meta_,\n            )\n\n        # Data response\n        results = []\n        for database_provider, entries in self.attributes.response.data.items():\n            results.extend(\n                [await _update_id(entry, database_provider) for entry in entries]\n            )\n\n        return self.attributes.endpoint.get_response_model()(\n            data=results,\n            meta=meta_,\n            links=self.attributes.response.links,\n        )\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.attributes","title":"<code>attributes: QueryResourceAttributes</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.type","title":"<code>type: Annotated[Literal['queries'], Field(description='The name of the type of an entry.')] = 'queries'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.response_as_optimade","title":"<code>response_as_optimade(url=None)</code>  <code>async</code>","text":"<p>Return <code>attributes.response</code> as a valid OPTIMADE entry listing response.</p> <p>Note, this method disregards the state of the query and will simply return the query results as they currently are (if there are any at all).</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>None | ParseResult | SplitResult | URL | str</code> <p>Optionally, update the <code>meta.query.representation</code> value with this.</p> <code>None</code> <p>Returns:</p> Type Description <code>EntryResponseMany | ErrorResponse</code> <p>A valid OPTIMADE entry-listing response according to the</p> <code>EntryResponseMany | ErrorResponse</code> <p>OPTIMADE specification</p> <code>EntryResponseMany | ErrorResponse</code> <p>or an error response, if errors were returned or occurred during the query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>async def response_as_optimade(\n    self,\n    url: None | (\n        urllib.parse.ParseResult | urllib.parse.SplitResult | StarletteURL | str\n    ) = None,\n) -&gt; EntryResponseMany | ErrorResponse:\n    \"\"\"Return `attributes.response` as a valid OPTIMADE entry listing response.\n\n    Note, this method disregards the state of the query and will simply return the\n    query results as they currently are (if there are any at all).\n\n    Parameters:\n        url: Optionally, update the `meta.query.representation` value with this.\n\n    Returns:\n        A valid OPTIMADE entry-listing response according to the\n        [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints)\n        or an error response, if errors were returned or occurred during the query.\n\n    \"\"\"\n    from optimade.server.routers.utils import (\n        meta_values,\n    )\n\n    async def _update_id(\n        entry_: EntryResource | dict[str, Any], database_provider_: str\n    ) -&gt; EntryResource | dict[str, Any]:\n        \"\"\"Internal utility function to prepend the entries' `id` with\n        `provider/database/`.\n\n        Parameters:\n            entry_: The entry as a model or a dictionary.\n            database_provider_: `provider/database` string.\n\n        Returns:\n            The entry with an updated `id` value.\n\n        \"\"\"\n        if isinstance(entry_, dict):\n            _entry = deepcopy(entry_)\n            _entry[\"id\"] = f\"{database_provider_}/{entry_['id']}\"\n            return _entry\n\n        return entry_.model_copy(\n            update={\"id\": f\"{database_provider_}/{entry_.id}\"},\n            deep=True,\n        ).model_dump(exclude_unset=True, exclude_none=True)\n\n    if not self.attributes.response:\n        # The query has not yet been initiated\n        return ErrorResponse(\n            errors=[\n                {\n                    \"detail\": (\n                        \"Can not return as a valid OPTIMADE response as the query \"\n                        \"has not yet been initialized.\"\n                    ),\n                    \"id\": \"OPTIMADE_GATEWAY_QUERY_NOT_INITIALIZED\",\n                }\n            ],\n            meta=meta_values(\n                url=url or f\"/queries/{self.id}?\",\n                data_returned=0,\n                data_available=0,\n                more_data_available=False,\n                schema=CONFIG.schema_url,\n            ),\n        )\n\n    meta_ = self.attributes.response.meta\n\n    if url:\n        meta_ = meta_.model_dump(exclude_unset=True)\n        for repeated_key in (\n            \"query\",\n            \"api_version\",\n            \"time_stamp\",\n            \"provider\",\n            \"implementation\",\n        ):\n            meta_.pop(repeated_key, None)\n        meta_ = meta_values(url=url, **meta_)\n\n    # Error response\n    if self.attributes.response.errors:\n        return ErrorResponse(\n            errors=self.attributes.response.errors,\n            meta=meta_,\n        )\n\n    # Data response\n    results = []\n    for database_provider, entries in self.attributes.response.data.items():\n        results.extend(\n            [await _update_id(entry, database_provider) for entry in entries]\n        )\n\n    return self.attributes.endpoint.get_response_model()(\n        data=results,\n        meta=meta_,\n        links=self.attributes.response.links,\n    )\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes","title":"<code>QueryResourceAttributes</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Attributes for an OPTIMADE gateway query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryResourceAttributes(EntryResourceAttributes):\n    \"\"\"Attributes for an OPTIMADE gateway query.\"\"\"\n\n    gateway_id: Annotated[\n        str,\n        Field(\n            description=\"The OPTIMADE gateway ID for this query.\",\n        ),\n    ]\n\n    query_parameters: Annotated[\n        OptimadeQueryParameters,\n        Field(\n            description=(\n                \"OPTIMADE query parameters for entry listing endpoints used for this \"\n                \"query.\"\n            ),\n            json_schema_extra={\n                \"type\": \"object\",\n            },\n        ),\n    ]\n\n    state: Annotated[\n        QueryState,\n        Field(\n            description=\"Current state of Gateway Query.\",\n            title=\"State\",\n            json_schema_extra={\n                \"type\": \"enum\",\n            },\n        ),\n    ] = QueryState.CREATED\n\n    response: Annotated[\n        GatewayQueryResponse | None,\n        Field(\n            description=\"Response from gateway query.\",\n        ),\n    ] = None\n\n    endpoint: Annotated[\n        EndpointEntryType,\n        Field(\n            description=\"The entry endpoint queried, e.g., 'structures'.\",\n            title=\"Endpoint\",\n            json_schema_extra={\n                \"type\": \"enum\",\n            },\n        ),\n    ] = EndpointEntryType.STRUCTURES\n\n    @field_validator(\"endpoint\", mode=\"after\")\n    @classmethod\n    def only_allow_structures(cls, value: EndpointEntryType) -&gt; EndpointEntryType:\n        \"\"\"Temporarily only allow queries to \"structures\" endpoints.\"\"\"\n        if value != EndpointEntryType.STRUCTURES:\n            raise NotImplementedError(\n                'OPTIMADE Gateway temporarily only supports queries to \"structures\" '\n                'endpoints, i.e.: endpoint=\"structures\"'\n            )\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.endpoint","title":"<code>endpoint: Annotated[EndpointEntryType, Field(description=\"The entry endpoint queried, e.g., 'structures'.\", title='Endpoint', json_schema_extra={'type': 'enum'})] = EndpointEntryType.STRUCTURES</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.gateway_id","title":"<code>gateway_id: Annotated[str, Field(description='The OPTIMADE gateway ID for this query.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.query_parameters","title":"<code>query_parameters: Annotated[OptimadeQueryParameters, Field(description='OPTIMADE query parameters for entry listing endpoints used for this query.', json_schema_extra={'type': 'object'})]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.response","title":"<code>response: Annotated[GatewayQueryResponse | None, Field(description='Response from gateway query.')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.state","title":"<code>state: Annotated[QueryState, Field(description='Current state of Gateway Query.', title='State', json_schema_extra={'type': 'enum'})] = QueryState.CREATED</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.only_allow_structures","title":"<code>only_allow_structures(value)</code>  <code>classmethod</code>","text":"<p>Temporarily only allow queries to \"structures\" endpoints.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"endpoint\", mode=\"after\")\n@classmethod\ndef only_allow_structures(cls, value: EndpointEntryType) -&gt; EndpointEntryType:\n    \"\"\"Temporarily only allow queries to \"structures\" endpoints.\"\"\"\n    if value != EndpointEntryType.STRUCTURES:\n        raise NotImplementedError(\n            'OPTIMADE Gateway temporarily only supports queries to \"structures\" '\n            'endpoints, i.e.: endpoint=\"structures\"'\n        )\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState","title":"<code>QueryState</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enumeration of possible states for a Gateway Query.</p> <p>The states are enumerated here in the expected evolvement.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryState(Enum):\n    \"\"\"Enumeration of possible states for a Gateway Query.\n\n    The states are enumerated here in the expected evolvement.\n    \"\"\"\n\n    CREATED = \"created\"\n    STARTED = \"started\"\n    IN_PROGRESS = \"in progress\"\n    FINISHED = \"finished\"\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.CREATED","title":"<code>CREATED = 'created'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.FINISHED","title":"<code>FINISHED = 'finished'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.IN_PROGRESS","title":"<code>IN_PROGRESS = 'in progress'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.STARTED","title":"<code>STARTED = 'started'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/","title":"resources","text":"<p>Pydantic models/schemas for entry-endpoint resources.</p> <p>This module is mainly used for a special pydantic base model, which can be used as a mix-in class when creating entry-endpoint resources.</p>"},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate","title":"<code>EntryResourceCreate</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Generic model for creating new entry resources in the MongoDB</p> Source code in <code>optimade_gateway/models/resources.py</code> <pre><code>class EntryResourceCreate(EntryResourceAttributes):\n    \"\"\"Generic model for creating new entry resources in the MongoDB\"\"\"\n\n    model_config = ConfigDict(extra=\"ignore\")\n\n    last_modified: datetime | None = None\n\n    id: str | None = None\n\n    @model_validator(mode=\"after\")\n    def check_illegal_attributes_fields(self) -&gt; EntryResourceCreate:\n        \"\"\"Overwrite parental `check_illegal_attributes_fields` class validators.\"\"\"\n        return self\n</code></pre>"},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.id","title":"<code>id: str | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.last_modified","title":"<code>last_modified: datetime | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.model_config","title":"<code>model_config = ConfigDict(extra='ignore')</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.check_illegal_attributes_fields","title":"<code>check_illegal_attributes_fields()</code>","text":"<p>Overwrite parental <code>check_illegal_attributes_fields</code> class validators.</p> Source code in <code>optimade_gateway/models/resources.py</code> <pre><code>@model_validator(mode=\"after\")\ndef check_illegal_attributes_fields(self) -&gt; EntryResourceCreate:\n    \"\"\"Overwrite parental `check_illegal_attributes_fields` class validators.\"\"\"\n    return self\n</code></pre>"},{"location":"api_reference/models/responses/","title":"responses","text":"<p>Pydantic models/schemas for the API responses.</p>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponse","title":"<code>DatabasesResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /databases</code></p> <p>This model is essentially equal to <code>LinksResponse</code> with the exception of the <code>data</code> field's description.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class DatabasesResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /databases`\n\n    This model is essentially equal to\n    [`LinksResponse`](https://www.optimade.org/optimade-python-tools/api_reference/models/responses/#optimade.models.responses.LinksResponse)\n    with the exception of the `data` field's description.\n    \"\"\"\n\n    data: Annotated[\n        list[LinksResource],\n        StrictField(\n            description=(\n                \"List of unique OPTIMADE links resource objects.\\nThese links resource \"\n                \"objects represents OPTIMADE databases that can be used for queries in \"\n                \"gateways.\"\n            ),\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponse.data","title":"<code>data: Annotated[list[LinksResource], StrictField(description='List of unique OPTIMADE links resource objects.\\nThese links resource objects represents OPTIMADE databases that can be used for queries in gateways.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponseSingle","title":"<code>DatabasesResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /databases</code> and <code>GET /databases/{database_id}</code></p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class DatabasesResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /databases` and `GET /databases/{database_id}`\"\"\"\n\n    data: Annotated[\n        LinksResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE links resource object.\\nThe OPTIMADE links resource \"\n                \"object has just been created or found according to the specific query \"\n                \"parameter(s) or URL id.\\nIt represents an OPTIMADE database that can \"\n                \"be used for queries in gateways.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponseSingle.data","title":"<code>data: Annotated[LinksResource | None, Field(description='A unique OPTIMADE links resource object.\\nThe OPTIMADE links resource object has just been created or found according to the specific query parameter(s) or URL id.\\nIt represents an OPTIMADE database that can be used for queries in gateways.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponse","title":"<code>GatewaysResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /gateways</code></p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class GatewaysResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /gateways`\"\"\"\n\n    data: Annotated[\n        list[GatewayResource],\n        StrictField(\n            description=\"List of unique OPTIMADE gateway resource objects.\",\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponse.data","title":"<code>data: Annotated[list[GatewayResource], StrictField(description='List of unique OPTIMADE gateway resource objects.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponseSingle","title":"<code>GatewaysResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /gateways</code> and <code>GET /gateways/{gateway_id}</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class GatewaysResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /gateways` and `GET /gateways/{gateway_id}`.\"\"\"\n\n    data: Annotated[\n        GatewayResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE gateway resource object.\\nThe OPTIMADE gateway \"\n                \"resource object has just been created or found according to the \"\n                \"specific query parameter(s) or URL id.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponseSingle.data","title":"<code>data: Annotated[GatewayResource | None, Field(description='A unique OPTIMADE gateway resource object.\\nThe OPTIMADE gateway resource object has just been created or found according to the specific query parameter(s) or URL id.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponse","title":"<code>QueriesResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /gateways/{gateway_ID}/queries</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class QueriesResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /gateways/{gateway_ID}/queries`.\"\"\"\n\n    data: Annotated[\n        list[QueryResource],\n        StrictField(\n            description=\"List of unique OPTIMADE gateway query resource objects.\",\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponse.data","title":"<code>data: Annotated[list[QueryResource], StrictField(description='List of unique OPTIMADE gateway query resource objects.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponseSingle","title":"<code>QueriesResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /gateways/{gateway_ID}/queries</code> and <code>GET /gateways/{gateway_ID}/queries/{query_id}</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class QueriesResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /gateways/{gateway_ID}/queries`\n    and `GET /gateways/{gateway_ID}/queries/{query_id}`.\"\"\"\n\n    data: Annotated[\n        QueryResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE gateway query resource object.\\nThe OPTIMADE \"\n                \"gateway query resource object has just been created or found \"\n                \"according to the specific query parameter(s) or URL id.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponseSingle.data","title":"<code>data: Annotated[QueryResource | None, Field(description='A unique OPTIMADE gateway query resource object.\\nThe OPTIMADE gateway query resource object has just been created or found according to the specific query parameter(s) or URL id.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/","title":"search","text":"<p>Pydantic models/schemas for the Search resource.</p>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search","title":"<code>Search</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A general coordinated OPTIMADE search</p> <p>Important</p> <p>Either <code>database_ids</code> or <code>optimade_urls</code> MUST be specified.</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>class Search(BaseModel):\n    \"\"\"A general coordinated OPTIMADE search\n\n    !!! important\n        Either `database_ids` or `optimade_urls` MUST be specified.\n\n    \"\"\"\n\n    query_parameters: Annotated[\n        OptimadeQueryParameters,\n        Field(\n            description=(\n                \"OPTIMADE query parameters for entry listing endpoints used for this \"\n                \"query.\"\n            ),\n        ),\n    ] = OptimadeQueryParameters()\n\n    database_ids: Annotated[\n        set[str],\n        Field(\n            description=(\n                \"A list of registered database IDs. Go to `/databases` to get all \"\n                \"registered databases.\"\n            ),\n        ),\n    ] = set()\n\n    optimade_urls: Annotated[\n        set[AnyUrl],\n        Field(\n            description=(\n                \"A list of OPTIMADE base URLs. If a versioned base URL is supplied it \"\n                \"will be used as is, as long as it represents a supported version. If \"\n                \"an un-versioned base URL, standard version negotiation will be \"\n                \"conducted to get the versioned base URL, which will be used as long \"\n                \"as it represents a supported version. Note, a single URL can be \"\n                \"supplied as well, and it will automatically be wrapped in a list in \"\n                \"the server logic.\"\n            ),\n        ),\n    ] = set()\n\n    endpoint: Annotated[\n        str,\n        Field(\n            description=(\n                \"The entry endpoint queried. According to the OPTIMADE specification, \"\n                \"this is the same as the resource's type.\"\n            ),\n        ),\n    ] = \"structures\"\n\n    @model_validator(mode=\"after\")\n    def either_ids_or_urls(self) -&gt; Search:\n        \"\"\"Either `database_ids` or `optimade_urls` must be defined\"\"\"\n        if not any(getattr(self, field) for field in (\"database_ids\", \"optimade_urls\")):\n            raise ValueError(\n                \"Either 'database_ids' or 'optimade_urls' MUST be specified.\"\n            )\n        return self\n\n    @field_validator(\"query_parameters\", mode=\"after\")\n    @classmethod\n    def sort_not_supported(\n        cls, value: OptimadeQueryParameters\n    ) -&gt; OptimadeQueryParameters:\n        \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n        if value.sort:\n            warnings.warn(SortNotSupported())\n            value.sort = None\n        return value\n</code></pre>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.database_ids","title":"<code>database_ids: Annotated[set[str], Field(description='A list of registered database IDs. Go to `/databases` to get all registered databases.')] = set()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.endpoint","title":"<code>endpoint: Annotated[str, Field(description=\"The entry endpoint queried. According to the OPTIMADE specification, this is the same as the resource's type.\")] = 'structures'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.optimade_urls","title":"<code>optimade_urls: Annotated[set[AnyUrl], Field(description='A list of OPTIMADE base URLs. If a versioned base URL is supplied it will be used as is, as long as it represents a supported version. If an un-versioned base URL, standard version negotiation will be conducted to get the versioned base URL, which will be used as long as it represents a supported version. Note, a single URL can be supplied as well, and it will automatically be wrapped in a list in the server logic.')] = set()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.query_parameters","title":"<code>query_parameters: Annotated[OptimadeQueryParameters, Field(description='OPTIMADE query parameters for entry listing endpoints used for this query.')] = OptimadeQueryParameters()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.either_ids_or_urls","title":"<code>either_ids_or_urls()</code>","text":"<p>Either <code>database_ids</code> or <code>optimade_urls</code> must be defined</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>@model_validator(mode=\"after\")\ndef either_ids_or_urls(self) -&gt; Search:\n    \"\"\"Either `database_ids` or `optimade_urls` must be defined\"\"\"\n    if not any(getattr(self, field) for field in (\"database_ids\", \"optimade_urls\")):\n        raise ValueError(\n            \"Either 'database_ids' or 'optimade_urls' MUST be specified.\"\n        )\n    return self\n</code></pre>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.sort_not_supported","title":"<code>sort_not_supported(value)</code>  <code>classmethod</code>","text":"<p>Warn and reset value if <code>sort</code> is supplied.</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>@field_validator(\"query_parameters\", mode=\"after\")\n@classmethod\ndef sort_not_supported(\n    cls, value: OptimadeQueryParameters\n) -&gt; OptimadeQueryParameters:\n    \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n    if value.sort:\n        warnings.warn(SortNotSupported())\n        value.sort = None\n    return value\n</code></pre>"},{"location":"api_reference/mongo/collection/","title":"collection","text":"<p>MongoDB collection for entry-endpoint resources.</p> <p>The <code>AsyncMongoCollection</code> represents an asynchronous version of the equivalent MongoDB collection in <code>optimade</code>: <code>MongoCollection</code>.</p>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection","title":"<code>AsyncMongoCollection</code>","text":"<p>               Bases: <code>EntryCollection</code></p> <p>MongoDB Collection for use with <code>asyncio</code></p> <p>The asynchronicity is implemented using <code>motor</code> and <code>asyncio</code>.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>class AsyncMongoCollection(EntryCollection):\n    \"\"\"MongoDB Collection for use with `asyncio`\n\n    The asynchronicity is implemented using [`motor`](https://motor.readthedocs.io) and\n    [`asyncio`](https://asyncio.readthedocs.io/).\n    \"\"\"\n\n    def __init__(\n        self,\n        name: str,\n        resource_cls: EntryResource,\n        resource_mapper: BaseResourceMapper,\n    ):\n        \"\"\"Initialize the AsyncMongoCollection for the given parameters.\n\n        Parameters:\n            name: The name of the collection.\n            resource_cls: The `EntryResource` model that is stored by the collection.\n            resource_mapper: A resource mapper object that handles aliases and format\n                changes between deserialization and response.\n\n        \"\"\"\n        from optimade_gateway.mongo.database import (\n            MONGO_DB,\n        )\n\n        super().__init__(\n            resource_cls=resource_cls,\n            resource_mapper=resource_mapper,\n            transformer=MongoTransformer(mapper=resource_mapper),\n        )\n\n        self.parser = LarkParser(version=(1, 0, 0), variant=\"default\")\n        self.collection: MongoCollection = MONGO_DB[name]\n\n        # Check aliases do not clash with mongo operators\n        self._check_aliases(self.resource_mapper.all_aliases())\n        self._check_aliases(self.resource_mapper.all_length_aliases())\n\n    def __str__(self) -&gt; str:\n        \"\"\"Standard printing result for an instance.\"\"\"\n        return (\n            f\"&lt;{self.__class__.__name__}: resource={self.resource_cls.__name__} \"\n            f\"endpoint(mapper)={self.resource_mapper.ENDPOINT} \"\n            f\"DB_collection={self.collection.name}&gt;\"\n        )\n\n    def __repr__(self) -&gt; str:\n        \"\"\"Representation of instance.\"\"\"\n        return (\n            f\"{self.__class__.__name__}(name={self.collection.name!r}, \"\n            f\"resource_cls={self.resource_cls!r}, \"\n            f\"resource_mapper={self.resource_mapper!r})\"\n        )\n\n    def __len__(self) -&gt; int:\n        warn(\n            OptimadeGatewayWarning(\n                detail=(\n                    \"Cannot calculate length of collection using `len()`. Use \"\n                    \"`count()` instead.\"\n                )\n            )\n        )\n        return 0\n\n    def insert(self, data: list[EntryResource]) -&gt; None:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `ainsert(data: \"\n            \"List[EntryResource])`.\"\n        )\n\n    async def ainsert(self, data: list[EntryResource]) -&gt; None:\n        \"\"\"Add the given entries to the underlying database.\n\n        This is the asynchronous version of the parent class method named `insert()`.\n\n        Arguments:\n            data: The entry resource objects to add to the database.\n\n        \"\"\"\n        await self.collection.insert_many(await clean_python_types(data))\n\n    def count(self, **kwargs) -&gt; int:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `acount(params: \"\n            \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n            \"**kwargs)`.\"\n        )\n\n    async def acount(\n        self,\n        params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n        **kwargs: Any,\n    ) -&gt; int:\n        \"\"\"Count documents in Collection.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Parameters:\n            params: URL query parameters, either from a general entry endpoint or a\n                single-entry endpoint.\n            **kwargs: Query parameters as keyword arguments. Valid keys will be passed\n                to the\n                [`AsyncIOMotorCollection.count_documents`](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html#motor.motor_asyncio.AsyncIOMotorCollection.count_documents)\n                method.\n\n        Returns:\n            int: The number of entries matching the query specified by the keyword\n                arguments.\n\n        \"\"\"\n        if params is not None and kwargs:\n            raise ValueError(\n                \"When 'params' is supplied, no other parameters can be supplied.\"\n            )\n\n        if params is not None:\n            kwargs = await self.ahandle_query_params(params)\n\n        valid_method_keys = (\n            \"filter\",\n            \"skip\",\n            \"limit\",\n            \"hint\",\n            \"maxTimeMS\",\n            \"collation\",\n            \"session\",\n        )\n        criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n        if criteria.get(\"filter\") is None:\n            criteria[\"filter\"] = {}\n\n        return await self.collection.count_documents(**criteria)\n\n    def find(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; tuple[\n        list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n    ]:\n        \"\"\"\n        Fetches results and indicates if more data is available.\n\n        Also gives the total number of data available in the absence of `page_limit`.\n        See\n        [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n        for more information.\n\n        Parameters:\n            params: Entry listing URL query params.\n\n        Returns:\n            A tuple of various relevant values:\n            (`results`, `data_returned`, `more_data_available`, `exclude_fields`,\n            `include_fields`).\n\n        \"\"\"\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `afind(params: \"\n            \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n            \"criteria: Optional[Dict[str, Any]])`.\"\n        )\n\n    async def afind(\n        self,\n        params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n        criteria: dict[str, Any] | None = None,\n    ) -&gt; tuple[\n        list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n    ]:\n        \"\"\"Perform the query on the underlying MongoDB Collection, handling projection\n        and pagination of the output.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Either provide `params` or `criteria`. Not both, but at least one.\n\n        Parameters:\n            params: URL query parameters, either from a general entry endpoint or a\n                single-entry endpoint.\n            criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A list of entry resource objects, how much data was returned for the query,\n            whether more data is available with pagination, and fields (excluded,\n            included).\n\n        \"\"\"\n        if (params is None and criteria is None) or (\n            params is not None and criteria is not None\n        ):\n            raise ValueError(\n                \"Exacly one of either `params` and `criteria` must be specified.\"\n            )\n\n        # Set single_entry to False, this is done since if criteria is defined,\n        # this is an unknown factor - better to then get a list of results.\n        single_entry = False\n        if criteria is None:\n            criteria = await self.ahandle_query_params(params)\n        else:\n            single_entry = isinstance(params, SingleEntryQueryParams)\n\n        response_fields = criteria.pop(\"fields\", self.all_fields)\n\n        results, data_returned, more_data_available = await self._arun_db_query(\n            criteria=criteria,\n            single_entry=single_entry,\n        )\n\n        if single_entry:\n            results = results[0] if results else None  # type: ignore[assignment]\n\n            if data_returned &gt; 1:\n                raise NotFound(\n                    detail=(\n                        f\"Instead of a single entry, {data_returned} entries were found\"\n                    ),\n                )\n\n        include_fields = (\n            response_fields - self.resource_mapper.TOP_LEVEL_NON_ATTRIBUTES_FIELDS\n        )\n        bad_optimade_fields = set()\n        bad_provider_fields = set()\n        for field in include_fields:\n            if field not in self.resource_mapper.ALL_ATTRIBUTES:\n                if field.startswith(\"_\"):\n                    if any(\n                        field.startswith(f\"_{prefix}_\")\n                        for prefix in self.resource_mapper.SUPPORTED_PREFIXES\n                    ):\n                        bad_provider_fields.add(field)\n                else:\n                    bad_optimade_fields.add(field)\n\n        if bad_provider_fields:\n            warn(\n                UnknownProviderProperty(\n                    detail=(\n                        \"Unrecognised field(s) for this provider requested in \"\n                        f\"`response_fields`: {bad_provider_fields}.\"\n                    )\n                )\n            )\n\n        if bad_optimade_fields:\n            raise BadRequest(\n                detail=(\n                    \"Unrecognised OPTIMADE field(s) in requested `response_fields`: \"\n                    f\"{bad_optimade_fields}.\"\n                )\n            )\n\n        if results:\n            results = await self.resource_mapper.adeserialize(results)\n\n        return (  # type: ignore[return-value]\n            results,\n            data_returned,\n            more_data_available,\n            self.all_fields - response_fields,\n            include_fields,\n        )\n\n    def handle_query_params(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; dict[str, Any]:\n        \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n        dictionary that can be used by the specific backend.\n\n        Note:\n            Currently this method returns the pymongo interpretation of the parameters,\n            which will need modification for modified for other backends.\n\n        Parameters:\n            params: The initialized query parameter model from the server.\n\n        Raises:\n            Forbidden: If too large of a page limit is provided.\n            BadRequest: If an invalid request is made, e.g., with incorrect fields\n                or response format.\n\n        Returns:\n            A dictionary representation of the query parameters.\n\n        \"\"\"\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method \"\n            \"`ahandle_query_params(params: Union[EntryListingQueryParams, \"\n            \"SingleEntryQueryParams])`.\"\n        )\n\n    async def ahandle_query_params(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; dict[str, Any]:\n        \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n        dictionary that can be used by the specific backend.\n\n        This is the asynchronous version of the parent class method named\n        `handle_query_params()`.\n\n        Note:\n            Currently this method returns the pymongo interpretation of the parameters,\n            which will need modification for modified for other backends.\n\n        Parameters:\n            params: The initialized query parameter model from the server.\n\n        Raises:\n            Forbidden: If too large of a page limit is provided.\n            BadRequest: If an invalid request is made, e.g., with incorrect fields or\n                response format.\n\n        Returns:\n            A dictionary representation of the query parameters.\n\n        \"\"\"\n        return super().handle_query_params(params)\n\n    def _run_db_query(\n        self, criteria: dict[str, Any], single_entry: bool = False\n    ) -&gt; tuple[list[dict[str, Any]], int, bool]:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method \"\n            \"`_arun_db_query(criteria: Dict[str, Any], single_entry: bool)`.\"\n        )\n\n    async def _arun_db_query(\n        self, criteria: dict[str, Any], single_entry: bool = False\n    ) -&gt; tuple[list[dict[str, Any]], int, bool]:\n        \"\"\"Run the query on the backend and collect the results.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Arguments:\n            criteria: A dictionary representation of the query parameters.\n            single_entry: Whether or not the caller is expecting a single entry\n                response.\n\n        Returns:\n            The list of entries from the database (without any re-mapping), the total\n            number of entries matching the query and a boolean for whether or not there\n            is more data available.\n\n        \"\"\"\n        results = []\n        async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n            if criteria.get(\"projection\", {}).get(\"_id\"):\n                document[\"_id\"] = str(document[\"_id\"])\n            results.append(document)\n\n        if single_entry:\n            data_returned = len(results)\n            more_data_available = False\n        else:\n            criteria_nolimit = criteria.copy()\n            criteria_nolimit.pop(\"limit\", None)\n            data_returned = await self.acount(params=None, **criteria_nolimit)\n            more_data_available = len(results) &lt; data_returned\n\n        return results, data_returned, more_data_available\n\n    @staticmethod\n    def _check_aliases(aliases: tuple[tuple[str, str]]) -&gt; None:\n        \"\"\"Check that aliases do not clash with mongo keywords.\n\n        Parameters:\n            aliases: Tuple of tuple of aliases to be checked.\n\n        Raises:\n            RuntimeError: If any alias starts with the dollar (`$`) character.\n\n        \"\"\"\n        if any(\n            alias[0].startswith(\"$\") or alias[1].startswith(\"$\") for alias in aliases\n        ):\n            raise RuntimeError(f\"Cannot define an alias starting with a '$': {aliases}\")\n\n    async def get_one(self, **criteria: Any) -&gt; EntryResource:\n        \"\"\"Get one resource based on criteria\n\n        Warning:\n            This is not to be used for creating a REST API response,\n            but is rather a utility function to easily retrieve a single resource.\n\n        Parameters:\n            **criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A single resource from the MongoDB (mapped to pydantic models).\n\n        \"\"\"\n        criteria = criteria or {}\n\n        return self.resource_cls(\n            **self.resource_mapper.map_back(\n                await self.collection.find_one(**self._valid_find_keys(**criteria))\n            )\n        )\n\n    async def get_multiple(self, **criteria: Any) -&gt; list[EntryResource]:\n        \"\"\"Get a list of resources based on criteria\n\n        Warning:\n            This is not to be used for creating a REST API response,\n            but is rather a utility function to easily retrieve a list of resources.\n\n        Parameters:\n            **criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A list of resources from the MongoDB (mapped to pydantic models).\n\n        \"\"\"\n        criteria = criteria or {}\n\n        results = []\n        async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n            results.append(self.resource_cls(**self.resource_mapper.map_back(document)))\n\n        return results\n\n    async def create_one(self, resource: EntryResourceCreate) -&gt; EntryResource:\n        \"\"\"Create a new document in the MongoDB collection based on query parameters.\n\n        Update the newly created document with an `\"id\"` field.\n        The value will be the string representation of the `\"_id\"` field.\n        This will only be done if `\"id\"` is not already present in `resource`.\n\n        Parameters:\n            resource: The resource to be created.\n\n        Returns:\n            The newly created document as a pydantic model entry resource.\n\n        \"\"\"\n        resource.last_modified = datetime.now(timezone.utc)\n        result = await self.collection.insert_one(\n            await clean_python_types(resource.model_dump(exclude_unset=True))\n        )\n        LOGGER.debug(\n            \"Inserted resource %r in DB collection %s with ID %s\",\n            resource,\n            self.collection.name,\n            result.inserted_id,\n        )\n\n        if not resource.id:\n            LOGGER.debug(\"Updating resource with an `id` field equal to str(id_).\")\n            await self.collection.update_one(\n                {\"_id\": result.inserted_id}, {\"$set\": {\"id\": str(result.inserted_id)}}\n            )\n\n        return self.resource_cls(\n            **self.resource_mapper.map_back(\n                await self.collection.find_one({\"_id\": result.inserted_id})\n            )\n        )\n\n    async def exists(self, entry_id: str) -&gt; bool:\n        \"\"\"Assert whether entry_id exists in the collection (value of `\"id\"`)\n\n        Parameters:\n            entry_id: The `\"id\"` value of the entry.\n\n        \"\"\"\n        return bool(await self.collection.count_documents({\"id\": entry_id}))\n\n    @staticmethod\n    def _valid_find_keys(**kwargs: dict[str, Any]) -&gt; dict[str, Any]:\n        \"\"\"Return valid MongoDB find() keys with values from kwargs\n\n        Note, not including deprecated flags\n        (see https://pymongo.readthedocs.io/en/3.11.0/api/pymongo/collection.html#pymongo.collection.Collection.find).\n        \"\"\"\n        valid_method_keys = (\n            \"filter\",\n            \"projection\",\n            \"session\",\n            \"skip\",\n            \"limit\",\n            \"no_cursor_timeout\",\n            \"cursor_type\",\n            \"sort\",\n            \"allow_partial_results\",\n            \"batch_size\",\n            \"collation\",\n            \"return_key\",\n            \"show_record_id\",\n            \"hint\",\n            \"max_time_ms\",\n            \"min\",\n            \"max\",\n            \"comment\",\n            \"allow_disk_use\",\n        )\n        criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n        if criteria.get(\"filter\") is None:\n            # Ensure documents are included in the result set\n            criteria[\"filter\"] = {}\n\n        return criteria\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.__init__","title":"<code>__init__(name, resource_cls, resource_mapper)</code>","text":"<p>Initialize the AsyncMongoCollection for the given parameters.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the collection.</p> required <code>resource_cls</code> <code>EntryResource</code> <p>The <code>EntryResource</code> model that is stored by the collection.</p> required <code>resource_mapper</code> <code>BaseResourceMapper</code> <p>A resource mapper object that handles aliases and format changes between deserialization and response.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def __init__(\n    self,\n    name: str,\n    resource_cls: EntryResource,\n    resource_mapper: BaseResourceMapper,\n):\n    \"\"\"Initialize the AsyncMongoCollection for the given parameters.\n\n    Parameters:\n        name: The name of the collection.\n        resource_cls: The `EntryResource` model that is stored by the collection.\n        resource_mapper: A resource mapper object that handles aliases and format\n            changes between deserialization and response.\n\n    \"\"\"\n    from optimade_gateway.mongo.database import (\n        MONGO_DB,\n    )\n\n    super().__init__(\n        resource_cls=resource_cls,\n        resource_mapper=resource_mapper,\n        transformer=MongoTransformer(mapper=resource_mapper),\n    )\n\n    self.parser = LarkParser(version=(1, 0, 0), variant=\"default\")\n    self.collection: MongoCollection = MONGO_DB[name]\n\n    # Check aliases do not clash with mongo operators\n    self._check_aliases(self.resource_mapper.all_aliases())\n    self._check_aliases(self.resource_mapper.all_length_aliases())\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.acount","title":"<code>acount(params=None, **kwargs)</code>  <code>async</code>","text":"<p>Count documents in Collection.</p> <p>This is the asynchronous version of the parent class method named <code>count()</code>.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>None | EntryListingQueryParams | SingleEntryQueryParams</code> <p>URL query parameters, either from a general entry endpoint or a single-entry endpoint.</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Query parameters as keyword arguments. Valid keys will be passed to the <code>AsyncIOMotorCollection.count_documents</code> method.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of entries matching the query specified by the keyword arguments.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def acount(\n    self,\n    params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n    **kwargs: Any,\n) -&gt; int:\n    \"\"\"Count documents in Collection.\n\n    This is the asynchronous version of the parent class method named `count()`.\n\n    Parameters:\n        params: URL query parameters, either from a general entry endpoint or a\n            single-entry endpoint.\n        **kwargs: Query parameters as keyword arguments. Valid keys will be passed\n            to the\n            [`AsyncIOMotorCollection.count_documents`](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html#motor.motor_asyncio.AsyncIOMotorCollection.count_documents)\n            method.\n\n    Returns:\n        int: The number of entries matching the query specified by the keyword\n            arguments.\n\n    \"\"\"\n    if params is not None and kwargs:\n        raise ValueError(\n            \"When 'params' is supplied, no other parameters can be supplied.\"\n        )\n\n    if params is not None:\n        kwargs = await self.ahandle_query_params(params)\n\n    valid_method_keys = (\n        \"filter\",\n        \"skip\",\n        \"limit\",\n        \"hint\",\n        \"maxTimeMS\",\n        \"collation\",\n        \"session\",\n    )\n    criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n    if criteria.get(\"filter\") is None:\n        criteria[\"filter\"] = {}\n\n    return await self.collection.count_documents(**criteria)\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.afind","title":"<code>afind(params=None, criteria=None)</code>  <code>async</code>","text":"<p>Perform the query on the underlying MongoDB Collection, handling projection and pagination of the output.</p> <p>This is the asynchronous version of the parent class method named <code>count()</code>.</p> <p>Either provide <code>params</code> or <code>criteria</code>. Not both, but at least one.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>None | EntryListingQueryParams | SingleEntryQueryParams</code> <p>URL query parameters, either from a general entry endpoint or a single-entry endpoint.</p> <code>None</code> <code>criteria</code> <code>dict[str, Any] | None</code> <p>Already handled/parsed URL query parameters.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource | None</code> <p>A list of entry resource objects, how much data was returned for the query,</p> <code>int</code> <p>whether more data is available with pagination, and fields (excluded,</p> <code>bool</code> <p>included).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def afind(\n    self,\n    params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n    criteria: dict[str, Any] | None = None,\n) -&gt; tuple[\n    list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n]:\n    \"\"\"Perform the query on the underlying MongoDB Collection, handling projection\n    and pagination of the output.\n\n    This is the asynchronous version of the parent class method named `count()`.\n\n    Either provide `params` or `criteria`. Not both, but at least one.\n\n    Parameters:\n        params: URL query parameters, either from a general entry endpoint or a\n            single-entry endpoint.\n        criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A list of entry resource objects, how much data was returned for the query,\n        whether more data is available with pagination, and fields (excluded,\n        included).\n\n    \"\"\"\n    if (params is None and criteria is None) or (\n        params is not None and criteria is not None\n    ):\n        raise ValueError(\n            \"Exacly one of either `params` and `criteria` must be specified.\"\n        )\n\n    # Set single_entry to False, this is done since if criteria is defined,\n    # this is an unknown factor - better to then get a list of results.\n    single_entry = False\n    if criteria is None:\n        criteria = await self.ahandle_query_params(params)\n    else:\n        single_entry = isinstance(params, SingleEntryQueryParams)\n\n    response_fields = criteria.pop(\"fields\", self.all_fields)\n\n    results, data_returned, more_data_available = await self._arun_db_query(\n        criteria=criteria,\n        single_entry=single_entry,\n    )\n\n    if single_entry:\n        results = results[0] if results else None  # type: ignore[assignment]\n\n        if data_returned &gt; 1:\n            raise NotFound(\n                detail=(\n                    f\"Instead of a single entry, {data_returned} entries were found\"\n                ),\n            )\n\n    include_fields = (\n        response_fields - self.resource_mapper.TOP_LEVEL_NON_ATTRIBUTES_FIELDS\n    )\n    bad_optimade_fields = set()\n    bad_provider_fields = set()\n    for field in include_fields:\n        if field not in self.resource_mapper.ALL_ATTRIBUTES:\n            if field.startswith(\"_\"):\n                if any(\n                    field.startswith(f\"_{prefix}_\")\n                    for prefix in self.resource_mapper.SUPPORTED_PREFIXES\n                ):\n                    bad_provider_fields.add(field)\n            else:\n                bad_optimade_fields.add(field)\n\n    if bad_provider_fields:\n        warn(\n            UnknownProviderProperty(\n                detail=(\n                    \"Unrecognised field(s) for this provider requested in \"\n                    f\"`response_fields`: {bad_provider_fields}.\"\n                )\n            )\n        )\n\n    if bad_optimade_fields:\n        raise BadRequest(\n            detail=(\n                \"Unrecognised OPTIMADE field(s) in requested `response_fields`: \"\n                f\"{bad_optimade_fields}.\"\n            )\n        )\n\n    if results:\n        results = await self.resource_mapper.adeserialize(results)\n\n    return (  # type: ignore[return-value]\n        results,\n        data_returned,\n        more_data_available,\n        self.all_fields - response_fields,\n        include_fields,\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.ahandle_query_params","title":"<code>ahandle_query_params(params)</code>  <code>async</code>","text":"<p>Parse and interpret the backend-agnostic query parameter models into a dictionary that can be used by the specific backend.</p> <p>This is the asynchronous version of the parent class method named <code>handle_query_params()</code>.</p> Note <p>Currently this method returns the pymongo interpretation of the parameters, which will need modification for modified for other backends.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>The initialized query parameter model from the server.</p> required <p>Raises:</p> Type Description <code>Forbidden</code> <p>If too large of a page limit is provided.</p> <code>BadRequest</code> <p>If an invalid request is made, e.g., with incorrect fields or response format.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>A dictionary representation of the query parameters.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def ahandle_query_params(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; dict[str, Any]:\n    \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n    dictionary that can be used by the specific backend.\n\n    This is the asynchronous version of the parent class method named\n    `handle_query_params()`.\n\n    Note:\n        Currently this method returns the pymongo interpretation of the parameters,\n        which will need modification for modified for other backends.\n\n    Parameters:\n        params: The initialized query parameter model from the server.\n\n    Raises:\n        Forbidden: If too large of a page limit is provided.\n        BadRequest: If an invalid request is made, e.g., with incorrect fields or\n            response format.\n\n    Returns:\n        A dictionary representation of the query parameters.\n\n    \"\"\"\n    return super().handle_query_params(params)\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.ainsert","title":"<code>ainsert(data)</code>  <code>async</code>","text":"<p>Add the given entries to the underlying database.</p> <p>This is the asynchronous version of the parent class method named <code>insert()</code>.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>list[EntryResource]</code> <p>The entry resource objects to add to the database.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def ainsert(self, data: list[EntryResource]) -&gt; None:\n    \"\"\"Add the given entries to the underlying database.\n\n    This is the asynchronous version of the parent class method named `insert()`.\n\n    Arguments:\n        data: The entry resource objects to add to the database.\n\n    \"\"\"\n    await self.collection.insert_many(await clean_python_types(data))\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.create_one","title":"<code>create_one(resource)</code>  <code>async</code>","text":"<p>Create a new document in the MongoDB collection based on query parameters.</p> <p>Update the newly created document with an <code>\"id\"</code> field. The value will be the string representation of the <code>\"_id\"</code> field. This will only be done if <code>\"id\"</code> is not already present in <code>resource</code>.</p> <p>Parameters:</p> Name Type Description Default <code>resource</code> <code>EntryResourceCreate</code> <p>The resource to be created.</p> required <p>Returns:</p> Type Description <code>EntryResource</code> <p>The newly created document as a pydantic model entry resource.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def create_one(self, resource: EntryResourceCreate) -&gt; EntryResource:\n    \"\"\"Create a new document in the MongoDB collection based on query parameters.\n\n    Update the newly created document with an `\"id\"` field.\n    The value will be the string representation of the `\"_id\"` field.\n    This will only be done if `\"id\"` is not already present in `resource`.\n\n    Parameters:\n        resource: The resource to be created.\n\n    Returns:\n        The newly created document as a pydantic model entry resource.\n\n    \"\"\"\n    resource.last_modified = datetime.now(timezone.utc)\n    result = await self.collection.insert_one(\n        await clean_python_types(resource.model_dump(exclude_unset=True))\n    )\n    LOGGER.debug(\n        \"Inserted resource %r in DB collection %s with ID %s\",\n        resource,\n        self.collection.name,\n        result.inserted_id,\n    )\n\n    if not resource.id:\n        LOGGER.debug(\"Updating resource with an `id` field equal to str(id_).\")\n        await self.collection.update_one(\n            {\"_id\": result.inserted_id}, {\"$set\": {\"id\": str(result.inserted_id)}}\n        )\n\n    return self.resource_cls(\n        **self.resource_mapper.map_back(\n            await self.collection.find_one({\"_id\": result.inserted_id})\n        )\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.exists","title":"<code>exists(entry_id)</code>  <code>async</code>","text":"<p>Assert whether entry_id exists in the collection (value of <code>\"id\"</code>)</p> <p>Parameters:</p> Name Type Description Default <code>entry_id</code> <code>str</code> <p>The <code>\"id\"</code> value of the entry.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def exists(self, entry_id: str) -&gt; bool:\n    \"\"\"Assert whether entry_id exists in the collection (value of `\"id\"`)\n\n    Parameters:\n        entry_id: The `\"id\"` value of the entry.\n\n    \"\"\"\n    return bool(await self.collection.count_documents({\"id\": entry_id}))\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.find","title":"<code>find(params)</code>","text":"<p>Fetches results and indicates if more data is available.</p> <p>Also gives the total number of data available in the absence of <code>page_limit</code>. See <code>EntryListingQueryParams</code> for more information.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>Entry listing URL query params.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource | None</code> <p>A tuple of various relevant values:</p> <code>int</code> <p>(<code>results</code>, <code>data_returned</code>, <code>more_data_available</code>, <code>exclude_fields</code>,</p> <code>bool</code> <p><code>include_fields</code>).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def find(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; tuple[\n    list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n]:\n    \"\"\"\n    Fetches results and indicates if more data is available.\n\n    Also gives the total number of data available in the absence of `page_limit`.\n    See\n    [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n    for more information.\n\n    Parameters:\n        params: Entry listing URL query params.\n\n    Returns:\n        A tuple of various relevant values:\n        (`results`, `data_returned`, `more_data_available`, `exclude_fields`,\n        `include_fields`).\n\n    \"\"\"\n    raise NotImplementedError(\n        \"This method cannot be used with this class and is a remnant from the \"\n        \"parent class. Use instead the asynchronous method `afind(params: \"\n        \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n        \"criteria: Optional[Dict[str, Any]])`.\"\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.get_multiple","title":"<code>get_multiple(**criteria)</code>  <code>async</code>","text":"<p>Get a list of resources based on criteria</p> Warning <p>This is not to be used for creating a REST API response, but is rather a utility function to easily retrieve a list of resources.</p> <p>Parameters:</p> Name Type Description Default <code>**criteria</code> <code>Any</code> <p>Already handled/parsed URL query parameters.</p> <code>{}</code> <p>Returns:</p> Type Description <code>list[EntryResource]</code> <p>A list of resources from the MongoDB (mapped to pydantic models).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def get_multiple(self, **criteria: Any) -&gt; list[EntryResource]:\n    \"\"\"Get a list of resources based on criteria\n\n    Warning:\n        This is not to be used for creating a REST API response,\n        but is rather a utility function to easily retrieve a list of resources.\n\n    Parameters:\n        **criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A list of resources from the MongoDB (mapped to pydantic models).\n\n    \"\"\"\n    criteria = criteria or {}\n\n    results = []\n    async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n        results.append(self.resource_cls(**self.resource_mapper.map_back(document)))\n\n    return results\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.get_one","title":"<code>get_one(**criteria)</code>  <code>async</code>","text":"<p>Get one resource based on criteria</p> Warning <p>This is not to be used for creating a REST API response, but is rather a utility function to easily retrieve a single resource.</p> <p>Parameters:</p> Name Type Description Default <code>**criteria</code> <code>Any</code> <p>Already handled/parsed URL query parameters.</p> <code>{}</code> <p>Returns:</p> Type Description <code>EntryResource</code> <p>A single resource from the MongoDB (mapped to pydantic models).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def get_one(self, **criteria: Any) -&gt; EntryResource:\n    \"\"\"Get one resource based on criteria\n\n    Warning:\n        This is not to be used for creating a REST API response,\n        but is rather a utility function to easily retrieve a single resource.\n\n    Parameters:\n        **criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A single resource from the MongoDB (mapped to pydantic models).\n\n    \"\"\"\n    criteria = criteria or {}\n\n    return self.resource_cls(\n        **self.resource_mapper.map_back(\n            await self.collection.find_one(**self._valid_find_keys(**criteria))\n        )\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.handle_query_params","title":"<code>handle_query_params(params)</code>","text":"<p>Parse and interpret the backend-agnostic query parameter models into a dictionary that can be used by the specific backend.</p> Note <p>Currently this method returns the pymongo interpretation of the parameters, which will need modification for modified for other backends.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>The initialized query parameter model from the server.</p> required <p>Raises:</p> Type Description <code>Forbidden</code> <p>If too large of a page limit is provided.</p> <code>BadRequest</code> <p>If an invalid request is made, e.g., with incorrect fields or response format.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>A dictionary representation of the query parameters.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def handle_query_params(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; dict[str, Any]:\n    \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n    dictionary that can be used by the specific backend.\n\n    Note:\n        Currently this method returns the pymongo interpretation of the parameters,\n        which will need modification for modified for other backends.\n\n    Parameters:\n        params: The initialized query parameter model from the server.\n\n    Raises:\n        Forbidden: If too large of a page limit is provided.\n        BadRequest: If an invalid request is made, e.g., with incorrect fields\n            or response format.\n\n    Returns:\n        A dictionary representation of the query parameters.\n\n    \"\"\"\n    raise NotImplementedError(\n        \"This method cannot be used with this class and is a remnant from the \"\n        \"parent class. Use instead the asynchronous method \"\n        \"`ahandle_query_params(params: Union[EntryListingQueryParams, \"\n        \"SingleEntryQueryParams])`.\"\n    )\n</code></pre>"},{"location":"api_reference/mongo/database/","title":"database","text":"<p>Initialize the MongoDB database.</p>"},{"location":"api_reference/mongo/database/#optimade_gateway.mongo.database.MONGO_CLIENT","title":"<code>MONGO_CLIENT = AsyncIOMotorClient(CONFIG.mongo_uri, **mongo_client_configuration)</code>  <code>module-attribute</code>","text":"<p>The MongoDB motor client.</p>"},{"location":"api_reference/mongo/database/#optimade_gateway.mongo.database.MONGO_DB","title":"<code>MONGO_DB = MONGO_CLIENT[CONFIG.mongo_database]</code>  <code>module-attribute</code>","text":"<p>The MongoDB motor database. This is a representation of the database used for the gateway service.</p>"},{"location":"api_reference/queries/params/","title":"params","text":"<p>URL query parameters.</p>"},{"location":"api_reference/queries/params/#optimade_gateway.queries.params.SearchQueryParams","title":"<code>SearchQueryParams</code>","text":"<p>URL query parameters for <code>GET /search</code></p> <p>This is an extension of the <code>EntryListingQueryParams</code> class in <code>optimade</code>, which defines the standard entry listing endpoint query parameters.</p> <p>The extra query parameters are as follows.</p> <p>Attributes:</p> Name Type Description <code>database_ids</code> <code>set[str]</code> <p>List of possible database IDs that are already known by the gateway. To be known they need to be registered with the gateway (currently not possible).</p> <code>optimade_urls</code> <code>set[AnyUrl]</code> <p>A list of OPTIMADE base URLs. If a versioned base URL is supplied it will be used as is, as long as it represents a supported version. If an un-versioned base URL, standard version negotiation will be conducted to get the versioned base URL, which will be used as long as it represents a supported version.</p> <p>Example: <code>http://example.org/optimade/v1/search?optimade_urls=\"https://example.org/optimade_db/v1\",\"https://optimade.herokuapp.com\"</code></p> <code>endpoint</code> <code>str</code> <p>The entry endpoint queried. According to the OPTIMADE specification, this is the same as the resource's type.</p> <p>Example: <code>structures</code></p> <code>timeout</code> <code>int</code> <p>Timeout time (in seconds) to wait for a query to finish before redirecting (after starting the query). Note, if the query has not finished after the timeout time, a redirection will still be performed, but to a zero-results page, which can be refreshed to get the finished query (once it has finished).</p> <code>as_optimade</code> <code>bool</code> <p>Return the response as a standard OPTIMADE entry listing endpoint response. Otherwise, the response will be based on the <code>QueriesResponseSingle</code> model.</p> Source code in <code>optimade_gateway/queries/params.py</code> <pre><code>class SearchQueryParams:\n    \"\"\"URL query parameters for `GET /search`\n\n    This is an extension of the\n    [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n    class in `optimade`, which defines the standard entry listing endpoint query\n    parameters.\n\n    The extra query parameters are as follows.\n\n    Attributes:\n        database_ids (set[str]): List of possible database IDs that are already known by\n            the gateway. To be known they need to be registered with the gateway\n            (currently not possible).\n\n        optimade_urls (set[AnyUrl]): A list of OPTIMADE base URLs. If a versioned base\n            URL is supplied it will be used as is, as long as it represents a supported\n            version. If an un-versioned base URL, standard version negotiation will be\n            conducted to get the versioned base URL, which will be used as long as it\n            represents a supported version.\n\n            **Example**: `http://example.org/optimade/v1/search?optimade_urls=\"https://example.org/optimade_db/v1\",\"https://optimade.herokuapp.com\"`\n\n        endpoint (str): The entry endpoint queried. According to the OPTIMADE\n            specification, this is the same as the resource's type.\n\n            **Example**: `structures`\n\n        timeout (int): Timeout time (in seconds) to wait for a query to finish before\n            redirecting (*after* starting the query). Note, if the query has not\n            finished after the timeout time, a redirection will still be performed, but\n            to a zero-results page, which can be refreshed to get the finished query\n            (once it has finished).\n\n        as_optimade (bool): Return the response as a standard OPTIMADE entry listing\n            endpoint response. Otherwise, the response will be based on the\n            [`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\n            model.\n\n    \"\"\"\n\n    def __init__(\n        self,\n        *,\n        database_ids: Annotated[\n            set[str],\n            Query(\n                description=(\n                    \"Unique list of possible database IDs that are already known by \"\n                    \"the gateway. To be known they need to be registered with the \"\n                    \"gateway (currently not possible).\"\n                ),\n            ),\n        ] = set(),\n        optimade_urls: Annotated[\n            set[AnyUrl],\n            Query(\n                description=(\n                    \"A unique list of OPTIMADE base URLs. If a versioned base URL is \"\n                    \"supplied it will be used as is, as long as it represents a \"\n                    \"supported version. If an un-versioned base URL, standard version \"\n                    \"negotiation will be conducted to get the versioned base URL, \"\n                    \"which will be used as long as it represents a supported version.\"\n                ),\n            ),\n        ] = set(),\n        endpoint: Annotated[\n            str,\n            Query(\n                description=(\n                    \"The entry endpoint queried. According to the OPTIMADE \"\n                    \"specification, this is the same as the resource's type.\"\n                ),\n            ),\n        ] = \"structures\",\n        timeout: Annotated[\n            int,\n            Query(\n                description=(\n                    \"Timeout time (in seconds) to wait for a query to finish before \"\n                    \"redirecting (*after* starting the query). Note, if the query has \"\n                    \"not finished after the timeout time, a redirection will still be \"\n                    \"performed, but to a zero-results page, which can be refreshed to \"\n                    \"get the finished query (once it has finished).\"\n                ),\n            ),\n        ] = 15,\n        as_optimade: Annotated[\n            bool,\n            Query(\n                description=(\n                    \"Return the response as a standard OPTIMADE entry listing endpoint \"\n                    \"response. Otherwise, the response will be based on the \"\n                    \"[`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\"\n                    \" model.\"\n                ),\n            ),\n        ] = False,\n    ) -&gt; None:\n        self.database_ids = database_ids\n        self.optimade_urls = optimade_urls\n        self.endpoint = endpoint\n        self.timeout = timeout\n        self.as_optimade = as_optimade\n</code></pre>"},{"location":"api_reference/queries/perform/","title":"perform","text":"<p>Perform OPTIMADE queries</p>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.db_find","title":"<code>db_find(database, endpoint, response_model, query_params='', raw_url=None)</code>","text":"<p>Imitate <code>Collection.find()</code> for any given database for entry-resource endpoints</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>LinksResource | dict[str, Any]</code> <p>The OPTIMADE implementation to be queried. It must have a valid base URL and id.</p> required <code>endpoint</code> <code>str</code> <p>The entry-listing endpoint, e.g., <code>\"structures\"</code>.</p> required <code>response_model</code> <code>EntryResponseMany | EntryResponseOne</code> <p>The expected OPTIMADE pydantic response model, e.g., <code>optimade.models.StructureResponseMany</code>.</p> required <code>query_params</code> <code>str</code> <p>URL query parameters to pass to the database.</p> <code>''</code> <code>raw_url</code> <code>AnyUrl | str | None</code> <p>A raw URL to use straight up instead of deriving a URL from <code>database</code>, <code>endpoint</code>, and <code>query_params</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>tuple[ErrorResponse | EntryResponseMany | EntryResponseOne, str]</code> <p>Response as an <code>optimade</code> pydantic model and the <code>database</code>'s ID.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>def db_find(\n    database: LinksResource | dict[str, Any],\n    endpoint: str,\n    response_model: EntryResponseMany | EntryResponseOne,\n    query_params: str = \"\",\n    raw_url: AnyUrl | str | None = None,\n) -&gt; tuple[ErrorResponse | EntryResponseMany | EntryResponseOne, str]:\n    \"\"\"Imitate `Collection.find()` for any given database for entry-resource endpoints\n\n    Parameters:\n        database: The OPTIMADE implementation to be queried.\n            It **must** have a valid base URL and id.\n        endpoint: The entry-listing endpoint, e.g., `\"structures\"`.\n        response_model: The expected OPTIMADE pydantic response model, e.g.,\n            `optimade.models.StructureResponseMany`.\n        query_params: URL query parameters to pass to the database.\n        raw_url: A raw URL to use straight up instead of deriving a URL from `database`,\n            `endpoint`, and `query_params`.\n\n    Returns:\n        Response as an `optimade` pydantic model and the `database`'s ID.\n\n    \"\"\"\n    if TYPE_CHECKING or bool(os.getenv(\"MKDOCS_BUILD\", \"\")):  # pragma: no cover\n        response: (\n            httpx.Response\n            | dict[str, Any]\n            | EntryResponseMany\n            | EntryResponseOne\n            | ErrorResponse\n        )\n\n    if raw_url:\n        url = str(raw_url)\n    else:\n        url = \"\"\n\n        base_url = str(get_resource_attribute(database, \"attributes.base_url\")).rstrip(\n            \"/\"\n        )\n        url += base_url\n\n        # Check whether base_url is a versioned base URL\n        if not any(base_url.endswith(_) for _ in BASE_URL_PREFIXES.values()):\n            # Unversioned base URL - add the currently supported major version\n            url += BASE_URL_PREFIXES[\"major\"]\n\n        url += f\"/{endpoint.strip('/')}?{query_params}\"\n\n    response = httpx.get(url, timeout=60)\n\n    try:\n        response = response.json()\n    except json.JSONDecodeError:\n        return (\n            ErrorResponse(\n                errors=[\n                    {\n                        \"detail\": f\"Could not JSONify response from {url}\",\n                        \"id\": \"OPTIMADE_GATEWAY_DB_FIND_MANY_JSONDECODEERROR\",\n                    }\n                ],\n                meta={\n                    \"query\": {\n                        \"representation\": f\"/{endpoint.strip('/')}?{query_params}\"\n                    },\n                    \"api_version\": __api_version__,\n                    \"more_data_available\": False,\n                },\n            ),\n            get_resource_attribute(database, \"id\"),\n        )\n\n    try:\n        response = response_model(**response)\n    except ValidationError:\n        try:\n            response = ErrorResponse(**response)\n        except ValidationError as exc:\n            # If it's an error and `meta` is missing, it is not a valid OPTIMADE\n            # response, but this happens a lot, and is therefore worth having an\n            # edge-case for.\n            if \"errors\" in response:\n                errors = list(response[\"errors\"])\n                errors.append(\n                    {\n                        \"detail\": (\n                            f\"Could not pass response from {url} as either a \"\n                            f\"{response_model.__name__!r} or 'ErrorResponse'. \"\n                            f\"ValidationError: {exc}\"\n                        ),\n                        \"id\": \"OPTIMADE_GATEWAY_DB_FINDS_MANY_VALIDATIONERRORS\",\n                    }\n                )\n                return (\n                    ErrorResponse(\n                        errors=errors,\n                        meta={\n                            \"query\": {\n                                \"representation\": (\n                                    f\"/{endpoint.strip('/')}?{query_params}\"\n                                )\n                            },\n                            \"api_version\": __api_version__,\n                            \"more_data_available\": False,\n                        },\n                    ),\n                    get_resource_attribute(database, \"id\"),\n                )\n\n            return (\n                ErrorResponse(\n                    errors=[\n                        {\n                            \"detail\": (\n                                f\"Could not pass response from {url} as either a \"\n                                f\"{response_model.__name__!r} or 'ErrorResponse'. \"\n                                f\"ValidationError: {exc}\"\n                            ),\n                            \"id\": \"OPTIMADE_GATEWAY_DB_FINDS_MANY_VALIDATIONERRORS\",\n                        }\n                    ],\n                    meta={\n                        \"query\": {\n                            \"representation\": f\"/{endpoint.strip('/')}?{query_params}\"\n                        },\n                        \"api_version\": __api_version__,\n                        \"more_data_available\": False,\n                    },\n                ),\n                get_resource_attribute(database, \"id\"),\n            )\n\n    return response, get_resource_attribute(database, \"id\")\n</code></pre>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.db_get_all_resources","title":"<code>db_get_all_resources(database, endpoint, response_model, query_params='', raw_url=None)</code>  <code>async</code>","text":"<p>Recursively retrieve all resources from an entry-listing endpoint</p> <p>This function keeps pulling the <code>links.next</code> link if <code>meta.more_data_available</code> is <code>True</code> to ultimately retrieve all entries for <code>endpoint</code>.</p> <p>Warning</p> <p>This function can be dangerous if an endpoint with hundreds or thousands of entries is requested.</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>LinksResource | dict[str, Any]</code> <p>The OPTIMADE implementation to be queried. It must have a valid base URL and id.</p> required <code>endpoint</code> <code>str</code> <p>The entry-listing endpoint, e.g., <code>\"structures\"</code>.</p> required <code>response_model</code> <code>EntryResponseMany</code> <p>The expected OPTIMADE pydantic response model, e.g., <code>optimade.models.StructureResponseMany</code>.</p> required <code>query_params</code> <code>str</code> <p>URL query parameters to pass to the database.</p> <code>''</code> <code>raw_url</code> <code>AnyUrl | str | None</code> <p>A raw URL to use straight up instead of deriving a URL from <code>database</code>, <code>endpoint</code>, and <code>query_params</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>tuple[list[EntryResource | dict[str, Any]], LinksResource | dict[str, Any]]</code> <p>A collected list of successful responses' <code>data</code> value and the <code>database</code>'s ID.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>async def db_get_all_resources(\n    database: LinksResource | dict[str, Any],\n    endpoint: str,\n    response_model: EntryResponseMany,\n    query_params: str = \"\",\n    raw_url: AnyUrl | str | None = None,\n) -&gt; tuple[list[EntryResource | dict[str, Any]], LinksResource | dict[str, Any]]:\n    \"\"\"Recursively retrieve all resources from an entry-listing endpoint\n\n    This function keeps pulling the `links.next` link if `meta.more_data_available` is\n    `True` to ultimately retrieve *all* entries for `endpoint`.\n\n    !!! warning\n        This function can be dangerous if an endpoint with hundreds or thousands of\n        entries is requested.\n\n    Parameters:\n        database: The OPTIMADE implementation to be queried.\n            It **must** have a valid base URL and id.\n        endpoint: The entry-listing endpoint, e.g., `\"structures\"`.\n        response_model: The expected OPTIMADE pydantic response model, e.g.,\n            `optimade.models.StructureResponseMany`.\n        query_params: URL query parameters to pass to the database.\n        raw_url: A raw URL to use straight up instead of deriving a URL from `database`,\n            `endpoint`, and `query_params`.\n\n    Returns:\n        A collected list of successful responses' `data` value and the `database`'s ID.\n\n    \"\"\"\n    resulting_resources = []\n\n    response, _ = db_find(\n        database=database,\n        endpoint=endpoint,\n        response_model=response_model,\n        query_params=query_params,\n        raw_url=raw_url,\n    )\n\n    if isinstance(response, ErrorResponse):\n        # An errored response will result in no databases from a provider.\n        LOGGER.error(\n            \"Error while querying database (id=%r). Full response: %s\",\n            get_resource_attribute(database, \"id\"),\n            response.model_dump_json(indent=2),\n        )\n        return [], database\n\n    resulting_resources.extend(response.data)\n\n    if response.meta.more_data_available:\n        next_page = get_resource_attribute(response, \"links.next\")\n        if next_page is None:\n            LOGGER.error(\n                \"Could not find a 'next' link for an OPTIMADE query request to %r \"\n                \"(id=%r). Cannot get all resources from /%s, even though this was \"\n                \"asked and `more_data_available` is `True` in the response.\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n                endpoint,\n            )\n            return resulting_resources, database\n\n        more_resources, _ = await db_get_all_resources(\n            database=database,\n            endpoint=endpoint,\n            response_model=response_model,\n            query_params=query_params,\n            raw_url=next_page,\n        )\n        resulting_resources.extend(more_resources)\n\n    return resulting_resources, database\n</code></pre>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.perform_query","title":"<code>perform_query(url, query)</code>  <code>async</code>","text":"<p>Perform OPTIMADE query with gateway.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>URL</code> <p>Original request URL.</p> required <code>query</code> <code>QueryResource</code> <p>The query to be performed.</p> required <p>Returns:</p> Type Description <code>EntryResponseMany | ErrorResponse | GatewayQueryResponse</code> <p>This function returns the final response; a</p> <code>EntryResponseMany | ErrorResponse | GatewayQueryResponse</code> <p><code>GatewayQueryResponse</code>.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>async def perform_query(\n    url: URL,\n    query: QueryResource,\n) -&gt; EntryResponseMany | ErrorResponse | GatewayQueryResponse:\n    \"\"\"Perform OPTIMADE query with gateway.\n\n    Parameters:\n        url: Original request URL.\n        query: The query to be performed.\n\n    Returns:\n        This function returns the final response; a\n        [`GatewayQueryResponse`][optimade_gateway.models.queries.GatewayQueryResponse].\n\n    \"\"\"\n    await update_query(query, \"state\", QueryState.STARTED)\n\n    gateway: GatewayResource = await get_valid_resource(\n        await collection_factory(CONFIG.gateways_collection),\n        query.attributes.gateway_id,\n    )\n\n    filter_queries = await prepare_query_filter(\n        database_ids=[_.id for _ in gateway.attributes.databases],\n        filter_query=query.attributes.query_parameters.filter,\n    )\n\n    url = url.replace(path=f\"{url.path.rstrip('/')}/{query.id}\")\n    await update_query(\n        query,\n        \"response\",\n        GatewayQueryResponse(\n            data={},\n            links=ToplevelLinks(next=None),\n            meta=meta_values(\n                url=url,\n                data_available=0,\n                data_returned=0,\n                more_data_available=False,\n                schema=CONFIG.schema_url,\n            ),\n        ),\n        operator=None,\n        **{\"$set\": {\"state\": QueryState.IN_PROGRESS}},\n    )\n\n    loop = asyncio.get_running_loop()\n    with ThreadPoolExecutor(\n        max_workers=min(\n            32, (os.cpu_count() or 0) + 4, len(gateway.attributes.databases)\n        )\n    ) as executor:\n        # Run OPTIMADE DB queries in a thread pool, i.e., not using the main OS thread,\n        # where the asyncio event loop is running.\n        query_tasks = []\n        for database in gateway.attributes.databases:\n            query_params = await get_query_params(\n                query_parameters=query.attributes.query_parameters,\n                database_id=database.id,\n                filter_mapping=filter_queries,\n            )\n            query_tasks.append(\n                loop.run_in_executor(\n                    executor=executor,\n                    func=functools.partial(\n                        db_find,\n                        database=database,\n                        endpoint=query.attributes.endpoint.value,\n                        response_model=query.attributes.endpoint.get_response_model(),\n                        query_params=query_params,\n                    ),\n                )\n            )\n\n        for query_task in query_tasks:\n            (db_response, db_id) = await query_task\n\n            await process_db_response(\n                response=db_response,\n                database_id=db_id,\n                query=query,\n                gateway=gateway,\n            )\n\n    # Pagination\n    #\n    # if isinstance(results, list) and get_resource_attribute(\n    #     query,\n    #     \"attributes.response.meta.more_data_available\",\n    #     False,\n    #     disambiguate=False,  # Extremely minor speed-up\n    # ):\n    #     # Deduce the `next` link from the current request\n    #     query_string = urllib.parse.parse_qs(url.query)\n    #     query_string[\"page_offset\"] = [\n    #         int(query_string.get(\"page_offset\", [0])[0])  # type: ignore[list-item]\n    #         + len(results[: query.attributes.query_parameters.page_limit])\n    #     ]\n    #     urlencoded = urllib.parse.urlencode(query_string, doseq=True)\n    #     base_url = get_base_url(url)\n\n    #     links = ToplevelLinks(next=f\"{base_url}{url.path}?{urlencoded}\")\n\n    #     await update_query(query, \"response.links\", links)\n\n    await update_query(query, \"state\", QueryState.FINISHED)\n    return query.attributes.response\n</code></pre>"},{"location":"api_reference/queries/prepare/","title":"prepare","text":"<p>Prepare OPTIMADE queries.</p>"},{"location":"api_reference/queries/prepare/#optimade_gateway.queries.prepare.get_query_params","title":"<code>get_query_params(query_parameters, database_id, filter_mapping)</code>  <code>async</code>","text":"<p>Construct the parsed URL query parameters</p> Source code in <code>optimade_gateway/queries/prepare.py</code> <pre><code>async def get_query_params(\n    query_parameters: OptimadeQueryParameters,\n    database_id: str,\n    filter_mapping: Mapping[str, str | None],\n) -&gt; str:\n    \"\"\"Construct the parsed URL query parameters\"\"\"\n    query_params = {\n        param: value for param, value in query_parameters.model_dump().items() if value\n    }\n    if filter_mapping[database_id]:\n        query_params.update({\"filter\": filter_mapping[database_id]})\n    return urllib.parse.urlencode(query_params)\n</code></pre>"},{"location":"api_reference/queries/prepare/#optimade_gateway.queries.prepare.prepare_query_filter","title":"<code>prepare_query_filter(database_ids, filter_query)</code>  <code>async</code>","text":"<p>Update the query parameter <code>filter</code> value to be database-specific</p> <p>This is needed due to the served change of <code>id</code> values. If someone searches for a gateway-changed <code>id</code>, it needs to be reverted to be database-specific.</p> <p>Parameters:</p> Name Type Description Default <code>database_ids</code> <code>list[str]</code> <p>List of the databases to create updated filter values for. These values are part of the gateway-changed <code>id</code> values and are essential.</p> required <code>filter_query</code> <code>str | None</code> <p>The submitted <code>filter</code> query parameter value. Can be <code>None</code> if not supplied.</p> required <p>Returns:</p> Type Description <code>Mapping[str, str | None]</code> <p>A mapping for database IDs to database-specific <code>filter</code> query parameter values.</p> Source code in <code>optimade_gateway/queries/prepare.py</code> <pre><code>async def prepare_query_filter(\n    database_ids: list[str], filter_query: str | None\n) -&gt; Mapping[str, str | None]:\n    \"\"\"Update the query parameter `filter` value to be database-specific\n\n    This is needed due to the served change of `id` values.\n    If someone searches for a gateway-changed `id`, it needs to be reverted to be\n    database-specific.\n\n    Parameters:\n        database_ids: List of the databases to create updated filter values for.\n            These values are part of the gateway-changed `id` values and are essential.\n        filter_query: The submitted `filter` query parameter value. Can be `None` if not\n            supplied.\n\n    Returns:\n        A mapping for database IDs to database-specific `filter` query parameter values.\n\n    \"\"\"\n    updated_filter = {}.fromkeys(database_ids, filter_query)\n\n    if not filter_query:\n        return updated_filter\n\n    for id_match in re.finditer(\n        r'\"(?P&lt;id_value_l&gt;[^\\s]*)\"[\\s]*'\n        r\"(&lt;|&gt;|&lt;=|&gt;=|=|!=|CONTAINS|STARTS WITH|ENDS WITH|STARTS|ENDS)\"\n        r\"[\\s]*id|[^_]+id[\\s]*\"\n        r'(&lt;|&gt;|&lt;=|&gt;=|=|!=|CONTAINS|STARTS WITH|ENDS WITH|STARTS|ENDS)[\\s]*\"'\n        r'(?P&lt;id_value_r&gt;[^\\s]*)\"',\n        f\"={filter_query}\" if filter_query else \"\",\n    ):\n        matched_id: str = id_match.group(\"id_value_l\") or id_match.group(\"id_value_r\")\n        for database_id in database_ids:\n            if matched_id.startswith(f\"{database_id}/\"):\n                updated_filter_query = updated_filter[database_id]\n                if not updated_filter_query or not isinstance(\n                    updated_filter_query, str\n                ):\n                    raise TypeError(\n                        \"Expected a string for filter query, got \"\n                        f\"{type(updated_filter_query)}\"\n                    )\n\n                # Database found\n                updated_filter[database_id] = updated_filter_query.replace(\n                    f\"{database_id}/\", \"\", 1\n                )\n                break\n        else:\n            warn(\n                OptimadeGatewayWarning(\n                    title=\"Non-Unique Entry ID\",\n                    detail=(\n                        f\"The passed entry ID &lt;id={matched_id}&gt; may be ambiguous! To \"\n                        \"get a specific structures entry, one can prepend the ID with \"\n                        \"a database ID belonging to the gateway, followed by a forward\"\n                        f\" slash, e.g., '{database_ids[0]}/&lt;local_database_ID&gt;'. \"\n                        f\"Available databases for this gateway: {database_ids}\"\n                    ),\n                )\n            )\n    return updated_filter\n</code></pre>"},{"location":"api_reference/queries/process/","title":"process","text":"<p>Process performed OPTIMADE queries.</p>"},{"location":"api_reference/queries/process/#optimade_gateway.queries.process.process_db_response","title":"<code>process_db_response(response, database_id, query, gateway)</code>  <code>async</code>","text":"<p>Process an OPTIMADE database response.</p> <p>The passed <code>query</code> will be updated with the top-level <code>meta</code> information: <code>data_available</code>, <code>data_returned</code>, and <code>more_data_available</code>.</p> <p>Since, only either <code>data</code> or <code>errors</code> should ever be present, one or the other will be either an empty list or <code>None</code>.</p> <p>Parameters:</p> Name Type Description Default <code>response</code> <code>ErrorResponse | EntryResponseMany | EntryResponseOne</code> <p>The OPTIMADE database response to be processed.</p> required <code>database_id</code> <code>str</code> <p>The database's <code>id</code> under which the returned resources or errors will be delivered.</p> required <code>query</code> <code>QueryResource</code> <p>A resource representing the performed query.</p> required <code>gateway</code> <code>GatewayResource</code> <p>A resource representing the gateway that was queried.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | list[dict[str, Any]] | EntryResource | dict[str, Any] | None</code> <p>The response's <code>data</code>.</p> Source code in <code>optimade_gateway/queries/process.py</code> <pre><code>async def process_db_response(\n    response: ErrorResponse | EntryResponseMany | EntryResponseOne,\n    database_id: str,\n    query: QueryResource,\n    gateway: GatewayResource,\n) -&gt; list[EntryResource] | list[dict[str, Any]] | EntryResource | dict[str, Any] | None:\n    \"\"\"Process an OPTIMADE database response.\n\n    The passed `query` will be updated with the top-level `meta` information:\n    `data_available`, `data_returned`, and `more_data_available`.\n\n    Since, only either `data` or `errors` should ever be present, one or the other will\n    be either an empty list or `None`.\n\n    Parameters:\n        response: The OPTIMADE database response to be processed.\n        database_id: The database's `id` under which the returned resources or errors\n            will be delivered.\n        query: A resource representing the performed query.\n        gateway: A resource representing the gateway that was queried.\n\n    Returns:\n        The response's `data`.\n\n    \"\"\"\n    results = []\n    errors = []\n\n    LOGGER.debug(\"Starting to process database_id: %s\", database_id)\n\n    if isinstance(response, ErrorResponse):\n        for error in response.errors:\n            if isinstance(error.id, str) and error.id.startswith(\"OPTIMADE_GATEWAY\"):\n                warn(error.detail, OptimadeGatewayWarning)\n            else:\n                # The model `ErrorResponse` does not allow the objects in the top-level\n                # `errors` list to be parsed as dictionaries - they must be a pydantic\n                # model.\n                meta_error = {}\n                if error.meta:\n                    meta_error = error.meta.model_dump()\n                meta_error.update(\n                    {\n                        f\"_{CONFIG.provider.prefix}_source_gateway\": {\n                            \"id\": gateway.id,\n                            \"type\": gateway.type,\n                            \"links\": {\"self\": gateway.links.self},\n                        },\n                        f\"_{CONFIG.provider.prefix}_source_database\": {\n                            \"id\": database_id,\n                            \"type\": \"links\",\n                            \"links\": {\n                                \"self\": (\n                                    str(gateway.links.self).split(\n                                        \"gateways\", maxsplit=1\n                                    )[0]\n                                    + f\"databases/{database_id}\"\n                                )\n                            },\n                        },\n                    }\n                )\n                error.meta = Meta(**meta_error)\n                errors.append(error)\n        data_returned = 0\n        more_data_available = False\n    else:\n        results = response.data\n\n        if isinstance(results, list):\n            data_returned = response.meta.data_returned or len(results)\n        else:\n            data_returned = response.meta.data_returned or (0 if not results else 1)\n\n        more_data_available = response.meta.more_data_available or False\n\n    data_available = response.meta.data_available or 0\n\n    extra_updates = {\n        \"$inc\": {\n            \"response.meta.data_available\": data_available,\n            \"response.meta.data_returned\": data_returned,\n        }\n    }\n    if not get_resource_attribute(\n        query,\n        \"attributes.response.meta.more_data_available\",\n        False,\n        disambiguate=False,  # Extremely minor speed-up\n    ):\n        # Keep it True, if set to True once.\n        extra_updates.update(\n            {\"$set\": {\"response.meta.more_data_available\": more_data_available}}\n        )\n\n    # This ensures an empty list under `response.data.{database_id}` is returned if the\n    # case is simply that there are no results to return.\n    if errors:\n        extra_updates.update({\"$addToSet\": {\"response.errors\": {\"$each\": errors}}})\n    await update_query(\n        query,\n        f\"response.data.{database_id}\",\n        results,\n        operator=None,\n        **extra_updates,\n    )\n\n    return results\n</code></pre>"},{"location":"api_reference/queries/utils/","title":"utils","text":"<p>Utility functions for the <code>queries</code> module.</p>"},{"location":"api_reference/queries/utils/#optimade_gateway.queries.utils.update_query","title":"<code>update_query(query, field, value, operator=None, **mongo_kwargs)</code>  <code>async</code>","text":"<p>Update a query's <code>field</code> attribute with <code>value</code>.</p> <p>If <code>field</code> is a dot-separated value, then only the last field part may be a non-pre-existing field. Otherwise a <code>KeyError</code> or <code>AttributeError</code> will be raised.</p> <p>Note</p> <p>This can only update a field for a query's <code>attributes</code>, i.e., this function cannot update <code>id</code>, <code>type</code> or any other top-level resource field.</p> <p>Important</p> <p><code>mongo_kwargs</code> will not be considered for updating the pydantic model instance.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>QueryResource</code> <p>The query to be updated.</p> required <code>field</code> <code>str</code> <p>The <code>attributes</code> field (key) to be set. This can be a dot-separated key value to signify embedded fields.</p> <p>Example: <code>response.meta</code>.</p> required <code>value</code> <code>Any</code> <p>The (possibly) new value for <code>field</code>.</p> required <code>operator</code> <code>str | None</code> <p>A MongoDB operator to be used for updating <code>field</code> with <code>value</code>.</p> <code>None</code> <code>**mongo_kwargs</code> <code>Any</code> <p>Further MongoDB update filters.</p> <code>{}</code> Source code in <code>optimade_gateway/queries/utils.py</code> <pre><code>async def update_query(\n    query: QueryResource,\n    field: str,\n    value: Any,\n    operator: str | None = None,\n    **mongo_kwargs: Any,\n) -&gt; None:\n    \"\"\"Update a query's `field` attribute with `value`.\n\n    If `field` is a dot-separated value, then only the last field part may be a\n    non-pre-existing field. Otherwise a `KeyError` or `AttributeError` will be raised.\n\n    !!! note\n        This can *only* update a field for a query's `attributes`, i.e., this function\n        cannot update `id`, `type` or any other top-level resource field.\n\n    !!! important\n        `mongo_kwargs` will not be considered for updating the pydantic model instance.\n\n    Parameters:\n        query: The query to be updated.\n        field: The `attributes` field (key) to be set.\n            This can be a dot-separated key value to signify embedded fields.\n\n            **Example**: `response.meta`.\n        value: The (possibly) new value for `field`.\n        operator: A MongoDB operator to be used for updating `field` with `value`.\n        **mongo_kwargs: Further MongoDB update filters.\n\n    \"\"\"\n    operator = operator or \"$set\"\n\n    if operator and not operator.startswith(\"$\"):\n        operator = f\"${operator}\"\n\n    update_time = datetime.now(timezone.utc)\n\n    update_kwargs = {\"$set\": {\"last_modified\": update_time}}\n\n    if mongo_kwargs:\n        update_kwargs.update(mongo_kwargs)\n\n    if operator and operator == \"$set\":\n        update_kwargs[\"$set\"].update({field: value})\n    elif operator:\n        if operator in update_kwargs:\n            update_kwargs[operator].update({field: value})\n        else:\n            update_kwargs.update({operator: {field: value}})\n\n    # MongoDB\n    collection = await collection_factory(CONFIG.queries_collection)\n    result: UpdateResult = await collection.collection.update_one(\n        filter={\"id\": {\"$eq\": query.id}},\n        update=await clean_python_types(update_kwargs),\n    )\n    if result.matched_count != 1:\n        LOGGER.error(\n            (\n                \"matched_count should have been exactly 1, it was: %s. \"\n                \"Returned update_one result: %s\"\n            ),\n            result.matched_count,\n            result.raw_result,\n        )\n\n    # Pydantic model instance\n    query.attributes.last_modified = update_time\n    if \".\" in field:\n        field_list = field.split(\".\")\n        sub_field: BaseModel | dict[str, Any] = getattr(query.attributes, field_list[0])\n        for field_part in field_list[1:-1]:\n            if isinstance(sub_field, dict):\n                sub_field = sub_field.get(field_part, {})\n            else:\n                sub_field = getattr(sub_field, field_part)\n        if isinstance(sub_field, dict):\n            sub_field[field_list[-1]] = value\n        else:\n            setattr(sub_field, field_list[-1], value)\n    else:\n        setattr(query.attributes, field, value)\n</code></pre>"},{"location":"api_reference/routers/databases/","title":"databases","text":"<p>/databases/*</p> <p>This file describes the router for:</p> <pre><code>/databases/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p> <p>Database resources represent the available databases that may be used for the gateways.</p> <p>One can register a new database (by using <code>POST /databases</code>) or look through the available databases (by using <code>GET /databases</code>) using standard OPTIMADE filtering.</p>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.get_database","title":"<code>get_database(request, database_id, params)</code>  <code>async</code>","text":"<p><code>GET /databases/{database ID}</code></p> <p>Return a single <code>LinksResource</code> representing the database resource object with <code>id={database ID}</code>.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.get(\n    \"/databases/{database_id:path}\",\n    response_model=DatabasesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_database(\n    request: Request,\n    database_id: str,\n    params: Annotated[SingleEntryQueryParams, Depends()],\n) -&gt; DatabasesResponseSingle:\n    \"\"\"`GET /databases/{database ID}`\n\n    Return a single\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n    representing the database resource object with `id={database ID}`.\n    \"\"\"\n    collection = await collection_factory(CONFIG.databases_collection)\n\n    params.filter = f'id=\"{database_id}\"'\n    (\n        result,\n        data_returned,\n        more_data_available,\n        fields,\n        include_fields,\n    ) = await collection.afind(params=params)\n\n    if fields or include_fields and result is not None:\n        result = handle_response_fields(result, fields, include_fields)\n\n    result = result[0] if isinstance(result, list) and data_returned else None\n\n    return DatabasesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=data_returned,\n            data_available=await collection.acount(),\n            more_data_available=more_data_available,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.get_databases","title":"<code>get_databases(request, params)</code>  <code>async</code>","text":"<p><code>GET /databases</code></p> <p>Return overview of all (active) databases.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.get(\n    \"/databases\",\n    response_model=DatabasesResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_databases(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; DatabasesResponse:\n    \"\"\"`GET /databases`\n\n    Return overview of all (active) databases.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.databases_collection),\n        response_cls=DatabasesResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.post_databases","title":"<code>post_databases(request, database)</code>  <code>async</code>","text":"<p><code>POST /databases</code></p> <p>Create/Register or return an existing <code>LinksResource</code>, representing a database resource object, according to <code>database</code>.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.post(\n    \"/databases\",\n    response_model=DatabasesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def post_databases(\n    request: Request, database: DatabaseCreate\n) -&gt; DatabasesResponseSingle:\n    \"\"\"`POST /databases`\n\n    Create/Register or return an existing\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource),\n    representing a database resource object, according to `database`.\n    \"\"\"\n    result, created = await resource_factory(database)\n    collection = await collection_factory(CONFIG.databases_collection)\n\n    return DatabasesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/","title":"gateways","text":"<p>/gateways/*</p> <p>This file describes the router for:</p> <pre><code>/gateways/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.get_gateway","title":"<code>get_gateway(request, gateway_id)</code>  <code>async</code>","text":"<p><code>GET /gateways/{gateway ID}</code></p> <p>Return a single <code>GatewayResource</code>.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.get(\n    \"/gateways/{gateway_id}\",\n    response_model=GatewaysResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_gateway(request: Request, gateway_id: str) -&gt; GatewaysResponseSingle:\n    \"\"\"`GET /gateways/{gateway ID}`\n\n    Return a single\n    [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource].\n    \"\"\"\n    collection = await collection_factory(CONFIG.gateways_collection)\n    result = await get_valid_resource(collection, gateway_id)\n\n    return GatewaysResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.get_gateways","title":"<code>get_gateways(request, params)</code>  <code>async</code>","text":"<p><code>GET /gateways</code></p> <p>Return overview of all (active) gateways.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.get(\n    \"/gateways\",\n    response_model=GatewaysResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_gateways(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; GatewaysResponse:\n    \"\"\"`GET /gateways`\n\n    Return overview of all (active) gateways.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.gateways_collection),\n        response_cls=GatewaysResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.post_gateways","title":"<code>post_gateways(request, gateway)</code>  <code>async</code>","text":"<p><code>POST /gateways</code></p> <p>Create or return existing gateway according to <code>gateway</code>.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.post(\n    \"/gateways\",\n    response_model=GatewaysResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def post_gateways(\n    request: Request, gateway: GatewayCreate\n) -&gt; GatewaysResponseSingle:\n    \"\"\"`POST /gateways`\n\n    Create or return existing gateway according to `gateway`.\n    \"\"\"\n    if gateway.database_ids:\n        databases_collection = await collection_factory(CONFIG.databases_collection)\n\n        databases = await databases_collection.get_multiple(\n            filter={\"id\": {\"$in\": await clean_python_types(gateway.database_ids)}}\n        )\n\n        if not isinstance(gateway.databases, list):\n            gateway.databases = []\n\n        current_database_ids = [_.id for _ in gateway.databases]\n        gateway.databases.extend(\n            _ for _ in databases if _.id not in current_database_ids\n        )\n\n    result, created = await resource_factory(gateway)\n    collection = await collection_factory(CONFIG.gateways_collection)\n\n    return GatewaysResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/info/","title":"info","text":"<p>/info/*</p> <p>This file describes the router for:</p> <pre><code>/info/{entry}\n</code></pre> <p>where, <code>entry</code> may be left out.</p>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.ENTRY_INFO_SCHEMAS","title":"<code>ENTRY_INFO_SCHEMAS: dict[str, type[EntryResource]] = {'databases': LinksResource, 'gateways': GatewayResource, 'queries': QueryResource}</code>  <code>module-attribute</code>","text":"<p>This dictionary is used to define the <code>/info/&lt;entry_type&gt;</code> endpoints.</p>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.get_entry_info","title":"<code>get_entry_info(request, entry)</code>  <code>async</code>","text":"<p><code>GET /info/{entry}</code></p> <p>Get information about the gateway service's entry-listing endpoints.</p> Source code in <code>optimade_gateway/routers/info.py</code> <pre><code>@ROUTER.get(\n    \"/info/{entry}\",\n    response_model=EntryInfoResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Info\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_entry_info(request: Request, entry: str) -&gt; EntryInfoResponse:\n    \"\"\"`GET /info/{entry}`\n\n    Get information about the gateway service's entry-listing endpoints.\n    \"\"\"\n    valid_entry_info_endpoints = ENTRY_INFO_SCHEMAS.keys()\n    if entry not in valid_entry_info_endpoints:\n        raise NotFound(\n            detail=(\n                f\"Entry info not found for {entry}, valid entry info endpoints are: \"\n                f\"{', '.join(valid_entry_info_endpoints)}\"\n            ),\n        )\n\n    schema = ENTRY_INFO_SCHEMAS[entry]\n    queryable_properties = {\"id\", \"type\", \"attributes\"}\n    properties = await aretrieve_queryable_properties(\n        schema, queryable_properties, entry_type=entry\n    )\n\n    output_fields_by_format = {\"json\": list(properties)}\n\n    return EntryInfoResponse(\n        data=EntryInfoResource(\n            formats=list(output_fields_by_format),\n            description=getattr(schema, \"__doc__\", \"Entry Resources\"),\n            properties=properties,\n            output_fields_by_format=output_fields_by_format,\n        ),\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=1,\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.get_info","title":"<code>get_info(request)</code>  <code>async</code>","text":"<p><code>GET /info</code></p> <p>An introspective endpoint for the gateway service.</p> Source code in <code>optimade_gateway/routers/info.py</code> <pre><code>@ROUTER.get(\n    \"/info\",\n    response_model=InfoResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Info\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_info(request: Request) -&gt; InfoResponse:\n    \"\"\"`GET /info`\n\n    An introspective endpoint for the gateway service.\n    \"\"\"\n    return InfoResponse(\n        data=BaseInfoResource(\n            id=BaseInfoResource.model_fields[\"id\"].default,\n            type=BaseInfoResource.model_fields[\"type\"].default,\n            attributes=BaseInfoAttributes(\n                api_version=__api_version__,\n                available_api_versions=[\n                    {\n                        \"url\": (\n                            f\"{get_base_url(request.url)}\"\n                            f\"/v{__api_version__.split('.', maxsplit=1)[0]}\"\n                        ),\n                        \"version\": __api_version__,\n                    }\n                ],\n                formats=[\"json\"],\n                entry_types_by_format={\"json\": list(ENTRY_INFO_SCHEMAS.keys())},\n                available_endpoints=sorted(\n                    [\n                        \"docs\",\n                        \"info\",\n                        \"links\",\n                        \"openapi.json\",\n                        \"redoc\",\n                        \"search\",\n                        *list(ENTRY_INFO_SCHEMAS.keys()),\n                    ]\n                ),\n                is_index=False,\n            ),\n        ),\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=1,\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/links/","title":"links","text":"<p>/links/*</p> <p>This file describes the router for:</p> <pre><code>/links\n</code></pre>"},{"location":"api_reference/routers/links/#optimade_gateway.routers.links.get_links","title":"<code>get_links(request, params)</code>  <code>async</code>","text":"<p><code>GET /links</code></p> <p>Return a regular <code>/links</code> response for an OPTIMADE implementation.</p> Source code in <code>optimade_gateway/routers/links.py</code> <pre><code>@ROUTER.get(\n    \"/links\",\n    response_model=LinksResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Links\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_links(\n    request: Request, params: Annotated[EntryListingQueryParams, Depends()]\n) -&gt; LinksResponse:\n    \"\"\"`GET /links`\n\n    Return a regular `/links` response for an OPTIMADE implementation.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.links_collection),\n        response_cls=LinksResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/","title":"queries","text":"<p>General /queries endpoint to handle gateway queries</p> <p>This file describes the router for:</p> <pre><code>/queries/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.get_queries","title":"<code>get_queries(request, params)</code>  <code>async</code>","text":"<p><code>GET /queries</code></p> <p>Return overview of all (active) queries.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.get(\n    \"/queries\",\n    response_model=QueriesResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_queries(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; QueriesResponse:\n    \"\"\"`GET /queries`\n\n    Return overview of all (active) queries.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.queries_collection),\n        response_cls=QueriesResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.get_query","title":"<code>get_query(request, query_id, response)</code>  <code>async</code>","text":"<p><code>GET /queries/{query_id}</code></p> <p>Return a single <code>QueryResource</code>.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.get(\n    \"/queries/{query_id}\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_query(\n    request: Request,\n    query_id: str,\n    response: Response,\n) -&gt; QueriesResponseSingle:\n    \"\"\"`GET /queries/{query_id}`\n\n    Return a single [`QueryResource`][optimade_gateway.models.queries.QueryResource].\n    \"\"\"\n    collection = await collection_factory(CONFIG.queries_collection)\n    query: QueryResource = await get_valid_resource(collection, query_id)\n\n    if query.attributes.response and query.attributes.response.errors:\n        for error in query.attributes.response.errors:\n            if error.status:\n                for part in error.status.split(\" \"):\n                    try:\n                        response.status_code = int(part)\n                        break\n                    except ValueError:\n                        pass\n                if response.status_code and response.status_code &gt;= 300:\n                    break\n        else:\n            response.status_code = 500\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=query,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.post_queries","title":"<code>post_queries(request, query)</code>  <code>async</code>","text":"<p><code>POST /queries</code></p> <p>Create or return existing gateway query according to <code>query</code>.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.post(\n    \"/queries\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    status_code=status.HTTP_202_ACCEPTED,\n    responses=ERROR_RESPONSES,\n)\nasync def post_queries(\n    request: Request,\n    query: QueryCreate,\n) -&gt; QueriesResponseSingle:\n    \"\"\"`POST /queries`\n\n    Create or return existing gateway query according to `query`.\n    \"\"\"\n    await validate_resource(\n        await collection_factory(CONFIG.gateways_collection), query.gateway_id\n    )\n\n    result, created = await resource_factory(query)\n\n    background_tasks: set[asyncio.Task] = set()\n\n    if created:\n        task = asyncio.create_task(perform_query(url=request.url, query=result))\n\n        # Add task to the set. This creates a strong reference.\n        background_tasks.add(task)\n\n        # To prevent keeping references to finished tasks forever,\n        # make each task remove its own reference from the set after\n        # completion:\n        task.add_done_callback(background_tasks.discard)\n\n    collection = await collection_factory(CONFIG.queries_collection)\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/search/","title":"search","text":"<p>General /search endpoint to completely coordinate an OPTIMADE gateway query</p> <p>This file describes the router for:</p> <pre><code>/search\n</code></pre>"},{"location":"api_reference/routers/search/#optimade_gateway.routers.search.get_search","title":"<code>get_search(request, response, search_params, entry_params)</code>  <code>async</code>","text":"<p><code>GET /search</code></p> <p>Coordinate a new OPTIMADE query in multiple databases through a gateway:</p> <ol> <li>Create a <code>Search</code> <code>POST</code> data - calling     <code>POST /search</code>.</li> <li>Wait <code>search_params.timeout</code>     seconds before returning the query, if it has not finished before.</li> <li>Return query - similar to <code>GET /queries/{query_id}</code>.</li> </ol> <p>This endpoint works similarly to <code>GET /queries/{query_id}</code>, where one passes the query parameters directly in the URL, instead of first POSTing a query and then going to its URL. Hence, a <code>QueryResponseSingle</code> is the standard response model for this endpoint.</p> <p>If the timeout time is reached and the query has not yet finished, the user is redirected to the specific URL for the query.</p> <p>If the <code>as_optimade</code> query parameter is <code>True</code>, the response will be parseable as a standard OPTIMADE entry listing endpoint like, e.g., <code>/structures</code>. For more information see the OPTIMADE specification.</p> Source code in <code>optimade_gateway/routers/search.py</code> <pre><code>@ROUTER.get(\n    \"/search\",\n    response_model=Union[QueriesResponseSingle, ErrorResponse, EntryResponseMany],\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Search\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_search(\n    request: Request,\n    response: Response,\n    search_params: Annotated[SearchQueryParams, Depends()],\n    entry_params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; QueriesResponseSingle | EntryResponseMany | ErrorResponse | RedirectResponse:\n    \"\"\"`GET /search`\n\n    Coordinate a new OPTIMADE query in multiple databases through a gateway:\n\n    1. Create a [`Search`][optimade_gateway.models.search.Search] `POST` data - calling\n        `POST /search`.\n    1. Wait [`search_params.timeout`][optimade_gateway.queries.params.SearchQueryParams]\n        seconds before returning the query, if it has not finished before.\n    1. Return query - similar to `GET /queries/{query_id}`.\n\n    This endpoint works similarly to `GET /queries/{query_id}`, where one passes the\n    query parameters directly in the URL, instead of first POSTing a query and then\n    going to its URL. Hence, a\n    [`QueryResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle] is\n    the standard response model for this endpoint.\n\n    If the timeout time is reached and the query has not yet finished, the user is\n    redirected to the specific URL for the query.\n\n    If the `as_optimade` query parameter is `True`, the response will be parseable as a\n    standard OPTIMADE entry listing endpoint like, e.g., `/structures`.\n    For more information see the\n    [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints).\n\n    \"\"\"\n    try:\n        search = Search(\n            query_parameters=OptimadeQueryParameters(\n                **{\n                    field: getattr(entry_params, field)\n                    for field in OptimadeQueryParameters.model_fields\n                    if getattr(entry_params, field)\n                }\n            ),\n            optimade_urls=search_params.optimade_urls,\n            endpoint=search_params.endpoint,\n            database_ids=search_params.database_ids,\n        )\n    except ValidationError as exc:\n        raise BadRequest(\n            detail=(\n                \"A Search object could not be created from the given URL query \"\n                f\"parameters. Error(s): {exc.errors}\"\n            )\n        ) from exc\n\n    queries_response = await post_search(request, search=search)\n\n    if not queries_response.data:\n        LOGGER.error(\n            \"QueryResource not found in POST /search response:\\n%s\", queries_response\n        )\n        raise RuntimeError(\n            \"Expected the response from POST /search to return a QueryResource, it did \"\n            \"not\"\n        )\n\n    once = True\n    start_time = time()\n    while time() &lt; (start_time + search_params.timeout) or once:\n        # Make sure to run this at least once (e.g., if timeout=0)\n        once = False\n\n        collection = await collection_factory(CONFIG.queries_collection)\n\n        query: QueryResource = await collection.get_one(\n            filter={\"id\": queries_response.data.id}\n        )\n\n        if query.attributes.state == QueryState.FINISHED:\n            if query.attributes.response and query.attributes.response.errors:\n                for error in query.attributes.response.errors:\n                    if error.status:\n                        for part in error.status.split(\" \"):\n                            try:\n                                response.status_code = int(part)\n                                break\n                            except ValueError:\n                                pass\n                        if response.status_code and response.status_code &gt;= 300:\n                            break\n                else:\n                    response.status_code = 500\n\n            if search_params.as_optimade:\n                response = await query.response_as_optimade(url=request.url)\n                LOGGER.debug(\n                    \"Returning response as OPTIMADE entry listing:\\n%s\", response\n                )\n                return response\n\n            return QueriesResponseSingle(\n                links=ToplevelLinks(next=None),\n                data=query,\n                meta=meta_values(\n                    url=request.url,\n                    data_returned=1,\n                    data_available=await collection.acount(),\n                    more_data_available=False,\n                    schema=CONFIG.schema_url,\n                ),\n            )\n\n        await asyncio.sleep(0.1)\n\n    # The query has not yet succeeded and we're past the timeout time -&gt; Redirect to\n    # /queries/&lt;id&gt;\n    return RedirectResponse(query.links.self)\n</code></pre>"},{"location":"api_reference/routers/search/#optimade_gateway.routers.search.post_search","title":"<code>post_search(request, search)</code>  <code>async</code>","text":"<p><code>POST /search</code></p> <p>Coordinate a new OPTIMADE query in multiple databases through a gateway:</p> <ol> <li>Search for gateway in DB using <code>optimade_urls</code> and <code>database_ids</code></li> <li>Create <code>GatewayCreate</code> model</li> <li><code>POST</code> gateway resource to get ID - using functionality of <code>POST /gateways</code></li> <li>Create new Query resource</li> <li><code>POST</code> Query resource - using functionality of <code>POST /queries</code></li> <li>Return <code>POST /queries</code> response -     <code>QueriesResponseSingle</code></li> </ol> Source code in <code>optimade_gateway/routers/search.py</code> <pre><code>@ROUTER.post(\n    \"/search\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Search\"],\n    status_code=status.HTTP_202_ACCEPTED,\n    responses=ERROR_RESPONSES,\n)\nasync def post_search(request: Request, search: Search) -&gt; QueriesResponseSingle:\n    \"\"\"`POST /search`\n\n    Coordinate a new OPTIMADE query in multiple databases through a gateway:\n\n    1. Search for gateway in DB using `optimade_urls` and `database_ids`\n    1. Create [`GatewayCreate`][optimade_gateway.models.gateways.GatewayCreate] model\n    1. `POST` gateway resource to get ID - using functionality of `POST /gateways`\n    1. Create new [Query][optimade_gateway.models.queries.QueryCreate] resource\n    1. `POST` Query resource - using functionality of `POST /queries`\n    1. Return `POST /queries` response -\n        [`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\n\n    \"\"\"\n    databases_collection = await collection_factory(CONFIG.databases_collection)\n    # NOTE: It may be that the final list of base URLs (`base_urls`) contains the same\n    # provider(s), but with differring base URLS, if, for example, a versioned base URL\n    # is supplied.\n    base_urls: set[AnyUrl] = set()\n\n    if search.database_ids:\n        databases = await databases_collection.get_multiple(\n            filter={\"id\": {\"$in\": await clean_python_types(search.database_ids)}}\n        )\n        base_urls |= {\n            get_resource_attribute(database, \"attributes.base_url\")\n            for database in databases\n            if get_resource_attribute(database, \"attributes.base_url\") is not None\n        }\n\n    if search.optimade_urls:\n        base_urls |= {_ for _ in search.optimade_urls if _ is not None}\n\n    if not base_urls:\n        msg = \"No (valid) OPTIMADE URLs with:\"\n        if search.database_ids:\n            msg += (\n                f\"\\n  Database IDs: {search.database_ids} and corresponding found \"\n                \"URLs: \"\n                f\"{[get_resource_attribute(database, 'attributes.base_url') for database in databases]}\"  # noqa: E501\n            )\n        if search.optimade_urls:\n            msg += f\"\\n  Passed OPTIMADE URLs: {search.optimade_urls}\"\n        raise BadRequest(detail=msg)\n\n    # Ensure all URLs are `pydantic.AnyUrl`s\n    if not all(isinstance(_, AnyUrl) for _ in base_urls):\n        raise InternalServerError(\n            \"Could unexpectedly not validate all base URLs as proper URLs.\"\n        )\n\n    databases = await databases_collection.get_multiple(\n        filter={\"base_url\": {\"$in\": await clean_python_types(base_urls)}}\n    )\n\n    if len(databases) == len(base_urls):\n        # At this point it is expected that the list of databases in `databases`\n        # is a complete set of databases requested.\n        pass\n\n    elif len(databases) &lt; len(base_urls):\n        # There are unregistered databases, i.e., databases not in the local collection\n        current_base_urls: set[AnyUrl] = {\n            get_resource_attribute(database, \"attributes.base_url\")\n            for database in databases\n        }\n        databases.extend(\n            [\n                LinksResource(\n                    id=str(url)\n                    .replace(\".\", \"__\")[len(url.scheme) + 3 :]\n                    .split(\"?\", maxsplit=1)[0]\n                    .split(\"#\", maxsplit=1)[0],\n                    type=\"links\",\n                    attributes=LinksResourceAttributes(\n                        name=str(url)[len(url.scheme) + 3 :]\n                        .split(\"?\", maxsplit=1)[0]\n                        .split(\"#\", maxsplit=1)[0],\n                        description=\"\",\n                        base_url=url,\n                        link_type=LinkType.CHILD,\n                        homepage=None,\n                    ),\n                )\n                for url in base_urls - current_base_urls\n            ]\n        )\n    else:\n        LOGGER.error(\n            \"Found more database entries in MongoDB than then number of passed base \"\n            \"URLs. This suggests ambiguity in the base URLs of databases stored in \"\n            \"MongoDB.\\n  base_urls: %s\\n  databases %s\",\n            base_urls,\n            databases,\n        )\n        raise InternalServerError(\"Unambiguous base URLs. See logs for more details.\")\n\n    gateway = GatewayCreate(databases=databases)\n    gateway, created = await resource_factory(gateway)\n\n    if created:\n        LOGGER.debug(\"A new gateway was created for a query (id=%r)\", gateway.id)\n    else:\n        LOGGER.debug(\"A gateway was found and reused for a query (id=%r)\", gateway.id)\n\n    query = QueryCreate(\n        endpoint=search.endpoint,\n        gateway_id=gateway.id,\n        query_parameters=search.query_parameters,\n    )\n    query, created = await resource_factory(query)\n\n    background_tasks: set[asyncio.Task] = set()\n\n    if created:\n        task = asyncio.create_task(perform_query(url=request.url, query=query))\n\n        # Add task to the set. This creates a strong reference.\n        background_tasks.add(task)\n\n        # To prevent keeping references to finished tasks forever,\n        # make each task remove its own reference from the set after\n        # completion:\n        task.add_done_callback(background_tasks.discard)\n\n    collection = await collection_factory(CONFIG.queries_collection)\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=query,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/","title":"utils","text":"<p>Utility functions for all routers.</p>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.COLLECTIONS","title":"<code>COLLECTIONS: dict[str, AsyncMongoCollection] = {}</code>  <code>module-attribute</code>","text":"<p>A lazy-loaded dictionary of asynchronous MongoDB entry-endpoint collections.</p>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.aretrieve_queryable_properties","title":"<code>aretrieve_queryable_properties(schema, queryable_properties, entry_type=None)</code>  <code>async</code>","text":"<p>Asynchronous implementation of <code>retrieve_queryable_properties()</code> from <code>optimade</code></p> <p>Reference to the function in the <code>optimade</code> API documentation: <code>retrieve_queryable_properties()</code>.</p> <p>Recursively loops through the schema of a pydantic model and resolves all references, returning a dictionary of all the OPTIMADE-queryable properties of that model.</p> <p>Parameters:</p> Name Type Description Default <code>schema</code> <code>type[EntryResource]</code> <p>The schema of the pydantic model.</p> required <code>queryable_properties</code> <code>Iterable[str]</code> <p>The list of properties to find in the schema.</p> required <code>entry_type</code> <code>str | None</code> <p>The entry type of the model, if any.</p> <code>None</code> <p>Returns:</p> Type Description <code>QueryableProperties</code> <p>A flat dictionary with properties as keys, containing the field description,</p> <code>QueryableProperties</code> <p>unit, sortability, support level, queryability and type, where provided.</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def aretrieve_queryable_properties(\n    schema: type[EntryResource],\n    queryable_properties: Iterable[str],\n    entry_type: str | None = None,\n) -&gt; QueryableProperties:\n    \"\"\"Asynchronous implementation of `retrieve_queryable_properties()` from `optimade`\n\n    Reference to the function in the `optimade` API documentation:\n    [`retrieve_queryable_properties()`](https://www.optimade.org/optimade-python-tools/api_reference/server/schemas/#optimade.server.schemas.retrieve_queryable_properties).\n\n    Recursively loops through the schema of a pydantic model and resolves all\n    references, returning a dictionary of all the OPTIMADE-queryable properties of that\n    model.\n\n    Parameters:\n        schema: The schema of the pydantic model.\n        queryable_properties: The list of properties to find in the schema.\n        entry_type: The entry type of the model, if any.\n\n    Returns:\n        A flat dictionary with properties as keys, containing the field description,\n        unit, sortability, support level, queryability and type, where provided.\n\n    \"\"\"\n    return retrieve_queryable_properties(\n        schema=schema,\n        queryable_properties=queryable_properties,\n        entry_type=entry_type,\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.collection_factory","title":"<code>collection_factory(name)</code>  <code>async</code>","text":"<p>Get or initiate an entry-endpoint resource collection.</p> <p>This factory utilizes the global dictionary <code>COLLECTIONS</code>. It lazily instantiates the collections and then caches them in the dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The configured name for the entry-endpoint resource collection.</p> required <p>Returns:</p> Type Description <code>AsyncMongoCollection</code> <p>The OPTIMADE Gateway asynchronous implementation of the</p> <code>AsyncMongoCollection</code> <p><code>MongoCollection</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the supplied <code>name</code> is not one of the configured valid collection names.</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def collection_factory(name: str) -&gt; AsyncMongoCollection:\n    \"\"\"Get or initiate an entry-endpoint resource collection.\n\n    This factory utilizes the global dictionary\n    [`COLLECTIONS`][optimade_gateway.routers.utils.COLLECTIONS].\n    It lazily instantiates the collections and then caches them in the dictionary.\n\n    Parameters:\n        name: The configured name for the entry-endpoint resource collection.\n\n    Returns:\n        The OPTIMADE Gateway asynchronous implementation of the\n        [`MongoCollection`](https://www.optimade.org/optimade-python-tools/api_reference/server/entry_collections/mongo/#optimade.server.entry_collections.mongo.MongoCollection).\n\n    Raises:\n        ValueError: If the supplied `name` is not one of the configured valid collection\n            names.\n\n    \"\"\"\n    if name in COLLECTIONS:\n        return COLLECTIONS[name]\n\n    if name == CONFIG.databases_collection:\n        from optimade_gateway.mappers.databases import DatabasesMapper as ResourceMapper\n    elif name == CONFIG.gateways_collection:\n        from optimade_gateway.mappers.gateways import (  # type: ignore[no-redef]\n            GatewaysMapper as ResourceMapper,\n        )\n    elif name == CONFIG.queries_collection:\n        from optimade_gateway.mappers.queries import (  # type: ignore[no-redef]\n            QueryMapper as ResourceMapper,\n        )\n    elif name == CONFIG.links_collection:\n        from optimade_gateway.mappers.links import (  # type: ignore[no-redef]\n            LinksMapper as ResourceMapper,\n        )\n    else:\n        raise ValueError(\n            f\"{name!r} is not a valid entry-endpoint resource collection name. \"\n            \"Configured valid names: \"\n            f\"{(CONFIG.databases_collection, CONFIG.gateways_collection, CONFIG.queries_collection, CONFIG.links_collection)}\"  # noqa: E501\n        )\n\n    COLLECTIONS[name] = AsyncMongoCollection(\n        name=name,\n        resource_cls=ResourceMapper.ENTRY_RESOURCE_CLASS,\n        resource_mapper=ResourceMapper,\n    )\n\n    return COLLECTIONS[name]\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.get_entries","title":"<code>get_entries(collection, response_cls, request, params)</code>  <code>async</code>","text":"<p>Generalized <code>/{entries}</code> endpoint getter</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def get_entries(\n    collection: AsyncMongoCollection,\n    response_cls: EntryResponseMany,\n    request: Request,\n    params: EntryListingQueryParams,\n) -&gt; EntryResponseMany:\n    \"\"\"Generalized `/{entries}` endpoint getter\"\"\"\n    (\n        results,\n        data_returned,\n        more_data_available,\n        fields,\n        include_fields,\n    ) = await collection.afind(params=params)\n\n    if more_data_available:\n        # Deduce the `next` link from the current request\n        query = urllib.parse.parse_qs(request.url.query)\n        query[\"page_offset\"] = [int(query.get(\"page_offset\", [0])[0]) + len(results)]  # type: ignore[list-item, arg-type]\n        urlencoded = urllib.parse.urlencode(query, doseq=True)\n        base_url = get_base_url(request.url)\n\n        links = ToplevelLinks(next=f\"{base_url}{request.url.path}?{urlencoded}\")\n    else:\n        links = ToplevelLinks(next=None)\n\n    if fields or include_fields:\n        results = handle_response_fields(results, fields, include_fields)\n\n    return response_cls(\n        links=links,\n        data=results,\n        meta=meta_values(\n            url=request.url,\n            data_returned=data_returned,\n            data_available=await collection.acount(),\n            more_data_available=more_data_available,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.get_valid_resource","title":"<code>get_valid_resource(collection, entry_id)</code>  <code>async</code>","text":"<p>Validate and retrieve a resource</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def get_valid_resource(\n    collection: AsyncMongoCollection, entry_id: str\n) -&gt; EntryResource:\n    \"\"\"Validate and retrieve a resource\"\"\"\n    await validate_resource(collection, entry_id)\n    return await collection.get_one(filter={\"id\": entry_id})\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.resource_factory","title":"<code>resource_factory(create_resource)</code>  <code>async</code>","text":"<p>Get or create a resource</p> <p>Currently supported resources:</p> <ul> <li><code>\"databases\"</code>     (<code>DatabaseCreate</code>     -&gt;     <code>LinksResource</code>)</li> <li><code>\"gateways\"</code> (<code>GatewayCreate</code> -&gt;     <code>GatewayResource</code>)</li> <li><code>\"queries\"</code> (<code>QueryCreate</code> -&gt;     <code>QueryResource</code>)</li> </ul> <p>For each of the resources, \"uniqueness\" is determined in the following way:</p> Databases <p>The <code>base_url</code> field is considered unique across all databases.</p> <p>If a <code>base_url</code> is provided via a <code>Link</code> model, the <code>base_url.href</code> value is used to query the MongoDB.</p> Gateways <p>The collected list of <code>databases.attributes.base_url</code> values is considered unique across all gateways.</p> <p>In the database, the search is done as a combination of the length/size of the <code>databases</code>' Python list/MongoDB array and a match on all (using the MongoDB <code>$all</code> operator) of the <code>databases.attributes.base_url</code> element values, when compared with the <code>create_resource</code>.</p> <p>Important</p> <p>The <code>database_ids</code> attribute must not contain values that are not also included in the <code>databases</code> attribute, in the form of the IDs for the individual databases. If this should be the case an <code>OptimadeGatewayError</code> will be thrown.</p> Queries <p>The <code>gateway_id</code>, <code>query_parameters</code>, and <code>endpoint</code> fields are collectively considered to define uniqueness for a <code>QueryResource</code> in the MongoDB collection.</p> <p>Attention</p> <p>Only the <code>/structures</code> entry endpoint can be queried with multiple expected responses.</p> <p>This means the <code>endpoint</code> field defaults to <code>\"structures\"</code>, i.e., the <code>StructureResource</code> resource model.</p> <p>Parameters:</p> Name Type Description Default <code>create_resource</code> <code>DatabaseCreate | GatewayCreate | QueryCreate</code> <p>The resource to be retrieved or created anew.</p> required <p>Returns:</p> Type Description <code>tuple[LinksResource | GatewayResource | QueryResource, bool]</code> <p>Two things in a tuple:</p> <ul> <li>Either a     <code>GatewayResource</code>;     a <code>QueryResource</code>; or a     <code>LinksResource</code>     and</li> <li>whether or not the resource was newly created.</li> </ul> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def resource_factory(\n    create_resource: DatabaseCreate | GatewayCreate | QueryCreate,\n) -&gt; tuple[LinksResource | GatewayResource | QueryResource, bool]:\n    \"\"\"Get or create a resource\n\n    Currently supported resources:\n\n    - `\"databases\"`\n        ([`DatabaseCreate`][optimade_gateway.models.databases.DatabaseCreate]\n        -&gt;\n        [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource))\n    - `\"gateways\"` ([`GatewayCreate`][optimade_gateway.models.gateways.GatewayCreate] -&gt;\n        [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource])\n    - `\"queries\"` ([`QueryCreate`][optimade_gateway.models.queries.QueryCreate] -&gt;\n        [`QueryResource`][optimade_gateway.models.queries.QueryResource])\n\n    For each of the resources, \"uniqueness\" is determined in the following way:\n\n    === \"Databases\"\n        The `base_url` field is considered unique across all databases.\n\n        If a `base_url` is provided via a\n        [`Link`](https://www.optimade.org/optimade-python-tools/api_reference/models/jsonapi/#optimade.models.jsonapi.Link)\n        model, the `base_url.href` value is used to query the MongoDB.\n\n    === \"Gateways\"\n        The collected list of `databases.attributes.base_url` values is considered\n        unique across all gateways.\n\n        In the database, the search is done as a combination of the length/size of the\n        `databases`' Python list/MongoDB array and a match on all (using the MongoDB\n        `$all` operator) of the\n        [`databases.attributes.base_url`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes.base_url)\n        element values, when compared with the `create_resource`.\n\n        !!! important\n            The `database_ids` attribute **must not** contain values that are not also\n            included in the `databases` attribute, in the form of the IDs for the\n            individual databases. If this should be the case an\n            [`OptimadeGatewayError`][optimade_gateway.common.exceptions.OptimadeGatewayError]\n            will be thrown.\n\n    === \"Queries\"\n        The `gateway_id`, `query_parameters`, and `endpoint` fields are collectively\n        considered to define uniqueness for a\n        [`QueryResource`][optimade_gateway.models.queries.QueryResource] in the MongoDB\n        collection.\n\n        !!! attention\n            Only the `/structures` entry endpoint can be queried with multiple expected\n            responses.\n\n            This means the `endpoint` field defaults to `\"structures\"`, i.e., the\n            [`StructureResource`](https://www.optimade.org/optimade-python-tools/all_models/#optimade.models.structures.StructureResource)\n            resource model.\n\n    Parameters:\n        create_resource: The resource to be retrieved or created anew.\n\n    Returns:\n        Two things in a tuple:\n\n            - Either a\n                [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource];\n                a [`QueryResource`][optimade_gateway.models.queries.QueryResource]; or a\n                [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n                and\n            - whether or not the resource was newly created.\n\n    \"\"\"\n    created = False\n\n    if isinstance(create_resource, DatabaseCreate):\n        collection_name = CONFIG.databases_collection\n\n        base_url = get_resource_attribute(create_resource, \"base_url\")\n\n        mongo_query: dict[str, Any] = {\n            \"$or\": [\n                {\"base_url\": {\"$eq\": base_url}},\n                {\"base_url.href\": {\"$eq\": base_url}},\n            ]\n        }\n    elif isinstance(create_resource, GatewayCreate):\n        collection_name = CONFIG.gateways_collection\n\n        # One MUST have taken care of database_ids prior to calling `resource_factory()`\n        database_attr_ids = {_.id for _ in create_resource.databases or []}\n        unknown_ids = {\n            database_id\n            for database_id in create_resource.database_ids or []\n            if database_id not in database_attr_ids\n        }\n        if unknown_ids:\n            raise OptimadeGatewayError(\n                \"When using `resource_factory()` for `GatewayCreate`, `database_ids` \"\n                f\"MUST not include unknown IDs. Passed unknown IDs: {unknown_ids}\"\n            )\n\n        mongo_query = {\n            \"databases\": {\"$size\": len(create_resource.databases or [])},\n            \"databases.attributes.base_url\": {\n                \"$all\": [_.attributes.base_url for _ in create_resource.databases or []]\n            },\n        }\n    elif isinstance(create_resource, QueryCreate):\n        collection_name = CONFIG.queries_collection\n\n        # Currently only /structures entry endpoints can be queried with multiple\n        # expected responses.\n        create_resource.endpoint = (\n            create_resource.endpoint\n            if create_resource.endpoint is not None\n            else EndpointEntryType(\"structures\")\n        )\n\n        mongo_query = {\n            \"gateway_id\": {\"$eq\": create_resource.gateway_id},\n            \"query_parameters\": {\"$eq\": create_resource.query_parameters},\n            \"endpoint\": {\"$eq\": create_resource.endpoint},\n        }\n    else:\n        raise TypeError(\n            \"create_resource must be either a DatabaseCreate, GatewayCreate, or \"\n            f\"QueryCreate object, not {type(create_resource)!r}\"\n        )\n\n    collection = await collection_factory(collection_name)\n    result, data_returned, more_data_available, _, _ = await collection.afind(\n        criteria={\"filter\": await clean_python_types(mongo_query)}\n    )\n\n    if more_data_available:\n        raise OptimadeGatewayError(\n            \"more_data_available MUST be False for a single entry response, however it \"\n            f\"is {more_data_available}\"\n        )\n\n    if result:\n        if data_returned &gt; 1:\n            raise OptimadeGatewayError(\n                f\"More than one {result[0].type} were found. IDs of found \"\n                f\"{result[0].type}: {[_.id for _ in result]}\"\n            )\n        if isinstance(result, list):\n            result = result[0]\n    else:\n        if isinstance(create_resource, DatabaseCreate):\n            # Set required `LinksResourceAttributes` values if not set\n            if not create_resource.description:\n                create_resource.description = (\n                    f\"{create_resource.name} created by OPTIMADE gateway database \"\n                    \"registration.\"\n                )\n\n            if not create_resource.link_type:\n                create_resource.link_type = LinkType.EXTERNAL\n\n            if not create_resource.homepage:\n                create_resource.homepage = None\n\n        elif (\n            isinstance(create_resource, GatewayCreate)\n            and \"database_ids\" in create_resource.model_fields_set\n        ):\n            # Do not store `database_ids`\n            del create_resource.database_ids\n            create_resource.model_fields_set.remove(\"database_ids\")\n\n        elif isinstance(create_resource, QueryCreate):\n            create_resource.state = QueryState.CREATED\n\n        result = await collection.create_one(create_resource)\n        LOGGER.debug(\"Created new %s: %r\", result.type, result)\n        created = True\n\n    return result, created\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.validate_resource","title":"<code>validate_resource(collection, entry_id)</code>  <code>async</code>","text":"<p>Validate whether a resource exists in a collection</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def validate_resource(collection: AsyncMongoCollection, entry_id: str) -&gt; None:\n    \"\"\"Validate whether a resource exists in a collection\"\"\"\n    if not await collection.exists(entry_id):\n        raise NotFound(\n            detail=f\"Resource &lt;id={entry_id}&gt; not found in {collection}.\",\n        )\n</code></pre>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"OPTIMADE Gateway","text":"<p>A REST API server acting as a gateway for databases with an OPTIMADE API, handling the distribution and collection of a single query to several different OPTIMADE databases.</p> <p>The design outline is available here.</p>"},{"location":"#known-limitations","title":"Known limitations","text":"<p>Here follows a list of known limitations and oddities of the current OPTIMADE gateway code.</p>"},{"location":"#pagination","title":"Pagination","text":"<p>Pagination is a bit awkward in its current implementation state.</p> <p>When using the <code>page_limit</code> query parameter for a gateway query for gateways with multiple databases, i.e., for <code>GET /gateways/{gateway ID}/structures</code> and <code>GET /queries/{query ID}</code>, the resulting entry-resource number is the product of the <code>page_limit</code> value and the number of databases in the gateway (maximum). This is because the <code>page_limit</code> query parameter is passed straight through to the external database requests, and the returned entries are stitched together for the gateway response.</p> <p>So effectively, when querying <code>GET /gateways/{gateway with N databases}/structures?page_limit=5</code> the resulting (maximum) number of entries returned in the response (the size of the <code>data</code> array in the response) will be N x 5, and not 5 as would otherwise be expected.</p> <p>The intention is to fix this in the future, either through short-time caching of external database responses, or figuring out if there is a usable algorithm that doesn't extend the number of external requests (and therefore the gateway response times) by too much.</p>"},{"location":"#sorting","title":"Sorting","text":"<p>Sorting is supported for all the gateway's own resources, i.e., in the <code>/gateways</code>, <code>/databases</code>, and <code>/queries</code> endpoints. But sorting is not supported for the results from external OPTIMADE databases. This means the <code>sort</code> query parameter has no effect in the <code>GET /gateways/{gateway ID}/structures</code> and <code>GET /queries/{query ID}</code> endpoints.</p> <p>This shortcoming is a direct result of the current <code>page_limit</code> query parameter handling, and the limitation of the same.</p>"},{"location":"#license-copyright-funding-support","title":"License, copyright &amp; funding support","text":"<p>All code in this repository was originally written by Casper Welzel Andersen (@CasperWA). The design for the gateway as outlined in design.md was a joint effort between Casper Welzel Andersen &amp; Carl Simon Adorf (@csadorf).</p> <p>All files in this repository are licensed under the MIT license with copyright \u00a9 2021 Casper Welzel Andersen &amp; THEOS, EPFL.</p>"},{"location":"#funding-support","title":"Funding support","text":"<p>This work was funded by THEOS, EPFL and the MarketPlace project.</p> <p>The MarketPlace project is funded by Horizon 2020 under H2020-NMBP-25-2017 call with Grant agreement number: 760173.</p>"},{"location":"CHANGELOG/","title":"Changelog","text":""},{"location":"CHANGELOG/#unreleased-changes-2024-08-12","title":"Unreleased changes (2024-08-12)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Migrate to pydantic v2 #433</li> <li>Move to use flit build system #418</li> <li>Use callable workflows for CI/CD #391</li> </ul> <p>Fixed bugs:</p> <ul> <li>Support latest <code>pytest-asyncio</code> #447</li> <li>Wrong key used for ignore rules in CI job #423</li> <li>Revert update of codecov-action from v4 to v3 #405</li> <li><code>pre-commit</code> issue for the mypy hook #385</li> <li>Update docs config #366</li> </ul> <p>Closed issues:</p> <ul> <li>Upgrade to ruff #417</li> <li>Remove usage of permanent dependencies branch #411</li> <li>Python 3.8 support is being dropped in dependencies #387</li> <li>Don't use GITHUB_TOKEN for changelog CI steps #368</li> </ul> <p>Merged pull requests:</p> <ul> <li>[pre-commit.ci] pre-commit autoupdate #511 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #510 (pre-commit-ci[bot])</li> <li>Bump SINTEF/ci-cd from 2.7.4 to 2.8.0 in the actions group #509 (dependabot[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #508 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #507 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #506 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #505 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #504 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #503 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #502 (pre-commit-ci[bot])</li> <li>Set port as an env var #501 (CasperWA)</li> <li>Rejig Dockerfiles's CMD #500 (CasperWA)</li> <li>Deploy on fly.io #499 (CasperWA)</li> <li>[pre-commit.ci] pre-commit autoupdate #498 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #497 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #496 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #495 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #494 (pre-commit-ci[bot])</li> <li>[pre-commit.ci] pre-commit autoupdate #493 (pre-commit-ci[bot])</li> <li>Remove all CI/CD to do with the permanent dep branch #491 (CasperWA)</li> <li>Update to pytest-asyncio v0.23 #490 (CasperWA)</li> <li>Update mkdocstrings[python] requirement from ~=0.24.3 to ~=0.25.0 #488 (dependabot[bot])</li> <li>[Auto-generated] Update dependencies #487 (CasperWA)</li> <li>[Auto-generated] Update dependencies #485 (CasperWA)</li> <li>[Auto-generated] Update dependencies #484 (CasperWA)</li> <li>[Auto-generated] Update dependencies #482 (CasperWA)</li> <li>[Auto-generated] Update dependencies #480 (CasperWA)</li> <li>[Auto-generated] Update dependencies #478 (CasperWA)</li> <li>[Auto-generated] Update dependencies #476 (CasperWA)</li> <li>[Auto-generated] Update dependencies #475 (CasperWA)</li> <li>[Auto-generated] Update dependencies #472 (CasperWA)</li> <li>[Auto-generated] Update dependencies #469 (CasperWA)</li> <li>[Auto-generated] Update dependencies #466 (CasperWA)</li> <li>[Auto-generated] Update dependencies #464 (CasperWA)</li> <li>[Auto-generated] Update dependencies #463 (CasperWA)</li> <li>[Auto-generated] Update dependencies #459 (CasperWA)</li> <li>[Auto-generated] Update dependencies #456 (CasperWA)</li> <li>[Auto-generated] Update dependencies #455 (CasperWA)</li> <li>[Auto-generated] Update dependencies #451 (CasperWA)</li> <li>[Auto-generated] Update dependencies #449 (CasperWA)</li> <li>[Auto-generated] Update dependencies #448 (CasperWA)</li> <li>Migrate to pydantic v2 #446 (CasperWA)</li> <li>[Auto-generated] Update dependencies #441 (CasperWA)</li> <li>[Auto-generated] Update dependencies #439 (CasperWA)</li> <li>[Auto-generated] Update dependencies #438 (CasperWA)</li> <li>Bump SINTEF/ci-cd from 2.5.3 to 2.6.0 #437 (dependabot[bot])</li> <li>Update pytest-httpx requirement from ~=0.26.0 to ~=0.27.0 #436 (dependabot[bot])</li> <li>Update mkdocstrings[python-legacy] requirement from ~=0.23.0 to ~=0.24.0 #435 (dependabot[bot])</li> <li>[Auto-generated] Update dependencies #434 (CasperWA)</li> <li>[Auto-generated] Update dependencies #431 (CasperWA)</li> <li>[Auto-generated] Check &amp; update dependencies (<code>pyproject.toml</code>) #430 (CasperWA)</li> <li>[Auto-generated] Update dependencies #428 (CasperWA)</li> <li>[Auto-generated] Update dependencies #426 (CasperWA)</li> <li>Fix key in ignore rule for CI Check deps #424 (CasperWA)</li> <li>[Auto-generated] Update dependencies #422 (CasperWA)</li> <li>Use ruff as the Python linter #420 (CasperWA)</li> <li>Update build system to flit #419 (CasperWA)</li> <li>[Auto-generated] Update dependencies #416 (CasperWA)</li> <li>[Auto-generated] Update dependencies #413 (CasperWA)</li> <li>[Auto-generated] Update dependencies #410 (CasperWA)</li> <li>[Auto-generated] Update dependencies #407 (CasperWA)</li> <li>[Auto-generated] Update dependencies #399 (CasperWA)</li> <li>[Auto-generated] Update dependencies #397 (CasperWA)</li> <li>[Auto-generated] Update dependencies #393 (CasperWA)</li> <li>Use callable workflows for CI/CD #392 (CasperWA)</li> <li>Split dependency version ranges according to Py3.8 support #388 (CasperWA)</li> <li>Update hooks and use pydantic\\&lt;2 for mypy #386 (CasperWA)</li> <li>Update dependencies #378 (CasperWA)</li> <li>Update dependencies #372 (CasperWA)</li> <li>Use PAT instead of GITHUB_TOKEN for changelog steps #369 (CasperWA)</li> <li>Update mkdocs config #367 (CasperWA)</li> <li>Update dependencies #365 (CasperWA)</li> <li>Update dependencies #361 (CasperWA)</li> <li>Update dependencies #359 (CasperWA)</li> <li>Update dependencies #354 (CasperWA)</li> <li>Update dependencies #351 (CasperWA)</li> <li>Update dependencies #348 (CasperWA)</li> <li>Update dependencies #347 (CasperWA)</li> <li>Update dependencies #342 (CasperWA)</li> <li>Update dependencies #339 (CasperWA)</li> <li>Update dependencies #336 (CasperWA)</li> <li>Update dependencies #335 (CasperWA)</li> <li>Update dependencies #333 (CasperWA)</li> <li>Update dependencies #321 (CasperWA)</li> <li>Update dependencies #319 (CasperWA)</li> <li>Update dependencies #318 (CasperWA)</li> <li>Update dependencies #314 (CasperWA)</li> <li>Update dependencies #311 (CasperWA)</li> <li>Update dependencies #307 (CasperWA)</li> <li>Update dependencies #306 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v040-2022-09-28","title":"v0.4.0 (2022-09-28)","text":"<p>Full Changelog</p> <p>Merged pull requests:</p> <ul> <li>Update dependencies #301 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v030-2022-09-19","title":"v0.3.0 (2022-09-19)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>FastAPI safety issues #281</li> <li>pylint rules seems to be stricter #253</li> <li>Fix type for auto-merge workflow #238</li> <li>Pushing in automerge CI workflow not working #179</li> <li>Auto-merge CD workflow not working #177</li> <li>Resetting <code>ci/dependabot-updates</code> branch failing #174</li> <li>Single dependabot PR workflow failing #167</li> <li>Update mcdb name #296 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>More verbose in <code>main</code> push CI job #184</li> <li>Add <code>pre-commit</code> hooks autoupdate to CI #183</li> </ul> <p>Merged pull requests:</p> <ul> <li>Update dependencies #300 (CasperWA)</li> <li>Update dependencies #298 (CasperWA)</li> <li>Update dependencies #293 (CasperWA)</li> <li>Update dependencies #290 (CasperWA)</li> <li>Update dependencies #288 (CasperWA)</li> <li>Update dependencies #286 (CasperWA)</li> <li>Update dependencies #285 (CasperWA)</li> <li>Update dependencies #282 (CasperWA)</li> <li>Remove no-self-use disables #280 (CasperWA)</li> <li>Update dependencies #277 (CasperWA)</li> <li>Update dependencies #271 (CasperWA)</li> <li>Update dependencies #269 (CasperWA)</li> <li>Update dependencies #267 (CasperWA)</li> <li>Update dependencies #264 (CasperWA)</li> <li>Update dependencies #262 (CasperWA)</li> <li>Update dependencies #261 (CasperWA)</li> <li>Update dependencies #258 (CasperWA)</li> <li>Update dependencies #250 (CasperWA)</li> <li>Update dependencies #248 (CasperWA)</li> <li>Update dependencies #246 (CasperWA)</li> <li>Update dependencies #242 (CasperWA)</li> <li>Use <code>ID!</code> type instead of <code>String!</code> #239 (CasperWA)</li> <li>Update dependencies #237 (CasperWA)</li> <li>Update dependencies #235 (CasperWA)</li> <li>Update dependencies #232 (CasperWA)</li> <li>Update dependencies #227 (CasperWA)</li> <li>Update dependencies #223 (CasperWA)</li> <li>Update dependencies #219 (CasperWA)</li> <li>Update dependencies #217 (CasperWA)</li> <li>Update dependencies #210 (CasperWA)</li> <li>Update dependencies #209 (CasperWA)</li> <li>Update dependencies #207 (CasperWA)</li> <li>Update dependencies #205 (CasperWA)</li> <li>Update dependencies #202 (CasperWA)</li> <li>Update dependencies #198 (CasperWA)</li> <li>Update dependencies #197 (CasperWA)</li> <li>Update dependencies #196 (CasperWA)</li> <li>Be more verbose in CI/CD workflows #191 (CasperWA)</li> <li>Update <code>pre-commit</code> hooks in dependabot CI #186 (CasperWA)</li> <li>Update dependencies #182 (CasperWA)</li> <li>Use PAT for pushing to activate CI jobs #181 (CasperWA)</li> <li>Use push action for pushing to dependabot branch #180 (CasperWA)</li> <li>Use <code>ref</code> instead of <code>sha</code> #178 (CasperWA)</li> <li>Update dependencies #173 (CasperWA)</li> <li>Wrap def in quotations and change to single quote #168 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v022-2021-10-05","title":"v0.2.2 (2021-10-05)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>Fix auto-merge workflow to actually run #165</li> <li>Reset <code>ci/dependabot-updates</code> after merging <code>ci/update-dependencies</code> #131</li> </ul> <p>Closed issues:</p> <ul> <li>Activate auto-merge for Dependabot PRs #162</li> <li>Move automatic <code>ci/update-dependencies</code> PR to Tuesday or Friday #160</li> </ul> <p>Merged pull requests:</p> <ul> <li>Move check for dependabot head branch to job #166 (CasperWA)</li> <li>New auto-merge CI for dependabot PRs #163 (CasperWA)</li> <li>Reset <code>ci/dependabot-updates</code> branch upon merge to <code>main</code> #161 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v021-2021-10-04","title":"v0.2.1 (2021-10-04)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Run keep-up-to-date workflow immediately with push #140</li> <li>Update to versioned documentation #132</li> <li>Use <code>bandit</code>, <code>pylint</code>, <code>safety</code>, and <code>mypy</code> #119 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>GH Release action overwrites release description #155</li> <li>Fix condition in <code>main</code> docs deployment #152</li> <li>Properly authenticate the use of <code>gh api</code> in workflow #150</li> <li>Double documentation deploy during release #145</li> <li>Allow beta/alpha releases #143</li> <li>Use protected-push action for keep-up-to-date workflow #138</li> <li>Workflow not working #133</li> <li>Attempt with fetch-depth 0 #154 (CasperWA)</li> <li>Set git config before <code>mike deploy</code> #144 (CasperWA)</li> <li>Use <code>git push</code> instead of action #136 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>Update cron timings for dependency workflows #147</li> <li>Use <code>gh-pages</code> in documentation deploy workflows #142</li> </ul> <p>Merged pull requests:</p> <ul> <li>Update dependencies #159 (CasperWA)</li> <li>Deploy docs to <code>gh-pages</code> branch #157 (CasperWA)</li> <li>Use GH CLI instead of release action #156 (CasperWA)</li> <li>Fix conditional docs <code>main</code> build #153 (CasperWA)</li> <li>Add GITHUB_TOKEN env var to authenticate gh CLI #151 (CasperWA)</li> <li>Fix double docs deployment on release #149 (CasperWA)</li> <li>Update cron times #148 (CasperWA)</li> <li>Update dependencies #146 (CasperWA)</li> <li>Run up-to-date workflow immediately upon push #141 (CasperWA)</li> <li>Push via CasperWA/push-protected action #139 (CasperWA)</li> <li>Use versioned documentation #137 (CasperWA)</li> <li>Fetch everything and ensure correct checkout #135 (CasperWA)</li> <li>Attempt to fix workflow #134 (CasperWA)</li> <li>Run dependabot workflow more often #130 (CasperWA)</li> <li>Only update permanent dependabot branch after CI #127 (CasperWA)</li> <li>Don't use <code>env</code> outside of usable scope #126 (CasperWA)</li> <li>Setup dependabot automation #125 (CasperWA)</li> <li>Don't load providers on startup by default #121 (CasperWA)</li> <li>Update pylint requirement from ~=2.10 to ~=2.11 #120 (dependabot[bot])</li> </ul>"},{"location":"CHANGELOG/#v020-2021-09-07","title":"v0.2.0 (2021-09-07)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Minor re-design #82 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>Fix CD - remnants from #82 #117</li> </ul> <p>Merged pull requests:</p> <ul> <li>Remove references to docker_config.json #118 (CasperWA)</li> <li>Return to major version tags (where available) for GH Actions #114 (CasperWA)</li> <li>Update dependencies #112 (CasperWA)</li> <li>Update pytest-httpx requirement from ~=0.12.0 to ~=0.12.1 #108 (dependabot[bot])</li> <li>Update dependencies #107 (CasperWA)</li> <li>Update dependencies &amp; GH Actions #104 (CasperWA)</li> <li>Update dependencies and GH Actions #99 (CasperWA)</li> <li>Update dependencies #96 (CasperWA)</li> <li>Bump codecov/codecov-action from 1.5.0 to 1.5.2 #83 (dependabot[bot])</li> <li>Update dependencies + GH Actions #81 (CasperWA)</li> <li>Update optimade[server] requirement from ~=0.14.0 to ~=0.15.0 #79 (dependabot[bot])</li> <li>Bump mkdocs-material from 7.1.3 to 7.1.4 #67 (dependabot[bot])</li> <li>Update auto-changelog-action to v1.4 #65 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v012-2021-05-01","title":"v0.1.2 (2021-05-01)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>CD is still wrong #63</li> </ul> <p>Merged pull requests:</p> <ul> <li>Fix tag version retrieval #64 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v011-2021-05-01","title":"v0.1.1 (2021-05-01)","text":"<p>Full Changelog</p> <p>Fixed bugs:</p> <ul> <li>CD workflow not releasing latest documentation build #61</li> </ul> <p>Merged pull requests:</p> <ul> <li>Use ref variable for actions/checkout #62 (CasperWA)</li> </ul>"},{"location":"CHANGELOG/#v010-2021-05-01","title":"v0.1.0 (2021-05-01)","text":"<p>Full Changelog</p> <p>Implemented enhancements:</p> <ul> <li>Create a /search endpoint #40</li> <li>Sorting #20</li> <li>Add test and update code for creating queries accordingly #38 (CasperWA)</li> <li>Asynchronous queued queries #34 (CasperWA)</li> <li>Add extra endpoints #27 (CasperWA)</li> <li>Versioned base URLs #12 (CasperWA)</li> <li>Dockerfile and docker-compose #11 (CasperWA)</li> <li>Establish /gateways/{id}/structures endpoint #10 (CasperWA)</li> <li>Tests and GET /gateways #7 (CasperWA)</li> </ul> <p>Fixed bugs:</p> <ul> <li>Make tests more loose for model assertion #24 (CasperWA)</li> </ul> <p>Closed issues:</p> <ul> <li>Documentation #53</li> <li>Setup mock implementations for testing the gateway #32</li> <li>Finalize the APIs - Determine fate of CLI #16</li> <li>Further abstract and modularize the code #15</li> <li>Update docker CI job #13</li> <li>Don't use GH version of optimade package #8</li> </ul> <p>Merged pull requests:</p> <ul> <li>Change to v0.1.0-rc.1 #60 (CasperWA)</li> <li>Don't sort for external DB requests #59 (CasperWA)</li> <li>Update dependencies #58 (CasperWA)</li> <li>Create documentation site #54 (CasperWA)</li> <li>Update dependencies #52 (CasperWA)</li> <li>Implement /databases for registering and handling known OPTIMADE databases #49 (CasperWA)</li> <li>Change epfl-theos -&gt; Materials-Consortia &amp; update codecov CI step #48 (CasperWA)</li> <li>Update pytest-asyncio requirement from ~=0.14.0 to ~=0.15.0 #47 (dependabot[bot])</li> <li>Add license, copyright and funding information #46 (CasperWA)</li> <li>Update dependencies #45 (CasperWA)</li> <li>Set up the /search endpoint #41 (CasperWA)</li> <li>Use pytest-httpx to mock external responses #39 (CasperWA)</li> <li>Update optimade requirement from ~=0.13.3 to ~=0.14.0 #37 (dependabot[bot])</li> <li>Update httpx requirement from ~=0.17.0 to ~=0.17.1 #36 (dependabot[bot])</li> <li>Use latest MongoDB v4 (v4.4) #33 (CasperWA)</li> <li>Update dependencies #31 (CasperWA)</li> <li>Update httpx requirement from ~=0.16.1 to ~=0.17.0 #28 (dependabot[bot])</li> <li>Update dependencies #26 (CasperWA)</li> <li>Update optimade and docker CI job #14 (CasperWA)</li> <li>Various updates #9 (CasperWA)</li> <li>Update dependencies #6 (CasperWA)</li> </ul> <p>* This Changelog was automatically generated by github_changelog_generator</p>"},{"location":"LICENSE/","title":"License","text":"<p>MIT License</p> <p>Copyright (c) 2021 Casper Welzel Andersen &amp; THEOS, EPFL</p> <p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p> <p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p> <p>THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>"},{"location":"design/","title":"Design of the OPTIMADE gateway","text":"<p>The OPTIMADE gateway is intended to be implemented into the MarketPlace platform. Therefore, it should implement the MarketPlace Data Source API, as well as endpoints needed for the gateway capabilities themselves. To this end, the following sections defines/recaps these APIs and capabilities.</p>"},{"location":"design/#marketplace-data-source-api","title":"MarketPlace Data Source API","text":"<p>The MarketPlace Data Source API developed in T2.2 of the MarketPlace project. It can be found on the Fraunhofer GitLab here.</p> <p>Outline of the currently defined endpoints. Note, if there is no HTTP method next to the endpoint, it is not an available and reachable endpoint.</p> <p><code>/marketplace/</code></p> <ul> <li> <p><code>/schemas/</code> (<code>GET</code>)</p> </li> <li> <p><code>/{schema_id}/</code></p> <ul> <li><code>/attributes</code> (<code>GET</code>)</li> <li><code>/export</code> (<code>POST</code>)</li> <li><code>/search</code> (<code>POST</code>)</li> </ul> </li> </ul>"},{"location":"design/#optimade-gateway-api","title":"OPTIMADE gateway API","text":"<p>The suggested OPTIMADE gateway API.</p> <p>This API is based on the expected capabilities outlined below.</p> <p><code>/optimade/</code> Methods: <code>GET</code> Behavior: Introspective/static metadata overview of server.</p> <ul> <li> <p><code>/query/</code> Methods: <code>POST</code> or <code>GET</code> Behavior: Orchestrate an OPTIMADE query.</p> </li> <li> <p><code>/gateways/</code> Methods: <code>GET</code> Behavior: Standard reponse: Introspective/static metadata overview of all gateways. Using special query parameter: Create/retrieve and return unique gateway ID.</p> </li> <li> <p><code>/{gateway_id}/</code> Methods: <code>POST</code> or <code>GET</code> Behavior: Create/retrieve search ID and return unique search ID.     Start asynchronous search task.</p> <p>Either:</p> <ul> <li> <p><code>/queries/</code> Methods: None Behavior: Disallowed. Note: This endpoint could support <code>GET</code> requests with similar functionality and behavior as for <code>/gateways/</code>?   This would move some functionality away from <code>/{gateway_id}/</code> to this endpoint.   Making <code>/{gateway_id}/</code> act as a mix of <code>/query/</code> and <code>/gateways/</code> in terms of orchestrating the search and returning introspective/static metadata about the gateway.</p> </li> <li> <p><code>/{search_id}/</code> Methods: <code>GET</code> Behavior: Return current results according to state of asynchronous search task.</p> </li> </ul> <p>or:</p> <ul> <li><code>/{search_id}/</code> Methods: <code>GET</code> Behavior: Return current results according to state of asynchronous search task.</li> </ul> </li> </ul>"},{"location":"design/#optimade-gateway-capabilities","title":"OPTIMADE gateway capabilities","text":"<ul> <li>Searching in multiple OPTIMADE databases.</li> <li>Utilize the OPTIMADE filter language.</li> <li>Retrieve entries (OPTIMADE structures) as JSON-serialized CUDS.   Not a required capability for the base gateway API.</li> </ul>"},{"location":"design/#design-ideas-and-comments-by-simon-adorf-csadorf","title":"Design ideas and comments by Simon Adorf (@csadorf)","text":"<p>I think the way you would achieve the \u201cselection\u201d of databases is by creating provider-specific endpoints like this:</p> <pre><code>GET\n/gateway?providers=abc,def,xyz\n</code></pre> <p>This will return a deterministic gateway id related to specific set of providers, which you will then use for further queries like this:</p> <pre><code>GET\n/gateway/{gateway_id}/structures/\n</code></pre> <p>etc.</p> <p>The gateway id would provide introspection, so <code>/gateway/{gateway_id}</code> returns some information about the gateway (supported OPTIMADE API, list of providers) etc. You would cache the gateway id in the client, so you don\u2019t have to make two requests for each query. If you don\u2019t provide a list of providers, the current default set is used. But this ensures that the REST API is actually stateless, because one gateway is always tied to a specific set of providers even if the default list is changed. Obviously, if you use a gateway that includes providers that are no longer available you would respond with code 503 or so.</p> <p>This design solves the issue of how to provide a gateway that implements the OPTIMADE API and allows for the selection of providers. I assume your results are paginated, so IMO \u2014 unless you request a specific order \u2014 you should just return results as they come in. You need to implement this gateway asynchronously anyways so it really does not matter whether you include slow providers or not.</p> <p>Of course, this changes if the user requests a specific order, but that\u2019s just how it is. From a user perspective it would make sense to me that such a query across multiple providers may take a while.</p> <p>You should definitely define a timeout for each gateway where if a provider does not respond by then, the result is returned regardless of whether the provider has responded. Or you respond with a time out code.</p>"},{"location":"design/#searching","title":"Searching","text":"<p>Taking Simon's comments into account, the search capability should be:</p> <ul> <li>Asynchronous; and</li> <li>Dynamic.</li> </ul> <p>The asynchronicity comes from creating web calls (possibly using CORS) to each (chosen) database asynchronously, collating the results in a single (gateway) endpoint.</p> <p>The dynamics here relate to the suggested dynamic creation (and possible deletion) of gateway IDs under a <code>/gateway</code>-endpoint.</p>"},{"location":"design/#get-requests","title":"GET requests","text":"<p>Essentially, for each search, a new gateway will be created (if needed) with a unique ID. This unique ID will constitue the content of the initial response after performing a search, so that the user can go to the new gateway ID-specific endpoint to retrieve the results. To make this easier for the user, the server could automatically redirect the user after creating the endpoint. Here the response will contain the currently retrieved results as well as som metadata information about how the search is going and a general overview.</p> <p>This would ideally result in the following search sequence:</p> <p></p> <p>The final <code>GET</code> request can be repeated to retrieve more results during the timeline of the search happening, and to retrieve the final list of results in a set time period after the search has finished.</p>"},{"location":"design/#post-requests","title":"POST requests","text":"<p>One could also think of using <code>POST</code> requests instead, containing the OPTIMADE query parameters alongside with other information, mainly utilized for the <code>/gateway/{unique ID}</code>-endpoints. The response could contain a link or simply redirect to a <code>/gateway/{unique ID}/{search unique ID}</code>-endpoint. The latter part could also be done for the <code>GET</code> approach, since a specific gateway should support multiple unique simultaneous searched. Since the searches are asynchronous, the results don't come back from all resources simultaneously, thus demanding an extra endpoint, where the continuously updating results can be found - as well as the final list of results for a specific search.</p> <p>This differs from the section above, where a <code>GET</code> request should contain query parameters in the URL and this will be correlated with an ongoing (unique) search in the backend, which would potentially allow different users to experience the same loading of results if they performed the same search in the same gateway, even at slightly different times during the searching period.</p> <p>A sequence would ideally look this:</p> <p></p>"},{"location":"design/#conclusion","title":"Conclusion","text":"<p>The best approach here would be to create unique search IDs under each unique gateway, pertaining to a specific search. In the same way that gateways may be reused, search results may be reused. However, to ensure the \"freshness\" of the data, the \"live\"-period for any unique search should be significantly smaller than that of any unique gateway.</p> <p><code>POST</code> requests may be preferred due to the ability of combining OPTIMADE-specific query data and gateway-specific data.</p> <p>Suggested search sequence diagram:</p> <p></p>"},{"location":"design/#design-discussions-17122020","title":"Design discussions (17.12.2020)","text":"<p>To be backwards compatible (where each gateway may represent a fully fledged OPTIMADE database), make <code>/gateways/{unique ID}/</code> redirect to <code>/gateways/{unique ID}/structures/</code>.</p> <p>Note, remove CUDS as a required capability, content negotiation might be with different means than a URL query parameter.</p>"},{"location":"design/#caching","title":"Caching","text":"<p>Caching should be segmented for each database. For each new user query that retrieves and caches individual resources from a database, the lifetime of the cached resource should be updated to the set default (or what is determined by caching headers from the side of the database). Either the CacheControl or requests-cache packages will be utilized for caching.</p> <p>Since the time it takes for an OPTIMADE database to change its content varies, but is mainly quite long, individual search life times (<code>/gateways/{gateway ID}(/queries)/{search ID}/</code>) can be \"long\", e.g., a couple of hours. However, these two ways of \"caching\" should be separate.</p> <p>It should always be possible to forcefully ensure a \"fresh\" search.</p>"},{"location":"design/#optimade-filter-language","title":"OPTIMADE filter language","text":"<p>The filter language will be reused as the filter language for any search in any gateway.</p> <p>The filter language is defined in the OPTIMADE specification.</p>"},{"location":"design/#retrieval-formats","title":"Retrieval formats","text":"<p>All responses will be in JSON (for now).</p> <p>To choose the retrieval format of the structure, a query parameter will be dedicated for the <code>/{search unique ID}</code> endpoint.</p>"},{"location":"design/#optimade","title":"OPTIMADE","text":"<p>The standard OPTIMADE format for defining structures will be reused for listing the structure entries.</p> <p>See the OPTIMADE specification for a list of properties defining the structures entry.</p> <p>When returning the results in this format, the whole response should be compliant with a standard OPTIMADE response as is expected in the <code>/structures</code>-endpoint.</p>"},{"location":"design/#cuds","title":"CUDS","text":"<p>Utilizing the <code>optimade2cuds</code> Python package in the SimOPTIMADE repository on the Fraunhofer GitLab for the MarketPlace project, the resulting OPTIMADE structure can be converted to Python CUDS objects. From there they can be serialized to JSON representations (using the OSP-Core package) and returned as a search result response.</p>"},{"location":"design/#external-api-calls","title":"External API calls","text":"<p>When making external API calls, i.e., requesting the various OPTIMADE databases, this is technically done in a <code>concurrent.futures.ThreadPoolExecutor</code>. This is mainly done to not block the main OS thread, where the asyncio event loop is running. This is the event loop that handles incoming gateway requests. While the number of databases may not be significant, the response times can still vary and by using a <code>ThreadPoolExecutor</code>, the gateway is ready for more heavy use out-of-the-box.</p> <p>Another key reason to use a <code>ThreadPoolExecutor</code> (instead of Starlette's - and therefore FastAPI's - <code>BackgroundTask</code>) is for testing with the <code>pytest</code> framework. When using <code>BackgroundTask</code> the response cannot be properly mocked and instead blocks the main OS thread. Perhaps this could be solved by implementing the same solution as has been done for now, namely running a <code>time.sleep</code> function call in a <code>ThreadPoolExecutor</code>, in the mocked response callback, but the benefits of using a <code>ThreadPoolExecutor</code> also for the actual queries outweigh this in the long run.</p> <p>For further considerations a <code>ProcessPoolExecutor</code> might even be considered, but it shouldn't be necessary as the work done is IO blocking, not CPU blocking. The possible speed-up should not be significant.</p> <p>Further reading and considerations on this subject Multithreading vs. Multiprocessing in Python by Amine Baatout is a good read. Another source of inspiration was found in this StackOverflow post response.</p>"},{"location":"design/#other-ideas-a-queue","title":"Other ideas - a queue","text":"<p>Throughout the process of figuring this out, other ideas were on the table. One was to setup an <code>asyncio.Queue</code> - either a single \"unbuffered channel\" queue for the whole lifetime of the server, or one each per request. This would effectively split up the <code>perform_query</code> in producer/worker functions.</p> <p>For some nice reading on this, check out Latency in Asynchronous Python by Chris Wellons (null program).</p> <p>Since the <code>ThreadPoolExecutor</code> solution solves the issue of the analogous \"heartbeat\" function not losing its responsivenes, i.e., the asyncio event loop not being blocked, and it would work with the current code implementation, I opted for this solution instead. But I recon a queue solution would work similarly, but perhaps with slightly less gateway API responsiveness during heavy load, since it all still runs in the same event loop.</p>"},{"location":"api_reference/events/","title":"events","text":"<p>ASGI app events.</p> <p>These events can be run at application startup or shutdown. The specific events are listed in <code>EVENTS</code> along with their respected proper invocation time.</p>"},{"location":"api_reference/events/#optimade_gateway.events.EVENTS","title":"<code>EVENTS: Sequence[tuple[str, Callable[[], Coroutine[Any, Any, None]]]] = (('startup', ci_dev_startup), ('startup', load_optimade_providers_databases))</code>  <code>module-attribute</code>","text":"<p>A tuple of all pairs of events and event functions.</p> <p>To use this tuple of tuples:</p> <pre><code>from fastapi import FastAPI\nAPP = FastAPI()\nfor event, func in EVENTS:\n    APP.add_event_handler(event, func)\n</code></pre>"},{"location":"api_reference/events/#optimade_gateway.events.ci_dev_startup","title":"<code>ci_dev_startup()</code>  <code>async</code>","text":"<p>Function to run at app startup - only relevant for CI or development to add test data.</p> Source code in <code>optimade_gateway/events.py</code> <pre><code>async def ci_dev_startup() -&gt; None:\n    \"\"\"Function to run at app startup - only relevant for CI or development to add test\n    data.\"\"\"\n    if bool(os.getenv(\"CI\", \"\")):\n        LOGGER.info(\n            \"CI detected - Will load test gateways (after dropping the collection)!\"\n        )\n    elif os.getenv(\"OPTIMADE_MONGO_DATABASE\", \"\") == \"optimade_gateway_dev\":\n        LOGGER.info(\n            \"Running in development mode - Will load test gateways (after dropping the\"\n            \" collection)!\"\n        )\n    else:\n        LOGGER.debug(\"Not in CI or development mode - will start normally.\")\n        return\n\n    # Add test gateways\n    import json\n    from pathlib import Path\n\n    from optimade_gateway.mongo.database import MONGO_DB\n\n    test_data = (\n        Path(__file__).parent.parent.joinpath(\".ci/test_gateways.json\").resolve()\n    )\n\n    await MONGO_DB[CONFIG.gateways_collection].drop()\n\n    if await MONGO_DB[CONFIG.gateways_collection].count_documents({}) != 0:\n        raise RuntimeError(\n            f\"Unexpectedly found documents in the {CONFIG.gateways_collection!r} Mongo\"\n            \" collection after dropping it ! Found number of documents: \"\n            f\"{await MONGO_DB[CONFIG.gateways_collection].count_documents({})}\"\n        )\n\n    if not test_data.exists():\n        raise FileNotFoundError(\n            f\"Could not find test data file with test gateways at {test_data} !\"\n        )\n\n    data = json.loads(test_data.read_bytes())\n\n    await MONGO_DB[CONFIG.gateways_collection].insert_many(data)\n</code></pre>"},{"location":"api_reference/events/#optimade_gateway.events.load_optimade_providers_databases","title":"<code>load_optimade_providers_databases()</code>  <code>async</code>","text":"<p>Load in the providers' OPTIMADE databases from Materials-Consortia</p> <p>Utilize the Materials-Consortia list of OPTIMADE providers at https://providers.optimade.org. Load in all databases with a valid base URL.</p> Source code in <code>optimade_gateway/events.py</code> <pre><code>async def load_optimade_providers_databases() -&gt; None:\n    \"\"\"Load in the providers' OPTIMADE databases from Materials-Consortia\n\n    Utilize the Materials-Consortia list of OPTIMADE providers at\n    [https://providers.optimade.org](https://providers.optimade.org).\n    Load in all databases with a valid base URL.\n    \"\"\"\n    import asyncio\n\n    import httpx\n    from optimade import __api_version__\n    from optimade.models import LinksResponse\n    from optimade.models.links import LinkType\n    from optimade.server.routers.utils import BASE_URL_PREFIXES\n\n    from optimade_gateway.common.utils import clean_python_types, get_resource_attribute\n    from optimade_gateway.models.databases import DatabaseCreate\n    from optimade_gateway.queries.perform import db_get_all_resources\n    from optimade_gateway.routers.utils import resource_factory\n\n    if not CONFIG.load_optimade_providers_databases:\n        LOGGER.debug(\n            \"Will not load databases from Materials-Consortia list of providers.\"\n        )\n        return\n\n    if TYPE_CHECKING or bool(os.getenv(\"MKDOCS_BUILD\", \"\")):  # pragma: no cover\n        providers: httpx.Response | LinksResponse\n\n    async with httpx.AsyncClient() as client:\n        providers = await client.get(\n            \"https://providers.optimade.org/v\"\n            f\"{__api_version__.split('.', maxsplit=1)[0]}/links\"\n        )\n\n    if providers.is_error:\n        LOGGER.warning(\n            \"Response from Materials-Consortia's list of OPTIMADE providers was not \"\n            \"successful (status code != 200). No databases will therefore be added at \"\n            \"server startup.\"\n        )\n        return\n\n    LOGGER.info(\n        \"Registering Materials-Consortia list of OPTIMADE providers' databases.\"\n    )\n\n    providers = LinksResponse(**providers.json())\n\n    valid_providers = []\n    for provider in providers.data:\n        if get_resource_attribute(provider, \"id\") in (\"exmpl\", \"optimade\"):\n            LOGGER.info(\n                \"- %s (id=%r) - Skipping: Not a real provider.\",\n                get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(provider, \"id\"),\n            )\n            continue\n\n        if not get_resource_attribute(provider, \"attributes.base_url\"):\n            LOGGER.info(\n                \"- %s (id=%r) - Skipping: No base URL information.\",\n                get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(provider, \"id\"),\n            )\n            continue\n\n        valid_providers.append(provider)\n\n    # Run queries to each database using the supported major versioned base URL to get a\n    # list of the provider's databases.\n    # There is no need to use ThreadPoolExecutor here, since we want this to block\n    # everything and then finish, before the server actually starts up.\n    provider_queries = [\n        asyncio.create_task(\n            db_get_all_resources(\n                database=provider,\n                endpoint=\"links\",\n                response_model=LinksResponse,\n            )\n        )\n        for provider in valid_providers\n    ]\n\n    for query in asyncio.as_completed(provider_queries):\n        provider_databases, provider = await query\n\n        LOGGER.info(\n            \"- %s (id=%r) - Processing\",\n            get_resource_attribute(provider, \"attributes.name\", \"N/A\"),\n            get_resource_attribute(provider, \"id\"),\n        )\n        if not provider_databases:\n            LOGGER.info(\"  - No OPTIMADE databases found.\")\n            continue\n\n        provider_databases = [\n            db\n            for db in provider_databases\n            if await clean_python_types(\n                get_resource_attribute(db, \"attributes.link_type\", \"\")\n            )\n            == LinkType.CHILD.value\n        ]\n\n        if not provider_databases:\n            LOGGER.info(\"  - No OPTIMADE databases found.\")\n            continue\n\n        for database in provider_databases:\n            if not get_resource_attribute(database, \"attributes.base_url\"):\n                LOGGER.info(\n                    \"  - %s (id=%r) - Skipping: No base URL information.\",\n                    get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                    get_resource_attribute(database, \"id\"),\n                )\n                continue\n\n            LOGGER.info(\n                \"  - %s (id=%r) - Checking versioned base URL and /structures\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n            )\n\n            async with httpx.AsyncClient() as client:\n                try:\n                    db_response = await client.get(\n                        f\"{str(get_resource_attribute(database, 'attributes.base_url')).rstrip('/')}\"  # noqa: E501\n                        f\"{BASE_URL_PREFIXES['major']}/structures\",\n                    )\n                except httpx.ReadTimeout:\n                    LOGGER.info(\n                        \"  - %s (id=%r) - Skipping: Timeout while requesting \"\n                        \"%s/structures.\",\n                        get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                        get_resource_attribute(database, \"id\"),\n                        BASE_URL_PREFIXES[\"major\"],\n                    )\n                    continue\n            if db_response.status_code != 200:\n                LOGGER.info(\n                    \"  - %s (id=%r) - Skipping: Response from %s/structures is not \"\n                    \"200 OK.\",\n                    get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                    get_resource_attribute(database, \"id\"),\n                    BASE_URL_PREFIXES[\"major\"],\n                )\n                continue\n\n            new_id = (\n                f\"{get_resource_attribute(provider, 'id')}\"\n                f\"/{get_resource_attribute(database, 'id')}\"\n                if len(provider_databases) &gt; 1\n                else get_resource_attribute(database, \"id\")\n            )\n            registered_database, _ = await resource_factory(\n                DatabaseCreate(\n                    id=new_id,\n                    **await clean_python_types(\n                        get_resource_attribute(database, \"attributes\", {})\n                    ),\n                )\n            )\n            LOGGER.info(\n                \"  - %s (id=%r) - Registered database with id=%r\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n                registered_database.id,\n            )\n</code></pre>"},{"location":"api_reference/exception_handlers/","title":"exception_handlers","text":"<p>ASGI app exception handlers.</p> <p>These are in addition to the exception handlers available in OPTIMADE Python tools. For more information see https://www.optimade.org/optimade-python-tools/api_reference/server/exception_handlers/.</p>"},{"location":"api_reference/exception_handlers/#optimade_gateway.exception_handlers.request_validation_exception_handler","title":"<code>request_validation_exception_handler(request, exc)</code>  <code>async</code>","text":"<p>Special handler if a <code>RequestValidationError</code> comes from wrong <code>POST</code> data</p> Source code in <code>optimade_gateway/exception_handlers.py</code> <pre><code>async def request_validation_exception_handler(\n    request: Request, exc: RequestValidationError\n) -&gt; JSONResponse:\n    \"\"\"Special handler if a `RequestValidationError` comes from wrong `POST` data\"\"\"\n    status_code = 500\n    if request.method in (\"POST\", \"post\"):\n        status_code = 400\n\n    errors = set()\n    for error in exc.errors():\n        pointer = \"/\" + \"/\".join([str(_) for _ in error[\"loc\"]])\n        source = ErrorSource(pointer=pointer)\n        code = error[\"type\"]\n        detail = error[\"msg\"]\n        errors.add(\n            OptimadeError(\n                detail=detail,\n                status=status_code,\n                title=str(exc.__class__.__name__),\n                source=source,\n                code=code,\n            )\n        )\n\n    return general_exception(request, exc, status_code=status_code, errors=list(errors))\n</code></pre>"},{"location":"api_reference/main/","title":"main","text":"<p>The initialization of the ASGI FastAPI application.</p>"},{"location":"api_reference/main/#optimade_gateway.main.APP","title":"<code>APP = FastAPI(title='OPTIMADE Gateway', description='A gateway server to query multiple OPTIMADE databases.', version=__version__)</code>  <code>module-attribute</code>","text":"<p>The FastAPI ASGI application.</p>"},{"location":"api_reference/main/#optimade_gateway.main.get_root","title":"<code>get_root(request)</code>  <code>async</code>","text":"<p><code>GET /</code></p> <p>Introspective overview of gateway server.</p> <p>Note</p> <p>Temporarily redirecting to <code>GET /docs</code>.</p> Source code in <code>optimade_gateway/main.py</code> <pre><code>@APP.get(\"/\", include_in_schema=False)\nasync def get_root(request: Request) -&gt; RedirectResponse:\n    \"\"\"`GET /`\n\n    Introspective overview of gateway server.\n\n    !!! note\n        Temporarily redirecting to `GET /docs`.\n    \"\"\"\n    return RedirectResponse(\n        request.url.replace(path=f\"{request.url.path.strip('/')}/docs\")\n    )\n</code></pre>"},{"location":"api_reference/middleware/","title":"middleware","text":"<p>ASGI app middleware.</p> <p>These are in addition to the middleware available in OPTIMADE Python tools. For more information see https://www.optimade.org/optimade-python-tools/api_reference/server/middleware/.</p>"},{"location":"api_reference/middleware/#optimade_gateway.middleware.CheckWronglyVersionedBaseUrlsGateways","title":"<code>CheckWronglyVersionedBaseUrlsGateways</code>","text":"<p>               Bases: <code>BaseHTTPMiddleware</code></p> <p>If a non-supported versioned base URL is supplied to a gateway return <code>553 Version Not Supported</code>.</p> Source code in <code>optimade_gateway/middleware.py</code> <pre><code>class CheckWronglyVersionedBaseUrlsGateways(BaseHTTPMiddleware):\n    \"\"\"If a non-supported versioned base URL is supplied to a gateway\n    return `553 Version Not Supported`.\"\"\"\n\n    @staticmethod\n    async def check_url(url: URL):\n        \"\"\"Check URL path for versioned part.\n\n        Parameters:\n            url: A complete `urllib`-parsed raw URL.\n\n        Raises:\n            VersionNotSupported: If the URL represents an OPTIMADE versioned base URL\n                and the version part is not supported by the implementation.\n\n        \"\"\"\n        base_url = get_base_url(url)\n        optimade_path = f\"{url.scheme}://{url.netloc}{url.path}\"[len(base_url) :]\n        match = re.match(\n            r\"^/gateways/[^/\\s]+(?P&lt;version&gt;/v[0-9]+(\\.[0-9]+){0,2}).*\", optimade_path\n        )\n        if (\n            match is not None\n            and match.group(\"version\") not in BASE_URL_PREFIXES.values()\n        ):\n            raise VersionNotSupported(\n                detail=(\n                    f\"The parsed versioned base URL {match.group('version')!r} \"\n                    f\"from {url} is not supported by this implementation. \"\n                    \"Supported versioned base URLs are: \"\n                    f\"{', '.join(BASE_URL_PREFIXES.values())}\"\n                )\n            )\n\n    async def dispatch(self, request: Request, call_next):\n        if request.url.path:\n            await self.check_url(request.url)\n        return await call_next(request)\n</code></pre>"},{"location":"api_reference/middleware/#optimade_gateway.middleware.CheckWronglyVersionedBaseUrlsGateways.check_url","title":"<code>check_url(url)</code>  <code>async</code> <code>staticmethod</code>","text":"<p>Check URL path for versioned part.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>URL</code> <p>A complete <code>urllib</code>-parsed raw URL.</p> required <p>Raises:</p> Type Description <code>VersionNotSupported</code> <p>If the URL represents an OPTIMADE versioned base URL and the version part is not supported by the implementation.</p> Source code in <code>optimade_gateway/middleware.py</code> <pre><code>@staticmethod\nasync def check_url(url: URL):\n    \"\"\"Check URL path for versioned part.\n\n    Parameters:\n        url: A complete `urllib`-parsed raw URL.\n\n    Raises:\n        VersionNotSupported: If the URL represents an OPTIMADE versioned base URL\n            and the version part is not supported by the implementation.\n\n    \"\"\"\n    base_url = get_base_url(url)\n    optimade_path = f\"{url.scheme}://{url.netloc}{url.path}\"[len(base_url) :]\n    match = re.match(\n        r\"^/gateways/[^/\\s]+(?P&lt;version&gt;/v[0-9]+(\\.[0-9]+){0,2}).*\", optimade_path\n    )\n    if (\n        match is not None\n        and match.group(\"version\") not in BASE_URL_PREFIXES.values()\n    ):\n        raise VersionNotSupported(\n            detail=(\n                f\"The parsed versioned base URL {match.group('version')!r} \"\n                f\"from {url} is not supported by this implementation. \"\n                \"Supported versioned base URLs are: \"\n                f\"{', '.join(BASE_URL_PREFIXES.values())}\"\n            )\n        )\n</code></pre>"},{"location":"api_reference/warnings/","title":"warnings","text":"<p>Server warnings.</p> <p>The warnings in this module will all be caught by middleware and added to the response under <code>meta.warnings</code>.</p>"},{"location":"api_reference/warnings/#optimade_gateway.warnings.OptimadeGatewayWarning","title":"<code>OptimadeGatewayWarning</code>","text":"<p>               Bases: <code>OptimadeWarning</code></p> <p>Base Warning for the <code>optimade-gateway</code> package.</p> Source code in <code>optimade_gateway/warnings.py</code> <pre><code>class OptimadeGatewayWarning(OptimadeWarning):\n    \"\"\"Base Warning for the `optimade-gateway` package.\"\"\"\n</code></pre>"},{"location":"api_reference/warnings/#optimade_gateway.warnings.SortNotSupported","title":"<code>SortNotSupported</code>","text":"<p>               Bases: <code>OptimadeGatewayWarning</code></p> <p>Sorting (the <code>sort</code> query parameter) is currently not supported for gateway queries to external OPTIMADE databases. See https://optimade.org/optimade-gateway#sorting for more information.</p> Source code in <code>optimade_gateway/warnings.py</code> <pre><code>class SortNotSupported(OptimadeGatewayWarning):\n    \"\"\"Sorting (the `sort` query parameter) is currently not supported for gateway\n    queries to external OPTIMADE databases. See\n    https://optimade.org/optimade-gateway#sorting for more information.\"\"\"\n</code></pre>"},{"location":"api_reference/common/config/","title":"config","text":"<p>Configuration of the FastAPI server.</p>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig","title":"<code>ServerConfig</code>","text":"<p>               Bases: <code>ServerConfig</code></p> <p>This class stores server config parameters in a way that can be easily extended for new config file types.</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>class ServerConfig(OptimadeServerConfig):\n    \"\"\"This class stores server config parameters in a way that\n    can be easily extended for new config file types.\n\n    \"\"\"\n\n    databases_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/databases` endpoint resources.\",\n        ),\n    ] = \"databases\"\n\n    gateways_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/gateways` endpoint resources.\",\n        ),\n    ] = \"gateways\"\n\n    queries_collection: Annotated[\n        str,\n        Field(\n            description=\"Mongo collection name for `/queries` endpoint resources.\",\n        ),\n    ] = \"queries\"\n\n    load_optimade_providers_databases: Annotated[\n        bool,\n        Field(\n            description=(\n                \"Whether or not to load all valid OPTIMADE providers' databases from \"\n                \"the [Materials-Consortia list of OPTIMADE providers]\"\n                \"(https://providers.optimade.org) on server startup.\"\n            ),\n        ),\n    ] = True\n\n    mongo_certfile: Annotated[\n        Path,\n        Field(\n            description=\"Path to the MongoDB certificate file.\",\n        ),\n    ] = Path(\"/certs/mongodb.pem\")\n\n    mongo_atlas_pem_content: Annotated[\n        SecretStr | None,\n        Field(\n            description=\"PEM content for MongoDB Atlas certificate.\",\n        ),\n    ] = None\n\n    @field_validator(\"mongo_uri\", mode=\"after\")\n    @classmethod\n    def replace_with_env_vars(cls, value: str) -&gt; str:\n        \"\"\"Replace string variables with environment variables, if possible\"\"\"\n        res = value\n        for match in re.finditer(r\"\\{[^{}]+\\}\", value):\n            string_var = match.group()[1:-1]\n            env_var = os.getenv(\n                string_var, os.getenv(string_var.upper(), os.getenv(string_var.lower()))\n            )\n            if env_var is not None:\n                res = res.replace(match.group(), env_var)\n            else:\n                warn(\n                    OptimadeGatewayWarning(\n                        detail=(\n                            \"Could not find an environment variable for \"\n                            f\"{match.group()!r} from mongo_uri: {value}\"\n                        )\n                    )\n                )\n        return res\n\n    @model_validator(mode=\"after\")\n    def write_pem_content_to_file(self) -&gt; ServerConfig:\n        \"\"\"Write the MongoDB Atlas PEM content to a file\"\"\"\n        if self.mongo_atlas_pem_content:\n            self.mongo_certfile.parent.mkdir(parents=True, exist_ok=True)\n            self.mongo_certfile.write_text(\n                self.mongo_atlas_pem_content.get_secret_value()\n            )\n\n        return self\n</code></pre>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig.replace_with_env_vars","title":"<code>replace_with_env_vars(value)</code>  <code>classmethod</code>","text":"<p>Replace string variables with environment variables, if possible</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>@field_validator(\"mongo_uri\", mode=\"after\")\n@classmethod\ndef replace_with_env_vars(cls, value: str) -&gt; str:\n    \"\"\"Replace string variables with environment variables, if possible\"\"\"\n    res = value\n    for match in re.finditer(r\"\\{[^{}]+\\}\", value):\n        string_var = match.group()[1:-1]\n        env_var = os.getenv(\n            string_var, os.getenv(string_var.upper(), os.getenv(string_var.lower()))\n        )\n        if env_var is not None:\n            res = res.replace(match.group(), env_var)\n        else:\n            warn(\n                OptimadeGatewayWarning(\n                    detail=(\n                        \"Could not find an environment variable for \"\n                        f\"{match.group()!r} from mongo_uri: {value}\"\n                    )\n                )\n            )\n    return res\n</code></pre>"},{"location":"api_reference/common/config/#optimade_gateway.common.config.ServerConfig.write_pem_content_to_file","title":"<code>write_pem_content_to_file()</code>","text":"<p>Write the MongoDB Atlas PEM content to a file</p> Source code in <code>optimade_gateway/common/config.py</code> <pre><code>@model_validator(mode=\"after\")\ndef write_pem_content_to_file(self) -&gt; ServerConfig:\n    \"\"\"Write the MongoDB Atlas PEM content to a file\"\"\"\n    if self.mongo_atlas_pem_content:\n        self.mongo_certfile.parent.mkdir(parents=True, exist_ok=True)\n        self.mongo_certfile.write_text(\n            self.mongo_atlas_pem_content.get_secret_value()\n        )\n\n    return self\n</code></pre>"},{"location":"api_reference/common/exceptions/","title":"exceptions","text":"<p>Specific OPTIMADE Gateway Python exceptions.</p>"},{"location":"api_reference/common/exceptions/#optimade_gateway.common.exceptions.OptimadeGatewayError","title":"<code>OptimadeGatewayError</code>","text":"<p>               Bases: <code>Exception</code></p> <p>General OPTIMADE Gateway exception.</p> Source code in <code>optimade_gateway/common/exceptions.py</code> <pre><code>class OptimadeGatewayError(Exception):\n    \"\"\"General OPTIMADE Gateway exception.\"\"\"\n</code></pre>"},{"location":"api_reference/common/logger/","title":"logger","text":"<p>Logging to both file and console</p>"},{"location":"api_reference/common/logger/#optimade_gateway.common.logger.disable_logging","title":"<code>disable_logging()</code>","text":"<p>Temporarily disable logging.</p> <p>Usage:</p> <pre><code>from optimade_gateway.common.logger import disable_logging\n\n# Do stuff, logging to all handlers.\n# ...\nwith disable_logging():\n    # Do stuff, without logging to any handlers.\n    # ...\n# Do stuff, logging to all handlers now re-enabled.\n# ...\n</code></pre> Source code in <code>optimade_gateway/common/logger.py</code> <pre><code>@contextmanager\ndef disable_logging():\n    \"\"\"Temporarily disable logging.\n\n    Usage:\n\n    ```python\n    from optimade_gateway.common.logger import disable_logging\n\n    # Do stuff, logging to all handlers.\n    # ...\n    with disable_logging():\n        # Do stuff, without logging to any handlers.\n        # ...\n    # Do stuff, logging to all handlers now re-enabled.\n    # ...\n    ```\n\n    \"\"\"\n    try:\n        # Disable logging lower than CRITICAL level\n        logging.disable(logging.CRITICAL)\n        yield\n    finally:\n        # Re-enable logging to desired levels\n        logging.disable(logging.NOTSET)\n</code></pre>"},{"location":"api_reference/common/utils/","title":"utils","text":"<p>Common utility functions.</p> <p>These functions may be used in general throughout the OPTIMADE Gateway Python code.</p>"},{"location":"api_reference/common/utils/#optimade_gateway.common.utils.clean_python_types","title":"<code>clean_python_types(data, **dump_kwargs)</code>  <code>async</code>","text":"<p>Turn any types into MongoDB-friendly Python types.</p> <p>Use <code>model_dump()</code> method for Pydantic models. Use <code>value</code> property for Enums. Turn tuples and sets into lists.</p> Source code in <code>optimade_gateway/common/utils.py</code> <pre><code>async def clean_python_types(data: Any, **dump_kwargs: Any) -&gt; Any:\n    \"\"\"Turn any types into MongoDB-friendly Python types.\n\n    Use `model_dump()` method for Pydantic models.\n    Use `value` property for Enums.\n    Turn tuples and sets into lists.\n    \"\"\"\n    if isinstance(data, (list, tuple, set)):\n        res_list = []\n        for datum in data:\n            res_list.append(await clean_python_types(datum, **dump_kwargs))\n        return res_list\n\n    if isinstance(data, dict):\n        res_dict = {}\n        for key in list(data.keys()):\n            res_dict[key] = await clean_python_types(data[key], **dump_kwargs)\n        return res_dict\n\n    if isinstance(data, BaseModel):\n        # Pydantic model\n        return await clean_python_types(data.model_dump(**dump_kwargs))\n\n    if isinstance(data, Enum):\n        return await clean_python_types(data.value, **dump_kwargs)\n\n    if isinstance(data, type):\n        return await clean_python_types(\n            f\"{data.__module__}.{data.__name__}\", **dump_kwargs\n        )\n\n    if isinstance(data, AnyUrl):\n        return await clean_python_types(str(data), **dump_kwargs)\n\n    # Unknown or other basic type, e.g., str, int, etc.\n    return data\n</code></pre>"},{"location":"api_reference/common/utils/#optimade_gateway.common.utils.get_resource_attribute","title":"<code>get_resource_attribute(resource, field, default=None, disambiguate=True)</code>","text":"<p>Return a resource's field's value</p> <p>Get the field value no matter if the resource is a pydantic model or a Python dictionary.</p> <p>Determine ambiguous field values and return them if desired (<code>disambiguate</code>). For example, if <code>\"attributes.base_url\"</code> is requested for a <code>LinksResource</code> it can be either a string, a <code>Link</code> model or a dictionary resembling the <code>Link</code> model.</p> <p>Parameters:</p> Name Type Description Default <code>resource</code> <code>BaseModel | dict[str, Any] | None</code> <p>The resource, from which to get the field value.</p> required <code>field</code> <code>str</code> <p>The resource field. This can be a dot-separated nested field, e.g., <code>\"attributes.base_url\"</code>.</p> required <code>default</code> <code>Any</code> <p>The default value to return if <code>field</code> does not exist.</p> <code>None</code> <code>disambiguate</code> <code>bool</code> <p>Whether or not to \"shortcut\" a field value. For example, for <code>attributes.base_url</code>, if <code>True</code>, this would return the string value or the value of it's <code>\"href\"</code> key.</p> <code>True</code> <p>Returns:</p> Type Description <code>Any</code> <p>The resource's field's value.</p> Source code in <code>optimade_gateway/common/utils.py</code> <pre><code>def get_resource_attribute(\n    resource: BaseModel | dict[str, Any] | None,\n    field: str,\n    default: Any = None,\n    disambiguate: bool = True,\n) -&gt; Any:\n    \"\"\"Return a resource's field's value\n\n    Get the field value no matter if the resource is a pydantic model or a Python\n    dictionary.\n\n    Determine ambiguous field values and return them if desired (`disambiguate`).\n    For example, if\n    [`\"attributes.base_url\"`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes.base_url)\n    is requested for a\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n    it can be either a string, a\n    [`Link`](https://www.optimade.org/optimade-python-tools/api_reference/models/jsonapi/#optimade.models.jsonapi.Link)\n    model or a dictionary resembling the `Link` model.\n\n    Parameters:\n        resource: The resource, from which to get the field value.\n        field: The resource field. This can be a dot-separated nested field, e.g.,\n            `\"attributes.base_url\"`.\n        default: The default value to return if `field` does not exist.\n        disambiguate: Whether or not to \"shortcut\" a field value.\n            For example, for `attributes.base_url`, if `True`, this would return the\n            string value or the value of it's `\"href\"` key.\n\n    Returns:\n        The resource's field's value.\n\n    \"\"\"\n    if isinstance(resource, BaseModel):\n        _get_attr = getattr\n    elif isinstance(resource, dict):\n\n        def _get_attr(mapping: dict, key: str, default: Any) -&gt; Any:  # type: ignore[misc]\n            return mapping.get(key, default)\n\n    elif resource is None:\n        # Allow passing `None`, but simply return `default`\n        return default\n    else:\n        raise TypeError(\n            \"resource must be either a pydantic model or a Python dictionary, it was \"\n            f\"of type {type(resource)!r}\"\n        )\n\n    fields = field.split(\".\")\n    for _ in fields[:-1]:\n        resource = _get_attr(resource, _, {})\n    field = fields[-1]\n    value = _get_attr(resource, field, default)\n\n    if (\n        disambiguate\n        and field in (\"base_url\", \"next\", \"prev\", \"last\", \"first\")\n        and not isinstance(value, (str, AnyUrl))\n    ):\n        value = _get_attr(value, \"href\", default)\n\n    return value\n</code></pre>"},{"location":"api_reference/mappers/base/","title":"base","text":"<p>Base resource mapper.</p> <p>Based on the <code>BaseResourceMapper</code> in OPTIMADE Python tools.</p>"},{"location":"api_reference/mappers/base/#optimade_gateway.mappers.base.BaseResourceMapper","title":"<code>BaseResourceMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p>Generic Resource Mapper that defines and performs the mapping between objects in the database and the resource objects defined by the specification.</p> Note <p>This is a \"wrapped\" sub-class to make certain methods asynchronous.</p> <p>Attributes:</p> Name Type Description <code>ALIASES</code> <p>a tuple of aliases between OPTIMADE field names and the field names in the database , e.g. <code>((\"elements\", \"custom_elements_field\"))</code>.</p> <code>LENGTH_ALIASES</code> <p>a tuple of aliases between a field name and another field that defines its length, to be used when querying, e.g. <code>((\"elements\", \"nelements\"))</code>. e.g. <code>((\"elements\", \"custom_elements_field\"))</code>.</p> <code>ENTRY_RESOURCE_CLASS</code> <p>The entry type that this mapper corresponds to.</p> <code>PROVIDER_FIELDS</code> <p>a tuple of extra field names that this mapper should support when querying with the database prefix.</p> <code>TOP_LEVEL_NON_ATTRIBUTES_FIELDS</code> <p>the set of top-level field names common to all endpoints.</p> <code>SUPPORTED_PREFIXES</code> <p>The set of prefixes registered by this mapper.</p> <code>ALL_ATTRIBUTES</code> <p>The set of attributes defined across the entry resource class and the server configuration.</p> <code>ENTRY_RESOURCE_ATTRIBUTES</code> <p>A dictionary of attributes and their definitions defined by the schema of the entry resource class.</p> <code>ENDPOINT</code> <p>The expected endpoint name for this resource, as defined by the <code>type</code> in the schema of the entry resource class.</p> Source code in <code>optimade_gateway/mappers/base.py</code> <pre><code>class BaseResourceMapper(OptimadeBaseResourceMapper):\n    \"\"\"\n    Generic Resource Mapper that defines and performs the mapping\n    between objects in the database and the resource objects defined by\n    the specification.\n\n    Note:\n        This is a \"wrapped\" sub-class to make certain methods asynchronous.\n\n    Attributes:\n        ALIASES: a tuple of aliases between\n            OPTIMADE field names and the field names in the database ,\n            e.g. `((\"elements\", \"custom_elements_field\"))`.\n        LENGTH_ALIASES: a tuple of aliases between\n            a field name and another field that defines its length, to be used\n            when querying, e.g. `((\"elements\", \"nelements\"))`.\n            e.g. `((\"elements\", \"custom_elements_field\"))`.\n        ENTRY_RESOURCE_CLASS: The entry type that this mapper corresponds to.\n        PROVIDER_FIELDS: a tuple of extra field names that this\n            mapper should support when querying with the database prefix.\n        TOP_LEVEL_NON_ATTRIBUTES_FIELDS: the set of top-level\n            field names common to all endpoints.\n        SUPPORTED_PREFIXES: The set of prefixes registered by this mapper.\n        ALL_ATTRIBUTES: The set of attributes defined across the entry\n            resource class and the server configuration.\n        ENTRY_RESOURCE_ATTRIBUTES: A dictionary of attributes and their definitions\n            defined by the schema of the entry resource class.\n        ENDPOINT: The expected endpoint name for this resource, as defined by\n            the `type` in the schema of the entry resource class.\n\n    \"\"\"\n\n    @classmethod\n    async def adeserialize(\n        cls, results: dict | Iterable[dict]\n    ) -&gt; list[EntryResource] | EntryResource:\n        \"\"\"Asynchronous version of the `deserialize()` class method.\n\n        Parameters:\n            results: A list of or a single dictionary, representing an entry-endpoint\n                resource.\n\n        Returns:\n            The deserialized list of or single pydantic resource model for the input\n            `results`.\n\n        \"\"\"\n        return super().deserialize(results)\n\n    @classmethod\n    def map_back(cls, doc: dict) -&gt; dict:\n        from optimade.server.routers.utils import BASE_URL_PREFIXES\n\n        if \"_id\" in doc:\n            _id = str(doc.pop(\"_id\"))\n            if \"id\" not in doc:\n                doc[\"id\"] = _id\n\n        doc[\"links\"] = {\n            \"self\": AnyUrl(\n                url=(\n                    f\"{CONFIG.base_url.strip('/')}{BASE_URL_PREFIXES['major']}\"\n                    f\"/{cls.ENDPOINT}/{doc['id']}\"\n                ),\n            )\n        }\n        return super().map_back(doc)\n</code></pre>"},{"location":"api_reference/mappers/base/#optimade_gateway.mappers.base.BaseResourceMapper.adeserialize","title":"<code>adeserialize(results)</code>  <code>async</code> <code>classmethod</code>","text":"<p>Asynchronous version of the <code>deserialize()</code> class method.</p> <p>Parameters:</p> Name Type Description Default <code>results</code> <code>dict | Iterable[dict]</code> <p>A list of or a single dictionary, representing an entry-endpoint resource.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource</code> <p>The deserialized list of or single pydantic resource model for the input</p> <code>list[EntryResource] | EntryResource</code> <p><code>results</code>.</p> Source code in <code>optimade_gateway/mappers/base.py</code> <pre><code>@classmethod\nasync def adeserialize(\n    cls, results: dict | Iterable[dict]\n) -&gt; list[EntryResource] | EntryResource:\n    \"\"\"Asynchronous version of the `deserialize()` class method.\n\n    Parameters:\n        results: A list of or a single dictionary, representing an entry-endpoint\n            resource.\n\n    Returns:\n        The deserialized list of or single pydantic resource model for the input\n        `results`.\n\n    \"\"\"\n    return super().deserialize(results)\n</code></pre>"},{"location":"api_reference/mappers/databases/","title":"databases","text":"<p>Resource mapper for resources under <code>/databases</code>.</p> <p>These resources are <code>LinksResource</code>s.</p>"},{"location":"api_reference/mappers/databases/#optimade_gateway.mappers.databases.DatabasesMapper","title":"<code>DatabasesMapper</code>","text":"<p>               Bases: <code>LinksMapper</code></p> <p><code>/databases</code>-endpoint resources mapper.</p> Source code in <code>optimade_gateway/mappers/databases.py</code> <pre><code>class DatabasesMapper(LinksMapper):\n    \"\"\"`/databases`-endpoint resources mapper.\"\"\"\n\n    ENDPOINT = \"databases\"\n</code></pre>"},{"location":"api_reference/mappers/gateways/","title":"gateways","text":"<p>Resource mapper for <code>GatewayResource</code>.</p>"},{"location":"api_reference/mappers/gateways/#optimade_gateway.mappers.gateways.GatewaysMapper","title":"<code>GatewaysMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p><code>GatewayResource</code> mapper.</p> Source code in <code>optimade_gateway/mappers/gateways.py</code> <pre><code>class GatewaysMapper(BaseResourceMapper):\n    \"\"\"[`GatewayResource`][optimade_gateway.models.gateways.GatewayResource] mapper.\"\"\"\n\n    ENDPOINT = \"gateways\"\n    ENTRY_RESOURCE_CLASS = GatewayResource\n</code></pre>"},{"location":"api_reference/mappers/links/","title":"links","text":"<p>Replicate of <code>LinksMapper</code> in OPTIMADE Python tools.</p>"},{"location":"api_reference/mappers/links/#optimade_gateway.mappers.links.LinksMapper","title":"<code>LinksMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p>Replicate of <code>LinksMapper</code> in OPTIMADE Python tools.</p> <p>This is based on the OPTIMADE Gateway <code>BaseResourceMapper</code> however.</p> Source code in <code>optimade_gateway/mappers/links.py</code> <pre><code>class LinksMapper(BaseResourceMapper):\n    \"\"\"Replicate of\n    [`LinksMapper`](https://www.optimade.org/optimade-python-tools/api_reference/server/mappers/links/#optimade.server.mappers.links.LinksMapper)\n    in OPTIMADE Python tools.\n\n    This is based on the OPTIMADE Gateway\n    [`BaseResourceMapper`][optimade_gateway.mappers.base.BaseResourceMapper] however.\n    \"\"\"\n\n    ENDPOINT = \"links\"\n    ENTRY_RESOURCE_CLASS = LinksResource\n\n    @classmethod\n    def map_back(cls, doc: dict) -&gt; dict:\n        type_ = doc.get(\"type\") or \"links\"\n        newdoc = super().map_back(doc)\n        newdoc[\"type\"] = type_\n        return newdoc\n</code></pre>"},{"location":"api_reference/mappers/queries/","title":"queries","text":"<p>Resource mapper for <code>QueryResource</code>.</p>"},{"location":"api_reference/mappers/queries/#optimade_gateway.mappers.queries.QueryMapper","title":"<code>QueryMapper</code>","text":"<p>               Bases: <code>BaseResourceMapper</code></p> <p><code>QueryResource</code> mapper.</p> Source code in <code>optimade_gateway/mappers/queries.py</code> <pre><code>class QueryMapper(BaseResourceMapper):\n    \"\"\"[`QueryResource`][optimade_gateway.models.queries.QueryResource] mapper.\"\"\"\n\n    ENDPOINT = \"queries\"\n    ENTRY_RESOURCE_CLASS = QueryResource\n</code></pre>"},{"location":"api_reference/models/databases/","title":"databases","text":"<p>Pydantic models/schemas for the LinksResource used in /databases</p>"},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate","title":"<code>DatabaseCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>LinksResourceAttributes</code></p> <p>Model for creating new LinksResources representing <code>/databases</code> resources in the MongoDB.</p> <p>Required fields:</p> <ul> <li><code>name</code></li> <li><code>base_url</code></li> </ul> <p>Original required fields for a <code>LinksResourceAttributes</code> model:</p> <ul> <li><code>name</code></li> <li><code>description</code></li> <li><code>link_type</code></li> </ul> Source code in <code>optimade_gateway/models/databases.py</code> <pre><code>class DatabaseCreate(EntryResourceCreate, LinksResourceAttributes):\n    \"\"\"Model for creating new LinksResources representing `/databases` resources in the\n    MongoDB.\n\n    Required fields:\n\n    - `name`\n    - `base_url`\n\n    Original required fields for a\n    [`LinksResourceAttributes`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes)\n    model:\n\n    - `name`\n    - `description`\n    - `link_type`\n\n    \"\"\"\n\n    description: Annotated[\n        str | None,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"description\"].description\n        ),\n    ] = None\n\n    base_url: Annotated[\n        JsonLinkType,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"base_url\"].description\n        ),\n    ]\n\n    homepage: Annotated[\n        JsonLinkType | None,\n        StrictField(\n            description=LinksResourceAttributes.model_fields[\"homepage\"].description,\n        ),\n    ] = None\n\n    link_type: Annotated[\n        LinkType | None,\n        StrictField(\n            title=LinksResourceAttributes.model_fields[\"link_type\"].title,\n            description=LinksResourceAttributes.model_fields[\"link_type\"].description,\n        ),\n    ] = None\n\n    @field_validator(\"link_type\", mode=\"after\")\n    @classmethod\n    def ensure_database_link_type(cls, value: LinkType) -&gt; LinkType:\n        \"\"\"Ensure databases are not index meta-database-only types\n\n        I.e., ensure they're not of type `\"root\"` or `\"providers\"`.\n\n        !!! note\n            Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n            but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n        \"\"\"\n        if value in (LinkType.ROOT, LinkType.PROVIDERS):\n            raise ValueError(\n                \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                f\"gateway-usable database resources. Given link_type: {value}\"\n            )\n        return value\n</code></pre>"},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.base_url","title":"<code>base_url: Annotated[JsonLinkType, StrictField(description=LinksResourceAttributes.model_fields['base_url'].description)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.description","title":"<code>description: Annotated[str | None, StrictField(description=LinksResourceAttributes.model_fields['description'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.homepage","title":"<code>homepage: Annotated[JsonLinkType | None, StrictField(description=LinksResourceAttributes.model_fields['homepage'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.link_type","title":"<code>link_type: Annotated[LinkType | None, StrictField(title=LinksResourceAttributes.model_fields['link_type'].title, description=LinksResourceAttributes.model_fields['link_type'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/databases/#optimade_gateway.models.databases.DatabaseCreate.ensure_database_link_type","title":"<code>ensure_database_link_type(value)</code>  <code>classmethod</code>","text":"<p>Ensure databases are not index meta-database-only types</p> <p>I.e., ensure they're not of type <code>\"root\"</code> or <code>\"providers\"</code>.</p> <p>Note</p> <p>Both <code>\"external\"</code> and <code>\"child\"</code> can still represent index meta-dbs, but <code>\"root\"</code> and <code>\"providers\"</code> can not represent \"regular\" dbs.</p> Source code in <code>optimade_gateway/models/databases.py</code> <pre><code>@field_validator(\"link_type\", mode=\"after\")\n@classmethod\ndef ensure_database_link_type(cls, value: LinkType) -&gt; LinkType:\n    \"\"\"Ensure databases are not index meta-database-only types\n\n    I.e., ensure they're not of type `\"root\"` or `\"providers\"`.\n\n    !!! note\n        Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n        but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n    \"\"\"\n    if value in (LinkType.ROOT, LinkType.PROVIDERS):\n        raise ValueError(\n            \"Databases with 'root' or 'providers' link_type is not allowed for \"\n            f\"gateway-usable database resources. Given link_type: {value}\"\n        )\n    return value\n</code></pre>"},{"location":"api_reference/models/gateways/","title":"gateways","text":"<p>Pydantic models/schemas for the Gateways resource.</p>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate","title":"<code>GatewayCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>GatewayResourceAttributes</code></p> <p>Model for creating new Gateway resources in the MongoDB</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayCreate(EntryResourceCreate, GatewayResourceAttributes):\n    \"\"\"Model for creating new Gateway resources in the MongoDB\"\"\"\n\n    id: Annotated[\n        str | None,\n        OptimadeField(\n            description=EntryResource.model_fields[\"id\"].description,\n            support=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-support\"\n            ],\n            queryable=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-queryable\"\n            ],\n            pattern=r\"^[^/]*$\",  # This pattern is the special addition\n        ),\n    ] = None\n\n    database_ids: Annotated[\n        set[str] | None,\n        Field(description=\"A unique list of database IDs for registered databases.\"),\n    ] = None\n\n    databases: Annotated[\n        list[LinksResource] | None,\n        Field(\n            description=GatewayResourceAttributes.model_fields[\"databases\"].description\n        ),\n    ] = None  # type: ignore[assignment]\n\n    @model_validator(mode=\"after\")\n    def specify_databases(self) -&gt; GatewayCreate:\n        \"\"\"Either `database_ids` or `databases` must be non-empty.\n        Both together is also fine.\n        \"\"\"\n        if not any(getattr(self, field) for field in (\"database_ids\", \"databases\")):\n            raise ValueError(\"Either 'database_ids' or 'databases' MUST be specified\")\n        return self\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.database_ids","title":"<code>database_ids: Annotated[set[str] | None, Field(description='A unique list of database IDs for registered databases.')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.databases","title":"<code>databases: Annotated[list[LinksResource] | None, Field(description=GatewayResourceAttributes.model_fields['databases'].description)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.id","title":"<code>id: Annotated[str | None, OptimadeField(description=EntryResource.model_fields['id'].description, support=EntryResource.model_fields['id'].json_schema_extra['x-optimade-support'], queryable=EntryResource.model_fields['id'].json_schema_extra['x-optimade-queryable'], pattern='^[^/]*$')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayCreate.specify_databases","title":"<code>specify_databases()</code>","text":"<p>Either <code>database_ids</code> or <code>databases</code> must be non-empty. Both together is also fine.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>@model_validator(mode=\"after\")\ndef specify_databases(self) -&gt; GatewayCreate:\n    \"\"\"Either `database_ids` or `databases` must be non-empty.\n    Both together is also fine.\n    \"\"\"\n    if not any(getattr(self, field) for field in (\"database_ids\", \"databases\")):\n        raise ValueError(\"Either 'database_ids' or 'databases' MUST be specified\")\n    return self\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource","title":"<code>GatewayResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>OPTIMADE gateway</p> <p>A resource representing a dynamic collection of OPTIMADE databases. The gateway can be treated as any other OPTIMADE gateway, but the entries are an aggregate of multiple databases. The <code>id</code> of each aggregated resource will reflect the originating database.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayResource(EntryResource):\n    \"\"\"OPTIMADE gateway\n\n    A resource representing a dynamic collection of OPTIMADE databases.\n    The gateway can be treated as any other OPTIMADE gateway, but the entries are an\n    aggregate of multiple databases. The `id` of each aggregated resource will reflect\n    the originating database.\n    \"\"\"\n\n    id: Annotated[\n        str,\n        OptimadeField(\n            description=EntryResource.model_fields[\"id\"].description,\n            support=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-support\"\n            ],\n            queryable=EntryResource.model_fields[\"id\"].json_schema_extra[\n                \"x-optimade-queryable\"\n            ],\n            pattern=r\"^[^/]*$\",\n        ),\n    ]\n\n    type: Annotated[\n        Literal[\"gateways\"],\n        Field(description=\"The name of the type of an entry.\"),\n    ] = \"gateways\"\n\n    attributes: Annotated[\n        GatewayResourceAttributes,\n        Field(description=EntryResource.model_fields[\"attributes\"].description),\n    ]\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.attributes","title":"<code>attributes: Annotated[GatewayResourceAttributes, Field(description=EntryResource.model_fields['attributes'].description)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.id","title":"<code>id: Annotated[str, OptimadeField(description=EntryResource.model_fields['id'].description, support=EntryResource.model_fields['id'].json_schema_extra['x-optimade-support'], queryable=EntryResource.model_fields['id'].json_schema_extra['x-optimade-queryable'], pattern='^[^/]*$')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResource.type","title":"<code>type: Annotated[Literal['gateways'], Field(description='The name of the type of an entry.')] = 'gateways'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes","title":"<code>GatewayResourceAttributes</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Attributes for an OPTIMADE gateway</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>class GatewayResourceAttributes(EntryResourceAttributes):\n    \"\"\"Attributes for an OPTIMADE gateway\"\"\"\n\n    databases: Annotated[\n        list[LinksResource],\n        Field(\n            description=(\n                \"List of databases (OPTIMADE 'links') to be queried in this gateway.\"\n            ),\n        ),\n    ]\n\n    @field_validator(\"databases\", mode=\"after\")\n    @classmethod\n    def unique_base_urls(cls, value: list[LinksResource]) -&gt; list[LinksResource]:\n        \"\"\"Remove extra entries with repeated base_urls.\n\n        Also, ensure databases are not of type `\"root\"` or `\"providers\"`\n\n        !!! note\n            Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n            but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n        \"\"\"\n        for resource in value:\n            if resource.attributes.link_type in (LinkType.ROOT, LinkType.PROVIDERS):\n                raise ValueError(\n                    \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                    f\"gateway resources. Given database: {resource}\"\n                )\n\n        db_base_urls = [_.attributes.base_url for _ in value]\n        unique_base_urls = set(db_base_urls)\n        if len(db_base_urls) == len(unique_base_urls):\n            return value\n\n        repeated_base_urls = [_ for _ in unique_base_urls if db_base_urls.count(_) &gt; 1]\n        new_databases = [\n            _ for _ in value if _.attributes.base_url not in repeated_base_urls\n        ]\n        for base_url in repeated_base_urls:\n            new_databases.append(\n                next(_ for _ in value if _.attributes.base_url == base_url)\n            )\n        warnings.warn(\n            \"Removed extra database entries for a gateway, because the base_url was \"\n            \"repeated. The first found database entry was kept, while the others were \"\n            f\"removed. Original number of databases: {len(value)}. New number of \"\n            f\"databases: {len(new_databases)} Repeated base_urls (number of repeats): \"\n            \"{}\".format(\n                [\n                    f\"{base_url} ({db_base_urls.count(base_url)})\"\n                    for base_url in repeated_base_urls\n                ]\n            ),\n            OptimadeGatewayWarning,\n        )\n        return new_databases\n</code></pre>"},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes.databases","title":"<code>databases: Annotated[list[LinksResource], Field(description=\"List of databases (OPTIMADE 'links') to be queried in this gateway.\")]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/gateways/#optimade_gateway.models.gateways.GatewayResourceAttributes.unique_base_urls","title":"<code>unique_base_urls(value)</code>  <code>classmethod</code>","text":"<p>Remove extra entries with repeated base_urls.</p> <p>Also, ensure databases are not of type <code>\"root\"</code> or <code>\"providers\"</code></p> <p>Note</p> <p>Both <code>\"external\"</code> and <code>\"child\"</code> can still represent index meta-dbs, but <code>\"root\"</code> and <code>\"providers\"</code> can not represent \"regular\" dbs.</p> Source code in <code>optimade_gateway/models/gateways.py</code> <pre><code>@field_validator(\"databases\", mode=\"after\")\n@classmethod\ndef unique_base_urls(cls, value: list[LinksResource]) -&gt; list[LinksResource]:\n    \"\"\"Remove extra entries with repeated base_urls.\n\n    Also, ensure databases are not of type `\"root\"` or `\"providers\"`\n\n    !!! note\n        Both `\"external\"` and `\"child\"` can still represent index meta-dbs,\n        but `\"root\"` and `\"providers\"` can not represent \"regular\" dbs.\n\n    \"\"\"\n    for resource in value:\n        if resource.attributes.link_type in (LinkType.ROOT, LinkType.PROVIDERS):\n            raise ValueError(\n                \"Databases with 'root' or 'providers' link_type is not allowed for \"\n                f\"gateway resources. Given database: {resource}\"\n            )\n\n    db_base_urls = [_.attributes.base_url for _ in value]\n    unique_base_urls = set(db_base_urls)\n    if len(db_base_urls) == len(unique_base_urls):\n        return value\n\n    repeated_base_urls = [_ for _ in unique_base_urls if db_base_urls.count(_) &gt; 1]\n    new_databases = [\n        _ for _ in value if _.attributes.base_url not in repeated_base_urls\n    ]\n    for base_url in repeated_base_urls:\n        new_databases.append(\n            next(_ for _ in value if _.attributes.base_url == base_url)\n        )\n    warnings.warn(\n        \"Removed extra database entries for a gateway, because the base_url was \"\n        \"repeated. The first found database entry was kept, while the others were \"\n        f\"removed. Original number of databases: {len(value)}. New number of \"\n        f\"databases: {len(new_databases)} Repeated base_urls (number of repeats): \"\n        \"{}\".format(\n            [\n                f\"{base_url} ({db_base_urls.count(base_url)})\"\n                for base_url in repeated_base_urls\n            ]\n        ),\n        OptimadeGatewayWarning,\n    )\n    return new_databases\n</code></pre>"},{"location":"api_reference/models/queries/","title":"queries","text":"<p>Pydantic models/schemas for the Queries resource.</p>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QUERY_PARAMETERS","title":"<code>QUERY_PARAMETERS: QueryParameters = {'annotations': {name: FieldInfo.from_annotation(parameter.annotation)for (name, parameter) in inspect.signature(EntryListingQueryParams).parameters.items()}, 'defaults': EntryListingQueryParams()}</code>  <code>module-attribute</code>","text":"<p>Entry listing URL query parameters from the <code>optimade</code> package (<code>EntryListingQueryParams</code>).</p>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType","title":"<code>EndpointEntryType</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Entry endpoint resource types, mapping to their pydantic models from the <code>optimade</code> package.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class EndpointEntryType(Enum):\n    \"\"\"Entry endpoint resource types, mapping to their pydantic models from the\n    `optimade` package.\"\"\"\n\n    REFERENCES = \"references\"\n    STRUCTURES = \"structures\"\n\n    def get_resource_model(self) -&gt; ReferenceResource | StructureResource:\n        \"\"\"Get the matching pydantic model for a resource.\"\"\"\n        return {\n            \"references\": ReferenceResource,\n            \"structures\": StructureResource,\n        }[self.value]\n\n    def get_response_model(\n        self, single: bool = False\n    ) -&gt; (\n        ReferenceResponseMany\n        | ReferenceResponseOne\n        | StructureResponseMany\n        | StructureResponseOne\n    ):\n        \"\"\"Get the matching pydantic model for a successful response.\"\"\"\n        if single:\n            return {\n                \"references\": ReferenceResponseOne,\n                \"structures\": StructureResponseOne,\n            }[self.value]\n        return {\n            \"references\": ReferenceResponseMany,\n            \"structures\": StructureResponseMany,\n        }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.REFERENCES","title":"<code>REFERENCES = 'references'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.STRUCTURES","title":"<code>STRUCTURES = 'structures'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.get_resource_model","title":"<code>get_resource_model()</code>","text":"<p>Get the matching pydantic model for a resource.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>def get_resource_model(self) -&gt; ReferenceResource | StructureResource:\n    \"\"\"Get the matching pydantic model for a resource.\"\"\"\n    return {\n        \"references\": ReferenceResource,\n        \"structures\": StructureResource,\n    }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EndpointEntryType.get_response_model","title":"<code>get_response_model(single=False)</code>","text":"<p>Get the matching pydantic model for a successful response.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>def get_response_model(\n    self, single: bool = False\n) -&gt; (\n    ReferenceResponseMany\n    | ReferenceResponseOne\n    | StructureResponseMany\n    | StructureResponseOne\n):\n    \"\"\"Get the matching pydantic model for a successful response.\"\"\"\n    if single:\n        return {\n            \"references\": ReferenceResponseOne,\n            \"structures\": StructureResponseOne,\n        }[self.value]\n    return {\n        \"references\": ReferenceResponseMany,\n        \"structures\": StructureResponseMany,\n    }[self.value]\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EntryResource","title":"<code>EntryResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>Entry Resource ensuring datetimes are not naive.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class EntryResource(OptimadeEntryResource):\n    \"\"\"Entry Resource ensuring datetimes are not naive.\"\"\"\n\n    @field_validator(\"attributes\", mode=\"after\")\n    @classmethod\n    def ensure_non_naive_datetime(\n        cls, value: EntryResourceAttributes\n    ) -&gt; EntryResourceAttributes:\n        \"\"\"Set timezone to UTC if datetime is naive.\"\"\"\n        if value.last_modified and value.last_modified.tzinfo is None:\n            value.last_modified = value.last_modified.replace(tzinfo=timezone.utc)\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.EntryResource.ensure_non_naive_datetime","title":"<code>ensure_non_naive_datetime(value)</code>  <code>classmethod</code>","text":"<p>Set timezone to UTC if datetime is naive.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"attributes\", mode=\"after\")\n@classmethod\ndef ensure_non_naive_datetime(\n    cls, value: EntryResourceAttributes\n) -&gt; EntryResourceAttributes:\n    \"\"\"Set timezone to UTC if datetime is naive.\"\"\"\n    if value.last_modified and value.last_modified.tzinfo is None:\n        value.last_modified = value.last_modified.replace(tzinfo=timezone.utc)\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse","title":"<code>GatewayQueryResponse</code>","text":"<p>               Bases: <code>Response</code></p> <p>Response from a Gateway Query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class GatewayQueryResponse(Response):\n    \"\"\"Response from a Gateway Query.\"\"\"\n\n    data: Annotated[\n        dict[str, list[EntryResource] | list[dict[str, Any]]],\n        StrictField(uniqueItems=True, description=\"Outputted Data.\"),\n    ]\n\n    meta: Annotated[\n        ResponseMeta,\n        StrictField(description=\"A meta object containing non-standard information.\"),\n    ]\n\n    errors: Annotated[\n        list[OptimadeError] | None,\n        StrictField(\n            description=(\n                \"A list of OPTIMADE-specific JSON API error objects, where the field \"\n                \"detail MUST be present.\"\n            ),\n            uniqueItems=True,\n        ),\n    ] = []  # noqa: RUF012\n\n    included: Annotated[\n        list[EntryResource] | list[dict[str, Any]] | None,\n        StrictField(\n            description=\"A list of unique included OPTIMADE entry resources.\",\n            uniqueItems=True,\n            union_mode=\"left_to_right\",\n        ),\n    ] = None\n\n    @model_validator(mode=\"after\")\n    def either_data_meta_or_errors_must_be_set(self) -&gt; GatewayQueryResponse:\n        \"\"\"Overwrite `either_data_meta_or_errors_must_be_set`.\n\n        `errors` should be allowed to be present always for this special response.\n        \"\"\"\n        return self\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.data","title":"<code>data: Annotated[dict[str, list[EntryResource] | list[dict[str, Any]]], StrictField(uniqueItems=True, description='Outputted Data.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.errors","title":"<code>errors: Annotated[list[OptimadeError] | None, StrictField(description='A list of OPTIMADE-specific JSON API error objects, where the field detail MUST be present.', uniqueItems=True)] = []</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.included","title":"<code>included: Annotated[list[EntryResource] | list[dict[str, Any]] | None, StrictField(description='A list of unique included OPTIMADE entry resources.', uniqueItems=True, union_mode='left_to_right')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.meta","title":"<code>meta: Annotated[ResponseMeta, StrictField(description='A meta object containing non-standard information.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.GatewayQueryResponse.either_data_meta_or_errors_must_be_set","title":"<code>either_data_meta_or_errors_must_be_set()</code>","text":"<p>Overwrite <code>either_data_meta_or_errors_must_be_set</code>.</p> <p><code>errors</code> should be allowed to be present always for this special response.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@model_validator(mode=\"after\")\ndef either_data_meta_or_errors_must_be_set(self) -&gt; GatewayQueryResponse:\n    \"\"\"Overwrite `either_data_meta_or_errors_must_be_set`.\n\n    `errors` should be allowed to be present always for this special response.\n    \"\"\"\n    return self\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters","title":"<code>OptimadeQueryParameters</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>Common OPTIMADE entry listing endpoint query parameters.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class OptimadeQueryParameters(BaseModel):\n    \"\"\"Common OPTIMADE entry listing endpoint query parameters.\"\"\"\n\n    filter: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"filter\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].filter\n\n    response_format: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"response_format\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].response_format\n\n    email_address: Annotated[\n        EmailStr | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"email_address\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].email_address\n\n    response_fields: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"response_fields\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"response_fields\"]\n            .metadata[0]\n            .pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].response_fields\n\n    sort: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"sort\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"sort\"].metadata[0].pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].sort\n\n    page_limit: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_limit\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_limit\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_limit\n\n    page_offset: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_offset\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_offset\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_offset\n\n    page_number: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_number\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_number\n\n    page_cursor: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_cursor\"].description,\n            ge=QUERY_PARAMETERS[\"annotations\"][\"page_cursor\"].metadata[0].ge,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_cursor\n\n    page_above: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_above\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_above\n\n    page_below: Annotated[\n        int | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"page_below\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].page_below\n\n    include: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"include\"].description,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].include\n\n    api_hint: Annotated[\n        str | None,\n        Field(\n            description=QUERY_PARAMETERS[\"annotations\"][\"api_hint\"].description,\n            pattern=QUERY_PARAMETERS[\"annotations\"][\"api_hint\"].metadata[0].pattern,\n        ),\n    ] = QUERY_PARAMETERS[\"defaults\"].api_hint\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.api_hint","title":"<code>api_hint: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['api_hint'].description, pattern=QUERY_PARAMETERS['annotations']['api_hint'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].api_hint</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.email_address","title":"<code>email_address: Annotated[EmailStr | None, Field(description=QUERY_PARAMETERS['annotations']['email_address'].description)] = QUERY_PARAMETERS['defaults'].email_address</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.filter","title":"<code>filter: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['filter'].description)] = QUERY_PARAMETERS['defaults'].filter</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.include","title":"<code>include: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['include'].description)] = QUERY_PARAMETERS['defaults'].include</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_above","title":"<code>page_above: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_above'].description)] = QUERY_PARAMETERS['defaults'].page_above</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_below","title":"<code>page_below: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_below'].description)] = QUERY_PARAMETERS['defaults'].page_below</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_cursor","title":"<code>page_cursor: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_cursor'].description, ge=QUERY_PARAMETERS['annotations']['page_cursor'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_cursor</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_limit","title":"<code>page_limit: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_limit'].description, ge=QUERY_PARAMETERS['annotations']['page_limit'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_limit</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_number","title":"<code>page_number: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_number'].description)] = QUERY_PARAMETERS['defaults'].page_number</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.page_offset","title":"<code>page_offset: Annotated[int | None, Field(description=QUERY_PARAMETERS['annotations']['page_offset'].description, ge=QUERY_PARAMETERS['annotations']['page_offset'].metadata[0].ge)] = QUERY_PARAMETERS['defaults'].page_offset</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.response_fields","title":"<code>response_fields: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['response_fields'].description, pattern=QUERY_PARAMETERS['annotations']['response_fields'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].response_fields</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.response_format","title":"<code>response_format: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['response_format'].description)] = QUERY_PARAMETERS['defaults'].response_format</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.OptimadeQueryParameters.sort","title":"<code>sort: Annotated[str | None, Field(description=QUERY_PARAMETERS['annotations']['sort'].description, pattern=QUERY_PARAMETERS['annotations']['sort'].metadata[0].pattern)] = QUERY_PARAMETERS['defaults'].sort</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate","title":"<code>QueryCreate</code>","text":"<p>               Bases: <code>EntryResourceCreate</code>, <code>QueryResourceAttributes</code></p> <p>Model for creating new Query resources in the MongoDB</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryCreate(EntryResourceCreate, QueryResourceAttributes):\n    \"\"\"Model for creating new Query resources in the MongoDB\"\"\"\n\n    state: Annotated[\n        QueryState | None,\n        Field(\n            title=QueryResourceAttributes.model_fields[\"state\"].title,\n            description=QueryResourceAttributes.model_fields[\"state\"].description,\n            json_schema_extra=QueryResourceAttributes.model_fields[\n                \"state\"\n            ].json_schema_extra,\n        ),\n    ] = None  # type: ignore[assignment]\n    endpoint: Annotated[\n        EndpointEntryType | None,\n        Field(\n            title=QueryResourceAttributes.model_fields[\"endpoint\"].title,\n            description=QueryResourceAttributes.model_fields[\"endpoint\"].description,\n            json_schema_extra=QueryResourceAttributes.model_fields[\n                \"endpoint\"\n            ].json_schema_extra,\n        ),\n    ] = None  # type: ignore[assignment]\n\n    @field_validator(\"query_parameters\", mode=\"after\")\n    @classmethod\n    def sort_not_supported(\n        cls, value: OptimadeQueryParameters\n    ) -&gt; OptimadeQueryParameters:\n        \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n        if value.sort:\n            warnings.warn(SortNotSupported())\n            value.sort = None\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.endpoint","title":"<code>endpoint: Annotated[EndpointEntryType | None, Field(title=QueryResourceAttributes.model_fields['endpoint'].title, description=QueryResourceAttributes.model_fields['endpoint'].description, json_schema_extra=QueryResourceAttributes.model_fields['endpoint'].json_schema_extra)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.state","title":"<code>state: Annotated[QueryState | None, Field(title=QueryResourceAttributes.model_fields['state'].title, description=QueryResourceAttributes.model_fields['state'].description, json_schema_extra=QueryResourceAttributes.model_fields['state'].json_schema_extra)] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryCreate.sort_not_supported","title":"<code>sort_not_supported(value)</code>  <code>classmethod</code>","text":"<p>Warn and reset value if <code>sort</code> is supplied.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"query_parameters\", mode=\"after\")\n@classmethod\ndef sort_not_supported(\n    cls, value: OptimadeQueryParameters\n) -&gt; OptimadeQueryParameters:\n    \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n    if value.sort:\n        warnings.warn(SortNotSupported())\n        value.sort = None\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters","title":"<code>QueryParameters</code>","text":"<p>               Bases: <code>TypedDict</code></p> <p>Type definition for <code>QUERY_PARAMETERS</code>.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryParameters(TypedDict):\n    \"\"\"Type definition for `QUERY_PARAMETERS`.\"\"\"\n\n    annotations: dict[str, FieldInfo]\n    defaults: EntryListingQueryParams\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters.annotations","title":"<code>annotations: dict[str, FieldInfo]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryParameters.defaults","title":"<code>defaults: EntryListingQueryParams</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource","title":"<code>QueryResource</code>","text":"<p>               Bases: <code>EntryResource</code></p> <p>OPTIMADE query resource for a gateway</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryResource(EntryResource):\n    \"\"\"OPTIMADE query resource for a gateway\"\"\"\n\n    type: Annotated[\n        Literal[\"queries\"],\n        Field(\n            description=\"The name of the type of an entry.\",\n        ),\n    ] = \"queries\"\n\n    attributes: QueryResourceAttributes\n\n    async def response_as_optimade(\n        self,\n        url: None | (\n            urllib.parse.ParseResult | urllib.parse.SplitResult | StarletteURL | str\n        ) = None,\n    ) -&gt; EntryResponseMany | ErrorResponse:\n        \"\"\"Return `attributes.response` as a valid OPTIMADE entry listing response.\n\n        Note, this method disregards the state of the query and will simply return the\n        query results as they currently are (if there are any at all).\n\n        Parameters:\n            url: Optionally, update the `meta.query.representation` value with this.\n\n        Returns:\n            A valid OPTIMADE entry-listing response according to the\n            [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints)\n            or an error response, if errors were returned or occurred during the query.\n\n        \"\"\"\n        from optimade.server.routers.utils import (\n            meta_values,\n        )\n\n        async def _update_id(\n            entry_: EntryResource | dict[str, Any], database_provider_: str\n        ) -&gt; EntryResource | dict[str, Any]:\n            \"\"\"Internal utility function to prepend the entries' `id` with\n            `provider/database/`.\n\n            Parameters:\n                entry_: The entry as a model or a dictionary.\n                database_provider_: `provider/database` string.\n\n            Returns:\n                The entry with an updated `id` value.\n\n            \"\"\"\n            if isinstance(entry_, dict):\n                _entry = deepcopy(entry_)\n                _entry[\"id\"] = f\"{database_provider_}/{entry_['id']}\"\n                return _entry\n\n            return entry_.model_copy(\n                update={\"id\": f\"{database_provider_}/{entry_.id}\"},\n                deep=True,\n            ).model_dump(exclude_unset=True, exclude_none=True)\n\n        if not self.attributes.response:\n            # The query has not yet been initiated\n            return ErrorResponse(\n                errors=[\n                    {\n                        \"detail\": (\n                            \"Can not return as a valid OPTIMADE response as the query \"\n                            \"has not yet been initialized.\"\n                        ),\n                        \"id\": \"OPTIMADE_GATEWAY_QUERY_NOT_INITIALIZED\",\n                    }\n                ],\n                meta=meta_values(\n                    url=url or f\"/queries/{self.id}?\",\n                    data_returned=0,\n                    data_available=0,\n                    more_data_available=False,\n                    schema=CONFIG.schema_url,\n                ),\n            )\n\n        meta_ = self.attributes.response.meta\n\n        if url:\n            meta_ = meta_.model_dump(exclude_unset=True)\n            for repeated_key in (\n                \"query\",\n                \"api_version\",\n                \"time_stamp\",\n                \"provider\",\n                \"implementation\",\n            ):\n                meta_.pop(repeated_key, None)\n            meta_ = meta_values(url=url, **meta_)\n\n        # Error response\n        if self.attributes.response.errors:\n            return ErrorResponse(\n                errors=self.attributes.response.errors,\n                meta=meta_,\n            )\n\n        # Data response\n        results = []\n        for database_provider, entries in self.attributes.response.data.items():\n            results.extend(\n                [await _update_id(entry, database_provider) for entry in entries]\n            )\n\n        return self.attributes.endpoint.get_response_model()(\n            data=results,\n            meta=meta_,\n            links=self.attributes.response.links,\n        )\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.attributes","title":"<code>attributes: QueryResourceAttributes</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.type","title":"<code>type: Annotated[Literal['queries'], Field(description='The name of the type of an entry.')] = 'queries'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResource.response_as_optimade","title":"<code>response_as_optimade(url=None)</code>  <code>async</code>","text":"<p>Return <code>attributes.response</code> as a valid OPTIMADE entry listing response.</p> <p>Note, this method disregards the state of the query and will simply return the query results as they currently are (if there are any at all).</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>None | ParseResult | SplitResult | URL | str</code> <p>Optionally, update the <code>meta.query.representation</code> value with this.</p> <code>None</code> <p>Returns:</p> Type Description <code>EntryResponseMany | ErrorResponse</code> <p>A valid OPTIMADE entry-listing response according to the</p> <code>EntryResponseMany | ErrorResponse</code> <p>OPTIMADE specification</p> <code>EntryResponseMany | ErrorResponse</code> <p>or an error response, if errors were returned or occurred during the query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>async def response_as_optimade(\n    self,\n    url: None | (\n        urllib.parse.ParseResult | urllib.parse.SplitResult | StarletteURL | str\n    ) = None,\n) -&gt; EntryResponseMany | ErrorResponse:\n    \"\"\"Return `attributes.response` as a valid OPTIMADE entry listing response.\n\n    Note, this method disregards the state of the query and will simply return the\n    query results as they currently are (if there are any at all).\n\n    Parameters:\n        url: Optionally, update the `meta.query.representation` value with this.\n\n    Returns:\n        A valid OPTIMADE entry-listing response according to the\n        [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints)\n        or an error response, if errors were returned or occurred during the query.\n\n    \"\"\"\n    from optimade.server.routers.utils import (\n        meta_values,\n    )\n\n    async def _update_id(\n        entry_: EntryResource | dict[str, Any], database_provider_: str\n    ) -&gt; EntryResource | dict[str, Any]:\n        \"\"\"Internal utility function to prepend the entries' `id` with\n        `provider/database/`.\n\n        Parameters:\n            entry_: The entry as a model or a dictionary.\n            database_provider_: `provider/database` string.\n\n        Returns:\n            The entry with an updated `id` value.\n\n        \"\"\"\n        if isinstance(entry_, dict):\n            _entry = deepcopy(entry_)\n            _entry[\"id\"] = f\"{database_provider_}/{entry_['id']}\"\n            return _entry\n\n        return entry_.model_copy(\n            update={\"id\": f\"{database_provider_}/{entry_.id}\"},\n            deep=True,\n        ).model_dump(exclude_unset=True, exclude_none=True)\n\n    if not self.attributes.response:\n        # The query has not yet been initiated\n        return ErrorResponse(\n            errors=[\n                {\n                    \"detail\": (\n                        \"Can not return as a valid OPTIMADE response as the query \"\n                        \"has not yet been initialized.\"\n                    ),\n                    \"id\": \"OPTIMADE_GATEWAY_QUERY_NOT_INITIALIZED\",\n                }\n            ],\n            meta=meta_values(\n                url=url or f\"/queries/{self.id}?\",\n                data_returned=0,\n                data_available=0,\n                more_data_available=False,\n                schema=CONFIG.schema_url,\n            ),\n        )\n\n    meta_ = self.attributes.response.meta\n\n    if url:\n        meta_ = meta_.model_dump(exclude_unset=True)\n        for repeated_key in (\n            \"query\",\n            \"api_version\",\n            \"time_stamp\",\n            \"provider\",\n            \"implementation\",\n        ):\n            meta_.pop(repeated_key, None)\n        meta_ = meta_values(url=url, **meta_)\n\n    # Error response\n    if self.attributes.response.errors:\n        return ErrorResponse(\n            errors=self.attributes.response.errors,\n            meta=meta_,\n        )\n\n    # Data response\n    results = []\n    for database_provider, entries in self.attributes.response.data.items():\n        results.extend(\n            [await _update_id(entry, database_provider) for entry in entries]\n        )\n\n    return self.attributes.endpoint.get_response_model()(\n        data=results,\n        meta=meta_,\n        links=self.attributes.response.links,\n    )\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes","title":"<code>QueryResourceAttributes</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Attributes for an OPTIMADE gateway query.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryResourceAttributes(EntryResourceAttributes):\n    \"\"\"Attributes for an OPTIMADE gateway query.\"\"\"\n\n    gateway_id: Annotated[\n        str,\n        Field(\n            description=\"The OPTIMADE gateway ID for this query.\",\n        ),\n    ]\n\n    query_parameters: Annotated[\n        OptimadeQueryParameters,\n        Field(\n            description=(\n                \"OPTIMADE query parameters for entry listing endpoints used for this \"\n                \"query.\"\n            ),\n            json_schema_extra={\n                \"type\": \"object\",\n            },\n        ),\n    ]\n\n    state: Annotated[\n        QueryState,\n        Field(\n            description=\"Current state of Gateway Query.\",\n            title=\"State\",\n            json_schema_extra={\n                \"type\": \"enum\",\n            },\n        ),\n    ] = QueryState.CREATED\n\n    response: Annotated[\n        GatewayQueryResponse | None,\n        Field(\n            description=\"Response from gateway query.\",\n        ),\n    ] = None\n\n    endpoint: Annotated[\n        EndpointEntryType,\n        Field(\n            description=\"The entry endpoint queried, e.g., 'structures'.\",\n            title=\"Endpoint\",\n            json_schema_extra={\n                \"type\": \"enum\",\n            },\n        ),\n    ] = EndpointEntryType.STRUCTURES\n\n    @field_validator(\"endpoint\", mode=\"after\")\n    @classmethod\n    def only_allow_structures(cls, value: EndpointEntryType) -&gt; EndpointEntryType:\n        \"\"\"Temporarily only allow queries to \"structures\" endpoints.\"\"\"\n        if value != EndpointEntryType.STRUCTURES:\n            raise NotImplementedError(\n                'OPTIMADE Gateway temporarily only supports queries to \"structures\" '\n                'endpoints, i.e.: endpoint=\"structures\"'\n            )\n        return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.endpoint","title":"<code>endpoint: Annotated[EndpointEntryType, Field(description=\"The entry endpoint queried, e.g., 'structures'.\", title='Endpoint', json_schema_extra={'type': 'enum'})] = EndpointEntryType.STRUCTURES</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.gateway_id","title":"<code>gateway_id: Annotated[str, Field(description='The OPTIMADE gateway ID for this query.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.query_parameters","title":"<code>query_parameters: Annotated[OptimadeQueryParameters, Field(description='OPTIMADE query parameters for entry listing endpoints used for this query.', json_schema_extra={'type': 'object'})]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.response","title":"<code>response: Annotated[GatewayQueryResponse | None, Field(description='Response from gateway query.')] = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.state","title":"<code>state: Annotated[QueryState, Field(description='Current state of Gateway Query.', title='State', json_schema_extra={'type': 'enum'})] = QueryState.CREATED</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryResourceAttributes.only_allow_structures","title":"<code>only_allow_structures(value)</code>  <code>classmethod</code>","text":"<p>Temporarily only allow queries to \"structures\" endpoints.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>@field_validator(\"endpoint\", mode=\"after\")\n@classmethod\ndef only_allow_structures(cls, value: EndpointEntryType) -&gt; EndpointEntryType:\n    \"\"\"Temporarily only allow queries to \"structures\" endpoints.\"\"\"\n    if value != EndpointEntryType.STRUCTURES:\n        raise NotImplementedError(\n            'OPTIMADE Gateway temporarily only supports queries to \"structures\" '\n            'endpoints, i.e.: endpoint=\"structures\"'\n        )\n    return value\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState","title":"<code>QueryState</code>","text":"<p>               Bases: <code>Enum</code></p> <p>Enumeration of possible states for a Gateway Query.</p> <p>The states are enumerated here in the expected evolvement.</p> Source code in <code>optimade_gateway/models/queries.py</code> <pre><code>class QueryState(Enum):\n    \"\"\"Enumeration of possible states for a Gateway Query.\n\n    The states are enumerated here in the expected evolvement.\n    \"\"\"\n\n    CREATED = \"created\"\n    STARTED = \"started\"\n    IN_PROGRESS = \"in progress\"\n    FINISHED = \"finished\"\n</code></pre>"},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.CREATED","title":"<code>CREATED = 'created'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.FINISHED","title":"<code>FINISHED = 'finished'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.IN_PROGRESS","title":"<code>IN_PROGRESS = 'in progress'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/queries/#optimade_gateway.models.queries.QueryState.STARTED","title":"<code>STARTED = 'started'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/","title":"resources","text":"<p>Pydantic models/schemas for entry-endpoint resources.</p> <p>This module is mainly used for a special pydantic base model, which can be used as a mix-in class when creating entry-endpoint resources.</p>"},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate","title":"<code>EntryResourceCreate</code>","text":"<p>               Bases: <code>EntryResourceAttributes</code></p> <p>Generic model for creating new entry resources in the MongoDB</p> Source code in <code>optimade_gateway/models/resources.py</code> <pre><code>class EntryResourceCreate(EntryResourceAttributes):\n    \"\"\"Generic model for creating new entry resources in the MongoDB\"\"\"\n\n    model_config = ConfigDict(extra=\"ignore\")\n\n    last_modified: datetime | None = None\n\n    id: str | None = None\n\n    @model_validator(mode=\"after\")\n    def check_illegal_attributes_fields(self) -&gt; EntryResourceCreate:\n        \"\"\"Overwrite parental `check_illegal_attributes_fields` class validators.\"\"\"\n        return self\n</code></pre>"},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.id","title":"<code>id: str | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.last_modified","title":"<code>last_modified: datetime | None = None</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.model_config","title":"<code>model_config = ConfigDict(extra='ignore')</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/resources/#optimade_gateway.models.resources.EntryResourceCreate.check_illegal_attributes_fields","title":"<code>check_illegal_attributes_fields()</code>","text":"<p>Overwrite parental <code>check_illegal_attributes_fields</code> class validators.</p> Source code in <code>optimade_gateway/models/resources.py</code> <pre><code>@model_validator(mode=\"after\")\ndef check_illegal_attributes_fields(self) -&gt; EntryResourceCreate:\n    \"\"\"Overwrite parental `check_illegal_attributes_fields` class validators.\"\"\"\n    return self\n</code></pre>"},{"location":"api_reference/models/responses/","title":"responses","text":"<p>Pydantic models/schemas for the API responses.</p>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponse","title":"<code>DatabasesResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /databases</code></p> <p>This model is essentially equal to <code>LinksResponse</code> with the exception of the <code>data</code> field's description.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class DatabasesResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /databases`\n\n    This model is essentially equal to\n    [`LinksResponse`](https://www.optimade.org/optimade-python-tools/api_reference/models/responses/#optimade.models.responses.LinksResponse)\n    with the exception of the `data` field's description.\n    \"\"\"\n\n    data: Annotated[\n        list[LinksResource],\n        StrictField(\n            description=(\n                \"List of unique OPTIMADE links resource objects.\\nThese links resource \"\n                \"objects represents OPTIMADE databases that can be used for queries in \"\n                \"gateways.\"\n            ),\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponse.data","title":"<code>data: Annotated[list[LinksResource], StrictField(description='List of unique OPTIMADE links resource objects.\\nThese links resource objects represents OPTIMADE databases that can be used for queries in gateways.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponseSingle","title":"<code>DatabasesResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /databases</code> and <code>GET /databases/{database_id}</code></p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class DatabasesResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /databases` and `GET /databases/{database_id}`\"\"\"\n\n    data: Annotated[\n        LinksResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE links resource object.\\nThe OPTIMADE links resource \"\n                \"object has just been created or found according to the specific query \"\n                \"parameter(s) or URL id.\\nIt represents an OPTIMADE database that can \"\n                \"be used for queries in gateways.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.DatabasesResponseSingle.data","title":"<code>data: Annotated[LinksResource | None, Field(description='A unique OPTIMADE links resource object.\\nThe OPTIMADE links resource object has just been created or found according to the specific query parameter(s) or URL id.\\nIt represents an OPTIMADE database that can be used for queries in gateways.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponse","title":"<code>GatewaysResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /gateways</code></p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class GatewaysResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /gateways`\"\"\"\n\n    data: Annotated[\n        list[GatewayResource],\n        StrictField(\n            description=\"List of unique OPTIMADE gateway resource objects.\",\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponse.data","title":"<code>data: Annotated[list[GatewayResource], StrictField(description='List of unique OPTIMADE gateway resource objects.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponseSingle","title":"<code>GatewaysResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /gateways</code> and <code>GET /gateways/{gateway_id}</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class GatewaysResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /gateways` and `GET /gateways/{gateway_id}`.\"\"\"\n\n    data: Annotated[\n        GatewayResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE gateway resource object.\\nThe OPTIMADE gateway \"\n                \"resource object has just been created or found according to the \"\n                \"specific query parameter(s) or URL id.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.GatewaysResponseSingle.data","title":"<code>data: Annotated[GatewayResource | None, Field(description='A unique OPTIMADE gateway resource object.\\nThe OPTIMADE gateway resource object has just been created or found according to the specific query parameter(s) or URL id.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponse","title":"<code>QueriesResponse</code>","text":"<p>               Bases: <code>EntryResponseMany</code></p> <p>Successful response for <code>GET /gateways/{gateway_ID}/queries</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class QueriesResponse(EntryResponseMany):\n    \"\"\"Successful response for `GET /gateways/{gateway_ID}/queries`.\"\"\"\n\n    data: Annotated[\n        list[QueryResource],\n        StrictField(\n            description=\"List of unique OPTIMADE gateway query resource objects.\",\n            uniqueItems=True,\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponse.data","title":"<code>data: Annotated[list[QueryResource], StrictField(description='List of unique OPTIMADE gateway query resource objects.', uniqueItems=True)]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponseSingle","title":"<code>QueriesResponseSingle</code>","text":"<p>               Bases: <code>EntryResponseOne</code></p> <p>Successful response for <code>POST /gateways/{gateway_ID}/queries</code> and <code>GET /gateways/{gateway_ID}/queries/{query_id}</code>.</p> Source code in <code>optimade_gateway/models/responses.py</code> <pre><code>class QueriesResponseSingle(EntryResponseOne):\n    \"\"\"Successful response for `POST /gateways/{gateway_ID}/queries`\n    and `GET /gateways/{gateway_ID}/queries/{query_id}`.\"\"\"\n\n    data: Annotated[\n        QueryResource | None,\n        Field(\n            description=(\n                \"A unique OPTIMADE gateway query resource object.\\nThe OPTIMADE \"\n                \"gateway query resource object has just been created or found \"\n                \"according to the specific query parameter(s) or URL id.\"\n            ),\n        ),\n    ]\n</code></pre>"},{"location":"api_reference/models/responses/#optimade_gateway.models.responses.QueriesResponseSingle.data","title":"<code>data: Annotated[QueryResource | None, Field(description='A unique OPTIMADE gateway query resource object.\\nThe OPTIMADE gateway query resource object has just been created or found according to the specific query parameter(s) or URL id.')]</code>  <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/","title":"search","text":"<p>Pydantic models/schemas for the Search resource.</p>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search","title":"<code>Search</code>","text":"<p>               Bases: <code>BaseModel</code></p> <p>A general coordinated OPTIMADE search</p> <p>Important</p> <p>Either <code>database_ids</code> or <code>optimade_urls</code> MUST be specified.</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>class Search(BaseModel):\n    \"\"\"A general coordinated OPTIMADE search\n\n    !!! important\n        Either `database_ids` or `optimade_urls` MUST be specified.\n\n    \"\"\"\n\n    query_parameters: Annotated[\n        OptimadeQueryParameters,\n        Field(\n            description=(\n                \"OPTIMADE query parameters for entry listing endpoints used for this \"\n                \"query.\"\n            ),\n        ),\n    ] = OptimadeQueryParameters()\n\n    database_ids: Annotated[\n        set[str],\n        Field(\n            description=(\n                \"A list of registered database IDs. Go to `/databases` to get all \"\n                \"registered databases.\"\n            ),\n        ),\n    ] = set()\n\n    optimade_urls: Annotated[\n        set[AnyUrl],\n        Field(\n            description=(\n                \"A list of OPTIMADE base URLs. If a versioned base URL is supplied it \"\n                \"will be used as is, as long as it represents a supported version. If \"\n                \"an un-versioned base URL, standard version negotiation will be \"\n                \"conducted to get the versioned base URL, which will be used as long \"\n                \"as it represents a supported version. Note, a single URL can be \"\n                \"supplied as well, and it will automatically be wrapped in a list in \"\n                \"the server logic.\"\n            ),\n        ),\n    ] = set()\n\n    endpoint: Annotated[\n        str,\n        Field(\n            description=(\n                \"The entry endpoint queried. According to the OPTIMADE specification, \"\n                \"this is the same as the resource's type.\"\n            ),\n        ),\n    ] = \"structures\"\n\n    @model_validator(mode=\"after\")\n    def either_ids_or_urls(self) -&gt; Search:\n        \"\"\"Either `database_ids` or `optimade_urls` must be defined\"\"\"\n        if not any(getattr(self, field) for field in (\"database_ids\", \"optimade_urls\")):\n            raise ValueError(\n                \"Either 'database_ids' or 'optimade_urls' MUST be specified.\"\n            )\n        return self\n\n    @field_validator(\"query_parameters\", mode=\"after\")\n    @classmethod\n    def sort_not_supported(\n        cls, value: OptimadeQueryParameters\n    ) -&gt; OptimadeQueryParameters:\n        \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n        if value.sort:\n            warnings.warn(SortNotSupported())\n            value.sort = None\n        return value\n</code></pre>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.database_ids","title":"<code>database_ids: Annotated[set[str], Field(description='A list of registered database IDs. Go to `/databases` to get all registered databases.')] = set()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.endpoint","title":"<code>endpoint: Annotated[str, Field(description=\"The entry endpoint queried. According to the OPTIMADE specification, this is the same as the resource's type.\")] = 'structures'</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.optimade_urls","title":"<code>optimade_urls: Annotated[set[AnyUrl], Field(description='A list of OPTIMADE base URLs. If a versioned base URL is supplied it will be used as is, as long as it represents a supported version. If an un-versioned base URL, standard version negotiation will be conducted to get the versioned base URL, which will be used as long as it represents a supported version. Note, a single URL can be supplied as well, and it will automatically be wrapped in a list in the server logic.')] = set()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.query_parameters","title":"<code>query_parameters: Annotated[OptimadeQueryParameters, Field(description='OPTIMADE query parameters for entry listing endpoints used for this query.')] = OptimadeQueryParameters()</code>  <code>class-attribute</code> <code>instance-attribute</code>","text":""},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.either_ids_or_urls","title":"<code>either_ids_or_urls()</code>","text":"<p>Either <code>database_ids</code> or <code>optimade_urls</code> must be defined</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>@model_validator(mode=\"after\")\ndef either_ids_or_urls(self) -&gt; Search:\n    \"\"\"Either `database_ids` or `optimade_urls` must be defined\"\"\"\n    if not any(getattr(self, field) for field in (\"database_ids\", \"optimade_urls\")):\n        raise ValueError(\n            \"Either 'database_ids' or 'optimade_urls' MUST be specified.\"\n        )\n    return self\n</code></pre>"},{"location":"api_reference/models/search/#optimade_gateway.models.search.Search.sort_not_supported","title":"<code>sort_not_supported(value)</code>  <code>classmethod</code>","text":"<p>Warn and reset value if <code>sort</code> is supplied.</p> Source code in <code>optimade_gateway/models/search.py</code> <pre><code>@field_validator(\"query_parameters\", mode=\"after\")\n@classmethod\ndef sort_not_supported(\n    cls, value: OptimadeQueryParameters\n) -&gt; OptimadeQueryParameters:\n    \"\"\"Warn and reset value if `sort` is supplied.\"\"\"\n    if value.sort:\n        warnings.warn(SortNotSupported())\n        value.sort = None\n    return value\n</code></pre>"},{"location":"api_reference/mongo/collection/","title":"collection","text":"<p>MongoDB collection for entry-endpoint resources.</p> <p>The <code>AsyncMongoCollection</code> represents an asynchronous version of the equivalent MongoDB collection in <code>optimade</code>: <code>MongoCollection</code>.</p>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection","title":"<code>AsyncMongoCollection</code>","text":"<p>               Bases: <code>EntryCollection</code></p> <p>MongoDB Collection for use with <code>asyncio</code></p> <p>The asynchronicity is implemented using <code>motor</code> and <code>asyncio</code>.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>class AsyncMongoCollection(EntryCollection):\n    \"\"\"MongoDB Collection for use with `asyncio`\n\n    The asynchronicity is implemented using [`motor`](https://motor.readthedocs.io) and\n    [`asyncio`](https://asyncio.readthedocs.io/).\n    \"\"\"\n\n    def __init__(\n        self,\n        name: str,\n        resource_cls: EntryResource,\n        resource_mapper: BaseResourceMapper,\n    ):\n        \"\"\"Initialize the AsyncMongoCollection for the given parameters.\n\n        Parameters:\n            name: The name of the collection.\n            resource_cls: The `EntryResource` model that is stored by the collection.\n            resource_mapper: A resource mapper object that handles aliases and format\n                changes between deserialization and response.\n\n        \"\"\"\n        from optimade_gateway.mongo.database import (\n            MONGO_DB,\n        )\n\n        super().__init__(\n            resource_cls=resource_cls,\n            resource_mapper=resource_mapper,\n            transformer=MongoTransformer(mapper=resource_mapper),\n        )\n\n        self.parser = LarkParser(version=(1, 0, 0), variant=\"default\")\n        self.collection: MongoCollection = MONGO_DB[name]\n\n        # Check aliases do not clash with mongo operators\n        self._check_aliases(self.resource_mapper.all_aliases())\n        self._check_aliases(self.resource_mapper.all_length_aliases())\n\n    def __str__(self) -&gt; str:\n        \"\"\"Standard printing result for an instance.\"\"\"\n        return (\n            f\"&lt;{self.__class__.__name__}: resource={self.resource_cls.__name__} \"\n            f\"endpoint(mapper)={self.resource_mapper.ENDPOINT} \"\n            f\"DB_collection={self.collection.name}&gt;\"\n        )\n\n    def __repr__(self) -&gt; str:\n        \"\"\"Representation of instance.\"\"\"\n        return (\n            f\"{self.__class__.__name__}(name={self.collection.name!r}, \"\n            f\"resource_cls={self.resource_cls!r}, \"\n            f\"resource_mapper={self.resource_mapper!r})\"\n        )\n\n    def __len__(self) -&gt; int:\n        warn(\n            OptimadeGatewayWarning(\n                detail=(\n                    \"Cannot calculate length of collection using `len()`. Use \"\n                    \"`count()` instead.\"\n                )\n            )\n        )\n        return 0\n\n    def insert(self, data: list[EntryResource]) -&gt; None:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `ainsert(data: \"\n            \"List[EntryResource])`.\"\n        )\n\n    async def ainsert(self, data: list[EntryResource]) -&gt; None:\n        \"\"\"Add the given entries to the underlying database.\n\n        This is the asynchronous version of the parent class method named `insert()`.\n\n        Arguments:\n            data: The entry resource objects to add to the database.\n\n        \"\"\"\n        await self.collection.insert_many(await clean_python_types(data))\n\n    def count(self, **kwargs) -&gt; int:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `acount(params: \"\n            \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n            \"**kwargs)`.\"\n        )\n\n    async def acount(\n        self,\n        params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n        **kwargs: Any,\n    ) -&gt; int:\n        \"\"\"Count documents in Collection.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Parameters:\n            params: URL query parameters, either from a general entry endpoint or a\n                single-entry endpoint.\n            **kwargs: Query parameters as keyword arguments. Valid keys will be passed\n                to the\n                [`AsyncIOMotorCollection.count_documents`](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html#motor.motor_asyncio.AsyncIOMotorCollection.count_documents)\n                method.\n\n        Returns:\n            int: The number of entries matching the query specified by the keyword\n                arguments.\n\n        \"\"\"\n        if params is not None and kwargs:\n            raise ValueError(\n                \"When 'params' is supplied, no other parameters can be supplied.\"\n            )\n\n        if params is not None:\n            kwargs = await self.ahandle_query_params(params)\n\n        valid_method_keys = (\n            \"filter\",\n            \"skip\",\n            \"limit\",\n            \"hint\",\n            \"maxTimeMS\",\n            \"collation\",\n            \"session\",\n        )\n        criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n        if criteria.get(\"filter\") is None:\n            criteria[\"filter\"] = {}\n\n        return await self.collection.count_documents(**criteria)\n\n    def find(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; tuple[\n        list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n    ]:\n        \"\"\"\n        Fetches results and indicates if more data is available.\n\n        Also gives the total number of data available in the absence of `page_limit`.\n        See\n        [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n        for more information.\n\n        Parameters:\n            params: Entry listing URL query params.\n\n        Returns:\n            A tuple of various relevant values:\n            (`results`, `data_returned`, `more_data_available`, `exclude_fields`,\n            `include_fields`).\n\n        \"\"\"\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method `afind(params: \"\n            \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n            \"criteria: Optional[Dict[str, Any]])`.\"\n        )\n\n    async def afind(\n        self,\n        params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n        criteria: dict[str, Any] | None = None,\n    ) -&gt; tuple[\n        list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n    ]:\n        \"\"\"Perform the query on the underlying MongoDB Collection, handling projection\n        and pagination of the output.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Either provide `params` or `criteria`. Not both, but at least one.\n\n        Parameters:\n            params: URL query parameters, either from a general entry endpoint or a\n                single-entry endpoint.\n            criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A list of entry resource objects, how much data was returned for the query,\n            whether more data is available with pagination, and fields (excluded,\n            included).\n\n        \"\"\"\n        if (params is None and criteria is None) or (\n            params is not None and criteria is not None\n        ):\n            raise ValueError(\n                \"Exacly one of either `params` and `criteria` must be specified.\"\n            )\n\n        # Set single_entry to False, this is done since if criteria is defined,\n        # this is an unknown factor - better to then get a list of results.\n        single_entry = False\n        if criteria is None:\n            criteria = await self.ahandle_query_params(params)\n        else:\n            single_entry = isinstance(params, SingleEntryQueryParams)\n\n        response_fields = criteria.pop(\"fields\", self.all_fields)\n\n        results, data_returned, more_data_available = await self._arun_db_query(\n            criteria=criteria,\n            single_entry=single_entry,\n        )\n\n        if single_entry:\n            results = results[0] if results else None  # type: ignore[assignment]\n\n            if data_returned &gt; 1:\n                raise NotFound(\n                    detail=(\n                        f\"Instead of a single entry, {data_returned} entries were found\"\n                    ),\n                )\n\n        include_fields = (\n            response_fields - self.resource_mapper.TOP_LEVEL_NON_ATTRIBUTES_FIELDS\n        )\n        bad_optimade_fields = set()\n        bad_provider_fields = set()\n        for field in include_fields:\n            if field not in self.resource_mapper.ALL_ATTRIBUTES:\n                if field.startswith(\"_\"):\n                    if any(\n                        field.startswith(f\"_{prefix}_\")\n                        for prefix in self.resource_mapper.SUPPORTED_PREFIXES\n                    ):\n                        bad_provider_fields.add(field)\n                else:\n                    bad_optimade_fields.add(field)\n\n        if bad_provider_fields:\n            warn(\n                UnknownProviderProperty(\n                    detail=(\n                        \"Unrecognised field(s) for this provider requested in \"\n                        f\"`response_fields`: {bad_provider_fields}.\"\n                    )\n                )\n            )\n\n        if bad_optimade_fields:\n            raise BadRequest(\n                detail=(\n                    \"Unrecognised OPTIMADE field(s) in requested `response_fields`: \"\n                    f\"{bad_optimade_fields}.\"\n                )\n            )\n\n        if results:\n            results = await self.resource_mapper.adeserialize(results)\n\n        return (  # type: ignore[return-value]\n            results,\n            data_returned,\n            more_data_available,\n            self.all_fields - response_fields,\n            include_fields,\n        )\n\n    def handle_query_params(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; dict[str, Any]:\n        \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n        dictionary that can be used by the specific backend.\n\n        Note:\n            Currently this method returns the pymongo interpretation of the parameters,\n            which will need modification for modified for other backends.\n\n        Parameters:\n            params: The initialized query parameter model from the server.\n\n        Raises:\n            Forbidden: If too large of a page limit is provided.\n            BadRequest: If an invalid request is made, e.g., with incorrect fields\n                or response format.\n\n        Returns:\n            A dictionary representation of the query parameters.\n\n        \"\"\"\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method \"\n            \"`ahandle_query_params(params: Union[EntryListingQueryParams, \"\n            \"SingleEntryQueryParams])`.\"\n        )\n\n    async def ahandle_query_params(\n        self, params: EntryListingQueryParams | SingleEntryQueryParams\n    ) -&gt; dict[str, Any]:\n        \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n        dictionary that can be used by the specific backend.\n\n        This is the asynchronous version of the parent class method named\n        `handle_query_params()`.\n\n        Note:\n            Currently this method returns the pymongo interpretation of the parameters,\n            which will need modification for modified for other backends.\n\n        Parameters:\n            params: The initialized query parameter model from the server.\n\n        Raises:\n            Forbidden: If too large of a page limit is provided.\n            BadRequest: If an invalid request is made, e.g., with incorrect fields or\n                response format.\n\n        Returns:\n            A dictionary representation of the query parameters.\n\n        \"\"\"\n        return super().handle_query_params(params)\n\n    def _run_db_query(\n        self, criteria: dict[str, Any], single_entry: bool = False\n    ) -&gt; tuple[list[dict[str, Any]], int, bool]:\n        raise NotImplementedError(\n            \"This method cannot be used with this class and is a remnant from the \"\n            \"parent class. Use instead the asynchronous method \"\n            \"`_arun_db_query(criteria: Dict[str, Any], single_entry: bool)`.\"\n        )\n\n    async def _arun_db_query(\n        self, criteria: dict[str, Any], single_entry: bool = False\n    ) -&gt; tuple[list[dict[str, Any]], int, bool]:\n        \"\"\"Run the query on the backend and collect the results.\n\n        This is the asynchronous version of the parent class method named `count()`.\n\n        Arguments:\n            criteria: A dictionary representation of the query parameters.\n            single_entry: Whether or not the caller is expecting a single entry\n                response.\n\n        Returns:\n            The list of entries from the database (without any re-mapping), the total\n            number of entries matching the query and a boolean for whether or not there\n            is more data available.\n\n        \"\"\"\n        results = []\n        async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n            if criteria.get(\"projection\", {}).get(\"_id\"):\n                document[\"_id\"] = str(document[\"_id\"])\n            results.append(document)\n\n        if single_entry:\n            data_returned = len(results)\n            more_data_available = False\n        else:\n            criteria_nolimit = criteria.copy()\n            criteria_nolimit.pop(\"limit\", None)\n            data_returned = await self.acount(params=None, **criteria_nolimit)\n            more_data_available = len(results) &lt; data_returned\n\n        return results, data_returned, more_data_available\n\n    @staticmethod\n    def _check_aliases(aliases: tuple[tuple[str, str]]) -&gt; None:\n        \"\"\"Check that aliases do not clash with mongo keywords.\n\n        Parameters:\n            aliases: Tuple of tuple of aliases to be checked.\n\n        Raises:\n            RuntimeError: If any alias starts with the dollar (`$`) character.\n\n        \"\"\"\n        if any(\n            alias[0].startswith(\"$\") or alias[1].startswith(\"$\") for alias in aliases\n        ):\n            raise RuntimeError(f\"Cannot define an alias starting with a '$': {aliases}\")\n\n    async def get_one(self, **criteria: Any) -&gt; EntryResource:\n        \"\"\"Get one resource based on criteria\n\n        Warning:\n            This is not to be used for creating a REST API response,\n            but is rather a utility function to easily retrieve a single resource.\n\n        Parameters:\n            **criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A single resource from the MongoDB (mapped to pydantic models).\n\n        \"\"\"\n        criteria = criteria or {}\n\n        return self.resource_cls(\n            **self.resource_mapper.map_back(\n                await self.collection.find_one(**self._valid_find_keys(**criteria))\n            )\n        )\n\n    async def get_multiple(self, **criteria: Any) -&gt; list[EntryResource]:\n        \"\"\"Get a list of resources based on criteria\n\n        Warning:\n            This is not to be used for creating a REST API response,\n            but is rather a utility function to easily retrieve a list of resources.\n\n        Parameters:\n            **criteria: Already handled/parsed URL query parameters.\n\n        Returns:\n            A list of resources from the MongoDB (mapped to pydantic models).\n\n        \"\"\"\n        criteria = criteria or {}\n\n        results = []\n        async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n            results.append(self.resource_cls(**self.resource_mapper.map_back(document)))\n\n        return results\n\n    async def create_one(self, resource: EntryResourceCreate) -&gt; EntryResource:\n        \"\"\"Create a new document in the MongoDB collection based on query parameters.\n\n        Update the newly created document with an `\"id\"` field.\n        The value will be the string representation of the `\"_id\"` field.\n        This will only be done if `\"id\"` is not already present in `resource`.\n\n        Parameters:\n            resource: The resource to be created.\n\n        Returns:\n            The newly created document as a pydantic model entry resource.\n\n        \"\"\"\n        resource.last_modified = datetime.now(timezone.utc)\n        result = await self.collection.insert_one(\n            await clean_python_types(resource.model_dump(exclude_unset=True))\n        )\n        LOGGER.debug(\n            \"Inserted resource %r in DB collection %s with ID %s\",\n            resource,\n            self.collection.name,\n            result.inserted_id,\n        )\n\n        if not resource.id:\n            LOGGER.debug(\"Updating resource with an `id` field equal to str(id_).\")\n            await self.collection.update_one(\n                {\"_id\": result.inserted_id}, {\"$set\": {\"id\": str(result.inserted_id)}}\n            )\n\n        return self.resource_cls(\n            **self.resource_mapper.map_back(\n                await self.collection.find_one({\"_id\": result.inserted_id})\n            )\n        )\n\n    async def exists(self, entry_id: str) -&gt; bool:\n        \"\"\"Assert whether entry_id exists in the collection (value of `\"id\"`)\n\n        Parameters:\n            entry_id: The `\"id\"` value of the entry.\n\n        \"\"\"\n        return bool(await self.collection.count_documents({\"id\": entry_id}))\n\n    @staticmethod\n    def _valid_find_keys(**kwargs: dict[str, Any]) -&gt; dict[str, Any]:\n        \"\"\"Return valid MongoDB find() keys with values from kwargs\n\n        Note, not including deprecated flags\n        (see https://pymongo.readthedocs.io/en/3.11.0/api/pymongo/collection.html#pymongo.collection.Collection.find).\n        \"\"\"\n        valid_method_keys = (\n            \"filter\",\n            \"projection\",\n            \"session\",\n            \"skip\",\n            \"limit\",\n            \"no_cursor_timeout\",\n            \"cursor_type\",\n            \"sort\",\n            \"allow_partial_results\",\n            \"batch_size\",\n            \"collation\",\n            \"return_key\",\n            \"show_record_id\",\n            \"hint\",\n            \"max_time_ms\",\n            \"min\",\n            \"max\",\n            \"comment\",\n            \"allow_disk_use\",\n        )\n        criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n        if criteria.get(\"filter\") is None:\n            # Ensure documents are included in the result set\n            criteria[\"filter\"] = {}\n\n        return criteria\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.__init__","title":"<code>__init__(name, resource_cls, resource_mapper)</code>","text":"<p>Initialize the AsyncMongoCollection for the given parameters.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The name of the collection.</p> required <code>resource_cls</code> <code>EntryResource</code> <p>The <code>EntryResource</code> model that is stored by the collection.</p> required <code>resource_mapper</code> <code>BaseResourceMapper</code> <p>A resource mapper object that handles aliases and format changes between deserialization and response.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def __init__(\n    self,\n    name: str,\n    resource_cls: EntryResource,\n    resource_mapper: BaseResourceMapper,\n):\n    \"\"\"Initialize the AsyncMongoCollection for the given parameters.\n\n    Parameters:\n        name: The name of the collection.\n        resource_cls: The `EntryResource` model that is stored by the collection.\n        resource_mapper: A resource mapper object that handles aliases and format\n            changes between deserialization and response.\n\n    \"\"\"\n    from optimade_gateway.mongo.database import (\n        MONGO_DB,\n    )\n\n    super().__init__(\n        resource_cls=resource_cls,\n        resource_mapper=resource_mapper,\n        transformer=MongoTransformer(mapper=resource_mapper),\n    )\n\n    self.parser = LarkParser(version=(1, 0, 0), variant=\"default\")\n    self.collection: MongoCollection = MONGO_DB[name]\n\n    # Check aliases do not clash with mongo operators\n    self._check_aliases(self.resource_mapper.all_aliases())\n    self._check_aliases(self.resource_mapper.all_length_aliases())\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.acount","title":"<code>acount(params=None, **kwargs)</code>  <code>async</code>","text":"<p>Count documents in Collection.</p> <p>This is the asynchronous version of the parent class method named <code>count()</code>.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>None | EntryListingQueryParams | SingleEntryQueryParams</code> <p>URL query parameters, either from a general entry endpoint or a single-entry endpoint.</p> <code>None</code> <code>**kwargs</code> <code>Any</code> <p>Query parameters as keyword arguments. Valid keys will be passed to the <code>AsyncIOMotorCollection.count_documents</code> method.</p> <code>{}</code> <p>Returns:</p> Name Type Description <code>int</code> <code>int</code> <p>The number of entries matching the query specified by the keyword arguments.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def acount(\n    self,\n    params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n    **kwargs: Any,\n) -&gt; int:\n    \"\"\"Count documents in Collection.\n\n    This is the asynchronous version of the parent class method named `count()`.\n\n    Parameters:\n        params: URL query parameters, either from a general entry endpoint or a\n            single-entry endpoint.\n        **kwargs: Query parameters as keyword arguments. Valid keys will be passed\n            to the\n            [`AsyncIOMotorCollection.count_documents`](https://motor.readthedocs.io/en/stable/api-asyncio/asyncio_motor_collection.html#motor.motor_asyncio.AsyncIOMotorCollection.count_documents)\n            method.\n\n    Returns:\n        int: The number of entries matching the query specified by the keyword\n            arguments.\n\n    \"\"\"\n    if params is not None and kwargs:\n        raise ValueError(\n            \"When 'params' is supplied, no other parameters can be supplied.\"\n        )\n\n    if params is not None:\n        kwargs = await self.ahandle_query_params(params)\n\n    valid_method_keys = (\n        \"filter\",\n        \"skip\",\n        \"limit\",\n        \"hint\",\n        \"maxTimeMS\",\n        \"collation\",\n        \"session\",\n    )\n    criteria = {key: kwargs[key] for key in valid_method_keys if key in kwargs}\n\n    if criteria.get(\"filter\") is None:\n        criteria[\"filter\"] = {}\n\n    return await self.collection.count_documents(**criteria)\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.afind","title":"<code>afind(params=None, criteria=None)</code>  <code>async</code>","text":"<p>Perform the query on the underlying MongoDB Collection, handling projection and pagination of the output.</p> <p>This is the asynchronous version of the parent class method named <code>count()</code>.</p> <p>Either provide <code>params</code> or <code>criteria</code>. Not both, but at least one.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>None | EntryListingQueryParams | SingleEntryQueryParams</code> <p>URL query parameters, either from a general entry endpoint or a single-entry endpoint.</p> <code>None</code> <code>criteria</code> <code>dict[str, Any] | None</code> <p>Already handled/parsed URL query parameters.</p> <code>None</code> <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource | None</code> <p>A list of entry resource objects, how much data was returned for the query,</p> <code>int</code> <p>whether more data is available with pagination, and fields (excluded,</p> <code>bool</code> <p>included).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def afind(\n    self,\n    params: None | (EntryListingQueryParams | SingleEntryQueryParams) = None,\n    criteria: dict[str, Any] | None = None,\n) -&gt; tuple[\n    list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n]:\n    \"\"\"Perform the query on the underlying MongoDB Collection, handling projection\n    and pagination of the output.\n\n    This is the asynchronous version of the parent class method named `count()`.\n\n    Either provide `params` or `criteria`. Not both, but at least one.\n\n    Parameters:\n        params: URL query parameters, either from a general entry endpoint or a\n            single-entry endpoint.\n        criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A list of entry resource objects, how much data was returned for the query,\n        whether more data is available with pagination, and fields (excluded,\n        included).\n\n    \"\"\"\n    if (params is None and criteria is None) or (\n        params is not None and criteria is not None\n    ):\n        raise ValueError(\n            \"Exacly one of either `params` and `criteria` must be specified.\"\n        )\n\n    # Set single_entry to False, this is done since if criteria is defined,\n    # this is an unknown factor - better to then get a list of results.\n    single_entry = False\n    if criteria is None:\n        criteria = await self.ahandle_query_params(params)\n    else:\n        single_entry = isinstance(params, SingleEntryQueryParams)\n\n    response_fields = criteria.pop(\"fields\", self.all_fields)\n\n    results, data_returned, more_data_available = await self._arun_db_query(\n        criteria=criteria,\n        single_entry=single_entry,\n    )\n\n    if single_entry:\n        results = results[0] if results else None  # type: ignore[assignment]\n\n        if data_returned &gt; 1:\n            raise NotFound(\n                detail=(\n                    f\"Instead of a single entry, {data_returned} entries were found\"\n                ),\n            )\n\n    include_fields = (\n        response_fields - self.resource_mapper.TOP_LEVEL_NON_ATTRIBUTES_FIELDS\n    )\n    bad_optimade_fields = set()\n    bad_provider_fields = set()\n    for field in include_fields:\n        if field not in self.resource_mapper.ALL_ATTRIBUTES:\n            if field.startswith(\"_\"):\n                if any(\n                    field.startswith(f\"_{prefix}_\")\n                    for prefix in self.resource_mapper.SUPPORTED_PREFIXES\n                ):\n                    bad_provider_fields.add(field)\n            else:\n                bad_optimade_fields.add(field)\n\n    if bad_provider_fields:\n        warn(\n            UnknownProviderProperty(\n                detail=(\n                    \"Unrecognised field(s) for this provider requested in \"\n                    f\"`response_fields`: {bad_provider_fields}.\"\n                )\n            )\n        )\n\n    if bad_optimade_fields:\n        raise BadRequest(\n            detail=(\n                \"Unrecognised OPTIMADE field(s) in requested `response_fields`: \"\n                f\"{bad_optimade_fields}.\"\n            )\n        )\n\n    if results:\n        results = await self.resource_mapper.adeserialize(results)\n\n    return (  # type: ignore[return-value]\n        results,\n        data_returned,\n        more_data_available,\n        self.all_fields - response_fields,\n        include_fields,\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.ahandle_query_params","title":"<code>ahandle_query_params(params)</code>  <code>async</code>","text":"<p>Parse and interpret the backend-agnostic query parameter models into a dictionary that can be used by the specific backend.</p> <p>This is the asynchronous version of the parent class method named <code>handle_query_params()</code>.</p> Note <p>Currently this method returns the pymongo interpretation of the parameters, which will need modification for modified for other backends.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>The initialized query parameter model from the server.</p> required <p>Raises:</p> Type Description <code>Forbidden</code> <p>If too large of a page limit is provided.</p> <code>BadRequest</code> <p>If an invalid request is made, e.g., with incorrect fields or response format.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>A dictionary representation of the query parameters.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def ahandle_query_params(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; dict[str, Any]:\n    \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n    dictionary that can be used by the specific backend.\n\n    This is the asynchronous version of the parent class method named\n    `handle_query_params()`.\n\n    Note:\n        Currently this method returns the pymongo interpretation of the parameters,\n        which will need modification for modified for other backends.\n\n    Parameters:\n        params: The initialized query parameter model from the server.\n\n    Raises:\n        Forbidden: If too large of a page limit is provided.\n        BadRequest: If an invalid request is made, e.g., with incorrect fields or\n            response format.\n\n    Returns:\n        A dictionary representation of the query parameters.\n\n    \"\"\"\n    return super().handle_query_params(params)\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.ainsert","title":"<code>ainsert(data)</code>  <code>async</code>","text":"<p>Add the given entries to the underlying database.</p> <p>This is the asynchronous version of the parent class method named <code>insert()</code>.</p> <p>Parameters:</p> Name Type Description Default <code>data</code> <code>list[EntryResource]</code> <p>The entry resource objects to add to the database.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def ainsert(self, data: list[EntryResource]) -&gt; None:\n    \"\"\"Add the given entries to the underlying database.\n\n    This is the asynchronous version of the parent class method named `insert()`.\n\n    Arguments:\n        data: The entry resource objects to add to the database.\n\n    \"\"\"\n    await self.collection.insert_many(await clean_python_types(data))\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.create_one","title":"<code>create_one(resource)</code>  <code>async</code>","text":"<p>Create a new document in the MongoDB collection based on query parameters.</p> <p>Update the newly created document with an <code>\"id\"</code> field. The value will be the string representation of the <code>\"_id\"</code> field. This will only be done if <code>\"id\"</code> is not already present in <code>resource</code>.</p> <p>Parameters:</p> Name Type Description Default <code>resource</code> <code>EntryResourceCreate</code> <p>The resource to be created.</p> required <p>Returns:</p> Type Description <code>EntryResource</code> <p>The newly created document as a pydantic model entry resource.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def create_one(self, resource: EntryResourceCreate) -&gt; EntryResource:\n    \"\"\"Create a new document in the MongoDB collection based on query parameters.\n\n    Update the newly created document with an `\"id\"` field.\n    The value will be the string representation of the `\"_id\"` field.\n    This will only be done if `\"id\"` is not already present in `resource`.\n\n    Parameters:\n        resource: The resource to be created.\n\n    Returns:\n        The newly created document as a pydantic model entry resource.\n\n    \"\"\"\n    resource.last_modified = datetime.now(timezone.utc)\n    result = await self.collection.insert_one(\n        await clean_python_types(resource.model_dump(exclude_unset=True))\n    )\n    LOGGER.debug(\n        \"Inserted resource %r in DB collection %s with ID %s\",\n        resource,\n        self.collection.name,\n        result.inserted_id,\n    )\n\n    if not resource.id:\n        LOGGER.debug(\"Updating resource with an `id` field equal to str(id_).\")\n        await self.collection.update_one(\n            {\"_id\": result.inserted_id}, {\"$set\": {\"id\": str(result.inserted_id)}}\n        )\n\n    return self.resource_cls(\n        **self.resource_mapper.map_back(\n            await self.collection.find_one({\"_id\": result.inserted_id})\n        )\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.exists","title":"<code>exists(entry_id)</code>  <code>async</code>","text":"<p>Assert whether entry_id exists in the collection (value of <code>\"id\"</code>)</p> <p>Parameters:</p> Name Type Description Default <code>entry_id</code> <code>str</code> <p>The <code>\"id\"</code> value of the entry.</p> required Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def exists(self, entry_id: str) -&gt; bool:\n    \"\"\"Assert whether entry_id exists in the collection (value of `\"id\"`)\n\n    Parameters:\n        entry_id: The `\"id\"` value of the entry.\n\n    \"\"\"\n    return bool(await self.collection.count_documents({\"id\": entry_id}))\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.find","title":"<code>find(params)</code>","text":"<p>Fetches results and indicates if more data is available.</p> <p>Also gives the total number of data available in the absence of <code>page_limit</code>. See <code>EntryListingQueryParams</code> for more information.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>Entry listing URL query params.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | EntryResource | None</code> <p>A tuple of various relevant values:</p> <code>int</code> <p>(<code>results</code>, <code>data_returned</code>, <code>more_data_available</code>, <code>exclude_fields</code>,</p> <code>bool</code> <p><code>include_fields</code>).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def find(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; tuple[\n    list[EntryResource] | EntryResource | None, int, bool, set[str], set[str]\n]:\n    \"\"\"\n    Fetches results and indicates if more data is available.\n\n    Also gives the total number of data available in the absence of `page_limit`.\n    See\n    [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n    for more information.\n\n    Parameters:\n        params: Entry listing URL query params.\n\n    Returns:\n        A tuple of various relevant values:\n        (`results`, `data_returned`, `more_data_available`, `exclude_fields`,\n        `include_fields`).\n\n    \"\"\"\n    raise NotImplementedError(\n        \"This method cannot be used with this class and is a remnant from the \"\n        \"parent class. Use instead the asynchronous method `afind(params: \"\n        \"Optional[Union[EntryListingQueryParams, SingleEntryQueryParams]], \"\n        \"criteria: Optional[Dict[str, Any]])`.\"\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.get_multiple","title":"<code>get_multiple(**criteria)</code>  <code>async</code>","text":"<p>Get a list of resources based on criteria</p> Warning <p>This is not to be used for creating a REST API response, but is rather a utility function to easily retrieve a list of resources.</p> <p>Parameters:</p> Name Type Description Default <code>**criteria</code> <code>Any</code> <p>Already handled/parsed URL query parameters.</p> <code>{}</code> <p>Returns:</p> Type Description <code>list[EntryResource]</code> <p>A list of resources from the MongoDB (mapped to pydantic models).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def get_multiple(self, **criteria: Any) -&gt; list[EntryResource]:\n    \"\"\"Get a list of resources based on criteria\n\n    Warning:\n        This is not to be used for creating a REST API response,\n        but is rather a utility function to easily retrieve a list of resources.\n\n    Parameters:\n        **criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A list of resources from the MongoDB (mapped to pydantic models).\n\n    \"\"\"\n    criteria = criteria or {}\n\n    results = []\n    async for document in self.collection.find(**self._valid_find_keys(**criteria)):\n        results.append(self.resource_cls(**self.resource_mapper.map_back(document)))\n\n    return results\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.get_one","title":"<code>get_one(**criteria)</code>  <code>async</code>","text":"<p>Get one resource based on criteria</p> Warning <p>This is not to be used for creating a REST API response, but is rather a utility function to easily retrieve a single resource.</p> <p>Parameters:</p> Name Type Description Default <code>**criteria</code> <code>Any</code> <p>Already handled/parsed URL query parameters.</p> <code>{}</code> <p>Returns:</p> Type Description <code>EntryResource</code> <p>A single resource from the MongoDB (mapped to pydantic models).</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>async def get_one(self, **criteria: Any) -&gt; EntryResource:\n    \"\"\"Get one resource based on criteria\n\n    Warning:\n        This is not to be used for creating a REST API response,\n        but is rather a utility function to easily retrieve a single resource.\n\n    Parameters:\n        **criteria: Already handled/parsed URL query parameters.\n\n    Returns:\n        A single resource from the MongoDB (mapped to pydantic models).\n\n    \"\"\"\n    criteria = criteria or {}\n\n    return self.resource_cls(\n        **self.resource_mapper.map_back(\n            await self.collection.find_one(**self._valid_find_keys(**criteria))\n        )\n    )\n</code></pre>"},{"location":"api_reference/mongo/collection/#optimade_gateway.mongo.collection.AsyncMongoCollection.handle_query_params","title":"<code>handle_query_params(params)</code>","text":"<p>Parse and interpret the backend-agnostic query parameter models into a dictionary that can be used by the specific backend.</p> Note <p>Currently this method returns the pymongo interpretation of the parameters, which will need modification for modified for other backends.</p> <p>Parameters:</p> Name Type Description Default <code>params</code> <code>EntryListingQueryParams | SingleEntryQueryParams</code> <p>The initialized query parameter model from the server.</p> required <p>Raises:</p> Type Description <code>Forbidden</code> <p>If too large of a page limit is provided.</p> <code>BadRequest</code> <p>If an invalid request is made, e.g., with incorrect fields or response format.</p> <p>Returns:</p> Type Description <code>dict[str, Any]</code> <p>A dictionary representation of the query parameters.</p> Source code in <code>optimade_gateway/mongo/collection.py</code> <pre><code>def handle_query_params(\n    self, params: EntryListingQueryParams | SingleEntryQueryParams\n) -&gt; dict[str, Any]:\n    \"\"\"Parse and interpret the backend-agnostic query parameter models into a\n    dictionary that can be used by the specific backend.\n\n    Note:\n        Currently this method returns the pymongo interpretation of the parameters,\n        which will need modification for modified for other backends.\n\n    Parameters:\n        params: The initialized query parameter model from the server.\n\n    Raises:\n        Forbidden: If too large of a page limit is provided.\n        BadRequest: If an invalid request is made, e.g., with incorrect fields\n            or response format.\n\n    Returns:\n        A dictionary representation of the query parameters.\n\n    \"\"\"\n    raise NotImplementedError(\n        \"This method cannot be used with this class and is a remnant from the \"\n        \"parent class. Use instead the asynchronous method \"\n        \"`ahandle_query_params(params: Union[EntryListingQueryParams, \"\n        \"SingleEntryQueryParams])`.\"\n    )\n</code></pre>"},{"location":"api_reference/mongo/database/","title":"database","text":"<p>Initialize the MongoDB database.</p>"},{"location":"api_reference/mongo/database/#optimade_gateway.mongo.database.MONGO_CLIENT","title":"<code>MONGO_CLIENT = AsyncIOMotorClient(CONFIG.mongo_uri, **mongo_client_configuration)</code>  <code>module-attribute</code>","text":"<p>The MongoDB motor client.</p>"},{"location":"api_reference/mongo/database/#optimade_gateway.mongo.database.MONGO_DB","title":"<code>MONGO_DB = MONGO_CLIENT[CONFIG.mongo_database]</code>  <code>module-attribute</code>","text":"<p>The MongoDB motor database. This is a representation of the database used for the gateway service.</p>"},{"location":"api_reference/queries/params/","title":"params","text":"<p>URL query parameters.</p>"},{"location":"api_reference/queries/params/#optimade_gateway.queries.params.SearchQueryParams","title":"<code>SearchQueryParams</code>","text":"<p>URL query parameters for <code>GET /search</code></p> <p>This is an extension of the <code>EntryListingQueryParams</code> class in <code>optimade</code>, which defines the standard entry listing endpoint query parameters.</p> <p>The extra query parameters are as follows.</p> <p>Attributes:</p> Name Type Description <code>database_ids</code> <code>set[str]</code> <p>List of possible database IDs that are already known by the gateway. To be known they need to be registered with the gateway (currently not possible).</p> <code>optimade_urls</code> <code>set[AnyUrl]</code> <p>A list of OPTIMADE base URLs. If a versioned base URL is supplied it will be used as is, as long as it represents a supported version. If an un-versioned base URL, standard version negotiation will be conducted to get the versioned base URL, which will be used as long as it represents a supported version.</p> <p>Example: <code>http://example.org/optimade/v1/search?optimade_urls=\"https://example.org/optimade_db/v1\",\"https://optimade.herokuapp.com\"</code></p> <code>endpoint</code> <code>str</code> <p>The entry endpoint queried. According to the OPTIMADE specification, this is the same as the resource's type.</p> <p>Example: <code>structures</code></p> <code>timeout</code> <code>int</code> <p>Timeout time (in seconds) to wait for a query to finish before redirecting (after starting the query). Note, if the query has not finished after the timeout time, a redirection will still be performed, but to a zero-results page, which can be refreshed to get the finished query (once it has finished).</p> <code>as_optimade</code> <code>bool</code> <p>Return the response as a standard OPTIMADE entry listing endpoint response. Otherwise, the response will be based on the <code>QueriesResponseSingle</code> model.</p> Source code in <code>optimade_gateway/queries/params.py</code> <pre><code>class SearchQueryParams:\n    \"\"\"URL query parameters for `GET /search`\n\n    This is an extension of the\n    [`EntryListingQueryParams`](https://www.optimade.org/optimade-python-tools/api_reference/server/query_params/#optimade.server.query_params.EntryListingQueryParams)\n    class in `optimade`, which defines the standard entry listing endpoint query\n    parameters.\n\n    The extra query parameters are as follows.\n\n    Attributes:\n        database_ids (set[str]): List of possible database IDs that are already known by\n            the gateway. To be known they need to be registered with the gateway\n            (currently not possible).\n\n        optimade_urls (set[AnyUrl]): A list of OPTIMADE base URLs. If a versioned base\n            URL is supplied it will be used as is, as long as it represents a supported\n            version. If an un-versioned base URL, standard version negotiation will be\n            conducted to get the versioned base URL, which will be used as long as it\n            represents a supported version.\n\n            **Example**: `http://example.org/optimade/v1/search?optimade_urls=\"https://example.org/optimade_db/v1\",\"https://optimade.herokuapp.com\"`\n\n        endpoint (str): The entry endpoint queried. According to the OPTIMADE\n            specification, this is the same as the resource's type.\n\n            **Example**: `structures`\n\n        timeout (int): Timeout time (in seconds) to wait for a query to finish before\n            redirecting (*after* starting the query). Note, if the query has not\n            finished after the timeout time, a redirection will still be performed, but\n            to a zero-results page, which can be refreshed to get the finished query\n            (once it has finished).\n\n        as_optimade (bool): Return the response as a standard OPTIMADE entry listing\n            endpoint response. Otherwise, the response will be based on the\n            [`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\n            model.\n\n    \"\"\"\n\n    def __init__(\n        self,\n        *,\n        database_ids: Annotated[\n            set[str],\n            Query(\n                description=(\n                    \"Unique list of possible database IDs that are already known by \"\n                    \"the gateway. To be known they need to be registered with the \"\n                    \"gateway (currently not possible).\"\n                ),\n            ),\n        ] = set(),\n        optimade_urls: Annotated[\n            set[AnyUrl],\n            Query(\n                description=(\n                    \"A unique list of OPTIMADE base URLs. If a versioned base URL is \"\n                    \"supplied it will be used as is, as long as it represents a \"\n                    \"supported version. If an un-versioned base URL, standard version \"\n                    \"negotiation will be conducted to get the versioned base URL, \"\n                    \"which will be used as long as it represents a supported version.\"\n                ),\n            ),\n        ] = set(),\n        endpoint: Annotated[\n            str,\n            Query(\n                description=(\n                    \"The entry endpoint queried. According to the OPTIMADE \"\n                    \"specification, this is the same as the resource's type.\"\n                ),\n            ),\n        ] = \"structures\",\n        timeout: Annotated[\n            int,\n            Query(\n                description=(\n                    \"Timeout time (in seconds) to wait for a query to finish before \"\n                    \"redirecting (*after* starting the query). Note, if the query has \"\n                    \"not finished after the timeout time, a redirection will still be \"\n                    \"performed, but to a zero-results page, which can be refreshed to \"\n                    \"get the finished query (once it has finished).\"\n                ),\n            ),\n        ] = 15,\n        as_optimade: Annotated[\n            bool,\n            Query(\n                description=(\n                    \"Return the response as a standard OPTIMADE entry listing endpoint \"\n                    \"response. Otherwise, the response will be based on the \"\n                    \"[`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\"\n                    \" model.\"\n                ),\n            ),\n        ] = False,\n    ) -&gt; None:\n        self.database_ids = database_ids\n        self.optimade_urls = optimade_urls\n        self.endpoint = endpoint\n        self.timeout = timeout\n        self.as_optimade = as_optimade\n</code></pre>"},{"location":"api_reference/queries/perform/","title":"perform","text":"<p>Perform OPTIMADE queries</p>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.db_find","title":"<code>db_find(database, endpoint, response_model, query_params='', raw_url=None)</code>","text":"<p>Imitate <code>Collection.find()</code> for any given database for entry-resource endpoints</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>LinksResource | dict[str, Any]</code> <p>The OPTIMADE implementation to be queried. It must have a valid base URL and id.</p> required <code>endpoint</code> <code>str</code> <p>The entry-listing endpoint, e.g., <code>\"structures\"</code>.</p> required <code>response_model</code> <code>EntryResponseMany | EntryResponseOne</code> <p>The expected OPTIMADE pydantic response model, e.g., <code>optimade.models.StructureResponseMany</code>.</p> required <code>query_params</code> <code>str</code> <p>URL query parameters to pass to the database.</p> <code>''</code> <code>raw_url</code> <code>AnyUrl | str | None</code> <p>A raw URL to use straight up instead of deriving a URL from <code>database</code>, <code>endpoint</code>, and <code>query_params</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>tuple[ErrorResponse | EntryResponseMany | EntryResponseOne, str]</code> <p>Response as an <code>optimade</code> pydantic model and the <code>database</code>'s ID.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>def db_find(\n    database: LinksResource | dict[str, Any],\n    endpoint: str,\n    response_model: EntryResponseMany | EntryResponseOne,\n    query_params: str = \"\",\n    raw_url: AnyUrl | str | None = None,\n) -&gt; tuple[ErrorResponse | EntryResponseMany | EntryResponseOne, str]:\n    \"\"\"Imitate `Collection.find()` for any given database for entry-resource endpoints\n\n    Parameters:\n        database: The OPTIMADE implementation to be queried.\n            It **must** have a valid base URL and id.\n        endpoint: The entry-listing endpoint, e.g., `\"structures\"`.\n        response_model: The expected OPTIMADE pydantic response model, e.g.,\n            `optimade.models.StructureResponseMany`.\n        query_params: URL query parameters to pass to the database.\n        raw_url: A raw URL to use straight up instead of deriving a URL from `database`,\n            `endpoint`, and `query_params`.\n\n    Returns:\n        Response as an `optimade` pydantic model and the `database`'s ID.\n\n    \"\"\"\n    if TYPE_CHECKING or bool(os.getenv(\"MKDOCS_BUILD\", \"\")):  # pragma: no cover\n        response: (\n            httpx.Response\n            | dict[str, Any]\n            | EntryResponseMany\n            | EntryResponseOne\n            | ErrorResponse\n        )\n\n    if raw_url:\n        url = str(raw_url)\n    else:\n        url = \"\"\n\n        base_url = str(get_resource_attribute(database, \"attributes.base_url\")).rstrip(\n            \"/\"\n        )\n        url += base_url\n\n        # Check whether base_url is a versioned base URL\n        if not any(base_url.endswith(_) for _ in BASE_URL_PREFIXES.values()):\n            # Unversioned base URL - add the currently supported major version\n            url += BASE_URL_PREFIXES[\"major\"]\n\n        url += f\"/{endpoint.strip('/')}?{query_params}\"\n\n    response = httpx.get(url, timeout=60)\n\n    try:\n        response = response.json()\n    except json.JSONDecodeError:\n        return (\n            ErrorResponse(\n                errors=[\n                    {\n                        \"detail\": f\"Could not JSONify response from {url}\",\n                        \"id\": \"OPTIMADE_GATEWAY_DB_FIND_MANY_JSONDECODEERROR\",\n                    }\n                ],\n                meta={\n                    \"query\": {\n                        \"representation\": f\"/{endpoint.strip('/')}?{query_params}\"\n                    },\n                    \"api_version\": __api_version__,\n                    \"more_data_available\": False,\n                },\n            ),\n            get_resource_attribute(database, \"id\"),\n        )\n\n    try:\n        response = response_model(**response)\n    except ValidationError:\n        try:\n            response = ErrorResponse(**response)\n        except ValidationError as exc:\n            # If it's an error and `meta` is missing, it is not a valid OPTIMADE\n            # response, but this happens a lot, and is therefore worth having an\n            # edge-case for.\n            if \"errors\" in response:\n                errors = list(response[\"errors\"])\n                errors.append(\n                    {\n                        \"detail\": (\n                            f\"Could not pass response from {url} as either a \"\n                            f\"{response_model.__name__!r} or 'ErrorResponse'. \"\n                            f\"ValidationError: {exc}\"\n                        ),\n                        \"id\": \"OPTIMADE_GATEWAY_DB_FINDS_MANY_VALIDATIONERRORS\",\n                    }\n                )\n                return (\n                    ErrorResponse(\n                        errors=errors,\n                        meta={\n                            \"query\": {\n                                \"representation\": (\n                                    f\"/{endpoint.strip('/')}?{query_params}\"\n                                )\n                            },\n                            \"api_version\": __api_version__,\n                            \"more_data_available\": False,\n                        },\n                    ),\n                    get_resource_attribute(database, \"id\"),\n                )\n\n            return (\n                ErrorResponse(\n                    errors=[\n                        {\n                            \"detail\": (\n                                f\"Could not pass response from {url} as either a \"\n                                f\"{response_model.__name__!r} or 'ErrorResponse'. \"\n                                f\"ValidationError: {exc}\"\n                            ),\n                            \"id\": \"OPTIMADE_GATEWAY_DB_FINDS_MANY_VALIDATIONERRORS\",\n                        }\n                    ],\n                    meta={\n                        \"query\": {\n                            \"representation\": f\"/{endpoint.strip('/')}?{query_params}\"\n                        },\n                        \"api_version\": __api_version__,\n                        \"more_data_available\": False,\n                    },\n                ),\n                get_resource_attribute(database, \"id\"),\n            )\n\n    return response, get_resource_attribute(database, \"id\")\n</code></pre>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.db_get_all_resources","title":"<code>db_get_all_resources(database, endpoint, response_model, query_params='', raw_url=None)</code>  <code>async</code>","text":"<p>Recursively retrieve all resources from an entry-listing endpoint</p> <p>This function keeps pulling the <code>links.next</code> link if <code>meta.more_data_available</code> is <code>True</code> to ultimately retrieve all entries for <code>endpoint</code>.</p> <p>Warning</p> <p>This function can be dangerous if an endpoint with hundreds or thousands of entries is requested.</p> <p>Parameters:</p> Name Type Description Default <code>database</code> <code>LinksResource | dict[str, Any]</code> <p>The OPTIMADE implementation to be queried. It must have a valid base URL and id.</p> required <code>endpoint</code> <code>str</code> <p>The entry-listing endpoint, e.g., <code>\"structures\"</code>.</p> required <code>response_model</code> <code>EntryResponseMany</code> <p>The expected OPTIMADE pydantic response model, e.g., <code>optimade.models.StructureResponseMany</code>.</p> required <code>query_params</code> <code>str</code> <p>URL query parameters to pass to the database.</p> <code>''</code> <code>raw_url</code> <code>AnyUrl | str | None</code> <p>A raw URL to use straight up instead of deriving a URL from <code>database</code>, <code>endpoint</code>, and <code>query_params</code>.</p> <code>None</code> <p>Returns:</p> Type Description <code>tuple[list[EntryResource | dict[str, Any]], LinksResource | dict[str, Any]]</code> <p>A collected list of successful responses' <code>data</code> value and the <code>database</code>'s ID.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>async def db_get_all_resources(\n    database: LinksResource | dict[str, Any],\n    endpoint: str,\n    response_model: EntryResponseMany,\n    query_params: str = \"\",\n    raw_url: AnyUrl | str | None = None,\n) -&gt; tuple[list[EntryResource | dict[str, Any]], LinksResource | dict[str, Any]]:\n    \"\"\"Recursively retrieve all resources from an entry-listing endpoint\n\n    This function keeps pulling the `links.next` link if `meta.more_data_available` is\n    `True` to ultimately retrieve *all* entries for `endpoint`.\n\n    !!! warning\n        This function can be dangerous if an endpoint with hundreds or thousands of\n        entries is requested.\n\n    Parameters:\n        database: The OPTIMADE implementation to be queried.\n            It **must** have a valid base URL and id.\n        endpoint: The entry-listing endpoint, e.g., `\"structures\"`.\n        response_model: The expected OPTIMADE pydantic response model, e.g.,\n            `optimade.models.StructureResponseMany`.\n        query_params: URL query parameters to pass to the database.\n        raw_url: A raw URL to use straight up instead of deriving a URL from `database`,\n            `endpoint`, and `query_params`.\n\n    Returns:\n        A collected list of successful responses' `data` value and the `database`'s ID.\n\n    \"\"\"\n    resulting_resources = []\n\n    response, _ = db_find(\n        database=database,\n        endpoint=endpoint,\n        response_model=response_model,\n        query_params=query_params,\n        raw_url=raw_url,\n    )\n\n    if isinstance(response, ErrorResponse):\n        # An errored response will result in no databases from a provider.\n        LOGGER.error(\n            \"Error while querying database (id=%r). Full response: %s\",\n            get_resource_attribute(database, \"id\"),\n            response.model_dump_json(indent=2),\n        )\n        return [], database\n\n    resulting_resources.extend(response.data)\n\n    if response.meta.more_data_available:\n        next_page = get_resource_attribute(response, \"links.next\")\n        if next_page is None:\n            LOGGER.error(\n                \"Could not find a 'next' link for an OPTIMADE query request to %r \"\n                \"(id=%r). Cannot get all resources from /%s, even though this was \"\n                \"asked and `more_data_available` is `True` in the response.\",\n                get_resource_attribute(database, \"attributes.name\", \"N/A\"),\n                get_resource_attribute(database, \"id\"),\n                endpoint,\n            )\n            return resulting_resources, database\n\n        more_resources, _ = await db_get_all_resources(\n            database=database,\n            endpoint=endpoint,\n            response_model=response_model,\n            query_params=query_params,\n            raw_url=next_page,\n        )\n        resulting_resources.extend(more_resources)\n\n    return resulting_resources, database\n</code></pre>"},{"location":"api_reference/queries/perform/#optimade_gateway.queries.perform.perform_query","title":"<code>perform_query(url, query)</code>  <code>async</code>","text":"<p>Perform OPTIMADE query with gateway.</p> <p>Parameters:</p> Name Type Description Default <code>url</code> <code>URL</code> <p>Original request URL.</p> required <code>query</code> <code>QueryResource</code> <p>The query to be performed.</p> required <p>Returns:</p> Type Description <code>EntryResponseMany | ErrorResponse | GatewayQueryResponse</code> <p>This function returns the final response; a</p> <code>EntryResponseMany | ErrorResponse | GatewayQueryResponse</code> <p><code>GatewayQueryResponse</code>.</p> Source code in <code>optimade_gateway/queries/perform.py</code> <pre><code>async def perform_query(\n    url: URL,\n    query: QueryResource,\n) -&gt; EntryResponseMany | ErrorResponse | GatewayQueryResponse:\n    \"\"\"Perform OPTIMADE query with gateway.\n\n    Parameters:\n        url: Original request URL.\n        query: The query to be performed.\n\n    Returns:\n        This function returns the final response; a\n        [`GatewayQueryResponse`][optimade_gateway.models.queries.GatewayQueryResponse].\n\n    \"\"\"\n    await update_query(query, \"state\", QueryState.STARTED)\n\n    gateway: GatewayResource = await get_valid_resource(\n        await collection_factory(CONFIG.gateways_collection),\n        query.attributes.gateway_id,\n    )\n\n    filter_queries = await prepare_query_filter(\n        database_ids=[_.id for _ in gateway.attributes.databases],\n        filter_query=query.attributes.query_parameters.filter,\n    )\n\n    url = url.replace(path=f\"{url.path.rstrip('/')}/{query.id}\")\n    await update_query(\n        query,\n        \"response\",\n        GatewayQueryResponse(\n            data={},\n            links=ToplevelLinks(next=None),\n            meta=meta_values(\n                url=url,\n                data_available=0,\n                data_returned=0,\n                more_data_available=False,\n                schema=CONFIG.schema_url,\n            ),\n        ),\n        operator=None,\n        **{\"$set\": {\"state\": QueryState.IN_PROGRESS}},\n    )\n\n    loop = asyncio.get_running_loop()\n    with ThreadPoolExecutor(\n        max_workers=min(\n            32, (os.cpu_count() or 0) + 4, len(gateway.attributes.databases)\n        )\n    ) as executor:\n        # Run OPTIMADE DB queries in a thread pool, i.e., not using the main OS thread,\n        # where the asyncio event loop is running.\n        query_tasks = []\n        for database in gateway.attributes.databases:\n            query_params = await get_query_params(\n                query_parameters=query.attributes.query_parameters,\n                database_id=database.id,\n                filter_mapping=filter_queries,\n            )\n            query_tasks.append(\n                loop.run_in_executor(\n                    executor=executor,\n                    func=functools.partial(\n                        db_find,\n                        database=database,\n                        endpoint=query.attributes.endpoint.value,\n                        response_model=query.attributes.endpoint.get_response_model(),\n                        query_params=query_params,\n                    ),\n                )\n            )\n\n        for query_task in query_tasks:\n            (db_response, db_id) = await query_task\n\n            await process_db_response(\n                response=db_response,\n                database_id=db_id,\n                query=query,\n                gateway=gateway,\n            )\n\n    # Pagination\n    #\n    # if isinstance(results, list) and get_resource_attribute(\n    #     query,\n    #     \"attributes.response.meta.more_data_available\",\n    #     False,\n    #     disambiguate=False,  # Extremely minor speed-up\n    # ):\n    #     # Deduce the `next` link from the current request\n    #     query_string = urllib.parse.parse_qs(url.query)\n    #     query_string[\"page_offset\"] = [\n    #         int(query_string.get(\"page_offset\", [0])[0])  # type: ignore[list-item]\n    #         + len(results[: query.attributes.query_parameters.page_limit])\n    #     ]\n    #     urlencoded = urllib.parse.urlencode(query_string, doseq=True)\n    #     base_url = get_base_url(url)\n\n    #     links = ToplevelLinks(next=f\"{base_url}{url.path}?{urlencoded}\")\n\n    #     await update_query(query, \"response.links\", links)\n\n    await update_query(query, \"state\", QueryState.FINISHED)\n    return query.attributes.response\n</code></pre>"},{"location":"api_reference/queries/prepare/","title":"prepare","text":"<p>Prepare OPTIMADE queries.</p>"},{"location":"api_reference/queries/prepare/#optimade_gateway.queries.prepare.get_query_params","title":"<code>get_query_params(query_parameters, database_id, filter_mapping)</code>  <code>async</code>","text":"<p>Construct the parsed URL query parameters</p> Source code in <code>optimade_gateway/queries/prepare.py</code> <pre><code>async def get_query_params(\n    query_parameters: OptimadeQueryParameters,\n    database_id: str,\n    filter_mapping: Mapping[str, str | None],\n) -&gt; str:\n    \"\"\"Construct the parsed URL query parameters\"\"\"\n    query_params = {\n        param: value for param, value in query_parameters.model_dump().items() if value\n    }\n    if filter_mapping[database_id]:\n        query_params.update({\"filter\": filter_mapping[database_id]})\n    return urllib.parse.urlencode(query_params)\n</code></pre>"},{"location":"api_reference/queries/prepare/#optimade_gateway.queries.prepare.prepare_query_filter","title":"<code>prepare_query_filter(database_ids, filter_query)</code>  <code>async</code>","text":"<p>Update the query parameter <code>filter</code> value to be database-specific</p> <p>This is needed due to the served change of <code>id</code> values. If someone searches for a gateway-changed <code>id</code>, it needs to be reverted to be database-specific.</p> <p>Parameters:</p> Name Type Description Default <code>database_ids</code> <code>list[str]</code> <p>List of the databases to create updated filter values for. These values are part of the gateway-changed <code>id</code> values and are essential.</p> required <code>filter_query</code> <code>str | None</code> <p>The submitted <code>filter</code> query parameter value. Can be <code>None</code> if not supplied.</p> required <p>Returns:</p> Type Description <code>Mapping[str, str | None]</code> <p>A mapping for database IDs to database-specific <code>filter</code> query parameter values.</p> Source code in <code>optimade_gateway/queries/prepare.py</code> <pre><code>async def prepare_query_filter(\n    database_ids: list[str], filter_query: str | None\n) -&gt; Mapping[str, str | None]:\n    \"\"\"Update the query parameter `filter` value to be database-specific\n\n    This is needed due to the served change of `id` values.\n    If someone searches for a gateway-changed `id`, it needs to be reverted to be\n    database-specific.\n\n    Parameters:\n        database_ids: List of the databases to create updated filter values for.\n            These values are part of the gateway-changed `id` values and are essential.\n        filter_query: The submitted `filter` query parameter value. Can be `None` if not\n            supplied.\n\n    Returns:\n        A mapping for database IDs to database-specific `filter` query parameter values.\n\n    \"\"\"\n    updated_filter = {}.fromkeys(database_ids, filter_query)\n\n    if not filter_query:\n        return updated_filter\n\n    for id_match in re.finditer(\n        r'\"(?P&lt;id_value_l&gt;[^\\s]*)\"[\\s]*'\n        r\"(&lt;|&gt;|&lt;=|&gt;=|=|!=|CONTAINS|STARTS WITH|ENDS WITH|STARTS|ENDS)\"\n        r\"[\\s]*id|[^_]+id[\\s]*\"\n        r'(&lt;|&gt;|&lt;=|&gt;=|=|!=|CONTAINS|STARTS WITH|ENDS WITH|STARTS|ENDS)[\\s]*\"'\n        r'(?P&lt;id_value_r&gt;[^\\s]*)\"',\n        f\"={filter_query}\" if filter_query else \"\",\n    ):\n        matched_id: str = id_match.group(\"id_value_l\") or id_match.group(\"id_value_r\")\n        for database_id in database_ids:\n            if matched_id.startswith(f\"{database_id}/\"):\n                updated_filter_query = updated_filter[database_id]\n                if not updated_filter_query or not isinstance(\n                    updated_filter_query, str\n                ):\n                    raise TypeError(\n                        \"Expected a string for filter query, got \"\n                        f\"{type(updated_filter_query)}\"\n                    )\n\n                # Database found\n                updated_filter[database_id] = updated_filter_query.replace(\n                    f\"{database_id}/\", \"\", 1\n                )\n                break\n        else:\n            warn(\n                OptimadeGatewayWarning(\n                    title=\"Non-Unique Entry ID\",\n                    detail=(\n                        f\"The passed entry ID &lt;id={matched_id}&gt; may be ambiguous! To \"\n                        \"get a specific structures entry, one can prepend the ID with \"\n                        \"a database ID belonging to the gateway, followed by a forward\"\n                        f\" slash, e.g., '{database_ids[0]}/&lt;local_database_ID&gt;'. \"\n                        f\"Available databases for this gateway: {database_ids}\"\n                    ),\n                )\n            )\n    return updated_filter\n</code></pre>"},{"location":"api_reference/queries/process/","title":"process","text":"<p>Process performed OPTIMADE queries.</p>"},{"location":"api_reference/queries/process/#optimade_gateway.queries.process.process_db_response","title":"<code>process_db_response(response, database_id, query, gateway)</code>  <code>async</code>","text":"<p>Process an OPTIMADE database response.</p> <p>The passed <code>query</code> will be updated with the top-level <code>meta</code> information: <code>data_available</code>, <code>data_returned</code>, and <code>more_data_available</code>.</p> <p>Since, only either <code>data</code> or <code>errors</code> should ever be present, one or the other will be either an empty list or <code>None</code>.</p> <p>Parameters:</p> Name Type Description Default <code>response</code> <code>ErrorResponse | EntryResponseMany | EntryResponseOne</code> <p>The OPTIMADE database response to be processed.</p> required <code>database_id</code> <code>str</code> <p>The database's <code>id</code> under which the returned resources or errors will be delivered.</p> required <code>query</code> <code>QueryResource</code> <p>A resource representing the performed query.</p> required <code>gateway</code> <code>GatewayResource</code> <p>A resource representing the gateway that was queried.</p> required <p>Returns:</p> Type Description <code>list[EntryResource] | list[dict[str, Any]] | EntryResource | dict[str, Any] | None</code> <p>The response's <code>data</code>.</p> Source code in <code>optimade_gateway/queries/process.py</code> <pre><code>async def process_db_response(\n    response: ErrorResponse | EntryResponseMany | EntryResponseOne,\n    database_id: str,\n    query: QueryResource,\n    gateway: GatewayResource,\n) -&gt; list[EntryResource] | list[dict[str, Any]] | EntryResource | dict[str, Any] | None:\n    \"\"\"Process an OPTIMADE database response.\n\n    The passed `query` will be updated with the top-level `meta` information:\n    `data_available`, `data_returned`, and `more_data_available`.\n\n    Since, only either `data` or `errors` should ever be present, one or the other will\n    be either an empty list or `None`.\n\n    Parameters:\n        response: The OPTIMADE database response to be processed.\n        database_id: The database's `id` under which the returned resources or errors\n            will be delivered.\n        query: A resource representing the performed query.\n        gateway: A resource representing the gateway that was queried.\n\n    Returns:\n        The response's `data`.\n\n    \"\"\"\n    results = []\n    errors = []\n\n    LOGGER.debug(\"Starting to process database_id: %s\", database_id)\n\n    if isinstance(response, ErrorResponse):\n        for error in response.errors:\n            if isinstance(error.id, str) and error.id.startswith(\"OPTIMADE_GATEWAY\"):\n                warn(error.detail, OptimadeGatewayWarning)\n            else:\n                # The model `ErrorResponse` does not allow the objects in the top-level\n                # `errors` list to be parsed as dictionaries - they must be a pydantic\n                # model.\n                meta_error = {}\n                if error.meta:\n                    meta_error = error.meta.model_dump()\n                meta_error.update(\n                    {\n                        f\"_{CONFIG.provider.prefix}_source_gateway\": {\n                            \"id\": gateway.id,\n                            \"type\": gateway.type,\n                            \"links\": {\"self\": gateway.links.self},\n                        },\n                        f\"_{CONFIG.provider.prefix}_source_database\": {\n                            \"id\": database_id,\n                            \"type\": \"links\",\n                            \"links\": {\n                                \"self\": (\n                                    str(gateway.links.self).split(\n                                        \"gateways\", maxsplit=1\n                                    )[0]\n                                    + f\"databases/{database_id}\"\n                                )\n                            },\n                        },\n                    }\n                )\n                error.meta = Meta(**meta_error)\n                errors.append(error)\n        data_returned = 0\n        more_data_available = False\n    else:\n        results = response.data\n\n        if isinstance(results, list):\n            data_returned = response.meta.data_returned or len(results)\n        else:\n            data_returned = response.meta.data_returned or (0 if not results else 1)\n\n        more_data_available = response.meta.more_data_available or False\n\n    data_available = response.meta.data_available or 0\n\n    extra_updates = {\n        \"$inc\": {\n            \"response.meta.data_available\": data_available,\n            \"response.meta.data_returned\": data_returned,\n        }\n    }\n    if not get_resource_attribute(\n        query,\n        \"attributes.response.meta.more_data_available\",\n        False,\n        disambiguate=False,  # Extremely minor speed-up\n    ):\n        # Keep it True, if set to True once.\n        extra_updates.update(\n            {\"$set\": {\"response.meta.more_data_available\": more_data_available}}\n        )\n\n    # This ensures an empty list under `response.data.{database_id}` is returned if the\n    # case is simply that there are no results to return.\n    if errors:\n        extra_updates.update({\"$addToSet\": {\"response.errors\": {\"$each\": errors}}})\n    await update_query(\n        query,\n        f\"response.data.{database_id}\",\n        results,\n        operator=None,\n        **extra_updates,\n    )\n\n    return results\n</code></pre>"},{"location":"api_reference/queries/utils/","title":"utils","text":"<p>Utility functions for the <code>queries</code> module.</p>"},{"location":"api_reference/queries/utils/#optimade_gateway.queries.utils.update_query","title":"<code>update_query(query, field, value, operator=None, **mongo_kwargs)</code>  <code>async</code>","text":"<p>Update a query's <code>field</code> attribute with <code>value</code>.</p> <p>If <code>field</code> is a dot-separated value, then only the last field part may be a non-pre-existing field. Otherwise a <code>KeyError</code> or <code>AttributeError</code> will be raised.</p> <p>Note</p> <p>This can only update a field for a query's <code>attributes</code>, i.e., this function cannot update <code>id</code>, <code>type</code> or any other top-level resource field.</p> <p>Important</p> <p><code>mongo_kwargs</code> will not be considered for updating the pydantic model instance.</p> <p>Parameters:</p> Name Type Description Default <code>query</code> <code>QueryResource</code> <p>The query to be updated.</p> required <code>field</code> <code>str</code> <p>The <code>attributes</code> field (key) to be set. This can be a dot-separated key value to signify embedded fields.</p> <p>Example: <code>response.meta</code>.</p> required <code>value</code> <code>Any</code> <p>The (possibly) new value for <code>field</code>.</p> required <code>operator</code> <code>str | None</code> <p>A MongoDB operator to be used for updating <code>field</code> with <code>value</code>.</p> <code>None</code> <code>**mongo_kwargs</code> <code>Any</code> <p>Further MongoDB update filters.</p> <code>{}</code> Source code in <code>optimade_gateway/queries/utils.py</code> <pre><code>async def update_query(\n    query: QueryResource,\n    field: str,\n    value: Any,\n    operator: str | None = None,\n    **mongo_kwargs: Any,\n) -&gt; None:\n    \"\"\"Update a query's `field` attribute with `value`.\n\n    If `field` is a dot-separated value, then only the last field part may be a\n    non-pre-existing field. Otherwise a `KeyError` or `AttributeError` will be raised.\n\n    !!! note\n        This can *only* update a field for a query's `attributes`, i.e., this function\n        cannot update `id`, `type` or any other top-level resource field.\n\n    !!! important\n        `mongo_kwargs` will not be considered for updating the pydantic model instance.\n\n    Parameters:\n        query: The query to be updated.\n        field: The `attributes` field (key) to be set.\n            This can be a dot-separated key value to signify embedded fields.\n\n            **Example**: `response.meta`.\n        value: The (possibly) new value for `field`.\n        operator: A MongoDB operator to be used for updating `field` with `value`.\n        **mongo_kwargs: Further MongoDB update filters.\n\n    \"\"\"\n    operator = operator or \"$set\"\n\n    if operator and not operator.startswith(\"$\"):\n        operator = f\"${operator}\"\n\n    update_time = datetime.now(timezone.utc)\n\n    update_kwargs = {\"$set\": {\"last_modified\": update_time}}\n\n    if mongo_kwargs:\n        update_kwargs.update(mongo_kwargs)\n\n    if operator and operator == \"$set\":\n        update_kwargs[\"$set\"].update({field: value})\n    elif operator:\n        if operator in update_kwargs:\n            update_kwargs[operator].update({field: value})\n        else:\n            update_kwargs.update({operator: {field: value}})\n\n    # MongoDB\n    collection = await collection_factory(CONFIG.queries_collection)\n    result: UpdateResult = await collection.collection.update_one(\n        filter={\"id\": {\"$eq\": query.id}},\n        update=await clean_python_types(update_kwargs),\n    )\n    if result.matched_count != 1:\n        LOGGER.error(\n            (\n                \"matched_count should have been exactly 1, it was: %s. \"\n                \"Returned update_one result: %s\"\n            ),\n            result.matched_count,\n            result.raw_result,\n        )\n\n    # Pydantic model instance\n    query.attributes.last_modified = update_time\n    if \".\" in field:\n        field_list = field.split(\".\")\n        sub_field: BaseModel | dict[str, Any] = getattr(query.attributes, field_list[0])\n        for field_part in field_list[1:-1]:\n            if isinstance(sub_field, dict):\n                sub_field = sub_field.get(field_part, {})\n            else:\n                sub_field = getattr(sub_field, field_part)\n        if isinstance(sub_field, dict):\n            sub_field[field_list[-1]] = value\n        else:\n            setattr(sub_field, field_list[-1], value)\n    else:\n        setattr(query.attributes, field, value)\n</code></pre>"},{"location":"api_reference/routers/databases/","title":"databases","text":"<p>/databases/*</p> <p>This file describes the router for:</p> <pre><code>/databases/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p> <p>Database resources represent the available databases that may be used for the gateways.</p> <p>One can register a new database (by using <code>POST /databases</code>) or look through the available databases (by using <code>GET /databases</code>) using standard OPTIMADE filtering.</p>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.get_database","title":"<code>get_database(request, database_id, params)</code>  <code>async</code>","text":"<p><code>GET /databases/{database ID}</code></p> <p>Return a single <code>LinksResource</code> representing the database resource object with <code>id={database ID}</code>.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.get(\n    \"/databases/{database_id:path}\",\n    response_model=DatabasesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_database(\n    request: Request,\n    database_id: str,\n    params: Annotated[SingleEntryQueryParams, Depends()],\n) -&gt; DatabasesResponseSingle:\n    \"\"\"`GET /databases/{database ID}`\n\n    Return a single\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n    representing the database resource object with `id={database ID}`.\n    \"\"\"\n    collection = await collection_factory(CONFIG.databases_collection)\n\n    params.filter = f'id=\"{database_id}\"'\n    (\n        result,\n        data_returned,\n        more_data_available,\n        fields,\n        include_fields,\n    ) = await collection.afind(params=params)\n\n    if fields or include_fields and result is not None:\n        result = handle_response_fields(result, fields, include_fields)\n\n    result = result[0] if isinstance(result, list) and data_returned else None\n\n    return DatabasesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=data_returned,\n            data_available=await collection.acount(),\n            more_data_available=more_data_available,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.get_databases","title":"<code>get_databases(request, params)</code>  <code>async</code>","text":"<p><code>GET /databases</code></p> <p>Return overview of all (active) databases.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.get(\n    \"/databases\",\n    response_model=DatabasesResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_databases(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; DatabasesResponse:\n    \"\"\"`GET /databases`\n\n    Return overview of all (active) databases.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.databases_collection),\n        response_cls=DatabasesResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/databases/#optimade_gateway.routers.databases.post_databases","title":"<code>post_databases(request, database)</code>  <code>async</code>","text":"<p><code>POST /databases</code></p> <p>Create/Register or return an existing <code>LinksResource</code>, representing a database resource object, according to <code>database</code>.</p> Source code in <code>optimade_gateway/routers/databases.py</code> <pre><code>@ROUTER.post(\n    \"/databases\",\n    response_model=DatabasesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Databases\"],\n    responses=ERROR_RESPONSES,\n)\nasync def post_databases(\n    request: Request, database: DatabaseCreate\n) -&gt; DatabasesResponseSingle:\n    \"\"\"`POST /databases`\n\n    Create/Register or return an existing\n    [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource),\n    representing a database resource object, according to `database`.\n    \"\"\"\n    result, created = await resource_factory(database)\n    collection = await collection_factory(CONFIG.databases_collection)\n\n    return DatabasesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/","title":"gateways","text":"<p>/gateways/*</p> <p>This file describes the router for:</p> <pre><code>/gateways/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.get_gateway","title":"<code>get_gateway(request, gateway_id)</code>  <code>async</code>","text":"<p><code>GET /gateways/{gateway ID}</code></p> <p>Return a single <code>GatewayResource</code>.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.get(\n    \"/gateways/{gateway_id}\",\n    response_model=GatewaysResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_gateway(request: Request, gateway_id: str) -&gt; GatewaysResponseSingle:\n    \"\"\"`GET /gateways/{gateway ID}`\n\n    Return a single\n    [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource].\n    \"\"\"\n    collection = await collection_factory(CONFIG.gateways_collection)\n    result = await get_valid_resource(collection, gateway_id)\n\n    return GatewaysResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.get_gateways","title":"<code>get_gateways(request, params)</code>  <code>async</code>","text":"<p><code>GET /gateways</code></p> <p>Return overview of all (active) gateways.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.get(\n    \"/gateways\",\n    response_model=GatewaysResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_gateways(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; GatewaysResponse:\n    \"\"\"`GET /gateways`\n\n    Return overview of all (active) gateways.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.gateways_collection),\n        response_cls=GatewaysResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/gateways/#optimade_gateway.routers.gateways.post_gateways","title":"<code>post_gateways(request, gateway)</code>  <code>async</code>","text":"<p><code>POST /gateways</code></p> <p>Create or return existing gateway according to <code>gateway</code>.</p> Source code in <code>optimade_gateway/routers/gateways.py</code> <pre><code>@ROUTER.post(\n    \"/gateways\",\n    response_model=GatewaysResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Gateways\"],\n    responses=ERROR_RESPONSES,\n)\nasync def post_gateways(\n    request: Request, gateway: GatewayCreate\n) -&gt; GatewaysResponseSingle:\n    \"\"\"`POST /gateways`\n\n    Create or return existing gateway according to `gateway`.\n    \"\"\"\n    if gateway.database_ids:\n        databases_collection = await collection_factory(CONFIG.databases_collection)\n\n        databases = await databases_collection.get_multiple(\n            filter={\"id\": {\"$in\": await clean_python_types(gateway.database_ids)}}\n        )\n\n        if not isinstance(gateway.databases, list):\n            gateway.databases = []\n\n        current_database_ids = [_.id for _ in gateway.databases]\n        gateway.databases.extend(\n            _ for _ in databases if _.id not in current_database_ids\n        )\n\n    result, created = await resource_factory(gateway)\n    collection = await collection_factory(CONFIG.gateways_collection)\n\n    return GatewaysResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/info/","title":"info","text":"<p>/info/*</p> <p>This file describes the router for:</p> <pre><code>/info/{entry}\n</code></pre> <p>where, <code>entry</code> may be left out.</p>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.ENTRY_INFO_SCHEMAS","title":"<code>ENTRY_INFO_SCHEMAS: dict[str, type[EntryResource]] = {'databases': LinksResource, 'gateways': GatewayResource, 'queries': QueryResource}</code>  <code>module-attribute</code>","text":"<p>This dictionary is used to define the <code>/info/&lt;entry_type&gt;</code> endpoints.</p>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.get_entry_info","title":"<code>get_entry_info(request, entry)</code>  <code>async</code>","text":"<p><code>GET /info/{entry}</code></p> <p>Get information about the gateway service's entry-listing endpoints.</p> Source code in <code>optimade_gateway/routers/info.py</code> <pre><code>@ROUTER.get(\n    \"/info/{entry}\",\n    response_model=EntryInfoResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Info\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_entry_info(request: Request, entry: str) -&gt; EntryInfoResponse:\n    \"\"\"`GET /info/{entry}`\n\n    Get information about the gateway service's entry-listing endpoints.\n    \"\"\"\n    valid_entry_info_endpoints = ENTRY_INFO_SCHEMAS.keys()\n    if entry not in valid_entry_info_endpoints:\n        raise NotFound(\n            detail=(\n                f\"Entry info not found for {entry}, valid entry info endpoints are: \"\n                f\"{', '.join(valid_entry_info_endpoints)}\"\n            ),\n        )\n\n    schema = ENTRY_INFO_SCHEMAS[entry]\n    queryable_properties = {\"id\", \"type\", \"attributes\"}\n    properties = await aretrieve_queryable_properties(\n        schema, queryable_properties, entry_type=entry\n    )\n\n    output_fields_by_format = {\"json\": list(properties)}\n\n    return EntryInfoResponse(\n        data=EntryInfoResource(\n            formats=list(output_fields_by_format),\n            description=getattr(schema, \"__doc__\", \"Entry Resources\"),\n            properties=properties,\n            output_fields_by_format=output_fields_by_format,\n        ),\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=1,\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/info/#optimade_gateway.routers.info.get_info","title":"<code>get_info(request)</code>  <code>async</code>","text":"<p><code>GET /info</code></p> <p>An introspective endpoint for the gateway service.</p> Source code in <code>optimade_gateway/routers/info.py</code> <pre><code>@ROUTER.get(\n    \"/info\",\n    response_model=InfoResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Info\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_info(request: Request) -&gt; InfoResponse:\n    \"\"\"`GET /info`\n\n    An introspective endpoint for the gateway service.\n    \"\"\"\n    return InfoResponse(\n        data=BaseInfoResource(\n            id=BaseInfoResource.model_fields[\"id\"].default,\n            type=BaseInfoResource.model_fields[\"type\"].default,\n            attributes=BaseInfoAttributes(\n                api_version=__api_version__,\n                available_api_versions=[\n                    {\n                        \"url\": (\n                            f\"{get_base_url(request.url)}\"\n                            f\"/v{__api_version__.split('.', maxsplit=1)[0]}\"\n                        ),\n                        \"version\": __api_version__,\n                    }\n                ],\n                formats=[\"json\"],\n                entry_types_by_format={\"json\": list(ENTRY_INFO_SCHEMAS.keys())},\n                available_endpoints=sorted(\n                    [\n                        \"docs\",\n                        \"info\",\n                        \"links\",\n                        \"openapi.json\",\n                        \"redoc\",\n                        \"search\",\n                        *list(ENTRY_INFO_SCHEMAS.keys()),\n                    ]\n                ),\n                is_index=False,\n            ),\n        ),\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=1,\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/links/","title":"links","text":"<p>/links/*</p> <p>This file describes the router for:</p> <pre><code>/links\n</code></pre>"},{"location":"api_reference/routers/links/#optimade_gateway.routers.links.get_links","title":"<code>get_links(request, params)</code>  <code>async</code>","text":"<p><code>GET /links</code></p> <p>Return a regular <code>/links</code> response for an OPTIMADE implementation.</p> Source code in <code>optimade_gateway/routers/links.py</code> <pre><code>@ROUTER.get(\n    \"/links\",\n    response_model=LinksResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Links\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_links(\n    request: Request, params: Annotated[EntryListingQueryParams, Depends()]\n) -&gt; LinksResponse:\n    \"\"\"`GET /links`\n\n    Return a regular `/links` response for an OPTIMADE implementation.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.links_collection),\n        response_cls=LinksResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/","title":"queries","text":"<p>General /queries endpoint to handle gateway queries</p> <p>This file describes the router for:</p> <pre><code>/queries/{id}\n</code></pre> <p>where, <code>id</code> may be left out.</p>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.get_queries","title":"<code>get_queries(request, params)</code>  <code>async</code>","text":"<p><code>GET /queries</code></p> <p>Return overview of all (active) queries.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.get(\n    \"/queries\",\n    response_model=QueriesResponse,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_queries(\n    request: Request,\n    params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; QueriesResponse:\n    \"\"\"`GET /queries`\n\n    Return overview of all (active) queries.\n    \"\"\"\n    return await get_entries(\n        collection=await collection_factory(CONFIG.queries_collection),\n        response_cls=QueriesResponse,\n        request=request,\n        params=params,\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.get_query","title":"<code>get_query(request, query_id, response)</code>  <code>async</code>","text":"<p><code>GET /queries/{query_id}</code></p> <p>Return a single <code>QueryResource</code>.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.get(\n    \"/queries/{query_id}\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_query(\n    request: Request,\n    query_id: str,\n    response: Response,\n) -&gt; QueriesResponseSingle:\n    \"\"\"`GET /queries/{query_id}`\n\n    Return a single [`QueryResource`][optimade_gateway.models.queries.QueryResource].\n    \"\"\"\n    collection = await collection_factory(CONFIG.queries_collection)\n    query: QueryResource = await get_valid_resource(collection, query_id)\n\n    if query.attributes.response and query.attributes.response.errors:\n        for error in query.attributes.response.errors:\n            if error.status:\n                for part in error.status.split(\" \"):\n                    try:\n                        response.status_code = int(part)\n                        break\n                    except ValueError:\n                        pass\n                if response.status_code and response.status_code &gt;= 300:\n                    break\n        else:\n            response.status_code = 500\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=query,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/queries/#optimade_gateway.routers.queries.post_queries","title":"<code>post_queries(request, query)</code>  <code>async</code>","text":"<p><code>POST /queries</code></p> <p>Create or return existing gateway query according to <code>query</code>.</p> Source code in <code>optimade_gateway/routers/queries.py</code> <pre><code>@ROUTER.post(\n    \"/queries\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Queries\"],\n    status_code=status.HTTP_202_ACCEPTED,\n    responses=ERROR_RESPONSES,\n)\nasync def post_queries(\n    request: Request,\n    query: QueryCreate,\n) -&gt; QueriesResponseSingle:\n    \"\"\"`POST /queries`\n\n    Create or return existing gateway query according to `query`.\n    \"\"\"\n    await validate_resource(\n        await collection_factory(CONFIG.gateways_collection), query.gateway_id\n    )\n\n    result, created = await resource_factory(query)\n\n    background_tasks: set[asyncio.Task] = set()\n\n    if created:\n        task = asyncio.create_task(perform_query(url=request.url, query=result))\n\n        # Add task to the set. This creates a strong reference.\n        background_tasks.add(task)\n\n        # To prevent keeping references to finished tasks forever,\n        # make each task remove its own reference from the set after\n        # completion:\n        task.add_done_callback(background_tasks.discard)\n\n    collection = await collection_factory(CONFIG.queries_collection)\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=result,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/search/","title":"search","text":"<p>General /search endpoint to completely coordinate an OPTIMADE gateway query</p> <p>This file describes the router for:</p> <pre><code>/search\n</code></pre>"},{"location":"api_reference/routers/search/#optimade_gateway.routers.search.get_search","title":"<code>get_search(request, response, search_params, entry_params)</code>  <code>async</code>","text":"<p><code>GET /search</code></p> <p>Coordinate a new OPTIMADE query in multiple databases through a gateway:</p> <ol> <li>Create a <code>Search</code> <code>POST</code> data - calling     <code>POST /search</code>.</li> <li>Wait <code>search_params.timeout</code>     seconds before returning the query, if it has not finished before.</li> <li>Return query - similar to <code>GET /queries/{query_id}</code>.</li> </ol> <p>This endpoint works similarly to <code>GET /queries/{query_id}</code>, where one passes the query parameters directly in the URL, instead of first POSTing a query and then going to its URL. Hence, a <code>QueryResponseSingle</code> is the standard response model for this endpoint.</p> <p>If the timeout time is reached and the query has not yet finished, the user is redirected to the specific URL for the query.</p> <p>If the <code>as_optimade</code> query parameter is <code>True</code>, the response will be parseable as a standard OPTIMADE entry listing endpoint like, e.g., <code>/structures</code>. For more information see the OPTIMADE specification.</p> Source code in <code>optimade_gateway/routers/search.py</code> <pre><code>@ROUTER.get(\n    \"/search\",\n    response_model=Union[QueriesResponseSingle, ErrorResponse, EntryResponseMany],\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Search\"],\n    responses=ERROR_RESPONSES,\n)\nasync def get_search(\n    request: Request,\n    response: Response,\n    search_params: Annotated[SearchQueryParams, Depends()],\n    entry_params: Annotated[EntryListingQueryParams, Depends()],\n) -&gt; QueriesResponseSingle | EntryResponseMany | ErrorResponse | RedirectResponse:\n    \"\"\"`GET /search`\n\n    Coordinate a new OPTIMADE query in multiple databases through a gateway:\n\n    1. Create a [`Search`][optimade_gateway.models.search.Search] `POST` data - calling\n        `POST /search`.\n    1. Wait [`search_params.timeout`][optimade_gateway.queries.params.SearchQueryParams]\n        seconds before returning the query, if it has not finished before.\n    1. Return query - similar to `GET /queries/{query_id}`.\n\n    This endpoint works similarly to `GET /queries/{query_id}`, where one passes the\n    query parameters directly in the URL, instead of first POSTing a query and then\n    going to its URL. Hence, a\n    [`QueryResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle] is\n    the standard response model for this endpoint.\n\n    If the timeout time is reached and the query has not yet finished, the user is\n    redirected to the specific URL for the query.\n\n    If the `as_optimade` query parameter is `True`, the response will be parseable as a\n    standard OPTIMADE entry listing endpoint like, e.g., `/structures`.\n    For more information see the\n    [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/master/optimade.rst#entry-listing-endpoints).\n\n    \"\"\"\n    try:\n        search = Search(\n            query_parameters=OptimadeQueryParameters(\n                **{\n                    field: getattr(entry_params, field)\n                    for field in OptimadeQueryParameters.model_fields\n                    if getattr(entry_params, field)\n                }\n            ),\n            optimade_urls=search_params.optimade_urls,\n            endpoint=search_params.endpoint,\n            database_ids=search_params.database_ids,\n        )\n    except ValidationError as exc:\n        raise BadRequest(\n            detail=(\n                \"A Search object could not be created from the given URL query \"\n                f\"parameters. Error(s): {exc.errors}\"\n            )\n        ) from exc\n\n    queries_response = await post_search(request, search=search)\n\n    if not queries_response.data:\n        LOGGER.error(\n            \"QueryResource not found in POST /search response:\\n%s\", queries_response\n        )\n        raise RuntimeError(\n            \"Expected the response from POST /search to return a QueryResource, it did \"\n            \"not\"\n        )\n\n    once = True\n    start_time = time()\n    while time() &lt; (start_time + search_params.timeout) or once:\n        # Make sure to run this at least once (e.g., if timeout=0)\n        once = False\n\n        collection = await collection_factory(CONFIG.queries_collection)\n\n        query: QueryResource = await collection.get_one(\n            filter={\"id\": queries_response.data.id}\n        )\n\n        if query.attributes.state == QueryState.FINISHED:\n            if query.attributes.response and query.attributes.response.errors:\n                for error in query.attributes.response.errors:\n                    if error.status:\n                        for part in error.status.split(\" \"):\n                            try:\n                                response.status_code = int(part)\n                                break\n                            except ValueError:\n                                pass\n                        if response.status_code and response.status_code &gt;= 300:\n                            break\n                else:\n                    response.status_code = 500\n\n            if search_params.as_optimade:\n                response = await query.response_as_optimade(url=request.url)\n                LOGGER.debug(\n                    \"Returning response as OPTIMADE entry listing:\\n%s\", response\n                )\n                return response\n\n            return QueriesResponseSingle(\n                links=ToplevelLinks(next=None),\n                data=query,\n                meta=meta_values(\n                    url=request.url,\n                    data_returned=1,\n                    data_available=await collection.acount(),\n                    more_data_available=False,\n                    schema=CONFIG.schema_url,\n                ),\n            )\n\n        await asyncio.sleep(0.1)\n\n    # The query has not yet succeeded and we're past the timeout time -&gt; Redirect to\n    # /queries/&lt;id&gt;\n    return RedirectResponse(query.links.self)\n</code></pre>"},{"location":"api_reference/routers/search/#optimade_gateway.routers.search.post_search","title":"<code>post_search(request, search)</code>  <code>async</code>","text":"<p><code>POST /search</code></p> <p>Coordinate a new OPTIMADE query in multiple databases through a gateway:</p> <ol> <li>Search for gateway in DB using <code>optimade_urls</code> and <code>database_ids</code></li> <li>Create <code>GatewayCreate</code> model</li> <li><code>POST</code> gateway resource to get ID - using functionality of <code>POST /gateways</code></li> <li>Create new Query resource</li> <li><code>POST</code> Query resource - using functionality of <code>POST /queries</code></li> <li>Return <code>POST /queries</code> response -     <code>QueriesResponseSingle</code></li> </ol> Source code in <code>optimade_gateway/routers/search.py</code> <pre><code>@ROUTER.post(\n    \"/search\",\n    response_model=QueriesResponseSingle,\n    response_model_exclude_defaults=False,\n    response_model_exclude_none=False,\n    response_model_exclude_unset=True,\n    tags=[\"Search\"],\n    status_code=status.HTTP_202_ACCEPTED,\n    responses=ERROR_RESPONSES,\n)\nasync def post_search(request: Request, search: Search) -&gt; QueriesResponseSingle:\n    \"\"\"`POST /search`\n\n    Coordinate a new OPTIMADE query in multiple databases through a gateway:\n\n    1. Search for gateway in DB using `optimade_urls` and `database_ids`\n    1. Create [`GatewayCreate`][optimade_gateway.models.gateways.GatewayCreate] model\n    1. `POST` gateway resource to get ID - using functionality of `POST /gateways`\n    1. Create new [Query][optimade_gateway.models.queries.QueryCreate] resource\n    1. `POST` Query resource - using functionality of `POST /queries`\n    1. Return `POST /queries` response -\n        [`QueriesResponseSingle`][optimade_gateway.models.responses.QueriesResponseSingle]\n\n    \"\"\"\n    databases_collection = await collection_factory(CONFIG.databases_collection)\n    # NOTE: It may be that the final list of base URLs (`base_urls`) contains the same\n    # provider(s), but with differring base URLS, if, for example, a versioned base URL\n    # is supplied.\n    base_urls: set[AnyUrl] = set()\n\n    if search.database_ids:\n        databases = await databases_collection.get_multiple(\n            filter={\"id\": {\"$in\": await clean_python_types(search.database_ids)}}\n        )\n        base_urls |= {\n            get_resource_attribute(database, \"attributes.base_url\")\n            for database in databases\n            if get_resource_attribute(database, \"attributes.base_url\") is not None\n        }\n\n    if search.optimade_urls:\n        base_urls |= {_ for _ in search.optimade_urls if _ is not None}\n\n    if not base_urls:\n        msg = \"No (valid) OPTIMADE URLs with:\"\n        if search.database_ids:\n            msg += (\n                f\"\\n  Database IDs: {search.database_ids} and corresponding found \"\n                \"URLs: \"\n                f\"{[get_resource_attribute(database, 'attributes.base_url') for database in databases]}\"  # noqa: E501\n            )\n        if search.optimade_urls:\n            msg += f\"\\n  Passed OPTIMADE URLs: {search.optimade_urls}\"\n        raise BadRequest(detail=msg)\n\n    # Ensure all URLs are `pydantic.AnyUrl`s\n    if not all(isinstance(_, AnyUrl) for _ in base_urls):\n        raise InternalServerError(\n            \"Could unexpectedly not validate all base URLs as proper URLs.\"\n        )\n\n    databases = await databases_collection.get_multiple(\n        filter={\"base_url\": {\"$in\": await clean_python_types(base_urls)}}\n    )\n\n    if len(databases) == len(base_urls):\n        # At this point it is expected that the list of databases in `databases`\n        # is a complete set of databases requested.\n        pass\n\n    elif len(databases) &lt; len(base_urls):\n        # There are unregistered databases, i.e., databases not in the local collection\n        current_base_urls: set[AnyUrl] = {\n            get_resource_attribute(database, \"attributes.base_url\")\n            for database in databases\n        }\n        databases.extend(\n            [\n                LinksResource(\n                    id=str(url)\n                    .replace(\".\", \"__\")[len(url.scheme) + 3 :]\n                    .split(\"?\", maxsplit=1)[0]\n                    .split(\"#\", maxsplit=1)[0],\n                    type=\"links\",\n                    attributes=LinksResourceAttributes(\n                        name=str(url)[len(url.scheme) + 3 :]\n                        .split(\"?\", maxsplit=1)[0]\n                        .split(\"#\", maxsplit=1)[0],\n                        description=\"\",\n                        base_url=url,\n                        link_type=LinkType.CHILD,\n                        homepage=None,\n                    ),\n                )\n                for url in base_urls - current_base_urls\n            ]\n        )\n    else:\n        LOGGER.error(\n            \"Found more database entries in MongoDB than then number of passed base \"\n            \"URLs. This suggests ambiguity in the base URLs of databases stored in \"\n            \"MongoDB.\\n  base_urls: %s\\n  databases %s\",\n            base_urls,\n            databases,\n        )\n        raise InternalServerError(\"Unambiguous base URLs. See logs for more details.\")\n\n    gateway = GatewayCreate(databases=databases)\n    gateway, created = await resource_factory(gateway)\n\n    if created:\n        LOGGER.debug(\"A new gateway was created for a query (id=%r)\", gateway.id)\n    else:\n        LOGGER.debug(\"A gateway was found and reused for a query (id=%r)\", gateway.id)\n\n    query = QueryCreate(\n        endpoint=search.endpoint,\n        gateway_id=gateway.id,\n        query_parameters=search.query_parameters,\n    )\n    query, created = await resource_factory(query)\n\n    background_tasks: set[asyncio.Task] = set()\n\n    if created:\n        task = asyncio.create_task(perform_query(url=request.url, query=query))\n\n        # Add task to the set. This creates a strong reference.\n        background_tasks.add(task)\n\n        # To prevent keeping references to finished tasks forever,\n        # make each task remove its own reference from the set after\n        # completion:\n        task.add_done_callback(background_tasks.discard)\n\n    collection = await collection_factory(CONFIG.queries_collection)\n\n    return QueriesResponseSingle(\n        links=ToplevelLinks(next=None),\n        data=query,\n        meta=meta_values(\n            url=request.url,\n            data_returned=1,\n            data_available=await collection.acount(),\n            more_data_available=False,\n            schema=CONFIG.schema_url,\n            **{f\"_{CONFIG.provider.prefix}_created\": created},\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/","title":"utils","text":"<p>Utility functions for all routers.</p>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.COLLECTIONS","title":"<code>COLLECTIONS: dict[str, AsyncMongoCollection] = {}</code>  <code>module-attribute</code>","text":"<p>A lazy-loaded dictionary of asynchronous MongoDB entry-endpoint collections.</p>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.aretrieve_queryable_properties","title":"<code>aretrieve_queryable_properties(schema, queryable_properties, entry_type=None)</code>  <code>async</code>","text":"<p>Asynchronous implementation of <code>retrieve_queryable_properties()</code> from <code>optimade</code></p> <p>Reference to the function in the <code>optimade</code> API documentation: <code>retrieve_queryable_properties()</code>.</p> <p>Recursively loops through the schema of a pydantic model and resolves all references, returning a dictionary of all the OPTIMADE-queryable properties of that model.</p> <p>Parameters:</p> Name Type Description Default <code>schema</code> <code>type[EntryResource]</code> <p>The schema of the pydantic model.</p> required <code>queryable_properties</code> <code>Iterable[str]</code> <p>The list of properties to find in the schema.</p> required <code>entry_type</code> <code>str | None</code> <p>The entry type of the model, if any.</p> <code>None</code> <p>Returns:</p> Type Description <code>QueryableProperties</code> <p>A flat dictionary with properties as keys, containing the field description,</p> <code>QueryableProperties</code> <p>unit, sortability, support level, queryability and type, where provided.</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def aretrieve_queryable_properties(\n    schema: type[EntryResource],\n    queryable_properties: Iterable[str],\n    entry_type: str | None = None,\n) -&gt; QueryableProperties:\n    \"\"\"Asynchronous implementation of `retrieve_queryable_properties()` from `optimade`\n\n    Reference to the function in the `optimade` API documentation:\n    [`retrieve_queryable_properties()`](https://www.optimade.org/optimade-python-tools/api_reference/server/schemas/#optimade.server.schemas.retrieve_queryable_properties).\n\n    Recursively loops through the schema of a pydantic model and resolves all\n    references, returning a dictionary of all the OPTIMADE-queryable properties of that\n    model.\n\n    Parameters:\n        schema: The schema of the pydantic model.\n        queryable_properties: The list of properties to find in the schema.\n        entry_type: The entry type of the model, if any.\n\n    Returns:\n        A flat dictionary with properties as keys, containing the field description,\n        unit, sortability, support level, queryability and type, where provided.\n\n    \"\"\"\n    return retrieve_queryable_properties(\n        schema=schema,\n        queryable_properties=queryable_properties,\n        entry_type=entry_type,\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.collection_factory","title":"<code>collection_factory(name)</code>  <code>async</code>","text":"<p>Get or initiate an entry-endpoint resource collection.</p> <p>This factory utilizes the global dictionary <code>COLLECTIONS</code>. It lazily instantiates the collections and then caches them in the dictionary.</p> <p>Parameters:</p> Name Type Description Default <code>name</code> <code>str</code> <p>The configured name for the entry-endpoint resource collection.</p> required <p>Returns:</p> Type Description <code>AsyncMongoCollection</code> <p>The OPTIMADE Gateway asynchronous implementation of the</p> <code>AsyncMongoCollection</code> <p><code>MongoCollection</code>.</p> <p>Raises:</p> Type Description <code>ValueError</code> <p>If the supplied <code>name</code> is not one of the configured valid collection names.</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def collection_factory(name: str) -&gt; AsyncMongoCollection:\n    \"\"\"Get or initiate an entry-endpoint resource collection.\n\n    This factory utilizes the global dictionary\n    [`COLLECTIONS`][optimade_gateway.routers.utils.COLLECTIONS].\n    It lazily instantiates the collections and then caches them in the dictionary.\n\n    Parameters:\n        name: The configured name for the entry-endpoint resource collection.\n\n    Returns:\n        The OPTIMADE Gateway asynchronous implementation of the\n        [`MongoCollection`](https://www.optimade.org/optimade-python-tools/api_reference/server/entry_collections/mongo/#optimade.server.entry_collections.mongo.MongoCollection).\n\n    Raises:\n        ValueError: If the supplied `name` is not one of the configured valid collection\n            names.\n\n    \"\"\"\n    if name in COLLECTIONS:\n        return COLLECTIONS[name]\n\n    if name == CONFIG.databases_collection:\n        from optimade_gateway.mappers.databases import DatabasesMapper as ResourceMapper\n    elif name == CONFIG.gateways_collection:\n        from optimade_gateway.mappers.gateways import (  # type: ignore[no-redef]\n            GatewaysMapper as ResourceMapper,\n        )\n    elif name == CONFIG.queries_collection:\n        from optimade_gateway.mappers.queries import (  # type: ignore[no-redef]\n            QueryMapper as ResourceMapper,\n        )\n    elif name == CONFIG.links_collection:\n        from optimade_gateway.mappers.links import (  # type: ignore[no-redef]\n            LinksMapper as ResourceMapper,\n        )\n    else:\n        raise ValueError(\n            f\"{name!r} is not a valid entry-endpoint resource collection name. \"\n            \"Configured valid names: \"\n            f\"{(CONFIG.databases_collection, CONFIG.gateways_collection, CONFIG.queries_collection, CONFIG.links_collection)}\"  # noqa: E501\n        )\n\n    COLLECTIONS[name] = AsyncMongoCollection(\n        name=name,\n        resource_cls=ResourceMapper.ENTRY_RESOURCE_CLASS,\n        resource_mapper=ResourceMapper,\n    )\n\n    return COLLECTIONS[name]\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.get_entries","title":"<code>get_entries(collection, response_cls, request, params)</code>  <code>async</code>","text":"<p>Generalized <code>/{entries}</code> endpoint getter</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def get_entries(\n    collection: AsyncMongoCollection,\n    response_cls: EntryResponseMany,\n    request: Request,\n    params: EntryListingQueryParams,\n) -&gt; EntryResponseMany:\n    \"\"\"Generalized `/{entries}` endpoint getter\"\"\"\n    (\n        results,\n        data_returned,\n        more_data_available,\n        fields,\n        include_fields,\n    ) = await collection.afind(params=params)\n\n    if more_data_available:\n        # Deduce the `next` link from the current request\n        query = urllib.parse.parse_qs(request.url.query)\n        query[\"page_offset\"] = [int(query.get(\"page_offset\", [0])[0]) + len(results)]  # type: ignore[list-item, arg-type]\n        urlencoded = urllib.parse.urlencode(query, doseq=True)\n        base_url = get_base_url(request.url)\n\n        links = ToplevelLinks(next=f\"{base_url}{request.url.path}?{urlencoded}\")\n    else:\n        links = ToplevelLinks(next=None)\n\n    if fields or include_fields:\n        results = handle_response_fields(results, fields, include_fields)\n\n    return response_cls(\n        links=links,\n        data=results,\n        meta=meta_values(\n            url=request.url,\n            data_returned=data_returned,\n            data_available=await collection.acount(),\n            more_data_available=more_data_available,\n            schema=CONFIG.schema_url,\n        ),\n    )\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.get_valid_resource","title":"<code>get_valid_resource(collection, entry_id)</code>  <code>async</code>","text":"<p>Validate and retrieve a resource</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def get_valid_resource(\n    collection: AsyncMongoCollection, entry_id: str\n) -&gt; EntryResource:\n    \"\"\"Validate and retrieve a resource\"\"\"\n    await validate_resource(collection, entry_id)\n    return await collection.get_one(filter={\"id\": entry_id})\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.resource_factory","title":"<code>resource_factory(create_resource)</code>  <code>async</code>","text":"<p>Get or create a resource</p> <p>Currently supported resources:</p> <ul> <li><code>\"databases\"</code>     (<code>DatabaseCreate</code>     -&gt;     <code>LinksResource</code>)</li> <li><code>\"gateways\"</code> (<code>GatewayCreate</code> -&gt;     <code>GatewayResource</code>)</li> <li><code>\"queries\"</code> (<code>QueryCreate</code> -&gt;     <code>QueryResource</code>)</li> </ul> <p>For each of the resources, \"uniqueness\" is determined in the following way:</p> Databases <p>The <code>base_url</code> field is considered unique across all databases.</p> <p>If a <code>base_url</code> is provided via a <code>Link</code> model, the <code>base_url.href</code> value is used to query the MongoDB.</p> Gateways <p>The collected list of <code>databases.attributes.base_url</code> values is considered unique across all gateways.</p> <p>In the database, the search is done as a combination of the length/size of the <code>databases</code>' Python list/MongoDB array and a match on all (using the MongoDB <code>$all</code> operator) of the <code>databases.attributes.base_url</code> element values, when compared with the <code>create_resource</code>.</p> <p>Important</p> <p>The <code>database_ids</code> attribute must not contain values that are not also included in the <code>databases</code> attribute, in the form of the IDs for the individual databases. If this should be the case an <code>OptimadeGatewayError</code> will be thrown.</p> Queries <p>The <code>gateway_id</code>, <code>query_parameters</code>, and <code>endpoint</code> fields are collectively considered to define uniqueness for a <code>QueryResource</code> in the MongoDB collection.</p> <p>Attention</p> <p>Only the <code>/structures</code> entry endpoint can be queried with multiple expected responses.</p> <p>This means the <code>endpoint</code> field defaults to <code>\"structures\"</code>, i.e., the <code>StructureResource</code> resource model.</p> <p>Parameters:</p> Name Type Description Default <code>create_resource</code> <code>DatabaseCreate | GatewayCreate | QueryCreate</code> <p>The resource to be retrieved or created anew.</p> required <p>Returns:</p> Type Description <code>tuple[LinksResource | GatewayResource | QueryResource, bool]</code> <p>Two things in a tuple:</p> <ul> <li>Either a     <code>GatewayResource</code>;     a <code>QueryResource</code>; or a     <code>LinksResource</code>     and</li> <li>whether or not the resource was newly created.</li> </ul> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def resource_factory(\n    create_resource: DatabaseCreate | GatewayCreate | QueryCreate,\n) -&gt; tuple[LinksResource | GatewayResource | QueryResource, bool]:\n    \"\"\"Get or create a resource\n\n    Currently supported resources:\n\n    - `\"databases\"`\n        ([`DatabaseCreate`][optimade_gateway.models.databases.DatabaseCreate]\n        -&gt;\n        [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource))\n    - `\"gateways\"` ([`GatewayCreate`][optimade_gateway.models.gateways.GatewayCreate] -&gt;\n        [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource])\n    - `\"queries\"` ([`QueryCreate`][optimade_gateway.models.queries.QueryCreate] -&gt;\n        [`QueryResource`][optimade_gateway.models.queries.QueryResource])\n\n    For each of the resources, \"uniqueness\" is determined in the following way:\n\n    === \"Databases\"\n        The `base_url` field is considered unique across all databases.\n\n        If a `base_url` is provided via a\n        [`Link`](https://www.optimade.org/optimade-python-tools/api_reference/models/jsonapi/#optimade.models.jsonapi.Link)\n        model, the `base_url.href` value is used to query the MongoDB.\n\n    === \"Gateways\"\n        The collected list of `databases.attributes.base_url` values is considered\n        unique across all gateways.\n\n        In the database, the search is done as a combination of the length/size of the\n        `databases`' Python list/MongoDB array and a match on all (using the MongoDB\n        `$all` operator) of the\n        [`databases.attributes.base_url`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResourceAttributes.base_url)\n        element values, when compared with the `create_resource`.\n\n        !!! important\n            The `database_ids` attribute **must not** contain values that are not also\n            included in the `databases` attribute, in the form of the IDs for the\n            individual databases. If this should be the case an\n            [`OptimadeGatewayError`][optimade_gateway.common.exceptions.OptimadeGatewayError]\n            will be thrown.\n\n    === \"Queries\"\n        The `gateway_id`, `query_parameters`, and `endpoint` fields are collectively\n        considered to define uniqueness for a\n        [`QueryResource`][optimade_gateway.models.queries.QueryResource] in the MongoDB\n        collection.\n\n        !!! attention\n            Only the `/structures` entry endpoint can be queried with multiple expected\n            responses.\n\n            This means the `endpoint` field defaults to `\"structures\"`, i.e., the\n            [`StructureResource`](https://www.optimade.org/optimade-python-tools/all_models/#optimade.models.structures.StructureResource)\n            resource model.\n\n    Parameters:\n        create_resource: The resource to be retrieved or created anew.\n\n    Returns:\n        Two things in a tuple:\n\n            - Either a\n                [`GatewayResource`][optimade_gateway.models.gateways.GatewayResource];\n                a [`QueryResource`][optimade_gateway.models.queries.QueryResource]; or a\n                [`LinksResource`](https://www.optimade.org/optimade-python-tools/api_reference/models/links/#optimade.models.links.LinksResource)\n                and\n            - whether or not the resource was newly created.\n\n    \"\"\"\n    created = False\n\n    if isinstance(create_resource, DatabaseCreate):\n        collection_name = CONFIG.databases_collection\n\n        base_url = get_resource_attribute(create_resource, \"base_url\")\n\n        mongo_query: dict[str, Any] = {\n            \"$or\": [\n                {\"base_url\": {\"$eq\": base_url}},\n                {\"base_url.href\": {\"$eq\": base_url}},\n            ]\n        }\n    elif isinstance(create_resource, GatewayCreate):\n        collection_name = CONFIG.gateways_collection\n\n        # One MUST have taken care of database_ids prior to calling `resource_factory()`\n        database_attr_ids = {_.id for _ in create_resource.databases or []}\n        unknown_ids = {\n            database_id\n            for database_id in create_resource.database_ids or []\n            if database_id not in database_attr_ids\n        }\n        if unknown_ids:\n            raise OptimadeGatewayError(\n                \"When using `resource_factory()` for `GatewayCreate`, `database_ids` \"\n                f\"MUST not include unknown IDs. Passed unknown IDs: {unknown_ids}\"\n            )\n\n        mongo_query = {\n            \"databases\": {\"$size\": len(create_resource.databases or [])},\n            \"databases.attributes.base_url\": {\n                \"$all\": [_.attributes.base_url for _ in create_resource.databases or []]\n            },\n        }\n    elif isinstance(create_resource, QueryCreate):\n        collection_name = CONFIG.queries_collection\n\n        # Currently only /structures entry endpoints can be queried with multiple\n        # expected responses.\n        create_resource.endpoint = (\n            create_resource.endpoint\n            if create_resource.endpoint is not None\n            else EndpointEntryType(\"structures\")\n        )\n\n        mongo_query = {\n            \"gateway_id\": {\"$eq\": create_resource.gateway_id},\n            \"query_parameters\": {\"$eq\": create_resource.query_parameters},\n            \"endpoint\": {\"$eq\": create_resource.endpoint},\n        }\n    else:\n        raise TypeError(\n            \"create_resource must be either a DatabaseCreate, GatewayCreate, or \"\n            f\"QueryCreate object, not {type(create_resource)!r}\"\n        )\n\n    collection = await collection_factory(collection_name)\n    result, data_returned, more_data_available, _, _ = await collection.afind(\n        criteria={\"filter\": await clean_python_types(mongo_query)}\n    )\n\n    if more_data_available:\n        raise OptimadeGatewayError(\n            \"more_data_available MUST be False for a single entry response, however it \"\n            f\"is {more_data_available}\"\n        )\n\n    if result:\n        if data_returned &gt; 1:\n            raise OptimadeGatewayError(\n                f\"More than one {result[0].type} were found. IDs of found \"\n                f\"{result[0].type}: {[_.id for _ in result]}\"\n            )\n        if isinstance(result, list):\n            result = result[0]\n    else:\n        if isinstance(create_resource, DatabaseCreate):\n            # Set required `LinksResourceAttributes` values if not set\n            if not create_resource.description:\n                create_resource.description = (\n                    f\"{create_resource.name} created by OPTIMADE gateway database \"\n                    \"registration.\"\n                )\n\n            if not create_resource.link_type:\n                create_resource.link_type = LinkType.EXTERNAL\n\n            if not create_resource.homepage:\n                create_resource.homepage = None\n\n        elif (\n            isinstance(create_resource, GatewayCreate)\n            and \"database_ids\" in create_resource.model_fields_set\n        ):\n            # Do not store `database_ids`\n            del create_resource.database_ids\n            create_resource.model_fields_set.remove(\"database_ids\")\n\n        elif isinstance(create_resource, QueryCreate):\n            create_resource.state = QueryState.CREATED\n\n        result = await collection.create_one(create_resource)\n        LOGGER.debug(\"Created new %s: %r\", result.type, result)\n        created = True\n\n    return result, created\n</code></pre>"},{"location":"api_reference/routers/utils/#optimade_gateway.routers.utils.validate_resource","title":"<code>validate_resource(collection, entry_id)</code>  <code>async</code>","text":"<p>Validate whether a resource exists in a collection</p> Source code in <code>optimade_gateway/routers/utils.py</code> <pre><code>async def validate_resource(collection: AsyncMongoCollection, entry_id: str) -&gt; None:\n    \"\"\"Validate whether a resource exists in a collection\"\"\"\n    if not await collection.exists(entry_id):\n        raise NotFound(\n            detail=f\"Resource &lt;id={entry_id}&gt; not found in {collection}.\",\n        )\n</code></pre>"}]}
\ No newline at end of file
diff --git a/latest/sitemap.xml b/latest/sitemap.xml
index ce74fa9f..499d9738 100644
--- a/latest/sitemap.xml
+++ b/latest/sitemap.xml
@@ -2,192 +2,192 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/CHANGELOG/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/LICENSE/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/design/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/events/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/exception_handlers/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/main/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/middleware/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/warnings/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/common/config/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/common/exceptions/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/common/logger/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/common/utils/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mappers/base/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mappers/databases/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mappers/gateways/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mappers/links/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mappers/queries/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/databases/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/gateways/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/queries/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/resources/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/responses/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/models/search/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mongo/collection/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/mongo/database/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/queries/params/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/queries/perform/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/queries/prepare/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/queries/process/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/queries/utils/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/databases/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/gateways/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/info/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/links/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/queries/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/search/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
     <url>
          <loc>https://www.optimade.org/optimade-gateway/latest/api_reference/routers/utils/</loc>
-         <lastmod>2024-08-06</lastmod>
+         <lastmod>2024-08-12</lastmod>
          <changefreq>daily</changefreq>
     </url>
 </urlset>
\ No newline at end of file
diff --git a/latest/sitemap.xml.gz b/latest/sitemap.xml.gz
index 620a35222262fcf34d8a27fa27bfb0aa1f9e3080..d45558a8f64def2da252682300f95f0f3021da85 100644
GIT binary patch
literal 484
zcmV<A0UQ1wiwFpSP`PFT|8r?{Wo=<_E_iKh0Nt3uPUA2ThVMK@m3!+_ap<nnR4Y_q
zCBz;U&d6&|TnpRdjvWGTzfRjg9{?dub8&1<CjS?Y$K%xNH}58|K*?fQRhP4QHG!Z|
z+hA7J)8ox_S*@Fkx+9k$Pl|C!t7@Bb{3%4=_p@X(cp1|S$%v%3rIW;QP|RmPs^(%+
zuED|KZhzGdRWo==M>iO=^-{y$&Dfb5nW2~O!j(2<QH$ZRQ!g@QkGfgR7gy8ya(cNa
zCdaW8Gqsh$KufS|w6yNM7AGSIdE!Igmngly`}J_Ux&L#^Nb~*g>&?U84I{-Gk~M*m
zU>WT*K?_ut7zlWUkP~0|ZwiVbhUfBH?Mez^i{ho_8%Eyh^7VU3z!ss14`svQ8$b%Z
z$55KkTEm^<V_~zO4~ND8ai{3Ab)0i+jKkjWPbOdwp=Fi>2><Cg8u15lHoWks*mXdb
zb6BAUcNXj80K$KH95~J-t_Tu#q|O2)mcoiZNCHV}%a|e<ECrTxpoUVHImnoI*<y@&
zDoT<*@y7sakvxA6g2?&D!Y2oo&4Yhj@jeO?cKJL`Q6mZaGI0d4p+)u(ypMt-1^1GD
a<X~PQju_vRa`#Pw-24Yp2qW&29RL8f4(nI|

literal 483
zcmV<90UZ7xiwFpSXR&4i|8r?{Wo=<_E_iKh0Nt3)PUA2T$L~Bvm3!-e5Mozp5JCl3
zLU7pKGcxwXweS}+4uQAFX&dMRAf#z7j;+b$|BJ`tahi)a?`E%nWMf!X$BVj}K~PcK
zV3yVYf7kQ#>Y_brdUOPNR*VBJt98!lw-CcHEXZc?GSMQU5v10oLt-~5>cy|BJ(`tk
zbg;eKT#bvW9lg-bO-$K(sbS-0>dcMIFvxe|N=sQZVtj1hi=^zMZcply(|LV9ug{9f
zZfws?tz|IKA-uF&TKC?Fy^*av@u}}ylwRFl-rub59&Q+EzWZ~vy8pXkq*w!46Br4W
z$vz@<fMtn+fL92a_{x7%Pz+;uEU(qBq!6|!URu6k<gG4We~<`l5sLUwHXObIq@wpR
zlqPi6aHsfO*zD)SMPmTDQ}o$7&bc+Eac_8%1neQS%yI<bKOH+G{vghVXZ{o~J)q?r
zR#AgHi1o1r;lDh#90w9t2o!r%2LX~wVZ|SWK%!bRrU)jM0?Rp2W2ws=WXij2F{V6~
zBuY>GF#x-Wo<9dd;{0RbizAlJgMVD{J_=&&^I@E#CKC2#;sjzt7uiGbJ_=40+)MU}
ZgL#EGVf;|a-82Nb{Qw6j{``_1007%o?1=yX