Design documents

In CouchDB, design documents provide the main interface for building a CouchDB application. The design document defines the views used to extract information from CouchDB through one or more views. Design documents are created within your CouchDB instance in the same way as you create database documents, but the content and definition of the documents is different.

Warning

Show and List functions are deprecated in CouchDB 3.0, and will be removed in CouchDB 4.0.

Get a design document

Returns the contents of the design document specified with the name of the design document and from the specified database. Unless you request a specific revision, the latest revision of the document will always be returned.

Get-CouchDBDesignDocument -Database test -Document "space" -Authorization "admin:password"

To get all the Design Documents in a database.

Get-CouchDBDatabaseDesignDocument -Database test -Authorization "admin:password"

In this table you can find all the possible parameters to get the design documents with this cmdlet.

PARAMETER DESCRIPTION
Descending Return the design documents in descending by key order. Default is false.
EndKey Stop returning records when the specified key is reached.
EndKeyDocument Stop returning records when the specified design document ID is reached.
IncludeDocument Include the full content of the design documents in the return. Default is false.
InclusiveEnd Specifies whether the specified end key should be included in the result. Default is true.
Key Return only design documents that match the specified key.
Keys Return only design documents that match the specified keys.
Conflict Includes conflicts information in response. Ignored if include_docs isn’t true. Default is false.
Limit Limit the number of the returned design documents to the specified number.
Skip Skip this number of records before starting to return the results. Default is 0.
StartKey Return records starting with the specified key.
StartKeyDocument Return records starting with the specified design document ID.
UpdateSequence Response includes an update_seq value indicating which sequence id of the underlying database the view reflects. Default is false.

Get design document attachment

To retrieve or save an attachment in a design document.

Get-CouchDBDesignDocumentAttachment -Database test -Document space -Attachment test.txt -Authorization "admin:password"                             # Get content
Get-CouchDBDesignDocumentAttachment -Database test -Document space -Attachment test.txt -OutFile "C:\test.txt" -Authorization "admin:password"      # Save content

Creates a design document

Creates a new named design document.

New-CouchDBDesignDocument -Database test -Document "space" -ViewName "planet_view" -ViewMapFunction "function(doc){if(doc.planet && doc.name) {emit(doc.planet, doc.name);}}" -Authorization "admin:password"

Views

The definition of a view within a design document also creates an index based on the key information defined within each view. The production and use of the index significantly increases the speed of access and searching or selecting documents from the view. However, the index is not updated when new documents are added or modified in the database. View indexes are updated incrementally in the following situations:

  • A new document has been added to the database.
  • A document has been deleted from the database.
  • A document in the database has been updated.
New-CouchDBDesignDocument -Database test -Document "space" -ViewName "planet_view" -ViewMapFunction "function(doc){if(doc.planet && doc.name) {emit(doc.planet, doc.name);}}" -Authorization "admin:password"

Now, navigate with your favorite browser to http://localhost:5984/test/_design/space/_view/planet_view or

Get-CouchDBDocument -Database test -Document "_design/space/_view/planet_view" -Authorization "admin:password"

Validation

A design document may contain a function named validate_doc_update which can be used to prevent invalid or unauthorized document update requests from being stored. Only one function is allowed at a time.

Set-CouchDBDesignDocument -Database test -Document "space" -Revision "1-88972423aac3fe5d474dd17d3ee18a8b" -ValidationFunction "function(newDoc, oldDoc, userCtx, secObj){if (!(newDoc.name || newDoc.planet)) {throw({forbidden : 'no way'});}" -Authorization "admin:password"

Now try to creates a new document without validation element

$data = '{"planet":"Magrathea"}'
New-CouchDBDocument -Database test -Document "Test_Validation" -Data $data -Authorization "admin:password"

Received an error: Invoke-RestMethod : {"error":"forbidden","reason":"no way"}. Now retry with this:

$data = '{"planet":"Magrathea", "name":"Slartibartfast"}'
New-CouchDBDocument -Database test -Document "Test_Validation" -Data $data -Authorization "admin:password"

Custom functions

It is also possible to define a custom Design Document, creating a here string that defines the document itself.

$ddoc = @'
{
    "language": "javascript",
    "views": {
        "all": {
            "map": "function(doc) { emit(doc.title, doc) }"
        },
        "by_title": {
            "map": "function(doc) { if (doc.title != null) emit(doc.title, doc) }"
        },
        "by_planet": {
            "map": "function(doc) { for(i=0;i<doc.keywords.lenghth();i++) { emit(doc.keywords[i], doc); } }"
        }
    },
    "shows": {
        "planet": "function(doc, req) { return '<h1>' + doc.title + '</h1>' }"
    }
}
'@
New-CouchDBDesignDocument -Database test -Document space -Data $ddoc -Authorization "admin:password"

Create design document attachment

To create an attachment in a design document.

Add-CouchDBDesignDocumentAttachment -Database test -Document space -Attachment "C:\test.txt" -Revision 3-cfae968df80635ad15a9709e0264a988 -Authorization "admin:password"

Modify design document attachment

To modify or add an attachment in a design document.

Add-CouchDBDesignDocumentAttachment -Database test -Document space -Attachment "C:\test2.txt" -Revision 4-cfae968df80635ad15d5709e0264a988 -Authorization "admin:password"

Compress design document

The compaction operation is the way to reduce disk space usage by removing unused and old data from database or view index files. This operation is very similar to the vacuum (SQLite ex.) operation available for other database management systems.

Compress-CouchDBDesignDocument -Database test -DesignDoc space -Authorization "admin:password"

Remove design document

To remove a design document.

Remove-CouchDBDesignDocument -Database test -Document "mydesigndoc" -Revision "1-85a961d0d9b235b7b4f07baed1a38fda" -Authorization "admin:password"

Remove design document attachment

To remove an attachment in a design document.

Remove-CouchDBDesignDocumentAttachment -Database test -Document space -Attachment "C:\test2.txt" -Revision 5-cfae778df80635ad15daa09e0264a988 -Authorization "admin:password"