# Typesense

> Keep Typesense search collections in step with your other apps: create, replace, import, update and delete documents, search with filters and sorting, create and inspect collections, and make search-only keys.

App · 13 actions. Web page: https://docs.lodol.com/docs/integrations/typesense

## Actions

### Create collection

Create a collection with the fields you name, or let Typesense work them out from the documents added. One of that name already there is returned as it is, not an error.

**Inputs**

- Name (`name`, text, required): The new collection's name, such as products.
- Fields (`fields`, object): Each field's name and type: string (text), int64 (whole number), float (number), bool (true/false), string[] (list of text) or auto. Leave empty to let Typesense work them out.
- Fields (JSON) (`fields_json`, text): The fields in Typesense's own form, for settings Fields doesn't offer, such as [{"name": "title", "type": "string", "locale": "fr"}].
- Count by (`facet_fields`, list): Fields whose values results can be counted by (facets), such as brand or category.
- Default sort (`default_sorting_field`, text): A number field in Fields that results are sorted by when nothing else decides, such as popularity. Every document must have it.
- Detect other fields (`detect_other_fields`, true/false): Also add any other field Typesense finds in the documents, with the type it finds. On by default. Default: `true`.

**Outputs**

- `auto_schema` (true/false): Whether Typesense adds fields it finds in new documents
- `created` (true/false): False when a collection of that name was already there
- `created_at` (text): When it was made (ISO 8601, UTC)
- `default_sorting_field` (text): The number field results are sorted by when nothing else decides; empty if none
- `documents` (number): How many documents it holds
- `fields` (list): Its fields
- `name` (text): The collection's name

**Example output**

```json
{
  "auto_schema": true,
  "created": true,
  "created_at": "2026-10-01T09:00:00Z",
  "default_sorting_field": "",
  "documents": 0,
  "fields": [
    {
      "facet": false,
      "index": true,
      "name": "title",
      "optional": false,
      "sort": false,
      "type": "string"
    },
    {
      "facet": true,
      "index": true,
      "name": "brand",
      "optional": true,
      "sort": false,
      "type": "string"
    },
    {
      "facet": false,
      "index": true,
      "name": "price",
      "optional": true,
      "sort": true,
      "type": "float"
    }
  ],
  "name": "products"
}
```

### Create or replace document

Add a document to a collection from a form, a webhook or another app, or replace the one with the same ID, so the search index keeps up with the record. Can change only the fields given instead.

**Inputs**

- Collection (`collection`, text, required): The collection to add it to.
- Fields (`fields`, object): The document's fields by name, such as title Wireless headphones and price 79.99. Typesense turns text into the number or true/false a field holds.
- Document (JSON) (`document_json`, text): The document as JSON, such as {"title": "Lamp", "price": 24.5, "tags": ["home", "light"]}, for lists and nested fields. Fields given in Fields win over these.
- Document ID (`document_id`, text): Its ID, such as the record's ID in the app it comes from, so the next change replaces it. Leave blank for a new random one.
- If it exists (`mode`, text): What to do when the collection already has a document with this ID. Defaults to replacing it. One of: `upsert` (Replace it with this one), `emplace` (Change only the fields given), `create` (Leave it, and fail). Default: `upsert`.

**Outputs**

- `collection` (text): The collection, such as products
- `document` (object): The document as saved, with its id
- `id` (text): The document's ID, the one given or one Typesense chose
- `mode` (text): What was asked for one already there: upsert, emplace or create

**Example output**

```json
{
  "collection": "products",
  "document": {
    "brand": "Acme",
    "id": "sku-1042",
    "in_stock": true,
    "price": 79.99,
    "title": "Wireless headphones"
  },
  "id": "sku-1042",
  "mode": "upsert"
}
```

### Create search-only key

Make an API key that can only search, to give to a website or app, such as one per customer that only finds that customer's documents. It needs an admin key.

**Inputs**

- Collections (`collections`, list): The collections it may search. Leave empty for all of them.
- Only documents matching (`filter_by`, text): Limit every search with the key to documents matching this, such as customer_id:=4221. Whoever has the key can't remove it.
- Expires after (days) (`expires_in_days`, number): How many days the key works for. Leave empty for a key that doesn't expire. From 1 to 3650.
- Description (`description`, text): What the key is for, to recognise it later, such as Acme's storefront.

**Outputs**

- `collections` (list): The collections it can search; * for all
- `description` (text): What the key is for
- `expires_at` (text): When it stops working (ISO 8601, UTC); empty if never
- `filter_by` (text): The filter every search with it is limited to; empty if none
- `key` (text): The new key, to give to a website or app. It can only search, and only documents matching the filter when one was given
- `key_id` (number): The key's ID, for 'Delete API key'
- `scoped` (true/false): Whether the key carries that filter

