couchdb-view-by-keys

couchdb-view-by-keys

A command line tool to query CouchDB views, focused on easing queries with complex JSON keys (which are a pain to do with curl)

Summary

• Install
• How-To
  • General
  • Get rows
  • Get docs
  • Get keys
  • Get values
  • Get only view rows id and key
  • Limit
  • Skip
  • Output format
    • newline-delimited JSON
    • JSON
• Tips
  • use single quotes in JSON keys

Install

npm install -g couchdb-view-by-keys

How-To

General

url="http://username:password@localhost:5984/db-name/_design/design-doc-name/_view/view-name"
couchdb-view-by-keys "$url" keyA keyB keyC
couchdb-view-by-keys "$url" '["a", "complex", "key"]' '["another", "complex", "key"]'
# Or from a file with one key per line
cat keys | xargs couchdb-view-by-keys "$url"

Or to fetch many documents

url="http://username:password@localhost:5984/_all_docs"
couchdb-view-by-keys "$url" docIdA docIdB docIdC
# Or from a file with one doc id per line
cat ids | xargs couchdb-view-by-keys "$url"

Get rows

couchdb-view-by-keys "$url"

Get docs

couchdb-view-by-keys --docs "$url"

Get keys

couchdb-view-by-keys --keys "$url"

Get values

couchdb-view-by-keys --values "$url"

Get only view rows id and key

By default, view rows are returned with their document, but this can be disabled by setting include_docs=false

couchdb-view-by-keys "${url}?include_docs=false"

NB: reduce=false is also set by default, as reduce=true is incompatible with include_docs=true

Limit

couchdb-view-by-keys "${url}?limit=10"

Skip

couchdb-view-by-keys "${url}?skip=10"

Output format

newline-delimited JSON

Newline-delimited JSON (a.k.a NDJSON) is the the default output format

couchdb-view-by-keys "$url" keyA keyB keyC

set the indentation to 0 to drop newlines

couchdb-view-by-keys "$url" keyA keyB keyC --json 0

JSON

# Get all the rows as an array of object
couchdb-view-by-keys "$url" keyA keyB keyC --json
# Same, but with an indentation of 2
couchdb-view-by-keys "$url" keyA keyB keyC --json 2
# Same, but with an indentation of 4
couchdb-view-by-keys "$url" keyA keyB keyC --json 4

Tips

use single quotes in JSON keys

Some times you might need to use variable interpolation, which, in bash, requires to use double quotes. Unfortunately, JSON keys being expected to be valid JSON, they also require doubles quotes. You would thus normally endup with some horrible escaping of the kind:

couchdb-view-by-keys "$url" "[\"$1\",\"a\"]" "[\"$2\",\"b\"]" "[\"$3\",\"c\"]"

Horrified by so much anticipated pain, you might just stop there, give up on computing and start drinking. But fear no more! You can just use single quotes instead:

# works with simple arrays
couchdb-view-by-keys "$url" "['$1','a']" "['$2','b']" "['$3','c']"
# and simple objects
couchdb-view-by-keys "$url" "{ 'a': '$1'}"
# TODO: make it work for nested objects/arrays if you have the need

Changelog

4.1.0 - 2021-04-24

• Add --keys option