# ADS query

Search NASA ADS directly from your Obsidian notes.

## About the plugin

If you use the [NASA Astrophysics Data System](https://ui.adsabs.harvard.edu) (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](https://ui.adsabs.harvard.edu/help/api/). 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](https://ui.adsabs.harvard.edu/help/terms/)**.

## 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](https://github.com/arka378/obsidian-ads-query/releases/latest).
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](https://ui.adsabs.harvard.edu/help/api/).
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:

````markdown
```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`:

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

This becomes:

```text
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`:

````markdown
```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`:

````markdown
```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](https://ui.adsabs.harvard.edu/help/api/).

  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](LICENSE.md).