Data Connector Quickstart

extension.config.json names the extension, example/artic, and its only entry, example/data-connector. The entrypoint is the file the CLI bundles.

index.ts defines the connector with defineDataConnector. Its setup function runs when a data source starts and receives that data source's configuration. It returns the handlers Monospace calls:

• introspect reports the schema: the collections, fields, and operations callers can use.
• query handles reads. The scaffold ignores the request and returns the same two items.
• testConnection reports whether the connection works, and Monospace runs it before it creates a data source. The scaffold returns { ok: true } without sending a request. In step 7, you make it send a request to the Art Institute API.

schema.ts declares one collection, items, with an unfiltered readMany. The sample items are in ROWS.

Monospace offers callers only the operations the schema declares, and it doesn't filter the items query returns. Implement each filter, sort, or limit when you declare it.

See Data Connector API for setup, the handlers, and the query shapes.

In extension.config.json, rename the entry to example/artic-connector. A data source uses this entry ID as its provider. Point the entrypoint at a directory named after the connector, src/data-connectors/artic/.

Add the permission net:api.artic.edu to the entry. The connector can reach only the hosts its entry declares. When you create a data source, you approve access to those hosts.

Set the extension and entry icons to lucide:landmark. In package.json, rename the package from the scaffold's example-artic to artic-connector, and update the paths in the README. Keep the extension ID, example/artic, as the scaffold wrote it.

The code only moves, so the connector still serves the two sample items.

See Extension Config and Manifest for the extension's fields, and Declare the Entry for the entry's fields.

Move the code, then build to check the rename. The build lists the renamed entry and its artifact directory:

Install the extension before you change its code. The connector still serves the scaffold's two sample items, so this checks your setup end to end.

Create the quick-start in a directory named monospace next to artic, or change the --install-to path. ../monospace holds the quick-start docker-compose.yaml and its extensions directory.

--install-to builds the project and copies the result into that extensions directory. The output lists the artifact and the installed extension directory:

Restart the instance if automatic reloading is disabled. With automatic reloading enabled, Monospace loads the extension once its files stop changing, and the instance logs bundle installed.

In Studio, open Workspace Settings (the gear icon in the sidebar), then Extensions. The page lists the extension, Art Institute of Chicago (example/artic), and its entry, example/artic-connector, marked Data Connector. The names, IDs, and icon come from extension.config.json.

Run docker compose restart monospace in ../monospace in these cases:

• On macOS, the extension doesn't appear. The container can miss changes made on the host through a bind mount.
• The instance logged failed to watch installed bundles directory; bundle hot reloading is inactive. The install location didn't exist when the instance started.

See Reload Extensions Automatically.

A data source is a connector configured in one workspace. It adds the connector's collections to that workspace. Create a data source in Studio:

1. Open Data Model, then Add Source, and choose Art Institute of Chicago.
2. Enter artic as the Name. Leave Connection Parameters at {}, because this connector has no configuration.
3. Review Permissions: the data source requests access to api.artic.edu, for the reason declared in step 3. Creating the data source grants this permission.
4. Choose Test Connection. Studio reports Connection Test Successful. Then choose Continue.
5. Keep items selected, choose Review, then Add 1 Collection.

Open Content, then Items, to see the two sample items, First and Second. The collection is items from schema.ts, and its items come from ROWS. Add Item is disabled because the collection declares no writes.

Remove the sample data source before you change the schema. In Data Model, open the menu next to artic, choose Remove Data Source, and confirm with Remove. Removing a data source removes its collections from the workspace, so Items disappears from Content.

In schema.ts, replace the items collection with artworks, one item per artwork:

An int64 or uint64 field reaches the connector as a string, primary keys included. Don't check its values with typeof x === 'number'.

See Operations and Operators for everything a collection can declare.

In index.ts, remove the config parameter from setup, because the Art Institute API needs no configuration. Until step 8, make query reject every read with QueryRejected.

Every read goes to a search endpoint on api.artic.edu, such as POST /api/v1/artworks/search, which takes an Elasticsearch query. Create api.ts with a search function that sends one request to the collection's /search endpoint. Keeping every request in one function lets step 13 add a time limit in one place.

