# Apache CouchDB

> Create, read, update and delete documents in Apache CouchDB from workflows, find them with Mango queries, query views, attach files and manage databases. Start a workflow when a document is created, changed or deleted.

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

## Actions

### Add attachment

Attach a file to a document, such as a PDF invoice from an email, or save text as a file on it. A file of the same name is replaced.

**Inputs**

- Database (`database`, text, required): The database.
- Document ID (`document_id`, text, required): The document to attach it to, such as order-1042.
- File (`file`, text): The file: upload one, pick a file from an earlier step, or paste a link to one. Use this or Text.
- Text (`text`, text): Words to save as the file, such as notes or a CSV. Use this or File, and give a file name.
- File name (`file_name`, text): What to call it, such as invoice-1042.pdf. Leave blank to keep the file's own name.

**Outputs**

- `content_type` (text): Its type, such as application/pdf
- `database` (text): The database, such as orders
- `file_name` (text): The attachment's name
- `id` (text): The document's ID
- `rev` (text): The document's revision now
- `size` (number): Its size in bytes

**Example output**

```json
{
  "content_type": "application/pdf",
  "database": "orders",
  "file_name": "invoice-1042.pdf",
  "id": "order-1042",
  "rev": "2-b2a3157bd333dbfd109654c7a2cce380",
  "size": 48213
}
```

### Create database

Create a database, such as one per customer or per year. Only a server admin can. One of that name already there is reported, not an error.

**Inputs**

- Name (`name`, text, required): The new database's name: lowercase letters, digits and _ - + $ ( ) /, starting with a letter, such as orders_2026.

**Outputs**

- `created` (true/false): False when a database of that name was already there
- `name` (text): The database's name

**Example output**

```json
{
  "created": true,
  "name": "orders_2026"
}
```

### Create document

Create a document from a form, a webhook or another app: its fields, or the whole document as JSON, with the ID you give or a new random one.

**Inputs**

- Database (`database`, text, required): The database to add it to.
- Fields (`fields`, object): The document's fields by name, such as status paid and customer Acme Ltd. Values typed here are text; a value from an earlier step keeps its type.
- Document (JSON) (`document_json`, text): The document as JSON, such as {"status": "paid", "total": 42, "items": [...]}, for numbers, lists and nested fields. Fields given in Fields win over these.
- Document ID (`document_id`, text): The new document's ID, such as order-1042. Leave blank for a random one.

**Outputs**

- `database` (text): The database, such as orders
- `document` (object): The document: its fields by name, with _id (its ID) and _rev (its revision)
- `id` (text): The document's ID
- `rev` (text): The document's revision now, such as 2-a1b2c3...

**Example output**

```json
{
  "database": "orders",
  "document": {
    "_id": "order-1042",
    "_rev": "1-967a00dff5e02add41819138abb3284d",
    "customer": "Acme Ltd",
    "status": "paid",
    "total": 120.5,
    "type": "order"
  },
  "id": "order-1042",
  "rev": "1-967a00dff5e02add41819138abb3284d"
}
```

### Create documents

Create many documents at once, such as rows from a spreadsheet or records from another app. Each is created or fails on its own, and the result says which.

**Inputs**

- Database (`database`, text, required): The database to add them to.
- Documents (`documents`, list, required): A list of documents, from an earlier step or as JSON, such as [{"name": "Ada"}, {"name": "Grace"}]. Give one an _id to choose its ID. Up to 1000.

**Outputs**

- `created` (number): How many documents were created
- `database` (text): The database, such as orders
- `failed` (number): How many weren't, such as for an ID already taken
- `results` (list): One result per document, in the order given

**Example output**

```json
{
  "created": 2,
  "database": "contacts",
  "failed": 0,
  "results": [
    {
      "error": "",
      "id": "contact-ada",
      "ok": true,
      "rev": "1-4c6114c65e295552ab1019e2b046b10e"
    },
    {
      "error": "",
      "id": "contact-grace",
      "ok": true,
      "rev": "1-0b2d1e3c4f5a6b7c8d9e0f1a2b3c4d5e"
    }
  ]
}
```

### Delete database

Delete a database and every document in it. This can't be undone. Only a server admin can.

**Inputs**

- Database (`name`, text, required): The database to delete.

**Outputs**

- `deleted` (true/false): True once deleted; false when there was no such database
- `name` (text): The database's name

**Example output**

```json
{
  "deleted": true,
  "name": "orders_2025"
}
```

### Delete document

Delete a document by its ID. One that isn't there is left alone and reported, not an error.

**Inputs**

- Database (`database`, text, required): The database.
- Document ID (`document_id`, text, required): The document's ID, such as order-1042.
- Revision (`revision`, text): Only if the document is still at this revision (its _rev, such as 2-a1b2c3), so a change made since isn't lost. Leave blank for its newest.

**Outputs**

- `database` (text): The database, such as orders
- `deleted` (true/false): True once deleted; false when there was no such document
- `id` (text): The document's ID
- `rev` (text): The revision that marks it deleted; empty when nothing was deleted