**Example output**

```json
{
  "collections": [
    "products"
  ],
  "description": "Acme's storefront search",
  "expires_at": "2027-01-01T00:00:00Z",
  "filter_by": "brand:=Acme",
  "key": "RDhxa2VOTnBWOU1QcWdxbWk4NWVSa0FONnBZZ0ZKcXV7ImZpbHRlcl9ieSI6ImJyYW5kOj1BY21lIn0=",
  "key_id": 7,
  "scoped": true
}
```

### Delete API key

Delete an API key by its ID, so it stops working, such as a customer's search-only key when they leave. It needs an admin key.

**Inputs**

- Key ID (`key_id`, number, required): The key's ID, a number, such as the one 'Create search-only key' returned. At least 0.

**Outputs**

- `deleted` (true/false): True once deleted; false when there was no such key
- `key_id` (number): The key's ID

**Example output**

```json
{
  "deleted": true,
  "key_id": 7
}
```

### Delete collection

Delete a collection and every document in it. This can't be undone.

**Inputs**

- Collection (`collection`, text, required): The collection to delete.

**Outputs**

- `deleted` (true/false): True once deleted; false when there was no such collection
- `documents` (number): How many documents it held
- `name` (text): The collection's name

**Example output**

```json
{
  "deleted": true,
  "documents": 980,
  "name": "products_2025"
}
```

### Delete document

Delete a document by its ID, such as when its record is deleted in another app. One that isn't there is reported, not an error.

**Inputs**

- Collection (`collection`, text, required): The collection.
- Document ID (`document_id`, text, required): The document's ID, such as sku-1042.

**Outputs**

- `collection` (text): The collection, such as products
- `deleted` (true/false): True once deleted; false when there was no such document
- `document` (object): The document as it was; empty when there was none
- `id` (text): The document's ID

**Example output**

```json
{
  "collection": "products",
  "deleted": true,
  "document": {
    "brand": "Acme",
    "id": "sku-1042",
    "in_stock": true,
    "price": 79.99,
    "title": "Wireless headphones"
  },
  "id": "sku-1042"
}
```

### Delete documents by filter

Delete every document in a collection that matches a filter, such as products no longer for sale or articles older than a date.

**Inputs**

- Collection (`collection`, text, required): The collection.
- Filter (`filter_by`, text, required): Which documents to delete, such as in_stock:=false or published_at:<1735689600. Every document matching it is deleted.

**Outputs**

- `collection` (text): The collection, such as products
- `deleted` (number): How many documents were deleted
- `filter_by` (text): The filter the documents matched

**Example output**

```json
{
  "collection": "products",
  "deleted": 14,
  "filter_by": "in_stock:=false"
}
```

### Get collection

Get a collection's fields, their types, and how many documents it holds, such as for a daily count.

**Inputs**

- Collection (`collection`, text, required): The collection.

**Outputs**

- `auto_schema` (true/false): Whether Typesense adds fields it finds in new documents
- `created_at` (text): When it was made (ISO 8601, UTC)
- `default_sorting_field` (text): The number field results are sorted by when nothing else decides; empty if none
- `documents` (number): How many documents it holds
- `fields` (list): Its fields
- `name` (text): The collection's name

**Example output**

```json
{
  "auto_schema": true,
  "created_at": "2026-10-01T09:00:00Z",
  "default_sorting_field": "",
  "documents": 1250,
  "fields": [
    {
      "facet": false,
      "index": true,
      "name": "title",
      "optional": false,
      "sort": false,
      "type": "string"
    },
    {
      "facet": true,
      "index": true,
      "name": "brand",
      "optional": true,
      "sort": false,
      "type": "string"
    },
    {
      "facet": false,
      "index": true,
      "name": "price",
      "optional": true,
      "sort": true,
      "type": "float"
    }
  ],
  "name": "products"
}
```

### Get document

Get a document by its ID. One that isn't there comes back with found false, so a workflow can check.

**Inputs**

- Collection (`collection`, text, required): The collection.
- Document ID (`document_id`, text, required): The document's ID, such as sku-1042.

**Outputs**

- `collection` (text): The collection, such as products
- `document` (object): The document's fields; empty when not found
- `found` (true/false): False when the collection has no document with this ID
- `id` (text): The document's ID

**Example output**

```json
{
  "collection": "products",
  "document": {
    "brand": "Acme",
    "id": "sku-1042",
    "in_stock": true,
    "price": 79.99,
    "title": "Wireless headphones"
  },
  "found": true,
  "id": "sku-1042"
}
```

### Import documents

Add or replace many documents at once, such as the rows of a spreadsheet or records from another app. Each is saved or refused on its own, and the result lists the refused ones and why.

**Inputs**

