Glossary ======== Here is a list of the terms that have special meanings within the DSL and its documentation, most of which are taken from the larger Dimensions ecosystem. .. glossary:: Entity A record of special interest. Differs from a :term:`source` insofar as it does not have textual data to be searched, but instead only stores metadata about the object it represents. Examples: funder, research org., category, country, etc. See :ref:`data-sources` for a comprehensive list of supported entities. .. note:: Entities can only be considered in the context of the :term:`source` with which they are associated, and cannot be queried independently from that source. For example, we can retrieve funders of publications, or funders of research grants, but we can't search through the set of all funders generally. Facet A type of named :term:`field` on a :term:`source` :term:`record` which can be used for faceting, i.e. aggregation of a certain :term:`indicator` over the result set returned (with aggregations being calculated after any :ref:`filters ` have been applied and scoring by :term:`search term` similarity has been computed). Examples of facets for grants: ``funders``, ``research_orgs``, ``active_year`` A facet may correspond to an :term:`entity`, i.e. a :term:`record`, as is the case with e.g. the ``funders`` facet. Alternatively, a facet may correspond simply to a literal value, as is the case with the ``active_year`` facet. .. note:: Not every :term:`field` on a :term:`source` can be used as a facet; see the fields tables for each source on the :ref:`data-sources` page to know whether or not a given field may be used as a facet. Field A property of a :term:`record`, corresponding to a piece of information about the record or :term:`entity` which that record represents. Loosely corresponds to the notion of a column if the record is considered as a database row. Examples: ``id``, ``title``, ``year``, ``date`` May appear in the :ref:`fields specification ` of a :ref:`"return" phrase `, or in the :ref:`"sort by" phrase `. See the :ref:`data-sources` page for a comprehensive lists of fields available for each :term:`source` and :term:`entity`. Fieldset A named group of :term:`fields ` for a given :term:`source` or :term:`entity`. Examples: ``extras``, ``basics`` May appear in the :ref:`fields specification ` of a :ref:`"return" phrase `. See the :ref:`data-sources` page for a comprehensive lists of fields available for each :term:`source` and :term:`entity`. Function Expression Type of query useful for performing non-search requests. It allows calling functions with arguments. Arguments can be either named or not-named. Named arguments must come last and any non-named arguments must come first, in the proper order. See :doc:`language` for the language specification. See :doc:`functions` for use-cases and examples. Indicator A named numeric value which can be used for aggregating records over a :term:`facet` of a given :term:`source`, or for sorting aggregation results. Examples: ``count``, ``funding`` (sum of USD funding amounts), ``rcr_avg``, ``altmetric_median`` .. note:: The DSL does not permit arbitrary aggregations; aggregation can only be performed using a indicator from the pre-defined set for each :term:`source`, as listed on the :ref:`data-sources` page. Query A complete expression in the DSL query language, which corresponds to a request for Dimensions data. Example: ``search grants about "HIV" return funders`` See :doc:`examples` for more examples of valid queries, and :doc:`language` for a detailed reference of query component phrases. Record An entry (document). May correspond to a :term:`source` instance, or to an :term:`entity` instance. Search Index A full text search index that can be used to perform keyword search operations. For example, ``title_abstract_only`` or ``full_data`` as specified in the :ref:`"search in" syntax ` section. Search Term A :term:`string` containing keywords for ranking records by relevance. Appears in the :ref:`"for" phrase ` of a :term:`query`. Examples: ``"malaria"``, ``"malaria in Africa"`` Source A member of the set of Dimensions record types which can be searched (as opposed to an :term:`entity` record, which cannot be searched directly.) See :ref:`data-sources` for a comprehensive list of supported sources. String A short piece of text data, which begins and ends with double quotes (``"``). Examples: ``"malaria"``, ``"Universität des Saarlandes"`` May appear in various phrases of a :term:`query`, such as * :ref:`for-terms` * :ref:`where-filters` :ref:`entity-filters` * :ref:`group-specification` :ref:`alias-specification` .. note:: As the double quote character (``"``) is used to indicate the start and end of a string, if the string's text itself contains this character, it must be escaped with a preceding backslash (``\``). For example: ``"a so-called \"superbug\" virus"`` is a valid string, but ``"a so-called "superbug" virus"`` is not a valid string (it would be interpreted by the parser as the string ``"a so-called "``, the unknown name ``superbug``, and the string ``" virus"``, resulting in an error).