ADS query

Search NASA ADS directly from your Obsidian notes.

About the plugin

If you use the NASA Astrophysics Data System (ADS) for your research, and Obsidian to manage your research notes, this plugin might be for you.

This plugin allows you to perform queries on ADS without leaving Obsidian. Queries are sent over the network to the NASA ADS API using an API token, which you can obtain here. Query results are stored natively in your Markdown notes and can include links to ADS records and DOI URLs.

If you use this plugin, you are subject to the ADS API Terms of Use.

Installation

Obsidian 1.11.5 or newer is required because this plugin uses SecretStorage with encryption at rest to store the ADS API token.

From Obsidian Community Plugins (recommended)

1. Open Settings → Community plugins in Obsidian.
2. Select Browse and search for ADS query.
3. Select Install, then enable the plugin.

From the latest release

1. Download main.js, manifest.json, and styles.css from the latest GitHub release.
2. Create <vault>/.obsidian/plugins/ads-query/.
3. Place the three downloaded files in that directory.
4. Reload Obsidian, then enable ADS query under Settings → Community plugins.

From source

1. Download or clone the source repository.
2. Run npm ci and npm run build in the repository directory.
3. Create <vault>/.obsidian/plugins/ads-query/.
4. Copy main.js, manifest.json, and styles.css into that directory.
5. Reload Obsidian, then enable ADS query under Settings → Community plugins.

Configuration

The plugin needs an ADS API token to perform queries. First, if you don't already have a token, you can get one here. Then open Settings → ADS query and select or create an Obsidian secret containing your ADS API token.

Usage

Create an ads code block using a valid ADS search field:

```ads
author: "Einstein"
year: 1905
```

This code block renders a Run ADS query button in your note. Clicking it will run the query. After a successful run, the plugin writes the last-run timestamp, remaining API usage, and results table below the block. Running it again replaces the previous results.

In this simple form, every key must be an ADS search field, such as title, author, year, or abstract. The plugin does not provide aliases or accept arbitrary keys. Values are passed literally to ADS, so quotation marks, wildcards, ranges, and grouping retain their ADS meaning.

Multiple fields and list entries are automatically joined with AND:

```ads
author:
  - "Smith, J"
  - "Jones, A"
year: (2020-2026)
```

This becomes:

author:"Smith, J" AND author:"Jones, A" AND year:(2020-2026)

For OR, exclusions, grouping, or other advanced ADS syntax, write the complete query using q:

```ads
q: 'title:"dark energy" AND (author:"Smith, J" OR author:"Jones, A")'
```

When q is present, it is used as written and any separate search-field keys are ignored.

Use fq to filter a query without adding those filters to q:

```ads
q: 'title:"dark energy"'
fq:
  - property:refereed
  - database:astronomy
fl:
  - citation_count
sort: entry_date desc
rows: 20
start: 0
```

Multiple fq entries are applied together. fl adds retrievable ADS fields as table columns. Both fq and fl accept YAML lists or comma-separated strings.

All six ADS Search API controls are supported: q, fq, fl, sort, rows, and start. Block-level sort and rows override their plugin-setting defaults (see below).

Search keys are validated against ADS searchable fields. fl is validated separately against fields that the ADS API can return; searchable fields such as body cannot necessarily become table columns.

Plugin settings

• ADS API token: Save your ADS token using Obsidian's secret storage. Get your token here.

  Obsidian secrets are local to each device and vault. Configure the ADS token separately on every device where you use the plugin.

• Default columns: Comma-separated ADS fields shown in every results table. Defaults to title, author, year, doi. This field cannot be empty. Fields supplied through fl are added to these defaults.

• Last-run timestamp format: The format of the timestamp shown following a successful query.

• Results per query: Maximum number of results that will be shown. Can be set manually through the code block using the ADS keyword rows.

• Sort order: The default sort order of the table shown after a successful query. Can be set manually through the code block using the ADS keyword sort.

• Reset to defaults: Restores the default columns, timestamp format, results per query, and sort order. The selected ADS API-token secret is preserved.

License

Licensed under GPL-3.0-only. See LICENSE.md.