**Example output**

```json
{
  "database": "orders",
  "deleted": true,
  "id": "order-1042",
  "rev": "3-f1e2d3c4b5a6978877665544332211aa"
}
```

### Find documents

Find documents with a Mango query: fields equal to values, or a selector in JSON, with the fields, order and number you want, a page at a time.

**Inputs**

- Database (`database`, text, required): The database to search.
- Where (`match`, object): Fields that must equal these values, such as status paid and type order. Leave blank for every document.
- Selector (JSON) (`selector`, text): A Mango selector, for more than equals, such as {"total": {"$gt": 100}, "status": {"$in": ["paid", "shipped"]}}.
- Fields (`fields`, text): Only these fields, separated by commas, such as customer, total. Leave blank for whole documents.
- Sort by (`sort`, text): Fields to sort by, with desc for newest or largest first, such as created_at desc. CouchDB needs an index on them.
- How many (`limit`, number): The most to return. Defaults to 25, up to 1000. From 1 to 1000.
- Bookmark (`bookmark`, text): The bookmark an earlier search returned, to get its next page.

**Outputs**

- `bookmark` (text): Pass this as Bookmark to get the next page
- `count` (number): How many came back
- `database` (text): The database, such as orders
- `documents` (list): The documents found, each with _id and its fields (only the fields asked for, when Fields is set)
- `has_more` (true/false): Whether there may be more: pass the bookmark for the next page
- `warning` (text): CouchDB's note, such as that no index matched; usually empty

**Example output**

```json
{
  "bookmark": "g1AAAABEeJzLYWBgYMpgSmHgKy5JLCrJTq2MT8lPzkzJBYpz5RelpBbpGhoYGIFUcMBU",
  "count": 1,
  "database": "orders",
  "documents": [
    {
      "_id": "order-1042",
      "_rev": "1-967a00dff5e02add41819138abb3284d",
      "customer": "Acme Ltd",
      "status": "paid",
      "total": 120.5,
      "type": "order"
    }
  ],
  "has_more": false,
  "warning": ""
}
```

### Get attachment

Download a file attached to a document, to send or save in a later step. A text file of 1 MB or less is also given as text.

**Inputs**

- Database (`database`, text, required): The database.
- Document ID (`document_id`, text, required): The document it's attached to, such as order-1042.
- Attachment (`file_name`, text, required): The attachment's name, such as invoice-1042.pdf.

**Outputs**

- `content_type` (text): Its type, such as application/pdf
- `database` (text): The database, such as orders
- `document_ref` (text): The downloaded file, for a later step's file field
- `file_name` (text): The attachment's name
- `id` (text): The document's ID
- `size` (number): Its size in bytes
- `text` (text): What it says, for a text file of 1 MB or less; otherwise empty

**Example output**

```json
{
  "content_type": "text/plain",
  "database": "orders",
  "document_ref": "doc_0123456789abcdef0123456789abcdef",
  "file_name": "notes.txt",
  "id": "order-1042",
  "size": 27,
  "text": "Leave the parcel at the door"
}
```

### Get database info

See how many documents a database holds and how much space it takes, such as for a weekly report.

**Inputs**

- Database (`database`, text, required): The database.

**Outputs**

- `data_size` (number): The size of its documents and attachments, in bytes
- `data_size_text` (text): The size of its data, such as 1.2 KB
- `deleted_doc_count` (number): How many deleted documents it still keeps a mark of
- `doc_count` (number): How many documents it holds (not counting deleted ones)
- `file_size` (number): Its size on disk, in bytes
- `file_size_text` (text): Its size on disk, such as 3.8 KB
- `name` (text): The database's name
- `partitioned` (true/false): Whether it is a partitioned database
- `update_seq` (text): Where its changes are up to (a sequence)

**Example output**

```json
{
  "data_size": 1048576,
  "data_size_text": "1.0 MB",
  "deleted_doc_count": 12,
  "doc_count": 1250,
  "file_size": 4194304,
  "file_size_text": "4.0 MB",
  "name": "orders",
  "partitioned": false,
  "update_seq": "1262-g1AAAACLeJzLYWBgYMpgTmHgzcvPy09JdcjLz8gvLskBCeexAEmGBiD1HwiyEhlw"
}
```

### Get document

Get a document's fields by its ID, with the files attached to it. A document that isn't there comes back with found false, so a workflow can check.

**Inputs**

- Database (`database`, text, required): The database.
- Document ID (`document_id`, text, required): The document's ID, such as order-1042.
- Revision (`revision`, text): An earlier revision to read (its _rev). Leave blank for the newest.

**Outputs**

- `attachments` (list): The files attached to it
- `database` (text): The database, such as orders
- `document` (object): The document: its fields by name, with _id and _rev; empty when not found
- `found` (true/false): False when the database has no document with this ID
- `id` (text): The document's ID
- `rev` (text): The document's revision, such as 3-a1b2c3...; empty when not found

**Example output**

