> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/sql-api/views/catalog.md).

# catalog

```
catalog
catalog_latest
```

The `catalog` view provides a historical timeseries of catalog JSONs generated by running catalogers over time. Each row is a complete catalog snapshot at a point in time.

The `catalog_latest` view holds only the current catalog. It is guaranteed to return at most one row, and no rows until Lunar Hub has published a configuration manifest.

## Schema

Both views share the same columns.

| Column         | Type        | Description                                                                                                                            |
| -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `timestamp`    | `TIMESTAMP` | When the catalog last changed                                                                                                          |
| `captured_at`  | `TIMESTAMP` | When this version was recorded. `NULL` on the newest row when the current catalog has changed since the last recording. `catalog` only |
| `catalog_json` | `JSONB`     | The complete catalog data in JSON format                                                                                               |

## Notes

* The catalog JSON contains the full inventory of components and their metadata. The format is defined on the [Catalog JSON](/docs/catalog-json.md) page
* `catalog_latest` returns the same document as `lunar cataloger get-json`, so a query and the CLI always agree
* `timestamp` is when the catalog last **changed** — it does not advance when a cataloger runs and produces the same result
* **The history is sampled, not exhaustive.** Versions are recorded periodically, so several changes landing close together may appear as one row. A catalog that changes and changes back between recordings leaves no trace
* **History begins when your Lunar Hub was upgraded to record it.** Catalogs from before that point are not available here — use [`lunar cataloger get-json --ts`](/configuration/lunar-config/catalogers.md), which reconstructs any past catalog from the cataloger delta history
* Order the history by `captured_at`, not by `timestamp`. `timestamp` reflects when the catalog changed and can repeat across rows; `captured_at` always increases

## Usage examples

Get the current catalog:

```sql
SELECT timestamp, catalog_json
FROM catalog_latest;
```

Track how the component count has changed over time:

```sql
SELECT captured_at,
       jsonb_array_length(jsonb_path_query_array(catalog_json, '$.components.*')) AS components
FROM catalog
ORDER BY captured_at NULLS LAST;
```

List every component in the catalog with its domain and owner:

```sql
SELECT component.key              AS component,
       component.value->>'domain' AS domain,
       component.value->>'owner'  AS owner
FROM catalog_latest,
     jsonb_each(catalog_json->'components') AS component
ORDER BY component;
```

Fetch the catalog only when it has changed since you last looked. The `timestamp` filter is evaluated before the document is assembled, so a poll that finds nothing new is cheap — prefer this to re-fetching the whole document on a schedule:

```sql
SELECT timestamp, catalog_json
FROM catalog_latest
WHERE timestamp > '2026-08-10 12:00:00';
```

For per-component queries, the [`components` view](/sql-api/views/components.md) is usually a better fit than unpacking this document — it is row-shaped and indexed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-lunar.earthly.dev/sql-api/views/catalog.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.