> 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

Schema reference for the catalog and catalog\_latest SQL views — full catalog JSON snapshots produced by catalogers, with history over time.

```
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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.