---

Exploring The Dimensions Search Language (DSL) - Deep Dive

This tutorial provides a detailed walkthrough of the most important features of the Dimensions Search Language.

This tutorial is based on the Query Syntax section of the official documentation. So, it can be used as an interactive version of the documentation, as it allows to try out the various DSL queries presented there.

What is the Dimensions Search Language?

The DSL aims to capture the type of interaction with Dimensions data that users are accustomed to performing graphically via the web application, and enable web app developers, power users, and others to carry out such interactions by writing query statements in a syntax loosely inspired by SQL but particularly suited to our specific domain and data organization.

Note: this notebook uses the Python programming language, however all the DSL queries are not Python-specific and can in fact be reused with any other API client.

import datetime
print("==\nCHANGELOG\nThis notebook was last run on %s\n==" % datetime.date.today().strftime('%b %d, %Y'))

==
CHANGELOG
This notebook was last run on Jan 26, 2022
==

Prerequisites

This notebook assumes you have installed the Dimcli library and are familiar with the ‘Getting Started’ tutorial.

!pip install dimcli --quiet

import dimcli
from dimcli.utils import *
import json
import sys
import pandas as pd
#

print("==\nLogging in..")
# https://digital-science.github.io/dimcli/getting-started.html#authentication
ENDPOINT = "https://app.dimensions.ai"
if 'google.colab' in sys.modules:
  import getpass
  KEY = getpass.getpass(prompt='API Key: ')
  dimcli.login(key=KEY, endpoint=ENDPOINT)
else:
  KEY = ""
  dimcli.login(key=KEY, endpoint=ENDPOINT)
dsl = dimcli.Dsl()

Searching config file credentials for 'https://app.dimensions.ai' endpoint..

==
Logging in..
Dimcli - Dimensions API Client (v0.9.6)
Connected to: <https://app.dimensions.ai/api/dsl> - DSL v2.0
Method: dsl.ini file

Sections Index

1. Basic query structure

2. Full-text searching

3. Field searching

4. Searching for researchers

5. Returning results

6. Aggregations

1. Basic query structure

DSL queries consist of two required components: a search phrase that indicates the scientific records to be searched, and one or more return phrases which specify the contents and structure of the desired results.

The simplest valid DSL query is of the form search <source>|return <result>:

%%dsldf
search grants return  grants limit 5

