Apache CouchDB

App · 13 actions

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.

Actions

ActionWhat it does
Add attachmentAttach a file to a document, such as a PDF invoice from an email, or save text as a file on it.
Create databaseCreate a database, such as one per customer or per year.
Create documentCreate 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.
Create documentsCreate many documents at once, such as rows from a spreadsheet or records from another app.
Delete databaseDelete a database and every document in it.
Delete documentDelete a document by its ID.
Find documentsFind 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.
Get attachmentDownload a file attached to a document, to send or save in a later step.
Get database infoSee how many documents a database holds and how much space it takes, such as for a weekly report.
Get documentGet a document's fields by its ID, with the files attached to it.
List databasesList the databases on your CouchDB.
Query viewRead 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.
Update documentChange a document: merge the fields given into its newest revision, keeping the rest, or replace it.

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

DatabasedatabasetextRequired
The database.
Document IDdocument_idtextRequired
The document to attach it to, such as order-1042.
Filefiletext
The file: upload one, pick a file from an earlier step, or paste a link to one. Use this or Text.
Texttexttext
Words to save as the file, such as notes or a CSV. Use this or File, and give a file name.
File namefile_nametext
What to call it, such as invoice-1042.pdf. Leave blank to keep the file's own name.

Outputs

content_typetext
Its type, such as application/pdf
databasetext
The database, such as orders
file_nametext
The attachment's name
idtext
The document's ID
revtext
The document's revision now
sizenumber
Its size in bytes
Example output
{
  "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

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

Outputs

createdtrue/false
False when a database of that name was already there
nametext
The database's name
Example output
{
  "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

DatabasedatabasetextRequired
The database to add it to.
Fieldsfieldsobject
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_jsontext
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 IDdocument_idtext
The new document's ID, such as order-1042. Leave blank for a random one.

Outputs

databasetext
The database, such as orders
documentobject
The document: its fields by name, with _id (its ID) and _rev (its revision)
idtext
The document's ID
revtext
The document's revision now, such as 2-a1b2c3...
Example output
{
  "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

DatabasedatabasetextRequired
The database to add them to.
DocumentsdocumentslistRequired
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

creatednumber
How many documents were created
databasetext
The database, such as orders
failednumber
How many weren't, such as for an ID already taken
resultslist
One result per document, in the order given
Example output
{
  "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

DatabasenametextRequired
The database to delete.

Outputs

deletedtrue/false
True once deleted; false when there was no such database
nametext
The database's name
Example output
{
  "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

DatabasedatabasetextRequired
The database.
Document IDdocument_idtextRequired
The document's ID, such as order-1042.
Revisionrevisiontext
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

databasetext
The database, such as orders
deletedtrue/false
True once deleted; false when there was no such document
idtext
The document's ID
revtext
The revision that marks it deleted; empty when nothing was deleted
Example output
{
  "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

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

Outputs

bookmarktext
Pass this as Bookmark to get the next page
countnumber
How many came back
databasetext
The database, such as orders
documentslist
The documents found, each with _id and its fields (only the fields asked for, when Fields is set)
has_moretrue/false
Whether there may be more: pass the bookmark for the next page
warningtext
CouchDB's note, such as that no index matched; usually empty
Example output
{
  "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

DatabasedatabasetextRequired
The database.
Document IDdocument_idtextRequired
The document it's attached to, such as order-1042.
Attachmentfile_nametextRequired
The attachment's name, such as invoice-1042.pdf.

Outputs

content_typetext
Its type, such as application/pdf
databasetext
The database, such as orders
document_reftext
The downloaded file, for a later step's file field
file_nametext
The attachment's name
idtext
The document's ID
sizenumber
Its size in bytes
texttext
What it says, for a text file of 1 MB or less; otherwise empty
Example output
{
  "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

DatabasedatabasetextRequired
The database.

Outputs

data_sizenumber
The size of its documents and attachments, in bytes
data_size_texttext
The size of its data, such as 1.2 KB
deleted_doc_countnumber
How many deleted documents it still keeps a mark of
doc_countnumber
How many documents it holds (not counting deleted ones)
file_sizenumber
Its size on disk, in bytes
file_size_texttext
Its size on disk, such as 3.8 KB
nametext
The database's name
partitionedtrue/false
Whether it is a partitioned database
update_seqtext
Where its changes are up to (a sequence)
Example output
{
  "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

DatabasedatabasetextRequired
The database.
Document IDdocument_idtextRequired
The document's ID, such as order-1042.
Revisionrevisiontext
An earlier revision to read (its _rev). Leave blank for the newest.

Outputs

attachmentslist
The files attached to it
databasetext
The database, such as orders
documentobject
The document: its fields by name, with _id and _rev; empty when not found
foundtrue/false
False when the database has no document with this ID
idtext
The document's ID
revtext
The document's revision, such as 3-a1b2c3...; empty when not found
Example output
{
  "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 owninclude_systemtrue/false
Also list _users and _replicator, where CouchDB keeps its users and replications.Default: false.

Outputs

countnumber
How many there are
databaseslist
The databases' names
Example output
{
  "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

DatabasedatabasetextRequired
The database.
Design documentdesign_documenttextRequired
The design document that holds the view.
ViewviewtextRequired
The view.
Keykeytext
Only rows with this key, such as paid, 42 or ["Acme Ltd", 2026]. Quote text that looks like a number ("42").
From keystart_keytext
Rows from this key on, such as 2026-01-01.
To keyend_keytext
Rows up to and including this key, such as 2026-12-31.
Reducereducetext
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 levelgroup_levelnumber
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 documentsinclude_docstrue/false
Also return each row's whole document.Only when Reduce is List the rows (don't reduce). Default: false.
Newest firstdescendingtrue/false
Return rows from the highest key down. From key is then the higher key.Default: false.
How manylimitnumber
The most to return. Defaults to 25, up to 1000.From 1 to 1000.

Outputs

countnumber
How many rows came back
databasetext
The database, such as orders
design_documenttext
The design document, without _design/
has_moretrue/false
Whether there are more rows than the most asked for
rowslist
The rows: each key and value, the document's ID (not when reduced), and the document when Include documents is on
total_rowsnumber
How many rows the whole view has (not when reduced)
viewtext
The view
Example output
{
  "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

DatabasedatabasetextRequired
The database.
Document IDdocument_idtextRequired
The document's ID, such as order-1042.
Fieldsfieldsobject
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_jsontext
The document as JSON, such as {"status": "paid", "total": 42, "items": [...]}, for numbers, lists and nested fields. Fields given in Fields win over these.
Howmodetext
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 missingcreate_if_missingtrue/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.
Revisionrevisiontext
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

createdtrue/false
True when there was no document, and it was created
databasetext
The database, such as orders
documentobject
The document as saved, with _id and _rev
idtext
The document's ID
previous_revtext
The revision it replaced; empty when it was created
retriedtrue/false
True when it changed while saving, so it was read again and saved once more
revtext
The document's revision now, such as 2-a1b2c3...
Example output
{
  "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"
}

On this page