Documents¶
All documents are contained in a database. Each document is in json format.
Get a document¶
To get document by the specified Document
from the specified Database
. Unless you request a specific revision, the latest revision of the document will always be returned.
Get-CouchDBDocument -Database test -Document "Hitchhikers"
In this table you can find all the possible parameters to get the document.
PARAMETER | DESCRIPTION |
---|---|
Revision | The CouchDB revision document. |
Local | Return CouchDB local document. |
Revisions | Return all CouchDB db revisions. |
History | Return all info CouchDB db revisions. |
Attachments | Includes attachments bodies in response. |
AttachmentsInfo | Includes encoding information in attachment stubs if the particular attachment is compressed. |
AttachmentsSince | Includes attachments only since specified revisions. Doesn’t includes attachments for specified revisions. |
Conflicts | Includes information about conflicts in document. |
DeletedConflicts | Includes information about deleted conflicted revisions. |
Latest | Forces retrieving latest “leaf” revision, no matter what rev was requested. |
LocalSequence | Includes last update sequence for the document. |
Metadata | Acts same as specifying all conflicts, deleted_conflicts and revs_info query parameters. |
OpenRevisions | Retrieves documents of specified leaf revisions. Additionally, value all id default and to return all leaf revisions. |
And if use _all_docs view, in this table you can find all the possible parameters.
PARAMETER | DESCRIPTION |
---|---|
Descending | Return the 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 document ID is reached. |
Group | Group the results using the reduce function to a group or single row. Implies reduce is true and the maximum group_level. Default is false . |
GroupLevel | Specify the group level to be used. Implies group is true . |
IncludeDocuments | Include the associated document with each row. Default is false . |
InclusiveEnd | Specifies whether the specified end key should be included in the result. Default is true . |
Key | Return only documents that match the specified key. The document must be _all_docs. |
Keys | Return only documents where the key matches one of the keys specified in the array. |
Limit | Limit the number of the returned design documents to the specified number. |
Reduce | Use the reduction function. Default is true when a reduce function is defined. |
Skip | Skip this number of records before starting to return the results. |
Sorted | Sort returned rows. Setting this to false offers a performance boost. The total_rows and offset fields are not available when this is set to false . Default is true . |
Stable | Whether or not the view results should be returned from a stable set of shards. Default is false . |
Stale | Allow the results from a stale view to be used. Supported values: ok , update_after and false . ok is equivalent to stable=true&update=false . update_after is equivalent to stable=true&update=lazy . false is equivalent to stable=false&update=true . |
StartKey | Return records starting with the specified key. |
StartKeyDocument | Return records starting with the specified document ID. Ignored if startkey is not set. |
Update | Whether or not the view in question should be updated prior to responding to the user. Supported values: true , false , lazy . Default is true . |
UpdateSequence | Whether to include in the response an update_seq value indicating the sequence id of the database the view reflects. Default is false . |
Create a document¶
To creates a new named document, or creates a new revision of the existing document. The Data
parameter it can be a json or a hashtable object.
$data = '{"planet":"Magrathea", "name":"Slartibartfast"}'
New-CouchDBDocument -Database test -Document "Hitchhikers" -Data $data -Authorization "admin:password"
There is also the possibility of enabling a batch mode.
$data = '{"planet":"Magrathea", "name":"Slartibartfast"}'
New-CouchDBDocument -Database test -Document "Hitchhikers" -Data $data -BatchMode -Authorization "admin:password"
Write-CouchDBFullCommit -Database test -Authorization "admin:password"
Note
Until you run the Write-CouchDBFullCommit
cmdlet, the document will not be written to disk but kept only in memory. This can be useful in case of bulk writing.
Modify a document¶
With Revision
parameter it is possible to overwrite the document. The document retain the previously written elements. If an item is specified again, it will be overwritten.
$data = @{"answer"=42; "ask"="Ultimate Question of Life, the Universe and Everything"}
Set-CouchDBDocument -Database test -Document "Hitchhikers" -Revision 1-2c903913030efb4d711db085b1f44107 -Data $data -Authorization "admin:password"
With Replace
parameter, the document is re-write again.
$data = '{"planet":"Heart", "name":"Arthur Dent"}'
Set-CouchDBDocument -Database test -Document "Hitchhikers" -Revision 2-9a68ee74a8276c7f11146245ba43676f -Data $data -Replace -Authorization "admin:password"
Delete a document¶
To delete a document, specify Revision
parameter.
Note
CouchDB doesn’t completely delete the specified document. Instead, it leaves a tombstone with very basic information about the document. The tombstone is required so that the delete action can be replicated across databases.
Remove-CouchDBDocument -Database test -Document "Hitchhikers" -Revision "3-399796e5ce019e04311637e8a8a0f402" -Authorization "admin:password"
Copy a document¶
Copies an existing document to a new or existing document. Copying a document is only possible within the same database.
Copy-CouchDBDocument -Database test -Document "Hitchhikers" -Destination "Hitchhikers Guide" -Authorization "admin:password"
Copy-CouchDBDocument -Database test -Document "Hitchhikers" -Destination "Hitchhikers Guide _deleted" -Revision 3-399796e5ce019e04311637e8a8a0f402 -Authorization "admin:password"
Local document¶
To get of all of the local documents in a given database.
Get-CouchDBDocument -Database test -Local
Get a bulk documents¶
This method can be called to query several documents in bulk.
Get-CouchDBBulkDocument -Database test -Document "Hitchhikers","Hitchhikers Guide _deleted","Hitchhikers Guide"
Create documents in bulk¶
The bulk document API allows you to create and update multiple documents at the same time within a single request.
Set-CouchDBBulkDocument -Database test -Document "Hitchhikers","Hitchhikers_new","Hitchhikers Guide" -Revision 4-7051cbe5c8faecd085a3fa619e6e6337,$null,3-399796e5ce019e04311637e8a8a0f402 -Authorization "admin:password"
Attachments¶
Document can includes attachments, then the returned structure will contain a summary of the attachments associated with the document.
Get an attachment¶
It’s possible to retrieve document with all attached files content.
Get-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment test.txt
Also is possible save a file.
Get-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment test.txt -OutFile "C:\out.txt"
Or get info of specific attachment.
Get-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment test.txt -Info
Create an attachment¶
It’s possible to retrieve document with all attached files content.
New-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment "C:\test.txt" -Revision "4-f6d66c4d70da66cded6bea889468eb14" -Authorization "admin:password"
Modify an attachment¶
To replace or add an attachment.
Set-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment "C:\out.txt" -Authorization "admin:password"
Delete an attachment¶
To remove an attachment.
Remove-CouchDBAttachment -Database test -Document "Hitchhikers" -Attachment out.txt -Revision "5-7bf1766d9a5f3e4a60b400e98d62f523" -Authorization "admin:password"
Revisions¶
Get a list of revisions¶
You can obtain a list of the revisions for a given document.
Get-CouchDBDocument -Database test -Document "Hitchhikers" -Revisions
Get a history of revisions¶
You can get additional information (history) about the revisions for a given document.
Get-CouchDBDocument -Database test -Document "Hitchhikers" -History
Get a specific revision¶
To get a specific revision, use the Revision
parameter, and specify the full revision number.
Get-CouchDBDocument -Database test -Document "Hitchhikers" -Revision "5-7bf1766d9a5f3e4a60b400e98d62f523"
Missing revision¶
With given a list of document revisions, returns the document revisions that do not exist in the database.
Get-CouchDBMissingRevision -Database test -Document "Hitchhikers" -Revision 2-7051cbe5c8faecd085a3fa619e6e6337,5-7bf1766d9a5f3e4a60b400e98d62f523 -Authorization "admin:password"
Purge document¶
A database purge permanently removes the references to documents in the database. Normal deletion of a document within CouchDB does not remove the document from the database, instead, the document is marked as _deleted=true (and a new revision is created). This is to ensure that deleted documents can be replicated to other databases as having been deleted.
Clear-CouchDBDocuments -Database test -Document "Hitchhikers" -Authorization "admin:password"
Query¶
Find a document¶
To search for documents in a database, use the following cmdlet.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet
or with native Mango query
Find-CouchDBDocuments -Database test -Find '{"selector": {"name":{"$eq":"Arthur Dent"}},"fields":["_id","name","planet"]}'
or with class (for complex query)
using module PSCouchDB
$q = New-Object -TypeName PSCouchDBQuery
$q.AddSelector("name","Arthur Dent")
$q.AddSelectorOperator('$eq')
$q.AddFields("_id")
$q.AddFields("name")
$q.AddFields("planet")
Find-CouchDBDocuments -Database test -Find $q.GetNativeQuery()
If you want to use Mango queries, follow the next sections. Otherwise you can see more examples in the Classes section.
Search a document¶
To perform a more generic search in a database, without knowing the various selectors, use:
Search-CouchDBFullText -Database test -Patterns "space","planet"
Warning
This search is much slower than the Find-CouchdbDocuments
cmdlet.
Selector¶
Selectors are expressed as a JSON object describing documents of interest. Within this structure, you can apply conditional logic using specially named fields.
{
"selector": {
"name": "Arthur Dent"
}
}
{
"selector": {
"name": {
"FirstName": "Arthur Dent"
}
}
}
{
"selector": {
"name.FirstName": "Arthur Dent"
}
}
Operators¶
Operators are identified by the use of a dollar sign ($) prefix in the name field. There are two core types of operators in the selector syntax:
- Combination operators
- Condition operators
{
"selector": {
"name": "Arthur Dent"
}
}
There are two implicit operators:
- Equality
- And
In a selector, any field containing a JSON value, but that has no operators in it, is considered to be an equality condition. The implicit equality test applies also for fields and subfields.
{
"selector": {
"name": {
"$eq": "Arthur Dent"
}
}
}
is same to
{
"selector": {
"name": "Arthur Dent"
}
}
List of available operators:
Operator type | Operator | Purpose |
---|---|---|
(In)equality | lt | The field is less than the argument |
lte | The field is less than or equal to the argument | |
eq | The field is equal to the argument | |
ne | The field is not equal to the argument | |
gte | The field is greater than or equal to the argument | |
gt | The field is greater than the to the argument | |
Object | exists | Check whether the field exists or not, regardless |
type | Check the document field’s type. Valid values are “null”, “boolean”, “number”, “string”, “array”, and “object” | |
Array | in | The document field must exist in the list provided |
nin | The document field not must exist in the list provided | |
size | Special condition to match the length of an array field in a document. Non-array fields cannot match this condition | |
Miscellaneous | mod | Divisor and Remainder are both positive or negative integers. Non-integer values result in a 404. |
regex | A regular expression pattern to match against the document field.The matching algorithms are based on the Perl Compatible Regular Expression (PCRE) library. |
Examples
using module PSCouchDB
$q = New-Object -TypeName PSCouchDBQuery
$q.AddSelector("name","Arthur Dent")
$q.AddSelectorOperator('$eq')
$q.AddFields("_id")
$q.AddFields("name")
$q.AddFields("planet")
Find-CouchDBDocuments -Database test -Find $q.GetNativeQuery()
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet
Warning
Pay attention to the $
(dollar) sign. If you use the PSCouchDBQuery class or a native query, the sign is required.
Logical operators¶
Logical operators are used to combine selectors.
Important
Logical operators are only avalaible when creating an object of type PSCouchDBQuery
or use a native query string.
For more details, see Classes section section.
AND
{
"$and": [
{
"_id": { "$gt": null }
},
{
"name": {
"$eq": "Arthur Dent"
}
}
]
}
OR
{
"name": "Arthur Dent",
"$or": [
{ "planet": "Heart" },
{ "planet": "Magrathea" }
]
}
NOT
{
"name": {
"$eq": "Arthur Dent"
},
"name": {
"$eq": "Slartibartfast"
},
"$not": {
"name": "Ford Prefect"
}
}
Operator | Purpose |
---|---|
and | Matches if all the selectors in the array match |
or | Matches if any of the selectors in the array match. All selectors must use the same index |
not | Matches if the given selector does not match |
nor | Matches if none of the selectors in the array match |
all | Matches an array value if it contains all the elements of the argument array |
elemMatch | Matches and returns all documents that contain an array field with at least one element that matches all the specified query criteria |
allMatch | Matches and returns all documents that contain an array field with all its elements matching all the specified query criteria |
Sort¶
The sort field contains a list of field name and direction pairs, expressed as a basic array. The first field name and direction pair is the topmost level of sort. The second pair, if provided, is the next level of sort. The direction value is “asc” for ascending, and “desc” for descending. If you omit the direction value, the default “asc” is used.
{
"selector": {"name": "Arthur Dent"},
"sort": [{"name": "asc"}, {"planet": "asc"}]
}
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Sort name,planet
Limit¶
Maximum number of results returned. Default is 25.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Limit 100
Skip¶
Skip the first ‘n’ results, where ‘n’ is the value specified.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Skip 10
Use index¶
Instruct a query to use a specific index.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -UseIndex "index_planet"
Read quorum¶
Read quorum needed for the result. This defaults to 1, in which case the document found in the index is returned.
If set to a higher value, each document is read from at least that many replicas before it is returned in the results. This is likely to take more time than using only the document stored locally with the index.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -ReadQuorum 3
Bookmark¶
A string that enables you to specify which page of results you require. Used for paging through result sets. Every query returns an opaque string under the bookmark key that can then be passed back in a query to get the next page of results. If any part of the selector query changes between requests, the results are undefined.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Bookmark "my_bookmark"
No Update¶
Whether to update the index prior to returning the result. Default is true.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -NoUpdate
Stable¶
Whether or not the view results should be returned from a “stable” set of shards.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Stable
Stale¶
Combination of update=false
and stable=true
options. Possible options: "ok"
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Stale 'ok'
Execution statistics¶
Include execution statistics in the query response.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -ExecutionStats
Explain¶
Shows which index is being used by the query.
Find-CouchDBDocuments -Database test -Selector "name" -Operator eq -Value "Arthur Dent" -Fields _id,name,planet -Sort name,planet -Explain