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.

Entity

A record of special interest.

Differs from a 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 Data Sources for a comprehensive list of supported entities.

Note

Entities can only be considered in the context of the 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 field on a source record which can be used for faceting, i.e. aggregation of a certain indicator over the result set returned (with aggregations being calculated after any filters have been applied and scoring by search term similarity has been computed).

Examples of facets for grants: funders, research_orgs, active_year

A facet may correspond to an entity, i.e. a 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 field on a source can be used as a facet; see the fields tables for each source on the Data Sources page to know whether or not a given field may be used as a facet.

Field

A property of a record, corresponding to a piece of information about the record or 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 fields specification of a “return” phrase, or in the “sort by” phrase.

See the Data Sources page for a comprehensive lists of fields available for each source and entity.

Fieldset

A named group of fields for a given source or entity.

Examples: extras, basics

May appear in the fields specification of a “return” phrase.

See the Data Sources page for a comprehensive lists of fields available for each source and 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 Query Syntax for the language specification. See Functions Syntax for use-cases and examples.

Indicator

A named numeric value which can be used for aggregating records over a facet of a given 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 source, as listed on the 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 Example Queries and Results for more examples of valid queries, and Query Syntax for a detailed reference of query component phrases.

Record

An entry (document).

May correspond to a source instance, or to an 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 “search in” syntax section.

Search Term

A string containing keywords for ranking records by relevance. Appears in the “for” phrase of a query.

Examples: "malaria", "malaria in Africa"

Source

A member of the set of Dimensions record types which can be searched (as opposed to an entity record, which cannot be searched directly.)

See 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 query, such as

for "search term"

where Literal Fields Vs Entity Fields

return in "facets" aliases

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).