.. include:: ../../toolkit-substitutions

.. oe:namespace:: OEChem


.. _OEChem_OESubSearchQuery:

.. oe:class:: OESubSearchQuery

   .. attention::

      |TWOLANGUAGE|

   .. oe:api::

      class OESubSearchQuery

   The :ref:`OESubSearchQuery <OEChem_OESubSearchQuery>` class is used to submit queries
   to be searched in a database (:oe:meth:`OEChem::OESubSearchDatabase`).

   .. seealso::

      * :oe:meth:`OEChem::OESubSearchDatabase::Search` method
      * :oe:meth:`OEChem::OESubSearchDatabase::GetMatchIndices` method
      * :oe:meth:`OEChem::OESubSearchDatabase::GetMatchTitles` method

   .. admonition:: Code Example

      * :ref:`section_example_oechem_searchfastss` example

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESubSearchQuery(const OEQMolBase& query,
                             const size_t maxmatches = 1000u)

      .. oe:language:: python

         .. oe:api:: python

            OESubSearchQuery(arg2: OEQMol, maxmatches: int = 1000) -> OESubSearchQuery
            OESubSearchQuery(arg2: OESubSearchQueryImpl) -> OESubSearchQuery

      Creates an :ref:`OESubSearchQuery <OEChem_OESubSearchQuery>` object.

      query
        The query molecule (:ref:`OEQMolBase <OEChem_OEQMolBase>`).

      maxmatches
        The maximum number of matches that will be kept.

   .. oe:method:: SetFilter

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetFilter(const OESystem::OEUnaryPredicate<OEMolBase>&)

      .. oe:language:: python

         .. oe:api:: python

            SetFilter(arg2: OEUnaryMolBasePred) -> None

      Sets a molecule predicate that can be used to filter out molecules
      based on molecular properties other than the existence of a certain
      substructure.

      .. oe:language:: c++ python

         The following code snippet shows how to use the
         :oe:meth:`OEChem::OESubSearchQuery::SetFilter` method to identify
         molecules that are matching the given :term:`SMARTS` pattern and
         also have molecule weight in the given range:

         .. oe:source:: FilteredSubSearch.cpp
            :language: c++
            :noindent:
            :frag:     SNIPPET

         .. oe:source:: FilteredSubSearch.py
            :language: python
            :noindent:
            :frag:     SNIPPET

         The output of the code snippet above might look like this:

         .. code-block:: console

            Number of total matches = 20
            Number of total matches (filtered) = 7
            weight= 204.225 c1ccc2c(c1)c(c[nH]2)C[C@H](C(=O)O)N
            weight= 218.252 CN[C@@H](Cc1c[nH]c2c1cccc2)C(=O)O
            weight= 245.277 CC(=O)N[C@@H](Cc1c[nH]c2c1cccc2)C(=O)N
            weight= 275.303 c1ccc2c(c1)c(c[nH]2)C[C@@H](C(=O)O)NC(=O)CCN
            weight= 260.288 CC(=O)N[C@@H](Cc1c[nH]c2c1cccc2)C(=O)OC
            weight= 274.315 CCOC(=O)[C@H](Cc1c[nH]c2c1cccc2)NC(=O)C
            weight= 254.327 CN1CC(C=C2[C@H]1Cc3c[nH]c4c3c2ccc4)CO

         where ``MoleculeWeightPredicate`` is a molecule predicate that is defined as:

         .. oe:source:: FilteredSubSearch.cpp
            :language: c++
            :noindent:
            :frag:     SNIPPET-PREDICATE

         .. oe:source:: FilteredSubSearch.py
            :language: python
            :noindent:
            :frag:     SNIPPET-PREDICATE

      .. note::

         During the search, the predicate set by the
         :oe:meth:`OEChem::OESubSearchQuery::SetFilter` method is utilized after
         the screening phase and before the atom-by-atom validation of the
         substructure search match. Note that to minimize the memory footprints, the
         :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>` only stores the molecular graphs
         (no coordinates) and the titles of the molecules.

      .. seealso::

         * :ref:`chapter_predicates` chapter

   .. oe:method:: GetMaxMatches

      .. oe:language:: c++ java csharp

         .. oe:api::

            size_t GetMaxMatches() const

      .. oe:language:: python

         .. oe:api:: python

            GetMaxMatches() -> int

      Returns the maximum match limit when searching :ref:`OESubSearchDatabase <OEChem_OESubSearchDatabase>`.
      The :oe:meth:`OEChem::OESubSearchDatabase::GetMatchIndices` and
      :oe:meth:`OEChem::OESubSearchDatabase::GetMatchTitles` methods will terminate
      when this limit is reached.
      The default is ``1000``.

   .. oe:method:: SetMaxMatches

      .. oe:language:: c++ java csharp

         .. oe:api::

            void SetMaxMatches(const size_t limit)

      .. oe:language:: python

         .. oe:api:: python

            SetMaxMatches(arg2: int) -> None

      Sets the maximum match limit.

      .. note::

         While there is no upper limit on how many matches can be retrieve by the search,
         it is not recommended to set this limit very high (>10K).
         Searching a very large database with a very generic query can result in
         internally storing millions of indices or titles.
         The total number of matches can be determined (without storing all matches) either
         using the :oe:meth:`OEChem::OESubSearchDatabase::NumMatches` method or
         via the :oe:meth:`OEChem::OESubSearchResult::NumTotalMatches` counter when using
         the :oe:meth:`OEChem::OESubSearchDatabase::Search` method.
