Typesense integration

What it does

The Typesense integration lets your agency stand up and maintain typo-tolerant search on a client's data without writing glue code. Connect a Typesense cluster once and your workflows can create, alter and delete collections, push documents into the index one at a time or in bulk as records change upstream, update or delete documents by id or by filter, export a collection, run single or multi-collection searches, and swap aliases to put a freshly re-indexed collection live with no downtime. Two polling triggers react to what lands in a collection, because Typesense does not send webhooks.

Connect a Typesense account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose Typesense and click Connect.
3. In a new tab, open the Typesense Cloud dashboard for the client's cluster (or the admin UI of a self-hosted cluster).
4. Copy the cluster URL. On Typesense Cloud this is the nearest-node hostname under Cluster Configuration, shaped like https://{cluster-id}.a1.typesense.net. For self-hosted clusters use your origin (for example, https://search.example.com).
5. Generate or copy an API key scoped to the actions you want TaskJuice to perform. In Typesense Cloud, keys live under Cluster, API Keys. On self-hosted clusters, create one with POST /keys using the admin key. Alias actions need a key allowed to manage aliases.
6. Paste both values into TaskJuice and save the connection.

To rotate the API key later, mint a new one in Typesense, swap it into the TaskJuice connection, and the next run will pick it up.

Triggers

Both triggers ask for the cluster host (for example xyz.a1.typesense.net, with no https://) because a scheduled check runs before the connection is loaded. Use the same cluster the connection points at.

• typesense/new-document fires when a new document is added to a collection. It reads the documents at the top of the Sort By order (created_at:desc by default) and fires once per document id. When documents store created_at as Unix seconds, only documents created after the workflow is first published fire, so editing an old document does not set it off. The first check records a baseline and fires nothing.
• typesense/search-poll runs a saved search on a fixed interval and emits the full set of matching hits whenever that set changes. Use it for digests or to watch a filtered slice of a collection.

Each trigger emits one activation per check with the hits in items. Add a Loop node to handle each document on its own.

Actions

Collections

• typesense/list-collections lists every collection with its schema and document count.
• typesense/create-collection creates a collection from a schema definition with field names, types, and an optional default sorting field.
• typesense/retrieve-collection fetches a collection's schema and current document count.
• typesense/update-collection adds fields to a collection or drops them, in place.
• typesense/delete-collection permanently removes a collection and every document it holds.

Documents

• typesense/index-document writes one document, shaped like your collection schema, with a selectable write mode: create, upsert, update, or emplace.
• typesense/retrieve-document fetches one document by id.
• typesense/update-document changes the given fields of one document by id.
• typesense/delete-document permanently deletes one document by id.
• typesense/update-documents-by-filter sets the same fields on every document matching a filter_by expression.
• typesense/delete-documents-by-filter permanently deletes every document matching a filter_by expression.
• typesense/import-documents bulk-indexes up to 1,000 documents in one call and returns one result line per document.
• typesense/export-documents exports a collection, or a filtered slice of it, as JSON Lines.

Search

• typesense/search-documents runs a faceted search with query string, query_by fields, optional filter_by, sort_by, and facet_by clauses, paginated via page and per_page.
• typesense/multi-search runs several searches in one request across collections, optionally merged into one ranked result set.

Aliases

• typesense/list-aliases lists every alias and the collection it points to.
• typesense/retrieve-alias fetches one alias.
• typesense/upsert-alias creates an alias or repoints it at another collection.
• typesense/delete-alias removes an alias without touching the collection behind it.

Known limitations

• Typesense does not send webhooks, so both triggers check the collection on an interval. Intervals shorter than 60 seconds are rejected.
• Triggers reach the cluster over HTTPS on port 443. Typesense Cloud always does; a self-hosted cluster on another port (such as the default 8108) needs a reverse proxy on 443 for the triggers. Actions use the full connection URL and are not limited this way.
• typesense/new-document reads at most 250 documents per check. If more than that arrive between two checks, shorten the interval.
• Import Documents accepts at most 1,000 documents per call. Typesense answers 200 even when some lines fail, so check the per-line success values in the result.
• Multi Search also answers 200 when one of its searches fails. That search's entry in results carries error and code instead of hits, so check them before treating empty hits as no match.
• Synonym sets, curation sets, presets, stopwords, analytics rules, API key management and cluster operations are not available as actions.
• Collection names cannot be reused for a few seconds after typesense/delete-collection returns, because the cluster propagates the deletion asynchronously.
• Each connection points at one cluster URL, so connect a separate Typesense connection per cluster or region.