Data Access Low level

Description: Data Access Low level Service

Where possible, the Data Access High level Service should be used.

The Predix Mobile low-level database API follows a subset of the CouchDB API

Not all CouchDB API calls are supported. Below are details of some of the more useful CouchDB API commands that are supported.

The general calling pattern is:

URL: http://pmapi/cdb/{DatabaseName}/{CommandPath}

DatabaseName must be the default configured database name, or the tilde "~" character, which will be substituted for the default database name.

Guidelines:

Failure to follow these guidelines may produce unexpected or inconsistant results

All requests should be URL-encoded as per standard URL specs (RFC3986, RFC2279)
- Example: a document with an ID of: test_document-[foo] would be encoded as: test_document-%5Bfoo%5D in requests where the document ID is part of the URL or query parameters:

http://pmapi/cdb/~/test_document-%5Bfoo%5D
http://pmapi/cdb/~/_all_docs?key=%22test_document-%5Bfoo%5D%22

Query parameters containing keys or partial keys must be quoted
Example: startkey="test-document-a" would then be encoded as:

http://pmapi/cdb/~/_all_docs?startkey=%22test-document-a%22

Query parameters containing multiple keys must be in the form of a JSON string array
Example: keys=["test-document-a", "test-document-b"] would then be encoded as:

   http://pmapi/cdb/~/_all_docs?keys=%5B%22test-document-a%22%2C%20%22test-document-b%22%5D

Unless otherwise noted, all URLs, query parameters, and request payloads are case sensitive.
Example: test-document-a does not equal TEST-DOCUMENT-A

_all_docs query

CommandPath: _all_docs

Supported Methods: GET

Returns a JSON structure of all of the documents in a given database. The information is returned as a JSON structure containing meta information about the return structure, including a list of all documents and basic contents, consisting the ID, revision, and key. The key is, in this case, the document’s _id.

Optional Query Parameters:

conflicts (boolean) – Includes conflicts information in response. Ignored if include_docs isn’t true. The default is false.
descending (boolean) – Return the documents in descending key order. The default is false.
endkey (string) – Stop returning records when the specified key is reached. Optional.
end_key (string) – Alias for endkey param.
include_docs (boolean) – Include the full content of the documents in the return. The default is false.
inclusive_end (boolean) – Specifies whether the specified end key should be included in the result. The default is true.
key (string) – Return only documents that match the specified key. Optional.
keys (string) – Return only documents that match the specified keys. Optional.
limit (number) – Limit the number of the returned documents to the specified number. Optional.
skip (number) – Skip this number of records before starting to return the results. The default is 0.
startkey (string) – Return records starting with the specified key. Optional.
start_key (string) – Alias for startkey param.
update_seq (boolean) – Response includes an update_seq value indicating which sequence id of the underlying database the view reflects. The default is false.

Response JSON:

offset (number) – Offset where the document list started
rows (array) – Array of view row objects. By default, the information returned contains only the document ID and revision.
total_rows (number) – Number of documents in the database/view. Note that this is not the number of rows returned in the actual query.
update_seq (number) – Current update sequence for the database (if request included update_seq)

Status Codes:

200 OK - Request completed successfully

Example: http://pmapi/cdb/~/_all_docs

Response Status: 200 OK
Response JSON:

{
    "offset": 0,
    "rows": [
        {
            "id": "test-document-1",
            "key": "test-document-1",
            "value": {
                "rev": "1-325d7458259c4c8aa2ddda020b1bd6f8"
            }
        },
        {
            "id": "test-document-2",
            "key": "test-document-2",
            "value": {
                "rev": "2-669339dc872b404c8aa43342bec4b6b1"
            }
        },
        {
            "id": "test-document-3",
            "key": "test-document-3",
            "value": {
                "rev": "8-09d2ddfb032f443e9f361d183cbbd605"
            }
        },
        {
            "id": "test-document-4",
            "key": "test-document-4",
            "value": {
                "rev": "1-55b0ea2fb00b490b8e6567291cd40a24"
            }
        }
    ],
    "total_rows": 4
}

Bulk document edits

CommandPath: _bulk_docs

Supported Methods: POST