- Collection (`collection`, text, required): The collection to import them into.
- Documents (`documents`, list, required): A list of documents, such as the rows of an earlier step, or JSON such as [{"id": "1", "title": "Lamp"}]. Give each an id so the next import replaces it. Up to 10,000.
- How (`mode`, text): What to do with documents already in the collection (with the same id). Defaults to adding new ones and replacing existing ones. One of: `upsert` (Add new ones, replace existing ones), `emplace` (Add new ones, change only the fields given in existing ones), `create` (Add new ones only (existing ones fail)), `update` (Change existing ones only (new ones fail)). Default: `upsert`.

**Outputs**

- `collection` (text): The collection, such as products
- `failed` (number): How many it refused
- `failed_rows` (list): The documents it refused, each with why
- `imported` (number): How many Typesense saved
- `mode` (text): How existing documents were treated: upsert, emplace, create or update
- `total` (number): How many documents were sent

**Example output**

```json
{
  "collection": "products",
  "failed": 1,
  "failed_rows": [
    {
      "error": "Field `price` must be a float.",
      "id": "sku-3001",
      "row": 3
    }
  ],
  "imported": 2,
  "mode": "upsert",
  "total": 3
}
```

### List collections

List the collections on your Typesense, with how many documents each holds and its fields.

**Inputs**: None.

**Outputs**

- `collections` (list): The collections, by name
- `count` (number): How many collections there are

**Example output**

```json
{
  "collections": [
    {
      "created_at": "2026-09-14T08:30:00Z",
      "documents": 312,
      "fields": [
        "title",
        "body",
        "published_at"
      ],
      "name": "articles"
    },
    {
      "created_at": "2026-10-01T09:00:00Z",
      "documents": 1250,
      "fields": [
        "title",
        "brand",
        "price",
        "in_stock"
      ],
      "name": "products"
    }
  ],
  "count": 2
}
```

### Search

Search a collection for documents matching words, with a filter, a sort and pages, and get the matches as rows. Leave Search for empty to list every document the filter matches.

**Inputs**

- Collection (`collection`, text, required): The collection to search.
- Search for (`query`, text): The words to look for; small typos still match. Leave empty to match every document the filter allows.
- Search in (`query_by`, list): The text fields to look in, most important first. Leave empty to search every text field.
- Filter (`filter_by`, text): Only documents matching this, such as brand:=Acme or price:<50. Join conditions with && (and) or || (or).
- Sort by (`sort_by`, list): The order of results, up to 3 fields, such as price:desc. Defaults to best match.
- Fields to return (`include_fields`, list): Only these fields of each document. Defaults to every field.
- How many (`per_page`, number): How many results per page, up to 250. Defaults to 25. From 1 to 250.
- Page (`page`, number): Which page of results, from 1, to read past the first. Defaults to 1. At least 1.

**Outputs**

- `collection` (text): The collection, such as products
- `count` (number): How many came back on this page
- `found` (number): How many documents match in all
- `has_more` (true/false): Whether more pages match: ask for the next page
- `hits` (list): The matching documents, best match (or the sort) first, each with its id and fields
- `out_of` (number): How many documents the collection holds
- `page` (number): The page returned, from 1
- `query` (text): The words searched for; * when listing every match
- `search_time_ms` (number): How long the search took, in milliseconds

**Example output**

```json
{
  "collection": "products",
  "count": 2,
  "found": 2,
  "has_more": false,
  "hits": [
    {
      "brand": "Acme",
      "id": "sku-1042",
      "in_stock": true,
      "price": 79.99,
      "title": "Wireless headphones"
    },
    {
      "brand": "Acme",
      "id": "sku-2077",
      "in_stock": true,
      "price": 59.0,
      "title": "Wireless speaker"
    }
  ],
  "out_of": 1250,
  "page": 1,
  "query": "wireless",
  "search_time_ms": 3
}
```

### Update document

Change some fields of a document, keeping the rest, such as a price or a stock level.

**Inputs**

- Collection (`collection`, text, required): The collection.
- Document ID (`document_id`, text, required): The document's ID, such as sku-1042.
- Fields (`fields`, object): The fields to change and their new values, such as price 69.99. Typesense turns text into the number or true/false a field holds.
- Changes (JSON) (`document_json`, text): The changes as JSON, such as {"tags": ["sale"], "price": 59}, for lists and nested fields. Fields given in Fields win over these.

**Outputs**

- `changed` (list): The fields changed
- `collection` (text): The collection, such as products
- `document` (object): The whole document after the change
- `id` (text): The document's ID

**Example output**

```json
{
  "changed": [
    "price"
  ],
  "collection": "products",
  "document": {
    "brand": "Acme",
    "id": "sku-1042",
    "in_stock": true,
    "price": 69.99,
    "title": "Wireless headphones"
  },
  "id": "sku-1042"
}
```