• The connector reads two values from the response: data contains the items, and pagination.total gives the number of matching items.
• For a failed HTTP status, the connector throws a plain Error, which Monospace reports as a failed query.
• apiFieldName converts a connector field name to the API's field name (e.g., artistId becomes artist_id).

In index.ts, change testConnection to send a search for zero items. It checks that the API responds, without reading any artworks:

POST /api/v1/artworks/search
{"size": 0}

In schema.ts, add byId to readMany: a sort on id, ascending or descending. Create read.ts with a readMany function, and call it from query in index.ts. readMany translates each part of the caller's request into the search request:

The search API returns at most 100 items per request, so a larger limit becomes several requests. readMany stops when a page holds fewer items than requested, because no more items remain.

toItem returns exactly the selected fields, with null where the API has no value. The read fails if a returned value doesn't match its field's declared type.

GET /api/blog/items/artworks?fields=id,title&sort[0][id][direction]=desc&limit=3

POST /api/v1/artworks/search
{
  "sort": [{"id": {"order": "desc"}}],
  "fields": ["id", "title"],
  "from": 0,
  "size": 3
}

{"data": [
  {"id": 287848, "title": "Eat"},
  {"id": 286661, "title": "Siebrits-Bartz Anti-Apartheid Collection"},
  {"id": 286660, "title": "Risen Christ"}
]}

The search API matches IDs exactly, so in schema.ts, declare equals and in on id and artistId, with and to join conditions. The API matches titles case-insensitively, so title gets no filter: equals would return extra items.

Create filter.ts with toQuery, and call it from readMany in read.ts. toQuery translates each part of the filter:

For equals with null, the connector sends bool.must_not.exists, the search API's test for a missing value. The search API rejects null in terms, so in leaves null members out. An in filter therefore never matches an artwork whose filtered field has no value.

Declare a filter only where the API matches it exactly. Never skip part of a filter, because the read would return items that filter excludes.

GET /api/blog/items/artworks?fields=id,title,dateDisplay&filter[artistId][_eq]=40810&limit=3

POST /api/v1/artworks/search
{
  "query": {"term": {"artist_id": 40810}},
  "sort": [{"id": {"order": "asc"}}],
  "fields": ["id", "title", "date_display"],
  "from": 0,
  "size": 3
}

{"data": [
  {"id": 20199, "title": "Final Study for \"Bathers at Asnières\"", "dateDisplay": "1883"},
  {"id": 27992, "title": "A Sunday on La Grande Jatte — 1884", "dateDisplay": "1884–86, border added 1888–89"},
  {"id": 61616, "title": "Oil Sketch for \"A Sunday on La Grande Jatte — 1884\"", "dateDisplay": "1884"}
]}

The search API rejects any request that reaches past its 1,000th result. A schema can't declare a paging ceiling, so the connector checks it in code. See No Declarable Page Size or Depth Limit.

Add the search-window check to readMany in read.ts. For a read past result 1,000, readMany first counts the matches with a search for zero items, and caps the read at the last match. A filter that matches fewer than 1,000 artworks makes any offset safe.

If the capped read still reaches past result 1,000, readMany throws QueryRejected with a message that tells the caller how to narrow the read:

GET /api/blog/items/artworks?fields=id&limit=1001

POST /api/v1/artworks/search
{"size": 0}

{"message":"Query failed","source":{"message":"The data source rejected the query","source":{"message":"the extension returned an error: The Art Institute search API returns only the first 1000 results. Narrow the filter or read an earlier page."}}}

With limit=1000, the read ends at result 1,000, and it succeeds.

In schema.ts, declare readOne, a read of one artwork by its ID, with the same filter as readMany.

In read.ts, add a readOne function, and call it from query in index.ts. readOne calls readMany with the artwork ID, any filter the caller adds, and a limit of one item. This reuses the filter translation from step 9.

GET /api/blog/items/artworks/27992?fields=id,title,dateDisplay