The bulk document API allows you to create and update multiple documents at the same time within a single request. The basic operation is similar to creating or updating a single document, except that you batch the document structure and information.

When creating new documents the document ID (_id) is optional.

For updating existing documents, you must provide the document ID, revision information (_rev), and new document values.

In case of batch deleting documents, all fields as document ID, revision information and deletion status (_deleted) are required.

Request Body JSON:

docs (array) – List of document objects

Response JSON:

JSON Array of Objects:

id (string) – Document ID
rev (string) – New document revision token. Available if document has saved without errors. Optional
error (string) – Error type. Optional
reason (string) – Error reason. Optional

Status Codes:

201 Created – Document(s) have been created or updated
400 Bad Request – The request provided invalid JSON data
500 Internal Server Error – Malformed data provided, while it’s still valid JSON

Example:

POST http://pmapi/cdb/~/_bulk_docs

Request Body:

{
   "docs": [
   { "_id": "test-document-a",
     "_rev": "2-a98e511fa1f7461db293573e7e9d42e9",
     "foo": "bar" },
   { "_id": "test-document-b",
     "foo": "new document!" },
   { "_id": "test-document-c",
     "_rev": "3-cb7c5067838d4709a4fa0e34f17310f5",
     "foo": "somevalue" },
   { "_id": "test-document-d",
     "_rev": "not the current revision",
     "foo": "this will be a conflict" }
    ]
}

Response Status: 201 Created
Response JSON:

[
   { "id":"test-document-a",
     "rev":"3-b843e2b35ca7f76483cedb2004abae81",
     "ok":true},
   { "id":"test-document-b",
     "rev":"1-bedb6912eab495b0ab920df1a647c3c8",
     "ok":true}
   { "id":"test-document-c",
     "rev":"4-d25050177e3c0b7ae40fd73a797f8961",
     "ok":true},
   { "id":"test-document-d",
     "error":"conflict",
     "reason":"conflict"}
]

Single document operations

CommandPath: {document_id}

Supported Methods: GET, PUT, POST, DELETE

Method GET

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

Optional Query Parameters:

attachments (boolean) – Includes attachments bodies in response. The default is false
atts_since (array) – Includes attachments only since specified revisions. Doesn’t includes attachments for specified revisions. Optional
conflicts (boolean) – Includes information about conflicts in the document. The default is false
open_revs (array) – Retrieves documents of specified leaf revisions. Additionally, it accepts value as all to return all leaf revisions. Optional
rev (string) – Retrieves document of specified revision. Optional
revs (boolean) – Includes a list of all known document revisions. The default is false
revs_info (boolean) – Includes detailed information for all known document revisions. Default is false

Status Codes:

200 OK – Request completed successfully
404 Not Found – Document not found

Example: GET http://pmapi/cdb/~/test-document-a

Response JSON:

{
    "_id": "test-document-a",
    "_rev": "2-a98e511fa1f7461db293573e7e9d42e9",
     "foo": "bar" 
}

Method PUT

Updates an existing document, or creates a new document.

If updating an existing document, a new revision of the document is created, and the previous revision id of the document must be provided as part of the request body, or as the rev query parameter.

Optional Query Parameters:

rev (string) – Current revision number of the document. Optional

Status Codes:

201 Created – Document created and stored on disk
400 Bad Request – Invalid request body or parameters
404 Not Found – Specified document ID doesn’t exist
409 Conflict – Document with the specified ID already exists or specified revision is not latest for target document

Examples:

PUT http://pmapi/cdb/~/test-document-a

Request Body:

{
    "_id": "test-document-a",
    "_rev": "2-a98e511fa1f7461db293573e7e9d42e9",
     "foo": "new value"
}

Response Status: 201 Created
Response JSON:

{
    "_id": "test-document-a",
    "_rev": "3-fe8f79ab8473483ba7d442482ba98611",
     "ok": true
}

Document Contents would now be:

{
    "_id": "test-document-a",
    "_rev": "3-fe8f79ab8473483ba7d442482ba98611",
     "foo": "new value"
}

PUT http://pmapi/cdb/~/test-document-a?rev=2-a98e511fa1f7461db293573e7e9d42e9

Request Body:

{
     "foo": "new value"
}

