Query language (OQL)

OQL cheat sheet

Note: The OpenAlex Query Language is in alpha. It may change without warning — build against it at your own risk, and tell us what you think.

OQL is the OpenAlex Query Language — a readable way to write any OpenAlex query. A query reads almost like a sentence: works where title has (cancer) and year >= (2020). Try it in the new OQL tab at the top of the search page, or hit the API directly: https://api.openalex.org/?oql=<your query>.

Every example below runs on production today. Counts are live and will drift.

The shape

<entity> where <filters> [ group by <dims> ] [ sample <n> ]
  • entity — what you get back: works, authors, institutions, sources, funders, topics, …
  • where — your filters (skip it for everything: works).
  • A filter is <field> <operator> (<value>): year >= (2020), type is (review), title has (cancer). The value always sits in ( … ).
works
works where year is (2020)
authors where last known institution is (I136199984 [Harvard University])

Filter on a field — is, >=, <=, >, <

Example Meaning
works where year is (2020) exact match
works where type is (article) a single value
works where type is (article or review) one of several — join values with or
works where citation count >= (100) numeric comparison
works where FWCI >= (2.0) floats allowed
works where year >= (2019) and year <= (2023) a range = two endpoint filters
works where institution is (I136199984 [Harvard University]) entities use their OpenAlex ID; the [name] is optional and just for reading
works where language is (en) · works where SDG is (3) closed vocabularies use codes/ids

The ID is what counts — anything in [ … ] is ignored on input and auto-filled as the entity’s name when the query is displayed back to you.

Search text — has

Search a text field with has. Bare words are stemmed (so cancer also matches cancers); quotes turn stemming off for an exact match.

Example Meaning
works where title has (cancer) one stemmed word
works where title has (machine learning) a phrase — one search unit, ranked by adjacency
works where title has ("climate change") exact phrase (no stemming)
works where title has ("cat") exact single word — excludes cats
works where title has (stemmed "genome editing") exact-adjacent but still stemmed
works where title has ("psoriat*") wildcard — must be quoted; * = any chars, ? = exactly one char ("wom?n", "wo??n")
works where title has (within 3 ("smart", "phone")) proximity — terms within N words, any order
works where title/abstract is similar to ("ocean acidification on coral") semantic (meaning-based) search

Text fields: title, abstract, title/abstract, full text, raw affiliation, byline.

Combine & nest — and, or, ( … )

Join filters with and / or. Use parentheses to group; and binds tighter than or.

works where title has (cancer) and year >= (2020)
works where institution is (I136199984) or funder is (F4320332161)
works where title/abstract has ((vape or vaping) and (health or harm))
works where (year < (2000) and title/abstract has ("global warming"))
  or (title/abstract has ("climate change") and year > (2020))

Exclude — not

Put not right before the value you want to exclude.

works where country is (not FR)
works where title has (covid) and abstract has (not pediatric)
works where title has (not mouse and cancer)

Yes / no flags — is true / is false

works where open access is (true)
works where has DOI is (true)
works where retracted is (true)

Citation links — it cites, it's cited by

Follow the citation edge in either direction — the subject it is each work in your results. Takes not and or in the value like any other filter. The bare verb also works as input (cites (W…), cited by (W…)); it canonicalizes to the it form.

works where it cites (W2741809807)                 works whose reference list includes W…
works where it's cited by (W2741809807)            works in W…'s reference list
works where it's related to (W2741809807)          OpenAlex "related works"
works where title has (climate) and it cites (W1767272795 or W2741809807)

Group & sample

works where year >= (2020) group by topic
works where year >= (2020) group by topic, year
works where year is (2020) sample 500

Sorting and choosing columns are not part of OQL — they’re controls in the results view (and ?sort= / ?select= on the API). OQL describes which results, not how they’re displayed.

When something’s wrong, OQL tells you

OQL never guesses — a query that can’t do what it looks like it does is a clear error with a fix-it, never a silent wrong answer.

You wrote OQL says
title contains cancer contains was renamed → use title has (cancer)
title has bar* wildcards need quotes → title has ("bar*")
title has climate change or warming wrap the terms → title has (climate change or warming)
type is (article review) two values need a connective → add or between them (or and if you mean both)
pub_year is 2020 unknown field pub_year — check the field name (you want year)

Go deeper: the Cases page (browsable worked examples), the Guide (a readable walkthrough), and — for the truly curious — the Spec, Grammar, and OQO schema pages, all under /query.

View as Markdown
View as Markdown