Returned Grants: 5 (total = 6115921)
Time: 0.73s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2022, 2023, 2024, 2025, 2026, 2027]	2027-12-01	[{'acronym': 'ARC', 'city_name': 'Canberra', '...	Australian Research Council	FL210100107	grant.9782236	en	Tracking nanoparticles: from cell culture to i...	2022-12-01	2022	Tracking nanoparticles: from cell culture to i...
1	[2022, 2023]	2023-05-31	[{'acronym': 'NSF GEO', 'city_name': 'Arlingto...	Directorate for Geosciences	2127438	grant.9752271	en	NNA Planning: Developing community frameworks ...	2022-12-01	2022	NNA Planning: Developing community frameworks ...
2	[2022, 2023, 2024, 2025, 2026, 2027]	2027-11-30	[{'acronym': 'ERC', 'city_name': 'Brussels', '...	European Research Council	101019146	grant.9708025	en	Seeking Constraints on Open Ocean Biocalcifica...	2022-12-01	2022	Seeking Constraints on Open Ocean Biocalcifica...
3	[2022, 2023, 2024, 2025, 2026, 2027]	2027-11-30	[{'acronym': 'ERC', 'city_name': 'Brussels', '...	European Research Council	101003021	grant.9661402	en	New frontiers in advanced glycotherapy for cancer	2022-12-01	2022	New frontiers in advanced glycotherapy for cancer
4	[2022, 2023, 2024, 2025]	2025-10-31	[{'acronym': 'NSF MPS', 'city_name': 'Arlingto...	Directorate for Mathematical & Physical Sciences	2105918	grant.9890102	en	RUI: Exciton-Phonon Interactions in Solids bas...	2022-11-15	2022	RUI: Exciton-Phonon Interactions in Solids bas...

search source

A query must begin with the word search followed by a source name, i.e. the name of a type of scientific record, such as grants or publications.

What are the sources available? See the data sources section of the documentation.

Alternatively, we can use the ‘schema’ API (describe) to return this information programmatically:

dsl.query("describe schema")

<dimcli.DslDataset object #4642007888. Dict keys: 'entities', 'sources'>

A more useful query might also make use of the optional for and where phrases to limit the set of records returned.

%%dsldf
search grants  for "lung cancer"
    where active_year=2000
return  grants  limit 5

Returned Grants: 5 (total = 1764)
Time: 0.69s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2000, 2001, 2002]	2002-01-01	[{'acronym': 'NHLBI', 'city_name': 'Bethesda',...	National Heart Lung and Blood Institute	F32HL010455	grant.2386513	en	ROLE OF CD44 ISOFORMS IN ENDOTHELIAL CELL DAMAGE	2000-12-31	2000	ROLE OF CD44 ISOFORMS IN ENDOTHELIAL CELL DAMAGE
1	[2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007]	2007-11-30	[{'acronym': 'NHLBI', 'city_name': 'Bethesda',...	National Heart Lung and Blood Institute	R01HL066221	grant.2537801	en	GENETIC ANALYSIS OF EPHRIN-EPH SIGNALING IN AN...	2000-12-18	2000	GENETIC ANALYSIS OF EPHRIN-EPH SIGNALING IN AN...
2	[2000, 2001, 2002, 2003, 2004]	2004-11-30	[{'acronym': 'NHLBI', 'city_name': 'Bethesda',...	National Heart Lung and Blood Institute	R01HL063695	grant.2537116	en	ESTROGEN, ANGIOGENESIS AND ENDOTHELIAL PROGENI...	2000-12-18	2000	ESTROGEN, ANGIOGENESIS AND ENDOTHELIAL PROGENI...
3	[2000, 2001, 2002, 2003, 2004, 2005, 2006, 200...	2017-12-31	[{'acronym': 'NHLBI', 'city_name': 'Bethesda',...	National Heart Lung and Blood Institute	R01HL062244	grant.2536777	en	Synthetic Heparan Sulfate: Probing Biosynthesi...	2000-12-15	2000	Synthetic Heparan Sulfate: Probing Biosynthesi...
4	[2000, 2001]	2001-02-28	[{'acronym': 'RWJF', 'city_name': 'Princeton',...	Robert Wood Johnson Foundation	41067	grant.8616620	en	SmokeLess States Program - Implementation	2000-12-01	2000	SmokeLess States Program - Implementation

return result (source or facet)

The most basic return phrase consists of the keyword return followed by the name of a record or facet to be returned.

This must be the name of the source used in the search phrase, or the name of a facet of that source.

%%dsldf
search grants for "laryngectomy"
return grants limit 5

Returned Grants: 5 (total = 127)
Time: 0.54s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2021, 2022, 2023, 2024, 2025]	2025-09-30	[{'acronym': 'NCN', 'city_name': 'Krakow', 'co...	National Science Center	2020/39/O/HS6/01774	grant.9750968	pl	Psychologia ekologiczna i enaktywizm w praktyc...	2021-07-07	2021	Ecological psychology and enactivism in resear...
1	[2021, 2022, 2023, 2024, 2025, 2026]	2026-03-31	[{'acronym': 'NIDCD', 'city_name': 'Bethesda',...	National Institute on Deafness and Other Commu...	R01DC019352	grant.9643970	en	Reducing social isolation for adults with chro...	2021-04-05	2021	Reducing social isolation for adults with chro...
2	[2021, 2022, 2023, 2024]	2024-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	21K17363	grant.9692444	ja	喉頭摘出術後の無喉頭者の嗅覚リハビリテーション効果について	2021-04-01	2021	About the olfactory rehabilitation effect of l...
3	[2021, 2022, 2023, 2024, 2025]	2025-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	21K10776	grant.9685857	ja	喉頭がん、下咽頭がんにより喉頭摘出術を受けた患者に対する携帯型嗅覚知覚装置の開発	2021-04-01	2021	Development of a portable sensory sensory devi...
4	[2021, 2022, 2023, 2024, 2025]	2025-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	21K10721	grant.9685802	ja	喉頭摘出者の食道発声トレーニングプログラムの構築と効果の検証	2021-04-01	2021	Construction and effectiveness verification of...

Eg let’s see what are the facets available for the grants source:

fields = dsl.query("describe schema")['sources']['grants']['fields']
[x for x in fields if fields[x]['is_facet']]

['active_year',
 'category_bra',
 'category_for',
 'category_hra',
 'category_hrcs_hc',
 'category_hrcs_rac',
 'category_icrp_cso',
 'category_icrp_ct',
 'category_rcdc',
 'category_sdg',
 'category_uoa',
 'funder_countries',
 'funders',
 'funding_currency',
 'funding_org_acronym',
 'funding_org_city',
 'funding_org_name',
 'language',
 'language_title',
 'research_org_cities',
 'research_org_countries',
 'research_org_state_codes',
 'research_orgs',
 'researchers',
 'start_year']

2. Full-text Searching

Full-text search or keyword search finds all instances of a term (keyword) in a document, or group of documents.

Full text search works by using search indexes, which can be targeting specific sections of a document e.g. its \(abstract\), \(authors\), \(full text\) etc…

%%dsldf
search publications
    in full_data for "moon landing"
return publications limit 5

Returned Publications: 5 (total = 198654)
Time: 1.49s

	authors	id	pages	title	type	volume	year	journal.id	journal.title	issue
0	[{'affiliations': [{'city': 'Noumea', 'city_id...	pub.1144582099	106194	Estimating post-release mortality of long-line...	article	249	2022	jour.1032122	Fisheries Research	NaN
1	[{'affiliations': [{'name': 'ESSEC Business Sc...	pub.1141367962	1-20	Optimization in Multimodal Freight Transportat...	article	299	2022	jour.1027009	European Journal of Operational Research	1
2	[{'affiliations': [{'city': 'Beijing', 'city_i...	pub.1144677835	197-208	Adaptive control of hypersonic vehicles with u...	article	193	2022	jour.1134138	Acta Astronautica	NaN
3	[{'affiliations': [{'city': 'Shanghai', 'city_...	pub.1144650554	106956	Constructing Highly Tribopositive Elastic Yarn...	article	94	2022	jour.1051417	Nano Energy	NaN
4	[{'affiliations': [{'city': 'Chengdu', 'city_i...	pub.1144554233	108783	Nonlinear vibration model and response charact...	article	169	2022	jour.1042338	Mechanical Systems and Signal Processing	NaN

2.1 in [search index]

This optional phrase consists of the particle in followed by a term indicating a search index, specifying for example whether the search is limited to full text, title and abstract only, or title only.

%%dsldf
search grants
    in title_abstract_only for "something"
return grants limit 5

Returned Grants: 5 (total = 11654)
Time: 0.54s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2022, 2023, 2024]	2024-08-31	[{'acronym': 'EC', 'city_name': 'Brussels', 'c...	European Commission	101018408	grant.9662248	en	Conceptual Engineering, Inquiry and Communication	2022-09-01	2022	Conceptual Engineering, Inquiry and Communication
1	[2022, 2023, 2024]	2024-08-31	[{'acronym': 'EC', 'city_name': 'Brussels', 'c...	European Commission	101031970	grant.9652677	en	Molecular dynamics of size sensing at the sing...	2022-09-01	2022	Molecular dynamics of size sensing at the sing...
2	[2022, 2023, 2024, 2025]	2025-04-30	[{'acronym': 'EC', 'city_name': 'Brussels', 'c...	European Commission	101019008	grant.9662230	en	Yamatology of the Axis. Japan as a Nazi-Fascis...	2022-05-01	2022	Yamatology of the Axis. Japan as a Nazi-Fascis...
3	[2022]	2022-09-30	[{'acronym': 'SNF', 'city_name': 'Bern', 'coun...	Swiss National Science Foundation	205597	grant.9943737	en	Innovation performance and knowledge spillover...	2022-04-01	2022	Innovation performance and knowledge spillover...
4	[2022, 2023, 2024]	2024-12-31	[{'acronym': 'EPSRC', 'city_name': 'Swindon', ...	Engineering and Physical Sciences Research Cou...	EP/W002817/1	grant.9944524	en	The Farey framework for SL2-tilings	2022-01-01	2022	The Farey framework for SL2-tilings

Eg let’s see what are the search fields available for the grants source:

dsl.query("describe schema")['sources']['grants']['search_fields']

['full_data', 'concepts', 'title_only', 'title_abstract_only', 'investigators']

%%dsldf
search grants
    in full_data for "graphene AND computer AND iron"
return grants limit 5

Returned Grants: 5 (total = 13)
Time: 0.55s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2020, 2021]	2021-03-31	[{'acronym': 'NSERC', 'city_name': 'Ottawa', '...	Natural Sciences and Engineering Research Council	N/A	grant.9873234	en	Phase transitions in two-dimensional ultrathin...	2020-04-01	2020	Phase transitions in two-dimensional ultrathin...
1	[2019, 2020]	2020-03-31	[{'acronym': 'NSERC', 'city_name': 'Ottawa', '...	Natural Sciences and Engineering Research Council	N/A	grant.9445377	en	Phase transitions in two-dimensional ultrathin...	2019-04-01	2019	Phase transitions in two-dimensional ultrathin...
2	[2019, 2020, 2021]	2021-12-31	[{'acronym': 'RSF', 'city_name': 'Moscow', 'co...	Russian Science Foundation	19-43-04129	grant.8413990	en	Weyl and Dirac semimetals and beyond - predict...	2019-01-01	2019	Weyl and Dirac semimetals and beyond - predict...
3	[2018]	2018-12-31	[{'acronym': 'RFBR', 'city_name': 'Moscow', 'c...	Russian Foundation for Basic Research	18-02-20097	grant.8731867	ru	Проект организации 18-ой Международной конфере...	2018-01-01	2018	Project of the organization of the 18th Intern...
4	[2016]	2016-12-31	[{'acronym': 'MNiSW', 'city_name': 'Warsaw', '...	Ministry of Science and Higher Education	4491/E-370/S/2016	grant.7397800	pl	Dotacja podmiotowa na utrzymanie potencjału ba...	2016-02-22	2016	Subject subsidy for maintaining the research p...

Special search indexes for persons names permit to perform full text searches on publications authors or grants investigators. Please see the Researchers Search section below for more information on how searches work in this case.

%dsldf search publications in authors for "\"Jennifer A Doudna\"" return publications limit 5

Returned Publications: 5 (total = 387)
Time: 0.69s

	authors	id	pages	title	type	year	journal.id	journal.title	issue	volume
0	[{'affiliations': [{'city': 'San Francisco', '...	pub.1144086202	2021.12.20.21268048	Omicron mutations enhance infectivity and redu...	preprint	2021	jour.1369542	medRxiv	NaN	NaN
1	[{'affiliations': [{'city': 'Berkeley', 'city_...	pub.1143670587	2021.12.06.471469	A naturally DNase-free CRISPR-Cas12c enzyme si...	preprint	2021	jour.1293558	bioRxiv	NaN	NaN
2	[{'affiliations': [{'city': 'Berkeley', 'city_...	pub.1143662570	34-47	Species- and site-specific genome editing in c...	article	2021	jour.1052984	Nature Microbiology	1	7
3	[{'affiliations': [{'city': 'Berkeley', 'city_...	pub.1142569174	100527-100527	Optimizing COVID-19 control with asymptomatic ...	article	2021	jour.1040589	Epidemics	NaN	37
4	[{'affiliations': [{'city': 'Berkeley', 'city_...	pub.1142452381	e0258263	LuNER: Multiplexed SARS-CoV-2 detection in cli...	article	2021	jour.1037553	PLOS ONE	11	16

2.2 for "search term"

This optional phrase consists of the keyword for followed by a search term string, enclosed in double quotes (").

Strings in double quotes can contain nested quotes escaped by a backslash \. This will ensure that the string in nested double quotes is searched for as if it was a single phrase, not multiple words.

An example of a phrase: "\"Machine Learning\"" : results must contain Machine Learning as a phrase.

%dsldf search publications for "\"Machine Learning\"" return publications limit 5

Returned Publications: 5 (total = 1750245)
Time: 1.20s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [{'city': 'Barcelona', 'city...	pub.1141731106	9	1-38	Computing Graph Neural Networks: A Survey from...	article	54	2022	jour.1119907	ACM Computing Surveys
1	[{'affiliations': [{'city': 'Barcelona', 'city...	pub.1141731105	9	1-35	A Survey on Uncertainty Estimation in Deep Lea...	article	54	2022	jour.1119907	ACM Computing Surveys
2	[{'affiliations': [{'city': 'Pittsburgh', 'cit...	pub.1141731091	9	1-36	A Survey on Data-driven Network Intrusion Dete...	article	54	2022	jour.1119907	ACM Computing Surveys
3	[{'affiliations': [{'city': "Xi'an", 'city_id'...	pub.1141731088	9	1-40	A Survey of Deep Active Learning	article	54	2022	jour.1119907	ACM Computing Surveys
4	[{'affiliations': [{'city': 'Kuwait City', 'ci...	pub.1141731057	9	1-35	Design Guidelines for Cooperative UAV-supporte...	article	54	2022	jour.1119907	ACM Computing Surveys

Example of multiple keywords: "Machine Learning" : this searches for keywords independently.

%dsldf search publications for "Machine Learning" return publications limit 5

Returned Publications: 5 (total = 3301914)
Time: 0.71s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [{'city': 'Barcelona', 'city...	pub.1141731106	9	1-38	Computing Graph Neural Networks: A Survey from...	article	54	2022	jour.1119907	ACM Computing Surveys
1	[{'affiliations': [{'city': 'Barcelona', 'city...	pub.1141731105	9	1-35	A Survey on Uncertainty Estimation in Deep Lea...	article	54	2022	jour.1119907	ACM Computing Surveys
2	[{'affiliations': [{'city': 'Pittsburgh', 'cit...	pub.1141731091	9	1-36	A Survey on Data-driven Network Intrusion Dete...	article	54	2022	jour.1119907	ACM Computing Surveys
3	[{'affiliations': [{'city': "Xi'an", 'city_id'...	pub.1141731088	9	1-40	A Survey of Deep Active Learning	article	54	2022	jour.1119907	ACM Computing Surveys
4	[{'affiliations': [{'city': 'Kuwait City', 'ci...	pub.1141731057	9	1-35	Design Guidelines for Cooperative UAV-supporte...	article	54	2022	jour.1119907	ACM Computing Surveys

Note: Special characters, such as any of ^ " : ~ \ [ ] { } ( ) ! | & + must be escaped by a backslash \. Also, please note escaping rules in Python (or other languages). For example, when writing a query with escaped quotes, such as search publications for "\"phrase 1\" AND \"phrase 2\"", in Python, it is necessary to escape the backslashes as well, so it would look like: 'search publications for "\\"phrase 1\\" AND \\"phrase 2\\""'.

See the official docs for more details.

2.3 Boolean Operators

Search term can consist of multiple keywords or phrases connected using boolean logic operators, e.g. AND, OR and NOT.

%dsldf search publications for "(dose AND concentration)" return publications limit 5

Returned Publications: 5 (total = 6050778)
Time: 0.99s

	authors	id	pages	title	type	year	journal.id	journal.title	volume
0	[{'affiliations': [{'city': 'Davangere', 'city...	pub.1143861372	1-14	Screening of Antibacterial and Antioxidant Act...	article	2022	jour.1047355	BioNanoScience	NaN
1	[{'affiliations': [{'city': 'Pune', 'city_id':...	pub.1144548884	17-22	Daily oral Vitamin D3 without concomitant ther...	article	2022	NaN	NaN	2
2	[{'affiliations': [{'city': 'Jatobá', 'city_id...	pub.1144546526	100051	Nutritional feed additives reduce the adverse ...	article	2022	jour.1400582	Fish and Shellfish Immunology Reports	3
3	[{'affiliations': [{'city': 'Lecce', 'city_id'...	pub.1144545525	100071	Income-dependent expansion of electricity dema...	article	2022	jour.1400160	Energy and Climate Change	3
4	[{'affiliations': [{'city': 'Tokyo', 'city_id'...	pub.1144519018	100049	Alteration of hemoglobin ß gene expression in ...	article	2022	jour.1400582	Fish and Shellfish Immunology Reports	3

When specifying Boolean operators with keywords such as AND, OR and NOT, the keywords must appear in all uppercase.

The operators available are shown in the table below. .

Boolean Operator	Alternative Symbol	Description
AND	&&	Requires both terms on either side of the Boolean operator to be present for a match.
NOT	!	Requires that the following term not be present.
OR	||	Requires that either term (or both terms) be present for a match.
	+	Requires that the following term be present.
	-	Prohibits the following term (that is, matches on fields or documents that do not include that term). The - operator is functionally similar to the Boolean operator !.

%dsldf search publications for "(dose OR concentration) AND (-malaria +africa)" return publications limit 5

Returned Publications: 5 (total = 1644481)
Time: 0.88s

	authors	id	pages	title	type	volume	year	journal.id	journal.title	issue
0	[{'affiliations': [{'city': 'Baltimore', 'city...	pub.1144345471	100059	Reliability and validity of a perinatal depres...	article	2	2022	jour.1410012	SSM - Mental Health	NaN
1	[{'affiliations': [{'city': 'Clemson', 'city_i...	pub.1144477432	100074	Detection of Trypanosoma brucei by microwave c...	article	4	2022	jour.1386020	Sensors and Actuators Reports	NaN
2	[{'affiliations': [{'city': 'Beijing', 'city_i...	pub.1144284673	1174-1190	Examining and applying the theory of “explorin...	article	8	2022	jour.1150945	Energy Reports	NaN
3	[{'affiliations': [{'city': 'Beijing', 'city_i...	pub.1143898003	161-182	A review of regional energy internet in smart ...	article	8	2022	jour.1150945	Energy Reports	NaN
4	[{'affiliations': [{'city': 'Giza', 'city_id':...	pub.1144780769	101687	A Unified index of water resources systems vul...	article	13	2022	jour.1139894	Ain Shams Engineering Journal	5

The combination of keywords and boolean operators allow to construct rather sophisticated queries. For example, here’s a real-world query used to extract publications related to COVID-19.

q_inner = """ "2019-nCoV" OR "COVID-19" OR "SARS-CoV-2" OR "HCoV-2019" OR "hcov" OR "NCOVID-19" OR
    "severe acute respiratory syndrome coronavirus 2" OR "severe acute respiratory syndrome corona virus 2"
    OR (("coronavirus"  OR "corona virus") AND (Wuhan OR China OR novel)) """

# tip: dsl_escape is a dimcli utility function for escaping special characters
q_outer = f"""search publications in full_data for "{dsl_escape(q_inner)}" return publications"""
print(q_outer)

dsl.query(q_outer)

search publications in full_data for " \"2019-nCoV\" OR \"COVID-19\" OR \"SARS-CoV-2\" OR \"HCoV-2019\" OR \"hcov\" OR \"NCOVID-19\" OR
    \"severe acute respiratory syndrome coronavirus 2\" OR \"severe acute respiratory syndrome corona virus 2\"
    OR ((\"coronavirus\"  OR \"corona virus\") AND (Wuhan OR China OR novel)) " return publications
Returned Publications: 20 (total = 937518)
Time: 4.56s

<dimcli.DslDataset object #4644757408. Records: 20/937518>

2.4 Wildcard Searches

The DSL supports single and multiple character wildcard searches within single terms. Wildcard characters can be applied to single terms, but not to search phrases.

%dsldf search publications in title_only for "ital? malaria" return publications limit 5

Returned Publications: 5 (total = 151)
Time: 0.90s

	authors	id	pages	title	type	year	journal.id	journal.title	issue	volume
0	[{'affiliations': [{'city': 'Milan', 'city_id'...	pub.1144404199	1-8	The value of lamp to rule out imported malaria...	article	2022	jour.1012240	Infectious Diseases	NaN	NaN
1	[{'affiliations': [{'city': 'Foggia', 'city_id...	pub.1143322096	1521	Entomological Surveillance in Former Malaria-e...	article	2021	jour.1047674	Pathogens	11	10
2	[{'affiliations': [{'city': 'Rome', 'city_id':...	pub.1136415339	621974	Plasmodium matutinum Transmitted by Culex pipi...	article	2021	jour.1052367	Frontiers in Veterinary Science	NaN	8
3	[{'affiliations': [{'city': 'Rome', 'city_id':...	pub.1133261890	NaN	Artemisinin resistance surveillance in African...	article	2020	jour.1112262	Journal of Travel Medicine	5	28
4	NaN	pub.1132438137	9744-9748	Does Living in Previously Exposed Malaria or W...	article	2020	jour.1278986	Biointerface Research in Applied Chemistry	2	11

%dsldf search publications in title_only for "it* malaria" return publications limit 5

Returned Publications: 5 (total = 1710)
Time: 0.65s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [{'city': 'Rāiganj', 'city_i...	pub.1144613444	1	630	Study of epidemiological behaviour of malaria ...	article	12	2022	jour.1045337	Scientific Reports
1	[{'affiliations': [{'city': 'Paris', 'city_id'...	pub.1144507923	1	e0262018	Retrospective study of toxoplasmosis prevalenc...	article	17	2022	jour.1037553	PLOS ONE
2	[{'affiliations': [{'city': 'Manaus', 'city_id...	pub.1144484495	NaN	NaN	Essential Oil of Piper Purusanum C.DC (Piperac...	preprint	NaN	2022	jour.1380788	Research Square
3	[{'affiliations': [{'city': 'Rio de Janeiro', ...	pub.1144409586	1	6	Naturally acquired antibody response to a Plas...	article	21	2022	jour.1030597	Malaria Journal
4	[{'affiliations': [{'city': 'Milan', 'city_id'...	pub.1144404199	NaN	1-8	The value of lamp to rule out imported malaria...	article	NaN	2022	jour.1012240	Infectious Diseases

Wildcard Search Type	Special Character	Example
Single character - matches a single character	?	The search string te?t would match both test and text.
Multiple characters - matches zero or more sequential characters	*	The wildcard search: tes* would match test, testing, and tester. You can also use wildcard characters in the middle of a term. For example: te*t would match test and text. *est would match pest and test.

2.5 Proximity Searches

A proximity search looks for terms that are within a specific distance from one another.

To perform a proximity search, add the tilde character ~ and a numeric value to the end of a search phrase. For example, to search for a formal and model within 10 words of each other in a document, use the search:

%dsldf search publications for "\"formal model\"~10" return publications limit 5

Returned Publications: 5 (total = 550689)
Time: 1.48s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [{'city': 'Linz', 'city_id':...	pub.1141731109	9	1-35	Adversary Models for Mobile Device Authentication	article	54	2022	jour.1119907	ACM Computing Surveys
1	[{'affiliations': [{'city': 'Singapore', 'city...	pub.1139789629	7	1-38	A Survey of Smart Contract Formal Specificatio...	article	54	2022	jour.1119907	ACM Computing Surveys
2	[{'affiliations': [{'city': 'Valencia', 'city_...	pub.1144441268	3	100187	Institutional factors affecting entrepreneursh...	article	28	2022	jour.1357518	Investigaciones Europeas de Dirección y Econom...
3	[{'affiliations': [{'city': 'Shanghai', 'city_...	pub.1144280894	7	1-20	Research on Evaluation of Intelligent Manufact...	article	30	2022	jour.1140896	Journal of Global Information Management
4	[{'affiliations': [{'city': 'Buffalo', 'city_i...	pub.1144816193	NaN	102306	Task allocation and planning for product disas...	article	76	2022	jour.1044008	Robotics and Computer-Integrated Manufacturing

%dsldf search publications for "\"digital humanities\"~5  +ontology" return publications limit 5

Returned Publications: 5 (total = 12057)
Time: 1.04s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [{'city': 'Ljubljana', 'city...	pub.1144807122	1	345-369	COVID-19, Digital Tracking Control and Chinese...	article	10	2022	jour.1371758	Asian Studies
1	[{'affiliations': [{'city': 'Wuhan', 'city_id'...	pub.1144781071	1	7-15	Reuse‐oriented data publishing: How to make th...	article	35	2022	jour.1043368	Learned Publishing
2	[{'affiliations': [{'city': 'Isparta', 'city_i...	pub.1144707794	NaN	1-21	Automatic and intelligent content visualizatio...	article	NaN	2022	jour.1104357	Neural Computing and Applications
3	NaN	pub.1144681286	NaN	NaN	Handbook of the American Short Story	book	15	2022	NaN	NaN
4	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1144619382	NaN	NaN	The Performance of Sculpture in Renaissance Ve...	monograph	NaN	2022	NaN	NaN

The distance referred to here is the number of term movements needed to match the specified phrase.

In the example above, if formal and model were 10 spaces apart in a field, but formal appeared before model, more than 10 term movements would be required to move the terms together and position formal to the right of model with a space in between.

3. Field Searching

Field searching allows to use a specific field of a source as a query filter. For example, this can be a Literal field such as the \(type\) of a publication, its \(date\), \(mesh terms\), etc.. Or it can be an Entity field, such as the \(journal title\) for a publication, the \(country name\) of its author affiliations, etc..

What are the fields available for each source? See the data sources section of the documentation.

Alternatively, we can use the ‘schema’ API (describe) to return this information programmatically:

%dsldocs publications

	sources	field	type	description	is_filter	is_entity	is_facet
0	publications	abstract	string	The publication abstract.	False	False	False
1	publications	acknowledgements	string	The acknowledgements section text as found in ...	False	False	False
2	publications	altmetric	float	Altmetric Attention Score.	True	False	False
3	publications	altmetric_id	integer	Altmetric Publication ID	True	False	False
4	publications	arxiv_id	string	The publications arXiv identifier (e.g. ‘arXiv...	True	False	False
...	...	...	...	...	...	...	...
62	publications	times_cited	integer	Number of citations (note: does not support em...	True	False	True
63	publications	title	string	Title of a publication.	False	False	False
64	publications	type	string	Publication type (one of: article, chapter, pr...	True	False	True
65	publications	volume	string	Publication volume.	True	False	False
66	publications	year	integer	The year for the version of record of publicat...	True	False	True

67 rows × 7 columns

3.1 where

This optional phrase consists of the keyword where followed by a filters phrase consisting of DSL filter expressions, as described below.

%dsldf search publications where type = "book" return publications limit 5

Returned Publications: 5 (total = 596368)
Time: 0.56s

	id	title	type	year
0	pub.1132180584	De consensu evangelistarum	book	2022
1	pub.1144839778	PESQUISAS EM PRÁTICAS DISCURSIVAS, SENTIDOS E ...	book	2022
2	pub.1144311572	L'anti-manuel de management dans les EHPAD	book	2022
3	pub.1144411807	Roots and Trajectories of Violent Extremism an...	book	2022
4	pub.1144515956	Land Use Change and Its Ecological Effects in ...	book	2022

If a for phrase is also used in a filtered query, the system will first apply the filters, and then search the resulting restricted set of documents for the search term.

%dsldf search publications for "malaria" where type = "book" return publications limit 5

Returned Publications: 5 (total = 22341)
Time: 0.61s

	id	title	type	year	volume
0	pub.1144315336	Invertebrate Medicine	book	2022	NaN
1	pub.1144494935	Metallosurfactants	book	2022	NaN
2	pub.1144493884	Probiotics, Prebiotics and Synbiotics	book	2022	NaN
3	pub.1144718404	Zusammenfassung	book	2022	Band 10
4	pub.1144752324	Handbook of Biomass Valorization for Industria...	book	2022	NaN

3.2 in

For convenience, the DSL also supports shorthand notation for filters where a particular field should be restricted to a specified range or list of values (although the same logic may be expressed using complex filters as shown below).

Syntax: a range filter consists of the field name, the keyword in, and a range of values enclosed in square brackets ([]), where the range consists of a low value, colon :, and a high value.

%%dsldf
search grants
    for "malaria"
    where start_year in [ 2010 : 2015 ]
return grants limit 5

Returned Grants: 5 (total = 3281)
Time: 0.60s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2015, 2016, 2017]	2017-11-30	[{'acronym': 'NIAID', 'city_name': 'Bethesda',...	National Institute of Allergy and Infectious D...	R21AI120981	grant.4729738	en	Bloodborne tropical pathogen detection using m...	2015-12-28	2015	Bloodborne tropical pathogen detection using m...
1	[2015, 2016, 2017, 2018, 2019]	2019-02-28	[{'acronym': 'NIAID', 'city_name': 'Bethesda',...	National Institute of Allergy and Infectious D...	R21AI120973	grant.4729736	en	Field-deployable Assay for Differential Diagno...	2015-12-24	2015	Field-deployable Assay for Differential Diagno...
2	[2015, 2016, 2017, 2018]	2018-11-30	[{'acronym': 'NIAID', 'city_name': 'Bethesda',...	National Institute of Allergy and Infectious D...	R21AI109439	grant.4729699	en	T cell driven antigen discovery for vaccine ca...	2015-12-21	2015	T cell driven antigen discovery for vaccine ca...
3	[2015, 2016, 2017, 2018]	2018-12-18	[{'acronym': 'VolkswagenStiftung', 'city_name'...	Volkswagen Foundation	91488	grant.4854433	en	Senior Fellowship for Dr. Eduardo Samo Gudo: E...	2015-12-18	2015	Senior Fellowship for Dr. Eduardo Samo Gudo: E...
4	[2015, 2016, 2017, 2018, 2019]	2019-09-30	[{'acronym': 'NIFA', 'city_name': 'Washington ...	National Institute of Food and Agriculture	N/A	grant.8821176	en	Biology, Ecology & Management of Emerging Dise...	2015-12-10	2015	Biology, Ecology & Management of Emerging Dise...

Syntax: a list filter consists of the field name, the keyword in, and a list of one or more value s enclosed in square brackets ([]), where values are separated by commas (,):

%%dsldf
search grants
    for "malaria"
    where research_org_names in [ "UC Berkeley", "UC Davis", "UCLA"  ]
return grants limit 5

Returned Grants: 0
Time: 0.68s

3.3 count - filter function

The filter function count is supported on some fields in publications (e.g. researchers and research_orgs).

Use of this filter is shown on the example below:

%%dsldf
search publications
    for "malaria"
    where count(research_orgs) > 5
return research_orgs limit 5

Returned Research_orgs: 5
Time: 0.81s

	city_name	count	country_name	id	latitude	linkout	longitude	name	state_name	types	acronym
0	Oxford	2321	United Kingdom	grid.4991.5	51.753437	[http://www.ox.ac.uk/]	-1.254010	University of Oxford	Oxfordshire	[Education]	NaN
1	London	2043	United Kingdom	grid.8991.9	51.520900	[http://www.lshtm.ac.uk/]	-0.130700	London School of Hygiene & Tropical Medicine	Camden	[Education]	LSHTM
2	Cambridge	1901	United States	grid.38142.3c	42.377052	[http://www.harvard.edu/]	-71.116650	Harvard University	Massachusetts	[Education]	NaN
3	Baltimore	1121	United States	grid.21107.35	39.328888	[https://www.jhu.edu/]	-76.620280	Johns Hopkins University	Maryland	[Education]	JHU
4	London	1110	United Kingdom	grid.7445.2	51.498600	[http://www.imperial.ac.uk/]	-0.175478	Imperial College London	Westminster	[Education]	NaN

Number of publications with more than 50 researcher.

%%dsldf
search publications
    for "malaria"
    where count(researchers) > 50
return publications limit 5

Returned Publications: 5 (total = 323)
Time: 1.16s

	authors	id	issue	title	type	volume	year	journal.id	journal.title	pages
0	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1144290266	3	Cancer Incidence, Mortality, Years of Life Los...	article	8	2021	jour.1051466	JAMA Oncology	NaN
1	[{'affiliations': [{'city': 'Washington D.C.',...	pub.1143711356	12	SARS-CoV-2 ferritin nanoparticle vaccines elic...	article	37	2021	jour.1046010	Cell Reports	110143-110143
2	[{'affiliations': [{'city': 'Modena', 'city_id...	pub.1143715249	12	Guidelines for the use of flow cytometry and c...	article	51	2021	jour.1054998	European Journal of Immunology	2708-3145
3	[{'affiliations': [], 'corresponding': True, '...	pub.1143609205	1	The global burden of adolescent and young adul...	article	23	2021	jour.1023279	The Lancet Oncology	27-52
4	[{'affiliations': [{'city': 'Dhaka', 'city_id'...	pub.1143648995	NaN	Global research priorities on COVID-19 for mat...	article	11	2021	jour.1046459	Journal of Global Health	04071

Number of publications with more than one researcher.

%%dsldf
search publications
where count(researchers) > 1
return funders limit 5

Returned Funders: 5
Time: 2.10s

	acronym	city_name	count	country_name	id	latitude	linkout	longitude	name	types	state_name
0	NSFC	Beijing	2440430	China	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.339830	National Natural Science Foundation of China	[Government]	NaN
1	EC	Brussels	849457	Belgium	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]	NaN
2	MOST	Beijing	760688	China	grid.424020.0	39.827835	[http://www.most.gov.cn/eng/]	116.316284	Ministry of Science and Technology of the Peop...	[Government]	NaN
3	JSPS	Tokyo	656041	Japan	grid.54432.34	35.687160	[http://www.jsps.go.jp/]	139.740390	Japan Society for the Promotion of Science	[Nonprofit]	NaN
4	NCI	Bethesda	593537	United States	grid.48336.3a	39.004326	[http://www.cancer.gov/]	-77.101190	National Cancer Institute	[Government]	Maryland

International collaborations: number of publications with more than one author and affiliations located in more than one country.

%%dsldf
search publications
where count(researchers) > 1
and count(research_org_countries) > 1
return funders limit 5

Returned Funders: 5
Time: 1.00s

	acronym	city_name	count	country_name	id	latitude	linkout	longitude	name	types
0	NSFC	Beijing	574560	China	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.339830	National Natural Science Foundation of China	[Government]
1	EC	Brussels	440042	Belgium	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]
2	DFG	Bonn	192288	Germany	grid.424150.6	50.699340	[http://www.dfg.de/en/]	7.147797	German Research Foundation	[Nonprofit]
3	MOST	Beijing	186241	China	grid.424020.0	39.827835	[http://www.most.gov.cn/eng/]	116.316284	Ministry of Science and Technology of the Peop...	[Government]
4	JSPS	Tokyo	170517	Japan	grid.54432.34	35.687160	[http://www.jsps.go.jp/]	139.740390	Japan Society for the Promotion of Science	[Nonprofit]

Domestic collaborations: number of publications with more than one author and more than one affiliation located in exactly one country.

%%dsldf
search publications
where count(researchers) > 1
and count(research_org_countries) = 1
return funders limit 5

Returned Funders: 5
Time: 1.82s

	acronym	city_name	count	country_name	id	latitude	linkout	longitude	name	types	state_name
0	NSFC	Beijing	1812269	China	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.339830	National Natural Science Foundation of China	[Government]	NaN
1	MOST	Beijing	560284	China	grid.424020.0	39.827835	[http://www.most.gov.cn/eng/]	116.316284	Ministry of Science and Technology of the Peop...	[Government]	NaN
2	JSPS	Tokyo	454249	Japan	grid.54432.34	35.687160	[http://www.jsps.go.jp/]	139.740390	Japan Society for the Promotion of Science	[Nonprofit]	NaN
3	NCI	Bethesda	433280	United States	grid.48336.3a	39.004326	[http://www.cancer.gov/]	-77.101190	National Cancer Institute	[Government]	Maryland
4	EC	Brussels	389598	Belgium	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]	NaN

3.4 Filter Operators

A simple filter expression consists of a field name, an in-/equality operator op, and the desired field value.

The value must be a string enclosed in double quotes (") or an integer (e.g. 1234).

The available operators are:

op	meaning
=	is (or contains if the given field is multi-value)
!=	is not
>	is greater than
<	is less than
>=	is greater than or equal to
<=	is less than or equal to
~	partially matches (see partial-string-matching below)
is empty	is empty (see emptiness-filters below)
is not empty	is not empty (see emptiness-filters below)

A couple of examples

%dsldf search datasets where year > 2010 and year < 2012 return datasets limit 5

Returned Datasets: 5 (total = 158057)
Time: 0.65s

	authors	id	title	year
0	[{'name': 'Tsuji, Kazuki'}, {'name': 'Kikuta, ...	dataset.999	DiaBroodproduction Pupae	2011
1	[{'name': 'Tsuji, Kazuki'}, {'name': 'Kikuta, ...	dataset.998	Data from: Determination of the cost of worker...	2011
2	[{'name': 'Wessex Archaeology'}, {'name': 'Wes...	dataset.99758	Stricklands, Chapel Road, Southampton (OASIS I...	2011
3	[{'name': 'Vijendravarma, Roshan K.'}, {'name'...	dataset.997	critical weight data	2011
4	[{'name': 'Vijendravarma, Roshan K.'}, {'name'...	dataset.996	Data from: Chronic malnutrition favours smalle...	2011

%dsldf search patents where assignees != "grid.410484.d" return patents limit 5

Returned Patents: 5 (total = 142264864)
Time: 1.21s

	assignee_names	filing_status	id	inventor_names	publication_date	times_cited	title	year
0	[KHASHOGGI E IND]	Application	ZW-9994-A1	[ANDERSEN PER JUST, HODSON SIMON K]	1994-09-28	0	Sealable liquid-tight, thin-walled containers ...	1994
1	[H L & H TIMBER PROD]	Application	ZW-9993-A1	[FRANS ROELOF PETRUS PIENAAR, RICHARD GEORGE K...	1993-12-15	0	SPACER ASSEMBLY AND METHOD	1993
2	[GLAVERBEL]	Application	ZW-9992-A1	[JEAN-PIERRE MEYNCKENS, LEON-PHILIPPE MOTTET]	1993-07-28	0	PROCESS AND MIXTURE FOR FORMING A COHERENT REF...	1992
3	[SENTRACHEM LTD]	Application	ZW-9991-A1	[ANTHONY PATRICK REYNOLDS, MARK BURDON COCKSED...	1991-10-16	0	INORGANIC FLOCCULANT MANUFACTURE	1991
4	[DANTEX EXPLOSIVES]	Application	ZW-9990-A1	[LEON MICHAEL ZIMMERMANN]	1990-10-31	0	EXPLOSIVE COMPOSITION	1990

3.5 Partial string matching with ~

The ~ operator indicates that the given field need only partially, instead of exactly, match the given string (the value used with this operator must be a string, not an integer).

For example, the filter where research_orgs.name~"Saarland Uni" would match both the organization named “Saarland University” and the one named “Universitätsklinikum des Saarlandes”, and any other organization whose name includes the terms “Saarland” and “Uni” (the order is unimportant).

%%dsldf
search patents
    where assignee_names ~ "IBM"
return assignees limit 5

Returned Assignees: 5
Time: 4.83s

	city_name	count	country_name	id	latitude	linkout	longitude	name	state_name	types
0	Armonk	101184	United States	grid.410484.d	41.108540	[http://www.ibm.com/]	-73.720470	IBM (United States)	New York	[Company]
1	Winchester	5830	United Kingdom	grid.14648.3f	51.026752	[https://www.ibm.com/in-en]	-1.397260	IBM (United Kingdom)	Hampshire	[Company]
2	Böblingen	3806	Germany	grid.424815.e	48.673832	[http://www.ibm.com/de/de/]	9.034824	IBM (Germany)	NaN	[Company]
3	Paris	1511	France	grid.424192.8	48.843975	[https://www.ibm.com/fr-fr/]	2.396280	IBM (France)	NaN	[Company]
4	Markham	1359	Canada	grid.292504.8	43.819103	[http://www.ibm.com/ca/en/]	-79.333930	IBM (Canada)	Ontario	[Company]

3.6 Emptiness filters is empty

To filter records which contain specific field or to filter those which contain an empty field, it is possible to use something like where research_orgs is not empty or where issn is empty.

%%dsldf
search publications
    for "iron graphene"
    where researchers is empty
    and research_orgs is not empty
return publications[id+title+researchers+research_orgs+type] limit 5

Returned Publications: 5 (total = 5298)
Time: 1.45s

	id	research_orgs	title	type
0	pub.1144344172	[{'acronym': 'USP', 'city_name': 'São Paulo', ...	Electrochemical sensor for isoniazid detection...	article
1	pub.1143970005	[{'acronym': 'KFUPM', 'city_name': 'Dhahran', ...	A review on underground hydrogen storage: Insi...	article
2	pub.1144588192	[{'city_name': 'Shanghai', 'country_name': 'Ch...	Destructing surfactant network in nanoemulsion...	article
3	pub.1144553605	[{'acronym': 'SIT', 'city_name': 'Hoboken', 'c...	Release of Pb adsorbed on graphene oxide surfa...	article
4	pub.1144390006	[{'city_name': 'Semenyih', 'country_name': 'Ma...	Synthesis of a highly recoverable 3D MnO2/rGO ...	article

4. Searching for Researchers

The DSL offers different mechanisms for searching for researchers (e.g. publication authors, grant investigators), each of them presenting specific advantages.

4.1 Exact name searches

Special full-text indices allows to look up a researcher’s name and surname exactly as they appear in the source documents they derive from.

This approach has a broad scope, as it allows to search the full collection of Dimensions documents irrespectively of whether a researcher was succesfully disambiguated (and hence given a Dimensions ID). On the other hand, this approach will only match names as they appear in the source document, so different spellings or initials are not necessarily returned via a single query.

search in [authors|investigators|inventors]

It is possible to look up publications authors using a specific search index called authors.

This method expects case insensitive phrases, in format \("<first name> <last name>"\) or reverse order. Note that strings in double quotes that contain nested quotes must always be escaped by a backslash \.

%dsldf search publications in authors for "\"Charles Peirce\"" return publications limit 5

Returned Publications: 5 (total = 267)
Time: 0.54s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1141018395	4	81-91	PAP : prolégomènes à une apologie du pragmatisme	article	N° 163	2021	jour.1142204	Cahiers philosophiques
1	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1140830594	NaN	63-71	COMO TEORIZAR	chapter	NaN	2021	NaN	NaN
2	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1140830593	NaN	55-61	INDUÇÃO ABDUTÓRIA	chapter	NaN	2021	NaN	NaN
3	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1137292963	NaN	256-279	37 Lowell Lecture IV	chapter	NaN	2021	NaN	NaN
4	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1137292823	NaN	437-438	Name Index	chapter	NaN	2021	NaN	NaN

Instead of first name, initials can also be used. These are examples of valid research search phrases:

• \"Peirce, Charles S.\"

• \"Charles S. Peirce\"

• \"CS Peirce\"

• \"Peirce CS\"

• \"C S Peirce\"

• \"Peirce C S\"

• \"C Peirce\"

• \"Peirce C\"

• \"Charles Peirce\"

• \"Peirce Charles\"

Warning: In order to produce valid results an author or an investigator search query must contain at least two components or more (e.g., name and surname, either in full or initials).

Investigators search is similar to authors search, only it allows to search on grants and clinical trials using a separate search index investigators, and on patents using the index inventors.

%%dsldf
search clinical_trials in investigators for "\"John Smith\""
return clinical_trials limit 5

Returned Clinical_trials: 5 (total = 7)
Time: 1.00s

	active_years	id	investigators	title
0	[2021, 2022, 2023]	NCT05110248	[[Bryn M Horsington, , Contact, Gemini One, 55...	Research and Development of Novel Quantitative...
1	[2019, 2020]	NCT04107519	[[Herman Taylor, MD, MPH, Principal Investigat...	Goal-Directed Resilience Training to Mitigate ...
2	[2019, 2020, 2021]	NCT04072380	[[Sallie Pulliam, , Contact, Pinnacle Research...	A Phase 2, Double-blind, Placebo-controlled, P...
3	[2019, 2020, 2021, 2022, 2023]	NCT03694600	[[Alamdar Rizvi, MS, Study Director, Laborator...	Prospective Clinical Trial to Detect Liver Can...
4	[2018, 2019, 2020, 2021, 2022, 2023]	NCT03653832	[[Timothy Walsh, MBChB MD MSc, Principal Inves...	Alpha 2 Agonists for Sedation to Produce Bette...

%%dsldf
search grants in investigators for "\"Satoko Shimazaki\""
return grants limit 5

Returned Grants: 4 (total = 4)
Time: 0.54s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2021, 2022]	2022-08-31	[{'acronym': 'NEH', 'city_name': 'Washington D...	National Endowment for the Humanities	FEL-263245-19	grant.7925589	en	Kabuki Actors, Print Technology, and the Theat...	2021-09-01	2021	Kabuki Actors, Print Technology, and the Theat...
1	[2018, 2019, 2020, 2021]	2021-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	18K00431	grant.7527261	ja	古・中英語期における女性聖人伝の系譜研究：Aelfricのテクストと言語を中心に	2018-04-01	2018	Genealogy research on female saints in the Pal...
2	[2015, 2016, 2017, 2018]	2018-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	15K02313	grant.5858713	en	Images of Women in the Old English Lives of Sa...	2015-04-01	2015	Images of Women in the Old English Lives of Sa...
3	[2012, 2013, 2014, 2015]	2015-03-31	[{'acronym': 'JSPS', 'city_name': 'Tokyo', 'co...	Japan Society for the Promotion of Science	24520310	grant.6086985	en	Reception and Transfromation of the Images of ...	2012-04-01	2012	Reception and Transfromation of the Images of ...

%%dsldf
search patents in inventors for "\"John Smith\""
return patents limit 5

Returned Patents: 5 (total = 724)
Time: 0.72s

	assignee_names	filing_status	id	inventor_names	publication_date	times_cited	title	year	assignees
0	[KLEEN TEX IND INC]	Application	ZA-989065-B	[GORDON DAVID E, SMITH JOHN, LEVESQUE JIM, MCH...	1999-06-30	0	Track control floor mats and applications ther...	1998	NaN
1	[P I P PROPERTY MANAGERS CC]	Application	ZA-200303048-B	[SMITH JOHN, ROOS ANDREW IAN, ASHURST WILLIAM ...	2003-10-22	2	System for and method of transferring informat...	2003	NaN
2	[MILNES PTY LTD]	Application	ZA-200002202-B	[RICKARDS GARY, SMITH JOHN]	2000-11-23	0	Pipe clamp.	2000	NaN
3	[SMITH SOLUTIONS LP]	Application	WO-2021100020-A1	[SMITH JOHN]	2021-05-27	0	SOLAR BLOCKER	2020	NaN
4	[IBM CHINA INVESTMENT CO LTD, IBM UK, IBM]	Application	WO-2019224650-A1	[CONNELL II JONATHAN, PANKANTI SHARATHCHANDRA,...	2019-11-28	0	GENERATING A TEXTUAL DESCRIPTION OF AN IMAGE U...	2019	[{'city_name': 'Armonk', 'country_name': 'Unit...

4.2 Fuzzy Searches

This type of search is similar to full-text search, with the difference that it allows searching by only a part of a name, e.g. only the ‘last name’ of a person, by using the where clause.

Note At this moment, this type of search is only available for publications. Other sources will add this option in the future.

For example:

%%dsldf
search publications where authors = "Hawking"
return publications[id+doi+title+authors] limit 5

Returned Publications: 5 (total = 2103)
Time: 2.69s

	authors	doi	id	title
0	[{'affiliations': [{'city': 'Ghent', 'city_id'...	10.1016/j.geomorph.2021.108080	pub.1144137800	Long-lasting impacts of a 20th century glacial...
1	[{'affiliations': [{'city': "Xi'an", 'city_id'...	10.1038/s41467-022-28032-1	pub.1144813161	Globally elevated chemical weathering rates be...
2	[{'affiliations': [{'city': 'Marseille', 'city...	10.1007/jhep01(2022)063	pub.1144755056	Search for exotic decays of the Higgs boson in...
3	[{'affiliations': [{'city': 'Marseille', 'city...	10.1140/epjc/s10052-021-09807-0	pub.1144445886	Performance of the ATLAS Level-1 topological t...
4	[{'affiliations': [{'city': 'Marseille', 'city...	10.1103/physrevd.105.012006	pub.1144591364	Search for Higgs boson decays into a pair of p...

Generally speaking, using a where clause to search authors is less precise that using the relevant exact-search syntax.

On the other hand, using a where clause can be handy if one wants to combine an author search with another full-text search index.

For example:

%%dsldf
search publications
    in title_abstract_only for "dna replication"
    where authors = "smith"
return publications limit 5

Returned Publications: 5 (total = 1637)
Time: 1.14s

	authors	id	title	type	year	journal.id	journal.title	issue	pages	volume
0	[{'affiliations': [{'city': 'Seattle', 'city_i...	pub.1144684784	Dynamic configurations of meiotic DNA-break ho...	article	2022	jour.1006098	Journal of Cell Science	NaN	NaN	NaN
1	[{'affiliations': [{'city': 'Urbana', 'city_id...	pub.1144817613	Fundamental behaviors emerge from simulations ...	article	2022	jour.1019114	Cell	2	345-360.e28	185
2	[{'affiliations': [{'city': 'Jackson', 'city_i...	pub.1143745236	Epigenome-wide association study of serum urat...	article	2021	jour.1043282	Nature Communications	1	7173	12
3	[{'affiliations': [{'city': 'Rochester', 'city...	pub.1142528147	The mitochondrial iron transporter ABCB7 is re...	article	2021	jour.1046517	eLife	NaN	e69621	10
4	[{'affiliations': [{'city': 'London', 'city_id...	pub.1142494563	Pre-existing polymerase-specific T cells expan...	article	2021	jour.1018957	Nature	7891	110-117	601

4.3 Using the disambiguated Researchers database

The Dimensions Researchers source is a database of researchers information algorithmically extracted and disambiguated from all of the other content sources (publications, grants, clinical trials etc..).

By using the researchers source it is possible to match an ‘aggregated’ person object linking together multiple publication authors, grant investigators etc.. irrespectively of the form their names can take in the original source documents.

However, since database does not contain all authors and investigators information available in Dimensions.

E.g. think of authors from older publications, or authors with very common names that are difficult to disambiguate, or very new authors, who have only one or few publications. In such cases, using full-text authors search might be more appropriate.

Examples:

%%dsldf
search researchers for "\"Satoko Shimazaki\""
return researchers[basics+obsolete]

Returned Researchers: 4 (total = 4)
Time: 0.61s

	first_name	id	last_name	obsolete	research_orgs
0	Satoko	ur.07751146721.59	Shimazaki	0	NaN
1	Satoko	ur.015527473602.63	Shimazaki	0	[{'acronym': 'UCB', 'city_name': 'Boulder', 'c...
2	Satoko	ur.014307627665.09	Shimazaki	0	[{'acronym': 'UCLA', 'city_name': 'Los Angeles...
3	Satoko	ur.010537333602.30	Shimazaki	1	NaN

NOTE pay attentiont to the obsolete field. This indicates the researcher ID status. 0 means that the researcher ID is still active, 1 means that the researcher ID is no longer valid. This is due to the ongoing process of refinement of Dimensions researchers.

Hence the query above is best written like this:

%%dsldf
search researchers where obsolete=0 for "\"Satoko Shimazaki\""
return researchers[basics+obsolete]

Returned Researchers: 3 (total = 3)
Time: 1.00s

	first_name	id	last_name	obsolete	research_orgs
0	Satoko	ur.07751146721.59	Shimazaki	0	NaN
1	Satoko	ur.015527473602.63	Shimazaki	0	[{'acronym': 'UCB', 'city_name': 'Boulder', 'c...
2	Satoko	ur.014307627665.09	Shimazaki	0	[{'acronym': 'UCLA', 'city_name': 'Los Angeles...

With Researchers, one can use other fields as well:

%%dsldf
search researchers
    where obsolete=0 and last_name="Shimazaki"
return researchers[basics] limit 5

Returned Researchers: 5 (total = 479)
Time: 0.70s

	first_name	id	last_name	research_orgs
0	Yoshiaki	ur.07777053663.32	Shimazaki	[{'acronym': 'KUIS', 'city_name': 'Miki', 'cou...
1	Takanori	ur.07761700432.36	Shimazaki	[{'city_name': 'Sendai', 'country_name': 'Japa...
2	Toshiharu	ur.07755624517.66	Shimazaki	[{'city_name': 'Toyama', 'country_name': 'Japa...
3	Satoko	ur.07751146721.59	Shimazaki	NaN
4	Junya	ur.0773771745.48	Shimazaki	[{'city_name': 'Suita', 'country_name': 'Japan...

5. Returning results

After the search phrase, a query must contain one or more return phrases, specifying the content and format of the information that should be returned.

5.1 Returning Multiple Sources

Multiple results may not be returned in a single return phrase.

%%dsldf
search publications
return funders limit 5
return research_orgs limit 5
return year

Returned Funders: 5
Returned Research_orgs: 5
Returned Year: 20
Time: 3.56s
[Warning] Dataframe created from first available key, but more than one JSON key found: ['funders', 'research_orgs', 'year']

	acronym	city_name	count	country_name	id	latitude	linkout	longitude	name	types	state_name
0	NSFC	Beijing	2619510	China	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.339830	National Natural Science Foundation of China	[Government]	NaN
1	EC	Brussels	893414	Belgium	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]	NaN
2	MOST	Beijing	806641	China	grid.424020.0	39.827835	[http://www.most.gov.cn/eng/]	116.316284	Ministry of Science and Technology of the Peop...	[Government]	NaN
3	JSPS	Tokyo	712701	Japan	grid.54432.34	35.687160	[http://www.jsps.go.jp/]	139.740390	Japan Society for the Promotion of Science	[Nonprofit]	NaN
4	NCI	Bethesda	623054	United States	grid.48336.3a	39.004326	[http://www.cancer.gov/]	-77.101190	National Cancer Institute	[Government]	Maryland

5.2 Returning Specific Fields

For control over which information from each given record will be returned, a source or entity name in the results phrase can be optionally followed by a specification of fields and fieldsets to be included in the JSON results for each retrieved record.

The fields specification may be an arbitrary list of field names enclosed in brackets ([, ]), with field names separated by a plus sign (+). Minus sign (-) can be used to exclude field or a fieldset from the result. Field names thus listed within brackets must be “known” to the DSL, and therefore only a subset of fields may be used in this syntax (see note below).

%%dsldf
search grants
return grants[grant_number + title + language] limit 5

Returned Grants: 5 (total = 6115921)
Time: 0.59s

	grant_number	language	title
0	FL210100107	en	Tracking nanoparticles: from cell culture to i...
1	2127438	en	NNA Planning: Developing community frameworks ...
2	101019146	en	Seeking Constraints on Open Ocean Biocalcifica...
3	101003021	en	New frontiers in advanced glycotherapy for cancer
4	2105918	en	RUI: Exciton-Phonon Interactions in Solids bas...

%%dsldf
search clinical_trials
return clinical_trials [id+ title + acronym + phase] limit 5

Returned Clinical_trials: 5 (total = 685074)
Time: 0.53s

	acronym	id	phase	title
0	HFHRV	UMIN000046696	N/A	Prediction of development and severity of hear...
1	Examination of stimulation brightness of multi...	UMIN000046695	N/A	Examination of stimulation brightness of multi...
2	FJ logic test	UMIN000046689	N/A	Effect on logical thinking ability and cogniti...
3	A study to evaluate the effect after using dia...	UMIN000046688	N/A	A study to evaluate the effect after using dia...
4	The effect of Dipeptidyl Peptidase 4 inhibitor...	UMIN000046686	N/A	The effect of Dipeptidyl Peptidase 4 inhibitor...

Shortcuts: ``fieldsets``

The fields specification may be the name of a pre-defined fieldset (e.g. extras, basics). These are shortcuts that can be handy when testing out new queries, for example.

NOTE In general when writing code used in integrations or long-standing extraction scripts it is best to return specific fields rather that a predefined set. This has also the advantage of making queries faster by avoiding the extraction of unnecessary data.

%%dsldf
search grants
return grants [basics] limit 5

Returned Grants: 5 (total = 6115921)
Time: 0.57s

	active_year	end_date	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title
0	[2022, 2023, 2024, 2025, 2026, 2027]	2027-12-01	[{'acronym': 'ARC', 'city_name': 'Canberra', '...	Australian Research Council	FL210100107	grant.9782236	en	Tracking nanoparticles: from cell culture to i...	2022-12-01	2022	Tracking nanoparticles: from cell culture to i...
1	[2022, 2023]	2023-05-31	[{'acronym': 'NSF GEO', 'city_name': 'Arlingto...	Directorate for Geosciences	2127438	grant.9752271	en	NNA Planning: Developing community frameworks ...	2022-12-01	2022	NNA Planning: Developing community frameworks ...
2	[2022, 2023, 2024, 2025, 2026, 2027]	2027-11-30	[{'acronym': 'ERC', 'city_name': 'Brussels', '...	European Research Council	101019146	grant.9708025	en	Seeking Constraints on Open Ocean Biocalcifica...	2022-12-01	2022	Seeking Constraints on Open Ocean Biocalcifica...
3	[2022, 2023, 2024, 2025, 2026, 2027]	2027-11-30	[{'acronym': 'ERC', 'city_name': 'Brussels', '...	European Research Council	101003021	grant.9661402	en	New frontiers in advanced glycotherapy for cancer	2022-12-01	2022	New frontiers in advanced glycotherapy for cancer
4	[2022, 2023, 2024, 2025]	2025-10-31	[{'acronym': 'NSF MPS', 'city_name': 'Arlingto...	Directorate for Mathematical & Physical Sciences	2105918	grant.9890102	en	RUI: Exciton-Phonon Interactions in Solids bas...	2022-11-15	2022	RUI: Exciton-Phonon Interactions in Solids bas...

%%dsldf
search publications
return publications [basics+times_cited] limit 5

Returned Publications: 5 (total = 124848001)
Time: 1.29s

	authors	id	issue	pages	times_cited	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1144593888	3	284-292	0	Profile of ectoparasites and biometric conditi...	article	10	2022	jour.1150855	Depik Jurnal
1	[{'affiliations': [{'city': 'Shanghai', 'city_...	pub.1144587500	NaN	1-16	0	Experimental study of stratified lean burn cha...	article	NaN	2022	jour.1136510	Frontiers in Energy
2	[{'affiliations': [{'city': 'Budapest', 'city_...	pub.1144327837	NaN	NaN	0	Statistical approaches to explore the linkages...	article	NaN	2022	jour.1271150	Journal of Water Supply Research and Technolog...
3	[{'affiliations': [{'city': 'Hangzhou', 'city_...	pub.1141731113	9	1-40	0	Opportunities and Challenges in Code Search Tools	article	54	2022	jour.1119907	ACM Computing Surveys
4	[{'affiliations': [{'city': 'Melbourne', 'city...	pub.1141731112	9	1-36	0	Ransomware Mitigation in the Modern Era: A Com...	article	54	2022	jour.1119907	ACM Computing Surveys

The fields specification may be an (all), to indicate that all fields available for the given source should be returned.

%%dsldf
search publications
return publications [all] limit 5

Returned Errors: 1
Time: 0.48s
1 QueryError found
Semantic errors found:
        Field / Fieldset 'all' is not present in Source 'publications'. Available fields: abstract,acknowledgements,altmetric,altmetric_id,arxiv_id,authors,authors_count,book_doi,book_series_title,book_title,category_bra,category_for,category_hra,category_hrcs_hc,category_hrcs_rac,category_icrp_cso,category_icrp_ct,category_rcdc,category_sdg,category_uoa,clinical_trial_ids,concepts,concepts_scores,date,date_inserted,date_online,date_print,dimensions_url,doi,field_citation_ratio,funder_countries,funders,id,issn,issue,journal,journal_lists,journal_title_raw,linkout,mesh_terms,open_access,pages,pmcid,pmid,proceedings_title,publisher,recent_citations,reference_ids,referenced_pubs,relative_citation_ratio,research_org_cities,research_org_countries,research_org_country_names,research_org_names,research_org_state_codes,research_org_state_names,research_orgs,researchers,resulting_publication_doi,source_title,subtitles,supporting_grant_ids,times_cited,title,type,volume,year and available fieldsets: basics,book,categories,extras

5.3 Returning Facets

In addition to returning source records matching a query, it is possible to \(facet\) on the entity fields related to a particular source and return only those entity values as an aggregrated view of the related source data. This operation is similar to a \(group by\) or \(pivot table\).

Warning Faceting can return up to a maximum of 1000 results. This is to ensure adequate performance with all queries. Furthemore, although the limit operator is allowed, the skip operator cannot be used.

%%dsldf
search publications
    for "coronavirus"
return research_orgs limit 5

Returned Research_orgs: 5
Time: 0.59s

	city_name	count	country_name	id	latitude	linkout	longitude	name	state_name	types	acronym
0	Cambridge	7327	United States	grid.38142.3c	42.377052	[http://www.harvard.edu/]	-71.116650	Harvard University	Massachusetts	[Education]	NaN
1	Oxford	4357	United Kingdom	grid.4991.5	51.753437	[http://www.ox.ac.uk/]	-1.254010	University of Oxford	Oxfordshire	[Education]	NaN
2	Baltimore	4071	United States	grid.21107.35	39.328888	[https://www.jhu.edu/]	-76.620280	Johns Hopkins University	Maryland	[Education]	JHU
3	Toronto	3876	Canada	grid.17063.33	43.661667	[http://www.utoronto.ca/]	-79.395000	University of Toronto	Ontario	[Education]	NaN
4	London	3477	United Kingdom	grid.83440.3b	51.524470	[http://www.ucl.ac.uk/]	-0.133982	University College London	NaN	[Education]	UCL

%%dsldf
search publications
    for "coronavirus"
return research_org_countries limit 5
return year limit 5
return category_for limit 5

Returned Category_for: 5
Returned Research_org_countries: 5
Returned Year: 5
Time: 0.91s
[Warning] Dataframe created from first available key, but more than one JSON key found: ['category_for', 'research_org_countries', 'year']

	count	id	name
0	290203	2211	11 Medical and Health Sciences
1	116222	3177	1117 Public Health and Health Services
2	88129	3053	1103 Clinical Sciences
3	46291	2206	06 Biological Sciences
4	39871	3114	1108 Medical Microbiology

For control over the organization and headers of the JSON query results, the return keyword in a return phrase may be followed by the keyword in and then a group name for this group of results, where the group name is enclosed in double quotes(").

Also, one can define aliases that replace the defaul JSON fields names with other ones provided by the user.

See the official documentation for more details about this feature.

%%dsl
search publications
return in "facets" funders
return in "facets" research_orgs

Returned Facets: 2
Time: 2.74s

<dimcli.DslDataset object #4694861376. Records: 2/124848001>

5.4 What the query statistics refer to - sources VS facets

When performing a DSL search, a _stats object is return which contains some useful info eg the total number of records available for a search.

%%dsldf
search publications
  where year in [2013:2018] and research_orgs="grid.258806.1"
return publications limit 5

Returned Publications: 5 (total = 5807)
Time: 0.68s

	authors	id	pages	title	type	year	volume	issue	journal.id	journal.title
0	[{'affiliations': [{'city': 'Kitakyushu', 'cit...	pub.1113308928	123-127	A Hybrid DCT-CLAHE Approach for Brightness Enh...	proceeding	2018	NaN	NaN	NaN	NaN
1	[{'affiliations': [{'city': 'Khulna', 'city_id...	pub.1112614472	1-5	Saliency Detection using Boundary Aware Region...	proceeding	2018	00	NaN	NaN	NaN
2	[{'affiliations': [{'city': 'Kitakyushu', 'cit...	pub.1110958161	39	Optimized coordinated control of LFC and SMES ...	article	2018	3	1	jour.1157179	Protection and Control of Modern Power Systems
3	[{'affiliations': [{'city': 'El Paso', 'city_i...	pub.1110932965	1445-1452	Electrostatic Discharge Threshold on Coverglas...	article	2018	47	2	jour.1031080	IEEE Transactions on Plasma Science
4	[{'affiliations': [{'city': 'Kitakyushu', 'cit...	pub.1110012351	518-526	The Role of Lanthanum in a Nickel Oxide‐Based ...	article	2018	12	2	jour.1297486	ChemSusChem

It is important to note though that the total number always refers to the main source, never the facets one is searching for.

For example, in this query we return researchers linked to publications:

%%dsldf
search publications
  where year in [2013:2018] and research_orgs="grid.258806.1"
return researchers limit 5

Returned Researchers: 5
Time: 0.77s

	count	first_name	id	last_name	orcid_id	research_orgs
0	152	Shuzi	ur.01055753603.27	Hayase	[0000-0002-0756-4808]	[grid.419082.6, grid.266298.1, grid.410825.a, ...
1	108	Ting-Li	ur.01144540527.52	Ma	[0000-0002-3310-459X]	[grid.11135.37, grid.258806.1, grid.411485.d, ...
2	107	Masayuki	ur.011212042763.67	Hikita	NaN	[grid.27476.30, grid.462727.2, grid.258806.1]
3	101	Huimin	ur.016357156077.09	Lu	[0000-0001-9794-3221]	[grid.9227.e, grid.16821.3c, grid.1024.7, grid...
4	100	M Kozako M	ur.07644453127.11	Kozako	NaN	[grid.462727.2, grid.482504.f, grid.4444.0, gr...

NOTE: facet results can be 1000 at most (due to performance limitations) so if there are more than 1000 it is not possible to know the total number.

5.5 Paginating Results

At the end of a return phrase, the user can specify the maximum number of results to be returned and the number of top records to skip over before returning the first result record, for e.g. returning large result sets page-by-page (i.e. “paging” results) as described below.

This is done using the keyword limit followed by the maximum number of results to return, optionally followed by the keyword skip and the number of results to skip (the offset).

%%dsldf
search publications return publications limit 10

Returned Publications: 10 (total = 124848001)
Time: 0.59s

	authors	id	issue	pages	title	type	volume	year	journal.id	journal.title
0	[{'affiliations': [], 'corresponding': '', 'cu...	pub.1144593888	3	284-292	Profile of ectoparasites and biometric conditi...	article	10	2022	jour.1150855	Depik Jurnal
1	[{'affiliations': [{'city': 'Shanghai', 'city_...	pub.1144587500	NaN	1-16	Experimental study of stratified lean burn cha...	article	NaN	2022	jour.1136510	Frontiers in Energy
2	[{'affiliations': [{'city': 'Budapest', 'city_...	pub.1144327837	NaN	NaN	Statistical approaches to explore the linkages...	article	NaN	2022	jour.1271150	Journal of Water Supply Research and Technolog...
3	[{'affiliations': [{'city': 'Hangzhou', 'city_...	pub.1141731113	9	1-40	Opportunities and Challenges in Code Search Tools	article	54	2022	jour.1119907	ACM Computing Surveys
4	[{'affiliations': [{'city': 'Melbourne', 'city...	pub.1141731112	9	1-36	Ransomware Mitigation in the Modern Era: A Com...	article	54	2022	jour.1119907	ACM Computing Surveys
5	[{'affiliations': [{'city': 'Sydney', 'city_id...	pub.1141731111	9	1-38	Service Computing for Industry 4.0: State of t...	article	54	2022	jour.1119907	ACM Computing Surveys
6	[{'affiliations': [{'city': 'Berlin', 'city_id...	pub.1141731110	9	1-38	Handling Iterations in Distributed Dataflow Sy...	article	54	2022	jour.1119907	ACM Computing Surveys
7	[{'affiliations': [{'city': 'Linz', 'city_id':...	pub.1141731109	9	1-35	Adversary Models for Mobile Device Authentication	article	54	2022	jour.1119907	ACM Computing Surveys
8	[{'affiliations': [{'city': 'Amberg', 'city_id...	pub.1141731108	9	1-33	A Survey on Client Throughput Prediction Algor...	article	54	2022	jour.1119907	ACM Computing Surveys
9	[{'affiliations': [{'city': 'Genoa', 'city_id'...	pub.1141731107	9	1-33	Gotta CAPTCHA ’Em All: A Survey of 20 Years of...	article	54	2022	jour.1119907	ACM Computing Surveys

If paging information is not provided, the default values limit 20 skip 0 are used, so the two following queries are equivalent:

Combining limit and skip across multiple queries enables paging or batching of results; e.g. to retrieve 30 grant records divided into 3 pages of 10 records each, the following three queries could be used:

return grants limit 10           => get 1st 10 records for page 1 (skip 0, by default)
return grants limit 10 skip 10   => get next 10 for page 2; skip the 10 we already have
return grants limit 10 skip 20   => get another 10 for page 3, for a total of 30

5.6 Sorting Results

A sort order for the results in a given return phrase can be specified with the keyword sort by followed by the name of * a field (in the case that a source is being requested) * an indicator (aggregation) (in the case that one or more facets are being requested).

By default, the result set of full text queries (\(search ... for "full text query"\)) is sorted by “relevance”. Additionally, it is possible to specify the sort order, using asc or desc keywords. By default, descending order is selected.

%%dsldf
search grants
    for "nanomaterials"
return grants sort by title desc limit 5

Returned Grants: 5 (total = 20429)
Time: 0.71s

	active_year	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title	end_date
0	[2015]	[{'acronym': 'DFG', 'city_name': 'Bonn', 'coun...	German Research Foundation	280331443	grant.4841519	en	Transmissionselektronenmikroskop	2015-01-01	2015	Transmissionselektronenmikroskop	NaN
1	[2012]	[{'acronym': 'DFG', 'city_name': 'Bonn', 'coun...	German Research Foundation	220923099	grant.4823271	de	Transmissionselektronenmikroskop	2012-01-01	2012	Transmissionselektronenmikroskop	NaN
2	[2011, 2012, 2013, 2014, 2015]	[{'acronym': 'BELSPO', 'city_name': 'Brussels'...	Belgian Federal Science Policy Office	3E120109	grant.6774902	en	Snowcontrol.	2011-06-16	2011	Snowcontrol.	2015-06-13
3	[2015, 2016]	[{'acronym': 'FNP', 'city_name': 'Warsaw', 'co...	Foundation for Polish Science	START 79.2015	grant.9182996	pl	Stypendium Naukowe START	2015-06-01	2015	START Scholarship	2016-06-01
4	[2014, 2015]	[{'acronym': 'FNP', 'city_name': 'Warsaw', 'co...	Foundation for Polish Science	START 81.2014	grant.9182975	pl	Stypendium Naukowe START	2014-06-01	2014	START Scholarship	2015-06-01

%%dsldf
search grants
    for "nanomaterials"
return grants  sort by relevance desc limit 5

Returned Grants: 5 (total = 20429)
Time: 0.56s

	active_year	funders	funding_org_name	grant_number	id	language	original_title	start_date	start_year	title	end_date
0	[2016]	[{'acronym': 'BELSPO', 'city_name': 'Brussels'...	Belgian Federal Science Policy Office	37_3655	grant.8597838	en	"Bottom up" self-assembly of π-functional nano...	2016-11-09	2016	"Bottom up" self-assembly of π-functional nano...	NaN
1	[2005, 2006, 2007, 2008, 2009, 2010, 2011]	[{'acronym': 'Royal Society', 'city_name': 'Lo...	Royal Society	7780-1	grant.7928225	en	NANOMATERIALS FOR BIOMOLECULAR SCIENCES AND NA...	2005-10-01	2005	NANOMATERIALS FOR BIOMOLECULAR SCIENCES AND NA...	2011-03-01
2	[2011, 2012, 2013, 2014]	[{'acronym': 'Royal Society', 'city_name': 'Lo...	Royal Society	7780	grant.7928224	en	Nanomaterials for Biomolecular and Biomedical ...	2011-03-01	2011	Nanomaterials for Biomolecular and Biomedical ...	2014-03-01
3	[2005, 2006]	[{'acronym': 'ITC', 'city_name': 'Hong Kong', ...	Innovation and Technology Commission	InP/006/05	grant.7166197	en	Institute of NanoMaterials and NanoTechnology ...	2005-06-24	2005	Institute of NanoMaterials and NanoTechnology ...	2006-06-23
4	[2011]	[{'acronym': 'CFI', 'city_name': 'Ottawa', 'co...	Canada Foundation for Innovation	CFI9790	grant.6767895	en	Platform for nanomaterials excitation and in-s...	2011-06-14	2011	Platform for nanomaterials excitation and in-s...	NaN

Number of citations per publication

%%dsldf
search publications
return publications  [doi + times_cited]
    sort by times_cited limit 5

Returned Publications: 5 (total = 124848001)
Time: 1.27s

	doi	times_cited
0	10.1016/s0021-9258(19)52451-6	262717
1	10.1038/227680a0	220122
2	10.1016/0003-2697(76)90527-3	200817
3	10.1103/physrevlett.77.3865	117222
4	10.1006/meth.2001.1262	111893

Recent citations per publication. Note: Recent citation refers to the number of citations accrued in the last two year period. A single value is stored per document and the year window rolls over in July.

%%dsldf
search publications
return publications [doi + recent_citations]
    sort by recent_citations limit 5

Returned Publications: 5 (total = 124848001)
Time: 1.21s

	doi	recent_citations
0	10.1109/cvpr.2016.90	37726
1	10.3322/caac.21492	35929
2	10.1103/physrevlett.77.3865	30347
3	10.1006/meth.2001.1262	28571
4	10.1016/s0140-6736(20)30183-5	27347

When a facet is being returned, the indicator used in the sort phrase must either be count (the default, such that sort by count is unnecessary), or one of the indicators specified in the aggregate phrase, i.e. one whose values are being computed in the faceting operation.

%%dsldf
search publications
    for "nanomaterials"
return research_orgs
    aggregate altmetric_median, rcr_avg sort by rcr_avg limit 5

Returned Research_orgs: 5
Time: 3.38s

	acronym	altmetric_median	city_name	count	country_name	id	latitude	linkout	longitude	name	rcr_avg	state_name	types
0	NIDCD	85.0	Bethesda	1	United States	grid.214431.1	39.105713	[http://www.nidcd.nih.gov/Pages/default.aspx]	-77.186860	National Institute on Deafness and Other Commu...	245.190002	Maryland	[Government]
1	NaN	85.0	Providence	1	United States	grid.241223.4	41.810280	[http://www.womenandinfants.org/]	-71.410880	Women & Infants Hospital of Rhode Island	245.190002	Rhode Island	[Healthcare]
2	SGPGIMS	85.0	Lucknow	1	India	grid.263138.d	26.742609	[http://www.sgpgi.ac.in/]	80.946144	Sanjay Gandhi Post Graduate Institute of Medic...	245.190002	NaN	[Facility]
3	NaN	85.0	Charlottesville	1	United States	grid.412587.d	38.032307	[http://www.uvahealth.com/]	-78.498610	University of Virginia Health System	245.190002	Virginia	[Healthcare]
4	NaN	85.0	São Paulo	1	Brazil	grid.413320.7	-23.565285	[http://www.accamargo.org.br/]	-46.635864	AC Camargo Hospital	245.190002	NaN	[Healthcare]

5.7 Unnesting results

Multi-value entity and JSON fields, such as researchers, authors or research_orgs or any of category_* fields may be unnested into top level objects.

This operation makes it easier to do further operations on these objects e.g. counting or processing them further.

This functionality will transform all of the returned multi-value data and turn them into top level keys, such as researchers.id, researchers.first_name, researchers.last_name, while copying other, non-unnested fields, such as id or title of publication for each of them. Returned results are therefore multiplied by as many researchers and categories each original publication has, so they will likely be more than the overall query limit, as the limit applies on the source objects, not the unnested one. If multiple fields are being unnested, then a cartesian product of all unnested fields is being returned.

%%dsldf

search publications for "Japan AND Buddhism"
    where researchers is not empty
return publications[id+year+title+unnest(researchers)] limit 10

Returned objects: 23 (total publications= 45209)
Time: 1.38s

	id	researchers.first_name	researchers.id	researchers.last_name	researchers.orcid_id	researchers.research_orgs	title	year
0	pub.1142524267	Christophe J	ur.011737013277.00	Godlewski	[0000-0002-1391-1108]	[grid.11843.3f, grid.462209.b, grid.9156.b]	Family firms and the cost of borrowing: empiri...	2022
1	pub.1142437244	Saibal	ur.014521275617.23	Ghosh	NaN	[grid.465042.1, grid.507449.b]	Religiosity and bank performance: How strong i...	2022
2	pub.1144045080	Tsuyoshi	ur.016274403511.19	Hatori	NaN	[grid.255464.4, grid.258799.8, grid.32197.3e]	Posttraumatic stress disorder and its predicto...	2022
3	pub.1144045080	Netra Prakash	ur.015100044631.08	Bhandary	NaN	[grid.255464.4]	Posttraumatic stress disorder and its predicto...	2022
4	pub.1142405234	Sibel	ur.016623460225.89	Kuşdemir	NaN	NaN	A Critical Analysis of the Tidal Model of Ment...	2022
5	pub.1142405234	Abe	ur.01164051372.26	Oudshoorn	[0000-0003-0277-8724]	[grid.39381.30]	A Critical Analysis of the Tidal Model of Ment...	2022
6	pub.1142405234	Jean Pierre	ur.011564037563.23	Ndayisenga	[0000-0002-3508-975X]	[grid.39381.30, grid.10818.30]	A Critical Analysis of the Tidal Model of Ment...	2022
7	pub.1142222763	Namgay Pem	ur.011002223475.74	Dorji	NaN	[grid.1009.8, grid.449502.e]	Productivity improvement to sustain small-scal...	2022
8	pub.1142222763	Pema	ur.016673751074.70	Thinley	NaN	[grid.449502.e, grid.473381.a]	Productivity improvement to sustain small-scal...	2022
9	pub.1144292593	Ranjeet	ur.010660116554.38	John	[0000-0002-0150-8450]	[grid.430387.b, grid.17088.36, grid.65519.3e, ...	Sustainability challenges for the social-envir...	2022
10	pub.1144292593	Pavel Ya	ur.014213100657.48	Groisman	[0000-0001-6255-324X]	[grid.4886.2, grid.40803.3f, grid.426292.9, gr...	Sustainability challenges for the social-envir...	2022
11	pub.1144292593	Ginger R H	ur.01323604570.79	Allington	[0000-0003-0446-0576]	[grid.253615.6, grid.484514.8, grid.262962.b, ...	Sustainability challenges for the social-envir...	2022
12	pub.1144292593	Kirsten M	ur.07665600562.61	De Beurs	[0000-0002-9244-3292]	[grid.438526.e, grid.266900.b, grid.14003.36, ...	Sustainability challenges for the social-envir...	2022
13	pub.1144292593	Arnon M	ur.014070213767.33	Karnieli	[0000-0001-8065-9793]	[grid.7489.2, grid.410727.7, grid.41156.37]	Sustainability challenges for the social-envir...	2022
14	pub.1144292593	G Garik	ur.012323502577.70	Gutman	[0000-0002-2979-9675]	[grid.3532.7, grid.164295.d, grid.238252.c, gr...	Sustainability challenges for the social-envir...	2022
15	pub.1144292593	Beyza	ur.014460477732.44	Şat	NaN	NaN	Sustainability challenges for the social-envir...	2022
16	pub.1144292593	Geoffrey M	ur.0751300123.34	Henebry	[0000-0002-8999-2709]	[grid.419222.e, grid.430387.b, grid.17088.36, ...	Sustainability challenges for the social-envir...	2022
17	pub.1144292593	Amarjargal	ur.07662063177.45	Amartuvshin	NaN	[grid.444538.a]	Sustainability challenges for the social-envir...	2022
18	pub.1144292593	Maira	ur.014277742317.84	Kussainova	[0000-0002-9800-6093]	[grid.171588.2]	Sustainability challenges for the social-envir...	2022
19	pub.1143489614	Yunqi	ur.07715015627.67	Fan	NaN	[grid.258151.a]	Audit firm's Confucianism and stock price cras...	2022
20	pub.1140433062	Lorraine K C	ur.016053415455.43	Yeung	NaN	NaN	Which Way Down the Slippery Slope: Arkangel or...	2022
21	pub.1144342388	Goran	ur.010065312255.23	Zendelovski	NaN	NaN	The Ranking of the Western Balkan Countries Ac...	2021
22	pub.1144329854	Rajan Binayek	ur.012335611513.76	Pasa	NaN	[grid.80817.36]	Interface between Tourism and Rural Developmen...	2021

%%dsldf

search publications for "Japan AND Buddhism"
return publications[id+year+title+unnest(category_for)] limit 5

Returned objects: 12 (total publications= 139609)
Time: 1.00s

	category_for.id	category_for.name	id	title	year
0	3675	2103 Historical Studies	pub.1143990292	Arrangement Plan of Inner Mongolia Buddhist Te...	2022
1	2221	21 History and Archaeology	pub.1143990292	Arrangement Plan of Inner Mongolia Buddhist Te...	2022
2	3373	1506 Tourism	pub.1144778122	East meets West: Spiritual tourism in Chinese ...	2022
3	2215	15 Commerce, Management, Tourism and Services	pub.1144778122	East meets West: Spiritual tourism in Chinese ...	2022
4	2215	15 Commerce, Management, Tourism and Services	pub.1142524267	Family firms and the cost of borrowing: empiri...	2022
5	3335	1502 Banking, Finance and Investment	pub.1142524267	Family firms and the cost of borrowing: empiri...	2022
6	2217	17 Psychology and Cognitive Sciences	pub.1144241292	Racist Love	2022
7	3468	1701 Psychology	pub.1144241292	Racist Love	2022
8	3364	1505 Marketing	pub.1143842506	Comparison of localized and foreign restaurant...	2022
9	3373	1506 Tourism	pub.1143842506	Comparison of localized and foreign restaurant...	2022
10	3342	1503 Business and Management	pub.1143842506	Comparison of localized and foreign restaurant...	2022
11	2215	15 Commerce, Management, Tourism and Services	pub.1143842506	Comparison of localized and foreign restaurant...	2022

You can unnest as many fields as you want. However the number of results will grow pretty quickly!

%%dsldf

search publications for "Japan AND Buddhism"
return publications[id+year+title+unnest(category_for)+unnest(researchers)+unnest(research_orgs)] limit 5

Returned objects: 24 (total publications= 139609)
Time: 0.70s

	category_for.id	category_for.name	id	title	year	research_orgs.acronym	research_orgs.city_name	research_orgs.country_name	research_orgs.id	research_orgs.latitude	research_orgs.linkout	research_orgs.longitude	research_orgs.name	research_orgs.types	research_orgs.state_name	researchers.first_name	researchers.id	researchers.last_name	researchers.orcid_id	researchers.research_orgs
0	3675	2103 Historical Studies	pub.1143990292	Arrangement Plan of Inner Mongolia Buddhist Te...	2022	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN
1	2221	21 History and Archaeology	pub.1143990292	Arrangement Plan of Inner Mongolia Buddhist Te...	2022	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN
2	3373	1506 Tourism	pub.1144778122	East meets West: Spiritual tourism in Chinese ...	2022	UdG	Girona	Spain	grid.5319.e	41.985695	[http://www.udg.edu/Not%C3%ADciesiagenda/tabid...	2.827373	University of Girona	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
3	2215	15 Commerce, Management, Tourism and Services	pub.1144778122	East meets West: Spiritual tourism in Chinese ...	2022	UdG	Girona	Spain	grid.5319.e	41.985695	[http://www.udg.edu/Not%C3%ADciesiagenda/tabid...	2.827373	University of Girona	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
4	2215	15 Commerce, Management, Tourism and Services	pub.1142524267	Family firms and the cost of borrowing: empiri...	2022	NaN	Strasbourg	France	grid.11843.3f	48.580276	[http://www.en.unistra.fr/index.php?id=21707]	7.764444	University of Strasbourg	[Education]	Alsace	Christophe J	ur.011737013277.00	Godlewski	[0000-0002-1391-1108]	[grid.11843.3f, grid.462209.b, grid.9156.b]
5	3335	1502 Banking, Finance and Investment	pub.1142524267	Family firms and the cost of borrowing: empiri...	2022	NaN	Strasbourg	France	grid.11843.3f	48.580276	[http://www.en.unistra.fr/index.php?id=21707]	7.764444	University of Strasbourg	[Education]	Alsace	Christophe J	ur.011737013277.00	Godlewski	[0000-0002-1391-1108]	[grid.11843.3f, grid.462209.b, grid.9156.b]
6	2217	17 Psychology and Cognitive Sciences	pub.1144241292	Racist Love	2022	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN
7	3468	1701 Psychology	pub.1144241292	Racist Love	2022	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN	NaN
8	3364	1505 Marketing	pub.1143842506	Comparison of localized and foreign restaurant...	2022	MCU	Taoyuan District	Taiwan	grid.411804.8	25.086351	[http://www1.mcu.edu.tw/Apps/SB/SB_Site.aspx?P...	121.528080	Ming Chuan University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
9	3364	1505 Marketing	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NaN	Brisbane	Australia	grid.1022.1	-27.470610	[http://www.griffith.edu.au/]	153.022860	Griffith University	[Education]	Queensland	NaN	NaN	NaN	NaN	NaN
10	3364	1505 Marketing	pub.1143842506	Comparison of localized and foreign restaurant...	2022	FJU	Taipei	Taiwan	grid.256105.5	25.035807	[http://www.fju.edu.tw/#&panel1-1]	121.433170	Fu Jen Catholic University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
11	3364	1505 Marketing	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NKFUST	Kaohsiung City	Taiwan	grid.412071.1	22.754444	[http://www.nkfust.edu.tw/bin/home.php]	120.333336	National Kaohsiung First University of Science...	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
12	3373	1506 Tourism	pub.1143842506	Comparison of localized and foreign restaurant...	2022	MCU	Taoyuan District	Taiwan	grid.411804.8	25.086351	[http://www1.mcu.edu.tw/Apps/SB/SB_Site.aspx?P...	121.528080	Ming Chuan University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
13	3373	1506 Tourism	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NaN	Brisbane	Australia	grid.1022.1	-27.470610	[http://www.griffith.edu.au/]	153.022860	Griffith University	[Education]	Queensland	NaN	NaN	NaN	NaN	NaN
14	3373	1506 Tourism	pub.1143842506	Comparison of localized and foreign restaurant...	2022	FJU	Taipei	Taiwan	grid.256105.5	25.035807	[http://www.fju.edu.tw/#&panel1-1]	121.433170	Fu Jen Catholic University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
15	3373	1506 Tourism	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NKFUST	Kaohsiung City	Taiwan	grid.412071.1	22.754444	[http://www.nkfust.edu.tw/bin/home.php]	120.333336	National Kaohsiung First University of Science...	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
16	3342	1503 Business and Management	pub.1143842506	Comparison of localized and foreign restaurant...	2022	MCU	Taoyuan District	Taiwan	grid.411804.8	25.086351	[http://www1.mcu.edu.tw/Apps/SB/SB_Site.aspx?P...	121.528080	Ming Chuan University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
17	3342	1503 Business and Management	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NaN	Brisbane	Australia	grid.1022.1	-27.470610	[http://www.griffith.edu.au/]	153.022860	Griffith University	[Education]	Queensland	NaN	NaN	NaN	NaN	NaN
18	3342	1503 Business and Management	pub.1143842506	Comparison of localized and foreign restaurant...	2022	FJU	Taipei	Taiwan	grid.256105.5	25.035807	[http://www.fju.edu.tw/#&panel1-1]	121.433170	Fu Jen Catholic University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
19	3342	1503 Business and Management	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NKFUST	Kaohsiung City	Taiwan	grid.412071.1	22.754444	[http://www.nkfust.edu.tw/bin/home.php]	120.333336	National Kaohsiung First University of Science...	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
20	2215	15 Commerce, Management, Tourism and Services	pub.1143842506	Comparison of localized and foreign restaurant...	2022	MCU	Taoyuan District	Taiwan	grid.411804.8	25.086351	[http://www1.mcu.edu.tw/Apps/SB/SB_Site.aspx?P...	121.528080	Ming Chuan University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
21	2215	15 Commerce, Management, Tourism and Services	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NaN	Brisbane	Australia	grid.1022.1	-27.470610	[http://www.griffith.edu.au/]	153.022860	Griffith University	[Education]	Queensland	NaN	NaN	NaN	NaN	NaN
22	2215	15 Commerce, Management, Tourism and Services	pub.1143842506	Comparison of localized and foreign restaurant...	2022	FJU	Taipei	Taiwan	grid.256105.5	25.035807	[http://www.fju.edu.tw/#&panel1-1]	121.433170	Fu Jen Catholic University	[Education]	NaN	NaN	NaN	NaN	NaN	NaN
23	2215	15 Commerce, Management, Tourism and Services	pub.1143842506	Comparison of localized and foreign restaurant...	2022	NKFUST	Kaohsiung City	Taiwan	grid.412071.1	22.754444	[http://www.nkfust.edu.tw/bin/home.php]	120.333336	National Kaohsiung First University of Science...	[Education]	NaN	NaN	NaN	NaN	NaN	NaN

6. Aggregations

In a return phrase requesting one or more facet results, aggregation operations to perform during faceting can be specified after the facet name(s) by using the keyword aggregate followed by a comma-separated list of one or more indicator names corresponding to the source being searched.

%%dsldf
search publications
    where year > 2010
return research_orgs
    aggregate rcr_avg, altmetric_median limit 5

Returned Research_orgs: 5
Time: 19.81s

	altmetric_median	city_name	count	country_name	id	latitude	linkout	longitude	name	rcr_avg	state_name	types	acronym
0	5.0	Cambridge	270683	United States	grid.38142.3c	42.377052	[http://www.harvard.edu/]	-71.116650	Harvard University	2.493135	Massachusetts	[Education]	NaN
1	4.0	Toronto	177499	Canada	grid.17063.33	43.661667	[http://www.utoronto.ca/]	-79.395000	University of Toronto	2.051205	Ontario	[Education]	NaN
2	2.0	Tokyo	174026	Japan	grid.26999.3d	35.713333	[http://www.u-tokyo.ac.jp/en/]	139.762220	University of Tokyo	1.401742	NaN	[Education]	UT
3	2.0	São Paulo	169020	Brazil	grid.11899.38	-23.563051	[http://www5.usp.br/en/]	-46.730103	University of São Paulo	1.357405	NaN	[Education]	USP
4	2.0	Beijing	159195	China	grid.410726.6	39.909058	[http://www.ucas.ac.cn/]	116.250570	University of Chinese Academy of Sciences	1.678706	NaN	[Education]	UCAS

What are the metrics/aggregations available? See the data sources documentation for information about available indicators.

Alternatively, we can use the ‘schema’ API (describe) to return this information programmatically:

schema = dsl.query("describe schema")
sources = [x for x in schema['sources']]
# for each source name, extract metrics info
for s in sources:
    print("SOURCE:", s)
    for m in schema['sources'][s]['metrics']:
        print("--", schema['sources'][s]['metrics'][m]['name'], " => ", schema['sources'][s]['metrics'][m]['description'], )

SOURCE: clinical_trials
-- count  =>  Total count
SOURCE: datasets
-- count  =>  Total count
SOURCE: grants
-- count  =>  Total count
-- funding  =>  Total funding amount, in USD.
SOURCE: organizations
-- count  =>  Total count
SOURCE: patents
-- count  =>  Total count
SOURCE: policy_documents
-- count  =>  Total count
SOURCE: publications
-- altmetric_avg  =>  Altmetric Attention Score mean
-- altmetric_median  =>  Median Altmetric Attention Score
-- citations_avg  =>  Arithmetic mean of citations
-- citations_median  =>  Median of citations
-- citations_total  =>  Aggregated number of citations
-- count  =>  Total count
-- fcr_gavg  =>  Geometric mean of `field_citation_ratio` field (note: This field cannot be used for sorting results).
-- rcr_avg  =>  Arithmetic mean of `relative_citation_ratio` field.
-- recent_citations_total  =>  For a given article, in a given year, the number of citations accrued in the last two year period. Single value stored per document, year window rolls over in July.
SOURCE: reports
-- count  =>  Total count
SOURCE: researchers
-- count  =>  Total count
SOURCE: source_titles
-- count  =>  Total count

NOTE In addition to any specified aggregations, count is always computed and reported when facet results are requested.

%%dsldf
search grants
    for "5g network"
return funders
    aggregate count, funding sort by funding limit 5

Returned Funders: 5
Time: 0.63s

	acronym	city_name	count	country_name	funding	id	latitude	linkout	longitude	name	types	state_name
0	EC	Brussels	233	Belgium	1.190915e+09	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]	NaN
1	NSF CISE	Arlington	191	United States	1.078005e+08	grid.457785.c	38.880580	[http://www.nsf.gov/dir/index.jsp?org=CISE]	-77.111000	Directorate for Computer & Information Science...	[Government]	Virginia
2	EPSRC	Swindon	88	United Kingdom	6.816998e+07	grid.421091.f	51.567093	[https://www.epsrc.ac.uk/]	-1.784602	Engineering and Physical Sciences Research Cou...	[Government]	England
3	NCRD	Warsaw	8	Poland	5.036449e+07	grid.55047.33	52.227455	[http://www.ncbr.gov.pl/en/]	21.007630	National Centre for Research and Development	[Government]	NaN
4	ITC	Hong Kong	53	China	4.686881e+07	grid.453115.7	22.282640	[http://www.itc.gov.hk/en/about/org.htm]	114.166580	Innovation and Technology Commission	[Government]	NaN

Aggregated total number of citations

%%dsldf
search publications
    for "ontologies"
return funders
    aggregate citations_total
    sort by citations_total  limit 5

Returned Funders: 5
Time: 1.09s

	acronym	citations_total	city_name	count	country_name	id	latitude	linkout	longitude	name	state_name	types
0	NIGMS	1137448.0	Bethesda	16287	United States	grid.280785.0	38.997833	[http://www.nigms.nih.gov/Pages/default.aspx]	-77.09938	National Institute of General Medical Sciences	Maryland	[Facility]
1	NCI	1124818.0	Bethesda	15855	United States	grid.48336.3a	39.004326	[http://www.cancer.gov/]	-77.10119	National Cancer Institute	Maryland	[Government]
2	EC	812606.0	Brussels	23498	Belgium	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.36367	European Commission	NaN	[Government]
3	NHGRI	778811.0	Bethesda	5653	United States	grid.280128.1	38.996967	[https://www.genome.gov/]	-77.09693	National Human Genome Research Institute	Maryland	[Facility]
4	NSFC	728741.0	Beijing	47927	China	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.33983	National Natural Science Foundation of China	NaN	[Government]

Arithmetic mean number of citations

%%dsldf
search publications
return funders
    aggregate citations_avg
    sort by citations_avg limit 5

Returned Funders: 5
Time: 2.75s

	acronym	citations_avg	city_name	count	country_name	id	latitude	linkout	longitude	name	types	state_name
0	NIAA	436.0	London	1	United Kingdom	grid.453470.1	51.519370	[http://www.niaa.org.uk/]	-0.119685	National Institute of Academic Anaesthesia	[Facility]	NaN
1	NaN	401.0	Torrance	1	United States	grid.467593.a	33.851273	[http://www.toyota.com/usa/]	-118.316730	Toyota Motor Corporation (United States)	[Company]	California
2	AHF	365.0	Los Angeles	2	United States	grid.427827.c	34.098557	[http://www.aidshealth.org/#/]	-118.325600	AIDS Healthcare Foundation	[Nonprofit]	California
3	MDS	332.0	Milwaukee	1	United States	grid.469679.3	43.040794	[http://www.movementdisorders.org/MDS.htm]	-87.904630	International Parkinson and Movement Disorder ...	[Other]	Wisconsin
4	JRC	297.5	Brussels	2	Belgium	grid.489339.c	50.850403	[https://ec.europa.eu/info/departments/joint-r...	4.347922	Directorate-General Joint Research Centre	[Government]	NaN

Geometric mean of FCR

%%dsldf
search publications
return funders
    aggregate fcr_gavg limit 5

Returned Funders: 5
Time: 4.59s

	acronym	city_name	count	country_name	fcr_gavg	id	latitude	linkout	longitude	name	types	state_name
0	NSFC	Beijing	2619510	China	2.487496	grid.419696.5	40.005177	[http://www.nsfc.gov.cn/publish/portal1/]	116.339830	National Natural Science Foundation of China	[Government]	NaN
1	EC	Brussels	893414	Belgium	3.290802	grid.270680.b	50.851650	[http://ec.europa.eu/index_en.htm]	4.363670	European Commission	[Government]	NaN
2	MOST	Beijing	806641	China	2.695834	grid.424020.0	39.827835	[http://www.most.gov.cn/eng/]	116.316284	Ministry of Science and Technology of the Peop...	[Government]	NaN
3	JSPS	Tokyo	712701	Japan	2.298782	grid.54432.34	35.687160	[http://www.jsps.go.jp/]	139.740390	Japan Society for the Promotion of Science	[Nonprofit]	NaN
4	NCI	Bethesda	623054	United States	4.814527	grid.48336.3a	39.004326	[http://www.cancer.gov/]	-77.101190	National Cancer Institute	[Government]	Maryland

Median Altmetric Attention Score

%%dsldf
search publications
return funders aggregate altmetric_median
    sort by altmetric_median limit 5

Returned Funders: 5
Time: 8.40s

	acronym	altmetric_median	city_name	count	country_name	id	latitude	linkout	longitude	name	state_name	types
0	NPT	749.0	Jenkintown	1	United States	grid.479428.4	40.090862	[https://www.nptrust.org/]	-75.136150	National Philanthropic Trust	Pennsylvania	[Nonprofit]
1	NaN	679.0	Tel Aviv	1	Israel	grid.481313.c	32.089615	[http://www.rcf.org.il/index.php?lang=en]	34.778706	Rothschild Caesarea Foundation	NaN	[Nonprofit]
2	APSF	666.0	Indianapolis	1	United States	grid.478218.0	39.651688	[http://www.apsf.org/]	-86.157870	Anesthesia Patient Safety Foundation	Indiana	[Nonprofit]
3	TOS	649.0	Silver Spring	1	United States	grid.430827.a	38.998497	[http://www.obesity.org/]	-77.029990	Obesity Society	Maryland	[Nonprofit]
4	NaN	564.0	St Louis	2	United States	grid.453832.b	38.635190	[http://www.longerlife.org/]	-90.262726	Longer Life Foundation	Missouri	[Nonprofit]

6.1 Complex aggregations

The return phrase may be followed by a function expression, to return additional calculations, such as per year funding or citations statistics. These functions may take their own arguments, and are calculated using the source data as specified in the search part of the query.

At the time of writing, there are two functions available: Publications citations_per_year and Grants funding_per_year

Publications citations_per_year

Publication citations is the number of times that publications have been cited by other publications in the database. This function returns the number of citations received in each year.

%%dsldf

search publications for "brexit"
return citations_per_year(2010, 2020)

Returned Citations_per_year: 11
Time: 1.07s

	citations_per_year
2010	13.0
2011	14.0
2012	17.0
2013	31.0
2014	43.0
2015	170.0
2016	1007.0
2017	6321.0
2018	18699.0
2019	35480.0
2020	62346.0

Grants funding_per_year

Returns grant funding per year in the given currency, starting from specified year, ending in specified year (including).

Supported currencies are: CAD,USD,JPY,GBP,CHF,CNY,EUR,NZD,AUD

%%dsldf

search grants for "brexit"
return funding_per_year(2010, 2020, "USD")

Returned Funding_per_year: 11
Time: 0.57s

	funding_per_year
2010	0.0
2011	0.0
2012	0.0
2013	4412.0
2014	10020.0
2015	313173.0
2016	788787.0
2017	6194077.0
2018	15698532.0
2019	34474721.0
2020	42305367.0

---

Note

The Dimensions Analytics API allows to carry out sophisticated research data analytics tasks like the ones described on this website. Check out also the associated Github repository for examples, the source code of these tutorials and much more.