Response Status: 201 Created
Response JSON:

{
    "_id": "test-document-a",
    "_rev": "3-fe8f79ab8473483ba7d442482ba98611",
     "ok": true
}

Document Contents would now be:

{
    "_id": "test-document-a",
    "_rev": "3-fe8f79ab8473483ba7d442482ba98611",
     "foo": "new value"
}

PUT http://pmapi/cdb/~/test-document-a

Request Body:

{
    "_id": "test-document-a",
    "_rev": "not the current revision",
     "foo": "new value"
}

Response Status: 409 Conflict
Response JSON:

{
    "status": 409,
    "error": "conflict",
    "reason": "conflict"
}

Method POST

Creates a new document. The document ID in the URL path is optional in this case. It can either be in the URL, or as part of the request body, or if left out entirely will be auto-generated.

Status Codes:

201 Created – Document created and stored on disk
400 Bad Request – Invalid request body or parameters
409 Conflict – Document with the specified ID already exists

Examples:

POST http://pmapi/cdb/~/test-document-b

Request Body:

{
     "foo": "some value"
}

Response Status: 201 Created
Response JSON:

{
    "_id": "test-document-b",
    "_rev": "1-28034fa1e31e4cd180aa1b391ad5caf1",
     "ok": true
}

Document Contents would now be:

{
    "_id": "test-document-b",
    "_rev": "1-28034fa1e31e4cd180aa1b391ad5caf1",
     "foo": "some value"
}

POST http://pmapi/cdb/~/ note trailing slash is required

Request Body:

{
     "_id": "test-document-b",
     "foo": "some value"
}

Response Status: 201 Created
Response JSON:

{
    "_id": "test-document-b",
    "_rev": "1-28034fa1e31e4cd180aa1b391ad5caf1",
     "ok": true
}

Document Contents would now be:

{
    "_id": "test-document-b",
    "_rev": "1-28034fa1e31e4cd180aa1b391ad5caf1",
     "foo": "some value"
}

POST http://pmapi/cdb/~/ note trailing slash is required

Request Body:

{
     "foo": "some value"
}

Response Status: 201 Created
Response JSON:

{
    "_id": "zx9y0p2hJHqwKnQhsCp6Y1",
    "_rev": "1-5ff6d5706f1c4a928770137fa55325f3",
     "ok": true
}

Document Contents would now be:

{
    "_id": "zx9y0p2hJHqwKnQhsCp6Y1",
    "_rev": "1-5ff6d5706f1c4a928770137fa55325f3",
     "foo": "some value"
}

Method DELETE

Marks the specified document as deleted by adding a field _deleted with the value true. Documents with this field will not be returned within requests anymore, but stay in the database. You must supply the current (latest) revision, by using the rev parameter.

The document will not be completely deleted. Instead, it leaves a tombstone with very basic information about the document. The tombstone is required so that the delete action can be replicated back to the server.

Status Codes:

200 Created – The document successful marked deleted
409 Conflict – The specified revision is not latest for target document

Examples:

DELETE http://pmapi/cdb/~/test-document-b?rev=1-28034fa1e31e4cd180aa1b391ad5caf1

Response Status: 200 OK
Response JSON:

{
    "_id": "test-document-b",
    "_rev": "2-c9872039bb0746798353256f3368aff3",
     "ok": true
}

Document Contents would now be:

{
    "_id": "test-document-b",
    "_rev": "2-c9872039bb0746798353256f3368aff3",
    "_deleted": true
}

Querying Views

See Also: the Query functionality of the high-level database service.

CommandPath: _design/{view-name-prefix}/_view/{view-name-suffix}

Supported Methods: GET

Queries the specified view, as defined in the native container, with a view name {view-name-prefix}/{view-name-suffix}.

Returned key/values will depend on the definition of the view.

id	type	name
item-1	fruit	apple
item-2	veg	cabbage
item-3	fruit	banana
item-4	meat	chicken
item-5	veg	cucumber
item-6	meat	beef
item-7	veg	zucchini
item-8	meat	salmon

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Data Access Low level

Description: Data Access Low level Service

_all_docs query

Bulk document edits

Single document operations

Querying Views

Clone this wiki locally