POST /api/v1/artworks/search
{
  "query": {"term": {"id": 27992}},
  "sort": [{"id": {"order": "asc"}}],
  "fields": ["id", "title", "date_display"],
  "from": 0,
  "size": 1
}

{"data": {"id": 27992, "title": "A Sunday on La Grande Jatte — 1884", "dateDisplay": "1884–86, border added 1888–89"}}

readOne returns the artwork in record, or record: null when no artwork matches. It doesn't throw for a missing artwork; the caller gets 404 with the message "No record found".

In schema.ts, add the artists collection with id, title, and the same sort on id.

Add a relation that links artworks.artistId to artists.id. On an artwork, the to-one artist relation returns a single related item. On an artist, the to-many artworks relation returns a list of related items.

A relation is a declaration, not code. To include the artists, Monospace reads them by ID with in, which step 9 already translates.

GET /api/blog/items/artworks?fields=id,title&filter[id][_in][]=27992&filter[id][_in][]=28560&include[artist][fields]=id,title

{"data": [
  {"id": 27992, "title": "A Sunday on La Grande Jatte — 1884", "artist": {"id": 40810, "title": "Georges Seurat"}},
  {"id": 28560, "title": "The Bedroom", "artist": {"id": 40610, "title": "Vincent van Gogh"}}
]}

Monospace sets no time limit on query or testConnection. In api.ts, give each request a 10-second limit with AbortSignal.timeout, and throw ConnectionFailed when fetch fails. The connector then handles these outcomes:

See Data Connector Errors for the error classes.

Install the finished build over the sample build, as in step 4. The output lists the artifact and the installed extension directory:

The CLI replaces the entire install directory. With automatic reloading enabled, Monospace loads the new build once its files stop changing. Without it, restart the instance.

Create the data source again, as in step 5:

1. Open Data Model, then Add Source, and choose Art Institute of Chicago.
2. Enter artic as the Name, and leave Connection Parameters at {}.
3. Choose Test Connection, then Continue.
4. Keep both collections, artists and artworks, choose Review, then Add 2 Collections.

Choosing Test Connection or creating a data source runs testConnection. testConnection sends a real search request (step 7), so Monospace doesn't create a data source that can't reach the Art Institute API.

Open Content, then Artworks. Studio lists 25 artworks per page in id order, and shows each artwork's Artist through the relation. Each action below sends a read that runs code from Part 2:

1. Sort. Open the menu on the ID header and choose Descending. The list starts at the highest IDs: 287848 "Eat", 286661 "Siebrits-Bartz Anti-Apartheid Collection", 286660 "Risen Christ". toSort translates the sort (step 8).
2. Filter. Choose the Filter button in the toolbar, then Artist ID. Keep is, and enter 40810. Only works by Georges Seurat remain, because toQuery translates the filter into a term query (step 9).
3. Open one artwork. Choose A Sunday on La Grande Jatte — 1884. Studio reads the artwork by ID through readOne (step 11), and its Artist field shows Georges Seurat.
4. Follow the relation back. Open Artists, filter ID by 40810, and open Georges Seurat. The Artworks field lists his artworks through the to-many side of the relation (step 12).

Your data connector serves live queries from Monospace!

Query these collections over the API like any other collection. See Filtering and Relational Data.

Studio derives display names from the collection and field names the connector declares. It shows artworks as Artworks, artistId as Artist ID, and dateDisplay as Date Display.

On Artworks, choose Reset in the filter bar to clear the filter from step 15. Then choose 25 per Page at the bottom, and 1000 per Page.

Studio requests one extra artwork to check for a next page, so this read reaches result 1,001. readMany throws QueryRejected (step 10), and Studio shows Couldn't Load Items. Choose View Details to read the connector's message:

Filter Artist ID by 40810 again to narrow the read, and the page loads the works of Georges Seurat. Reset clears the filter and returns to 25 per page.

Studio offers only the filters and sorts the schema declares, and only the ID header offers sorting. The Filter list offers ID, Artist ID, and the Artist relation. It omits title and dateDisplay because neither field declares a filter.