```json
{
  "attachments": [
    {
      "content_type": "application/pdf",
      "name": "invoice.pdf",
      "size": 48213
    }
  ],
  "database": "orders",
  "document": {
    "_id": "order-1042",
    "_rev": "1-967a00dff5e02add41819138abb3284d",
    "customer": "Acme Ltd",
    "status": "paid",
    "total": 120.5,
    "type": "order"
  },
  "found": true,
  "id": "order-1042",
  "rev": "1-967a00dff5e02add41819138abb3284d"
}
```

### List databases

List the databases on your CouchDB. Only a server admin can list them.

**Inputs**

- Include CouchDB's own (`include_system`, true/false): Also list _users and _replicator, where CouchDB keeps its users and replications. Default: `false`.

**Outputs**

- `count` (number): How many there are
- `databases` (list): The databases' names

**Example output**

```json
{
  "count": 2,
  "databases": [
    "contacts",
    "orders"
  ]
}
```

### Query view

Read a view a design document defines: its rows for a key or a range of keys, with their documents, or its totals for each key or for everything.

**Inputs**

- Database (`database`, text, required): The database.
- Design document (`design_document`, text, required): The design document that holds the view.
- View (`view`, text, required): The view.
- Key (`key`, text): Only rows with this key, such as paid, 42 or ["Acme Ltd", 2026]. Quote text that looks like a number ("42").
- From key (`start_key`, text): Rows from this key on, such as 2026-01-01.
- To key (`end_key`, text): Rows up to and including this key, such as 2026-12-31.
- Reduce (`reduce`, text): List the rows, or total them with the view's reduce function. One of: `rows` (List the rows (don't reduce)), `group` (One total for each key), `total` (One total for every row). Default: `rows`.
- Group level (`group_level`, number): For keys that are lists, total by their first few items, such as 1 for [customer, date] keys to total by customer. Only when Reduce is One total for each key. From 1 to 100.
- Include documents (`include_docs`, true/false): Also return each row's whole document. Only when Reduce is List the rows (don't reduce). Default: `false`.
- Newest first (`descending`, true/false): Return rows from the highest key down. From key is then the higher key. Default: `false`.
- How many (`limit`, number): The most to return. Defaults to 25, up to 1000. From 1 to 1000.

**Outputs**

- `count` (number): How many rows came back
- `database` (text): The database, such as orders
- `design_document` (text): The design document, without _design/
- `has_more` (true/false): Whether there are more rows than the most asked for
- `rows` (list): The rows: each key and value, the document's ID (not when reduced), and the document when Include documents is on
- `total_rows` (number): How many rows the whole view has (not when reduced)
- `view` (text): The view

**Example output**

```json
{
  "count": 2,
  "database": "orders",
  "design_document": "reports",
  "has_more": false,
  "rows": [
    {
      "doc": null,
      "id": "order-1001",
      "key": "paid",
      "value": 120.5
    },
    {
      "doc": null,
      "id": "order-1004",
      "key": "paid",
      "value": 42.25
    }
  ],
  "total_rows": 6,
  "view": "by_status"
}
```

### Update document

Change a document: merge the fields given into its newest revision, keeping the rest, or replace it. If it changes while saving, Lodol reads it again and saves once more.

**Inputs**

- Database (`database`, text, required): The database.
- Document ID (`document_id`, text, required): The document's ID, such as order-1042.
- Fields (`fields`, object): The document's fields by name, such as status paid and customer Acme Ltd. Values typed here are text; a value from an earlier step keeps its type.
- Document (JSON) (`document_json`, text): The document as JSON, such as {"status": "paid", "total": 42, "items": [...]}, for numbers, lists and nested fields. Fields given in Fields win over these.
- How (`mode`, text): Merge changes only the fields given (a field holding an object is replaced whole). Replace makes the fields given the whole document, keeping its attachments. One of: `merge` (Merge: change the fields given, keep the rest), `replace` (Replace: the fields given become the whole document). Default: `merge`.
- Create if missing (`create_if_missing`, true/false): Create the document with this ID when there isn't one, such as to keep a copy of another app's records in sync. Default: `false`.
- Revision (`revision`, text): Only if the document is still at this revision (its _rev, such as 2-a1b2c3), so a change made since isn't lost. Leave blank for its newest.

**Outputs**

- `created` (true/false): True when there was no document, and it was created
- `database` (text): The database, such as orders
- `document` (object): The document as saved, with _id and _rev
- `id` (text): The document's ID
- `previous_rev` (text): The revision it replaced; empty when it was created
- `retried` (true/false): True when it changed while saving, so it was read again and saved once more
- `rev` (text): The document's revision now, such as 2-a1b2c3...

**Example output**

```json
{
  "created": false,
  "database": "orders",
  "document": {
    "_id": "order-1042",
    "_rev": "2-7051cbe5c8faecd085a3fa619e6e6337",
    "customer": "Acme Ltd",
    "status": "shipped",
    "total": 120.5,
    "type": "order"
  },
  "id": "order-1042",
  "previous_rev": "1-967a00dff5e02add41819138abb3284d",
  "retried": false,
  "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
}
```
